source: project/wiki/eggref/4/ini-file @ 25491

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

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

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

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

<parameter>(allow-empty-values? [boolean])</parameter>

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

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

* 0.2 Use regex unit
* 0.1 Initial release

=== Author

[[Evan Hanson]]

=== License

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