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 Nim 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: CfgParser 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))
Types
CfgEventKind = 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 occurred during parsing
- enumeration of all events that may occur when parsing Source
CfgEvent = object of RootObj case kind*: CfgEventKind ## 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 Source
CfgParser = object of BaseLexer tok: Token filename: string
- the parser object. Source
Procs
proc open(c: var CfgParser; input: Stream; filename: string; lineOffset = 0) {. gcsafe, extern: "npc$1", raises: [Exception], tags: [ReadIOEffect, RootEffect].}
- 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. Source
proc close(c: var CfgParser) {.gcsafe, extern: "npc$1", raises: [Exception], tags: [].}
- closes the parser c and its associated input stream. Source
proc getColumn(c: CfgParser): int {.gcsafe, extern: "npc$1", raises: [], tags: [].}
- get the current column the parser has arrived at. Source
proc getLine(c: CfgParser): int {.gcsafe, extern: "npc$1", raises: [], tags: [].}
- get the current line the parser has arrived at. Source
proc getFilename(c: CfgParser): string {.gcsafe, extern: "npc$1", raises: [], tags: [].}
- get the filename of the file that the parser processes. Source
proc errorStr(c: CfgParser; msg: string): string {.gcsafe, extern: "npc$1", raises: [ValueError], tags: [].}
- returns a properly formated error message containing current line and column information. Source
proc warningStr(c: CfgParser; msg: string): string {.gcsafe, extern: "npc$1", raises: [ValueError], tags: [].}
- returns a properly formated warning message containing current line and column information. Source
proc ignoreMsg(c: CfgParser; e: CfgEvent): string {.gcsafe, extern: "npc$1", raises: [ValueError], tags: [].}
- returns a properly formated warning message containing that an entry is ignored. Source
proc next(c: var CfgParser): CfgEvent {.gcsafe, extern: "npc$1", raises: [Exception, ValueError], tags: [ReadIOEffect].}
- retrieves the first/next event. This controls the parser. Source