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

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

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 https://github.com/kiatoa/ini-file (previously available at https://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 Scheme data; everything else is treated as a string. Any such string mapped by the property-value-map parameter will be replaced by its corresponding value.

[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 sections and properties is reverse that of alist.

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

The property-separator-patt parameter specifies the regex speparator pattern for which to separate property names & values when reading.

Any value mapped to by the property-value-map parameter will be replaced by its first corresponding key.

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 by 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] (property-separator-patt [string-or-regex])

Specifies the string or regex to be used by read-ini to separate property names & values. Defaults to " * *".

[parameter] (property-value-map [alist])

Specifies an alist mapping strings to Scheme values, used to translate INI values to & from Scheme data when reading & writing INI files.

The default map is simply:

   '(("true"  . #t)
     ("false" . #f))
[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 #f.

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  . #t)
   ;           (external . "/usr/local/bin/diff-wrapper"))
   ;     (core (filemode . #f)))

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

History

Author

Evan Hanson

Maintainer

Matt Welland

License

3-Clause BSD