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

Last change on this file since 25491 was 25491, checked in by evhan, 9 years ago

document parameters

File size: 3.5 KB
Line 
1[[tags: egg]]
2
3== ini-file
4
5[[toc:]]
6
7=== Description
8
9Read & write INI configuration files.
10
11=== Documentation
12
13{{ini-file}} is a small library for reading & writing INI files,
14such as those used in early Windows configuration scripts.
15
16INI syntax as a whole is underspecified and its implementations vary.
17This egg supports only its most basic features (comments, sections,
18zero- and one-valued properties).
19
20==== API
21
22<procedure>(read-property [port])</procedure>
23
24Reads a single INI property from {{port}}. If it is a section header,
25returns a symbol. If it is a property or property/value pair, a pair is
26returned. Invalid properties will signal an error.
27
28Numeric values and quoted strings are read as such; everything else is treated
29as a string literal.
30
31<procedure>(read-ini [file-or-port])</procedure>
32
33Reads configuration directives from {{file-or-port}} until {{#!eof}},
34returning an alist of alists corresponding hierarchically to the
35source INI's SECTION -> PROPERTY -> VALUE structure.
36
37Properties appearing before any section heading are associated
38with the key given by the {{default-section}} parameter.
39
40If {{file-or-port}} is a port, it is not closed.
41
42<procedure>(write-ini alist [file-or-port])</procedure>
43
44Writes {{alist}} as INI directives to {{file-or-port}}.
45
46A symbol at the head of {{alist}} signifies a section of that name.
47The write order of {{alist}}'s properties is reverse that of {{alist}}.
48
49The {{property-separator}} parameter specifies the character or
50string with which to separate property names & values.
51
52If {{file-or-port}} is a port, it is not closed.
53
54==== Parameters
55
56<parameter>(default-section [name])</parameter>
57
58Specifies the default alist key (usually a symbol) under which properties
59without a section label will be placed {{read-ini}}. Defaults to {{'default}}.
60
61<parameter>(property-separator [char-or-string])</parameter>
62
63Specifies the character or string to be used by {{write-ini}} to separate
64property names & values. Defaults to {{#\=}}.
65
66<parameter>(allow-empty-values? [boolean])</parameter>
67
68Specifies whether the empty string should be treated as a valid property value.
69If {{#f}}, an empty value will signal an error. Defaults to {{#f}}.
70
71<parameter>(allow-bare-properties? [boolean])</parameter>
72
73Specifies whether "bare" properties (those without a value) should be allowed.
74If {{#f}}, a line not following "key separator value" format will signal an
75error. Defaults to {{#t}}, making the default parsing behavior very forgiving.
76
77=== Example
78
79Git uses INI syntax for its configuration files. From {{man git-config}}:
80
81    #
82    # This is the config file, and
83    # a '#' or ';' character indicates
84    # a comment
85    #
86   
87    ; core variables
88    [core]
89            ; Don't trust file modes
90            filemode = false
91   
92    ; Our diff algorithm
93    [diff]
94            external = /usr/local/bin/diff-wrapper
95            renames = true
96   
97    ; Proxy settings
98    [core]
99            gitproxy="proxy-command" for kernel.org
100            gitproxy=default-proxy ; for all the rest
101
102    (use ini-file)
103    (read-ini ".git/config")
104    ; => ((core (gitproxy . "default-proxy")
105    ;           (gitproxy . "\"proxy-command\" for kernel.org"))
106    ;     (diff (renames  . "true")
107    ;           (external . "/usr/local/bin/diff-wrapper"))
108    ;     (core (filemode . "false")))
109
110Note that separate sections of the same name are not merged.
111
112=== History
113
114* 0.2 Use regex unit
115* 0.1 Initial release
116
117=== Author
118
119[[Evan Hanson]]
120
121=== License
122
123Copyright (c) 2011 Evan Hanson, 3-Clause BSD.
Note: See TracBrowser for help on using the repository browser.