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

Last change on this file since 36801 was 36801, checked in by evhan, 13 months ago

wiki/eggref: update docs/formatting/urls and eggref/5/{r7rs,fancypants,chicken-belt}

File size: 4.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
20The source for this egg is available at [[https://github.com/kiatoa/ini-file]]
21(previously available at [[https://github.com/evhan/ini-file]]).
22
23==== API
24
25<procedure>(read-property [port])</procedure>
26
27Reads a single INI property from {{port}}. If it is a section header,
28returns a symbol. If it is a property or property/value pair, a pair is
29returned. Invalid properties will signal an error.
30
31Numeric values and quoted strings are read as Scheme data; everything else is
32treated as a string. Any such string mapped by the {{property-value-map}}
33parameter will be replaced by its corresponding value.
34
35<procedure>(read-ini [file-or-port])</procedure>
36
37Reads configuration directives from {{file-or-port}} until {{#!eof}},
38returning an alist of alists corresponding hierarchically to the
39source INI's SECTION -> PROPERTY -> VALUE structure.
40
41Properties appearing before any section heading are associated
42with the key given by the {{default-section}} parameter.
43
44If {{file-or-port}} is a port, it is not closed.
45
46<procedure>(write-ini alist [file-or-port])</procedure>
47
48Writes {{alist}} as INI directives to {{file-or-port}}.
49
50A symbol at the head of {{alist}} signifies a section of that name.
51The write order of sections and properties is reverse that of {{alist}}.
52
53The {{property-separator}} parameter specifies the character or
54string with which to separate property names & values when writing.
55
56The {{property-separator-patt}} parameter specifies the regex speparator pattern
57for which to separate property names & values when reading.
58
59Any value mapped to by the {{property-value-map}} parameter will be
60replaced by its first corresponding key.
61
62If {{file-or-port}} is a port, it is not closed.
63
64==== Parameters
65
66<parameter>(default-section [name])</parameter>
67
68Specifies the default alist key (usually a symbol) under which properties
69without a section label will be placed by {{read-ini}}. Defaults to
70{{'default}}.
71
72<parameter>(property-separator [char-or-string])</parameter>
73
74Specifies the character or string to be used by {{write-ini}} to separate
75property names & values. Defaults to {{#\=}}.
76
77<parameter>(property-separator-patt [string-or-regex])</parameter>
78
79Specifies the string or regex to be used by {{read-ini}} to separate
80property names & values. Defaults to {{" * *"}}.
81
82<parameter>(property-value-map [alist])</parameter>
83
84Specifies an alist mapping strings to Scheme values, used to translate INI
85values to & from Scheme data when reading & writing INI files.
86
87The default map is simply:
88
89    '(("true"  . #t)
90      ("false" . #f))
91
92<parameter>(allow-empty-values? [boolean])</parameter>
93
94Specifies whether the empty string should be treated as a valid property value.
95If {{#f}}, an empty value will signal an error. Defaults to {{#f}}.
96
97<parameter>(allow-bare-properties? [boolean])</parameter>
98
99Specifies whether "bare" properties (those without a value) should be allowed.
100If {{#f}}, a line not following "key separator value" format will signal an
101error. Defaults to {{#f}}.
102
103=== Example
104
105Git uses INI syntax for its configuration files. From {{man git-config}}:
106
107    #
108    # This is the config file, and
109    # a '#' or ';' character indicates
110    # a comment
111    #
112   
113    ; core variables
114    [core]
115            ; Don't trust file modes
116            filemode = false
117   
118    ; Our diff algorithm
119    [diff]
120            external = /usr/local/bin/diff-wrapper
121            renames = true
122   
123    ; Proxy settings
124    [core]
125            gitproxy="proxy-command" for kernel.org
126            gitproxy=default-proxy ; for all the rest
127
128    (use ini-file)
129    (read-ini ".git/config")
130    ; => ((core (gitproxy . "default-proxy")
131    ;           (gitproxy . "\"proxy-command\" for kernel.org"))
132    ;     (diff (renames  . #t)
133    ;           (external . "/usr/local/bin/diff-wrapper"))
134    ;     (core (filemode . #f)))
135
136Note that separate sections of the same name are not merged.
137
138=== History
139
140* 0.3.4 Introduce property-separator-patt
141* 0.3 Introduce property-value-map parameter
142* 0.2 Use regex unit
143* 0.1 Initial release
144
145=== Author
146
147[[/users/evan-hanson|Evan Hanson]]
148
149=== Maintainer
150
151[[https://github.com/kiatoa|Matt Welland]]
152
153=== License
154
1553-Clause BSD
Note: See TracBrowser for help on using the repository browser.