# Module parsecfg

The `parsecfg` module implements a high performance configuration file parser. The configuration file's syntax is similar to the Windows `.ini` format, but much more powerful, as it is not a line based parser. String literals, raw string literals and triple quoted string literals are supported as in the Nimrod programming language.This is an example of how a configuration file may look like:

    # This is a comment.
    ; this too.

    [Common]
    cc=gcc     # '=' and ':' are the same
    --verbose

    [Windows]
    isConsoleApplication=False ; another comment

    [Posix]
    isConsoleApplication=True

    key1: "in this string backslash escapes are interpreted\n"
    key2: r"in this string not"
    key3: """triple quotes strings
    are also supported. They may span
    multiple lines."""

    --"long option with spaces": r"c:\myfiles\test.txt"

The file `examples/parsecfgex.nim` demonstrates how to use the configuration file parser:

    import
      os, parsecfg, strutils, streams

    var f = newFileStream(paramStr(1), fmRead)
    if f != nil:
      var p: TCfgParser
      open(p, f, paramStr(1))
      while true:
        var e = next(p)
        case e.kind
        of cfgEof:
          echo("EOF!")
          break
        of cfgSectionStart:   ## a ``[section]`` has been parsed
          echo("new section: " & e.section)
        of cfgKeyValuePair:
          echo("key-value-pair: " & e.key & ": " & e.value)
        of cfgOption:
          echo("command: " & e.key & ": " & e.value)
        of cfgError:
          echo(e.msg)
      close(p)
    else:
      echo("cannot open: " & paramStr(1))

# Imports

hashes, strutils, lexbase, streams

# Types

    TCfgEventKind = enum
      cfgEof,                     ## end of file reached
      cfgSectionStart,            ## a ``[section]`` has been parsed
      cfgKeyValuePair,            ## a ``key=value`` pair has been detected
      cfgOption,                  ## a ``--key=value`` command line option
      cfgError                    ## an error ocurred during parsing

  enumeration of all events that may occur when parsing

    TCfgEvent = object of TObject
      case kind*: TCfgEventKind   ## the kind of the event
      of cfgEof:
        nil
      of cfgSectionStart:
          section*: string        ## `section` contains the name of the
                                  ## parsed section start (syntax: ``[section]``)

      of cfgKeyValuePair, cfgOption:
          key*, value*: string    ## contains the (key, value) pair if an option
                                  ## of the form ``--key: value`` or an ordinary
                                  ## ``key= value`` pair has been parsed.
                                  ## ``value==""`` if it was not specified in the
                                  ## configuration file.

      of cfgError:                ## the parser encountered an error: `msg`
          msg*: string            ## contains the error message. No exceptions
                                  ## are thrown if a parse error occurs.

  describes a parsing event

    TCfgParser = object of TBaseLexer
      tok: TToken
      filename: string

  the parser object.

# Procs

    proc open(c: var TCfgParser; input: PStream; filename: string; lineOffset = 0) {.
        rtl, extern: "npc$1", raises: [E_Base], tags: [FReadIO, TEffect].}

  initializes the parser with an input stream. Filename is only used for nice error messages. lineOffset can be used to influence the line number information in the generated error messages.

    proc close(c: var TCfgParser) {.rtl, extern: "npc$1", raises: [E_Base], tags: [].}

  closes the parser c and its associated input stream.

    proc getColumn(c: TCfgParser): int {.rtl, extern: "npc$1", raises: [], tags: [].}

  get the current column the parser has arrived at.

    proc getLine(c: TCfgParser): int {.rtl, extern: "npc$1", raises: [], tags: [].}

  get the current line the parser has arrived at.

    proc getFilename(c: TCfgParser): string {.rtl, extern: "npc$1", raises: [],
        tags: [].}

  get the filename of the file that the parser processes.

    proc errorStr(c: TCfgParser; msg: string): string {.rtl, extern: "npc$1",
        raises: [EInvalidValue], tags: [].}

  returns a properly formated error message containing current line and column information.

    proc warningStr(c: TCfgParser; msg: string): string {.rtl, extern: "npc$1",
        raises: [EInvalidValue], tags: [].}

  returns a properly formated warning message containing current line and column information.

    proc ignoreMsg(c: TCfgParser; e: TCfgEvent): string {.rtl, extern: "npc$1",
        raises: [EInvalidValue], tags: [].}

  returns a properly formated warning message containing that an entry is ignored.

    proc next(c: var TCfgParser): TCfgEvent {.rtl, extern: "npc$1",
        raises: [E_Base, EInvalidValue], tags: [FReadIO].}

  retrieves the first/next event. This controls the parser.

Generated: 2013-05-21 09:55:10 UTC