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

Last change on this file since 30443 was 30443, checked in by svnwiki, 6 years ago

Anonymous wiki edit for IP [184.101.39.119]:

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