chickadee » ini-file

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

read-property #!optional portprocedure

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.

read-ini #!optional file-or-portprocedure

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.

write-ini alist #!optional file-or-portprocedure

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

default-section #!optional nameparameter

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

property-separator #!optional char-or-stringparameter

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

property-separator-patt #!optional string-or-regexparameter

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

property-value-map #!optional alistparameter

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))

allow-empty-values? #!optional booleanparameter

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.

allow-bare-properties? #!optional booleanparameter

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

• 0.3.4 Introduce property-separator-patt
• 0.3 Introduce property-value-map parameter
• 0.2 Use regex unit
• 0.1 Initial release

Author

Evan Hanson

Maintainer

Matt Welland

License

3-Clause BSD