You are looking at historical revision 25505 of this page. It may differ significantly from its current revision.

ini-file

Description

Read & write INI configuration files.

Documentation

ini-file is a small library for reading & writing INI files, such as those used in early Windows configuration scripts.

INI syntax as a whole is underspecified and its implementations vary. This egg supports only its most basic features (comments, sections, zero- and one-valued properties).

The source for this egg is available at http://github.com/evhan/ini-file.

API

[procedure] (read-property [port])

Reads a single INI property from port. If it is a section header, returns a symbol. If it is a property or property/value pair, a pair is returned. Invalid properties will signal an error.

Numeric values and quoted strings are read as such; everything else is treated as a string literal.

[procedure] (read-ini [file-or-port])

Reads configuration directives from file-or-port until #!eof, returning an alist of alists corresponding hierarchically to the source INI's SECTION -> PROPERTY -> VALUE structure.

Properties appearing before any section heading are associated with the key given by the default-section parameter.

If file-or-port is a port, it is not closed.

[procedure] (write-ini alist [file-or-port])

Writes alist as INI directives to file-or-port.

A symbol at the head of alist signifies a section of that name. The write order of alist's properties is reverse that of alist.

The property-separator parameter specifies the character or string with which to separate property names & values.

If file-or-port is a port, it is not closed.

Parameters

[parameter] (default-section [name])

Specifies the default alist key (usually a symbol) under which properties without a section label will be placed read-ini. Defaults to 'default.

[parameter] (property-separator [char-or-string])

Specifies the character or string to be used by write-ini to separate property names & values. Defaults to #\=.

[parameter] (allow-empty-values? [boolean])

Specifies whether the empty string should be treated as a valid property value. If #f, an empty value will signal an error. Defaults to #f.

[parameter] (allow-bare-properties? [boolean])

Specifies whether "bare" properties (those without a value) should be allowed. If #f, a line not following "key separator value" format will signal an error. Defaults to #t, making the default parsing behavior very forgiving.

Example

Git uses INI syntax for its configuration files. From man git-config:

   #
   # This is the config file, and
   # a '#' or ';' character indicates
   # a comment
   #
   
   ; core variables
   [core]
           ; Don't trust file modes
           filemode = false
   
   ; Our diff algorithm
   [diff]
           external = /usr/local/bin/diff-wrapper
           renames = true
   
   ; Proxy settings
   [core]
           gitproxy="proxy-command" for kernel.org
           gitproxy=default-proxy ; for all the rest

   (use ini-file)
   (read-ini ".git/config")
   ; => ((core (gitproxy . "default-proxy")
   ;           (gitproxy . "\"proxy-command\" for kernel.org"))
   ;     (diff (renames  . "true")
   ;           (external . "/usr/local/bin/diff-wrapper"))
   ;     (core (filemode . "false")))

Note that separate sections of the same name are not merged.

History

Author

Evan Hanson

License

Copyright (c) 2011 Evan Hanson, 3-Clause BSD.