[[tags: egg]]

== ini-file

[[toc:]]

=== 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])</procedure>

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])</procedure>

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])</parameter>

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])</parameter>

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

* 0.1 Initial release

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