std/parsecfg

  Source   Edit

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.

Example of how a configuration file may look like:

# This is a comment.
; this too.

[Common]
cc=gcc     # '=' and ':' are the same
--foo="bar"   # '--cc' and 'cc' are the same, 'bar' and '"bar"' are the same (except for '#')
macrosym: "#"  # Note that '#' is interpreted as a comment without the quotation
--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" 

Here is an example of how to use the configuration file parser:

Example: cmd: -r:off

import std/parsecfg
import std/[strutils, streams]

let configFile = "example.ini"
var f = newFileStream(configFile, fmRead)
assert f != nil, "cannot open " & configFile
var p: CfgParser
open(p, f, configFile)
while true:
  var e = next(p)
  case e.kind
  of cfgEof: 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)

Configuration file example

charset = "utf-8"
[Package]
name = "hello"
--threads:on
[Author]
name = "nim-lang"
website = "nim-lang.org"

Creating a configuration file

Example:

import std/parsecfg
var dict = newConfig()
dict.setSectionKey("","charset", "utf-8")
dict.setSectionKey("Package", "name", "hello")
dict.setSectionKey("Package", "--threads", "on")
dict.setSectionKey("Author", "name", "nim-lang")
dict.setSectionKey("Author", "website", "nim-lang.org")
assert $dict == """
charset=utf-8
[Package]
name=hello
--threads:on
[Author]
name=nim-lang
website=nim-lang.org
"""

Reading a configuration file

Example: cmd: -r:off

import std/parsecfg
let dict = loadConfig("config.ini")
let charset = dict.getSectionValue("","charset")
let threads = dict.getSectionValue("Package","--threads")
let pname = dict.getSectionValue("Package","name")
let name = dict.getSectionValue("Author","name")
let website = dict.getSectionValue("Author","website")
echo pname & "\n" & name & "\n" & website

Modifying a configuration file

Example: cmd: -r:off

import std/parsecfg
var dict = loadConfig("config.ini")
dict.setSectionKey("Author", "name", "nim-lang")
dict.writeConfig("config.ini")

Deleting a section key in a configuration file

Example: cmd: -r:off

import std/parsecfg
var dict = loadConfig("config.ini")
dict.delSectionKey("Author", "website")
dict.writeConfig("config.ini")

Supported INI File structure

Example:

import std/parsecfg
import std/streams

var dict = loadConfig(newStringStream("""[Simple Values]
    key=value
    spaces in keys=allowed
    spaces in values=allowed as well
    spaces around the delimiter = obviously
    you can also use : to delimit keys from values
    [All Values Are Strings]
    values like this: 19990429
    or this: 3.14159265359
    are they treated as numbers : no
    integers floats and booleans are held as: strings
    can use the API to get converted values directly: true
    [No Values]
    key_without_value
    # empty string value is not allowed =
    [ Seletion A   ]
    space around section name will be ignored
    [You can use comments]
    # like this
    ; or this
    # By default only in an empty line.
    # Inline comments can be harmful because they prevent users
    # from using the delimiting characters as parts of values.
    # That being said, this can be customized.
        [Sections Can Be Indented]
            can_values_be_as_well = True
            does_that_mean_anything_special = False
            purpose = formatting for readability
            # Did I mention we can indent comments, too?
    """)
)

let section1 = "Simple Values"
assert dict.getSectionValue(section1, "key") == "value"
assert dict.getSectionValue(section1, "spaces in keys") == "allowed"
assert dict.getSectionValue(section1, "spaces in values") == "allowed as well"
assert dict.getSectionValue(section1, "spaces around the delimiter") == "obviously"
assert dict.getSectionValue(section1, "you can also use") == "to delimit keys from values"

let section2 = "All Values Are Strings"
assert dict.getSectionValue(section2, "values like this") == "19990429"
assert dict.getSectionValue(section2, "or this") == "3.14159265359"
assert dict.getSectionValue(section2, "are they treated as numbers") == "no"
assert dict.getSectionValue(section2, "integers floats and booleans are held as") == "strings"
assert dict.getSectionValue(section2, "can use the API to get converted values directly") == "true"

let section3 = "Seletion A"
assert dict.getSectionValue(section3, 
  "space around section name will be ignored", "not an empty value") == ""

let section4 = "Sections Can Be Indented"
assert dict.getSectionValue(section4, "can_values_be_as_well") == "True"
assert dict.getSectionValue(section4, "does_that_mean_anything_special") == "False"
assert dict.getSectionValue(section4, "purpose") == "formatting for readability"

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   Edit
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   Edit
CfgParser = object of BaseLexer
  tok: Token
  filename: string
the parser object.   Source   Edit
Config = OrderedTableRef[string, OrderedTableRef[string, string]]
  Source   Edit

Procs

proc open(c: var CfgParser; input: Stream; filename: string; lineOffset = 0) {.
    ...gcsafe, extern: "npc$1", raises: [IOError, OSError, 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   Edit
proc close(c: var CfgParser) {....gcsafe, extern: "npc$1",
                               raises: [Exception, IOError, OSError],
                               tags: [WriteIOEffect].}
Closes the parser c and its associated input stream.   Source   Edit
proc getColumn(c: CfgParser): int {....gcsafe, extern: "npc$1", raises: [],
                                    tags: [].}
Gets the current column the parser has arrived at.   Source   Edit
proc getLine(c: CfgParser): int {....gcsafe, extern: "npc$1", raises: [], tags: [].}
Gets the current line the parser has arrived at.   Source   Edit
proc getFilename(c: CfgParser): string {....gcsafe, extern: "npc$1", raises: [],
    tags: [].}
Gets the filename of the file that the parser processes.   Source   Edit
proc errorStr(c: CfgParser; msg: string): string {....gcsafe, extern: "npc$1",
    raises: [ValueError], tags: [].}
Returns a properly formatted error message containing current line and column information.   Source   Edit
proc warningStr(c: CfgParser; msg: string): string {....gcsafe, extern: "npc$1",
    raises: [ValueError], tags: [].}
Returns a properly formatted warning message containing current line and column information.   Source   Edit
proc ignoreMsg(c: CfgParser; e: CfgEvent): string {....gcsafe, extern: "npc$1",
    raises: [ValueError], tags: [].}
Returns a properly formatted warning message containing that an entry is ignored.   Source   Edit
proc next(c: var CfgParser): CfgEvent {....gcsafe, extern: "npc$1",
                                        raises: [IOError, OSError, ValueError],
                                        tags: [ReadIOEffect].}
Retrieves the first/next event. This controls the parser.   Source   Edit
proc newConfig(): Config {....raises: [], tags: [].}
Creates a new configuration table. Useful when wanting to create a configuration file.   Source   Edit
proc loadConfig(stream: Stream; filename: string = "[stream]"): Config {.
    ...raises: [IOError, OSError, Exception, ValueError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect].}
Loads the specified configuration from stream into a new Config instance. filename parameter is only used for nicer error messages.   Source   Edit
proc loadConfig(filename: string): Config {.
    ...raises: [IOError, Exception, OSError, ValueError, KeyError],
    tags: [WriteIOEffect, ReadIOEffect, RootEffect].}
Loads the specified configuration file into a new Config instance.   Source   Edit
proc writeConfig(dict: Config; stream: Stream) {....raises: [IOError, OSError],
    tags: [WriteIOEffect].}
Writes the contents of the table to the specified stream.
Note: Comment statement will be ignored.
  Source   Edit
proc `$`(dict: Config): string {....raises: [Exception, IOError, OSError],
                                 tags: [WriteIOEffect].}
Writes the contents of the table to string.
Note: Comment statement will be ignored.
  Source   Edit
proc writeConfig(dict: Config; filename: string) {....raises: [IOError, OSError],
    tags: [WriteIOEffect].}
Writes the contents of the table to the specified configuration file.
Note: Comment statement will be ignored.
  Source   Edit
proc getSectionValue(dict: Config; section, key: string; defaultVal = ""): string {.
    ...raises: [KeyError], tags: [].}
Gets the key value of the specified Section. Returns the specified default value if the specified key does not exist.   Source   Edit
proc setSectionKey(dict: var Config; section, key, value: string) {.
    ...raises: [KeyError], tags: [].}
Sets the Key value of the specified Section.   Source   Edit
proc delSection(dict: var Config; section: string) {....raises: [], tags: [].}
Deletes the specified section and all of its sub keys.   Source   Edit
proc delSectionKey(dict: var Config; section, key: string) {....raises: [KeyError],
    tags: [].}
Deletes the key of the specified section.   Source   Edit

Iterators

iterator sections(dict: Config): lent string {....raises: [], tags: [].}
Iterates through the sections in the dict.   Source   Edit