You are looking at historical revision 25150 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).

API

[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.

Numeric values are read as such; everything else is treated as a string literal. Properties appearing before any section heading are placed in an alist under 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 section name (usually a symbol) under which properties without a section label will be placed when read 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 #\=.

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
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
   * Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.
   * The name of the author may not be used to endorse or promote products
     derived from this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.