[[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).
The source for this egg is available at [[http://github.com/evhan/ini-file]].
==== API
(read-property [port])
Reads a single INI property from {{file-or-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.
(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.
(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
(default-section [name])
Specifies the default alist key (usually a symbol) under which properties
without a section label will be placed {{read-ini}}. Defaults to {{'default}}.
(property-separator [char-or-string])
Specifies the character or string to be used by {{write-ini}} to separate
property names & values. Defaults to {{#\=}}.
(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}}.
(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 {{#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.