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

Last change on this file since 25150 was 25150, checked in by evhan, 10 years ago

replace AWOL ini-file docs

File size: 4.1 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-ini [file-or-port])</procedure>
23
24Reads configuration directives from {{file-or-port}} until {{#!eof}},
25returning an alist of alists corresponding hierarchically to the
26source INI's SECTION -> PROPERTY -> VALUE structure.
27
28Numeric values are read as such; everything else is treated
29as a string literal. Properties appearing before any section
30heading are placed in an alist under the key given by the
31{{default-section}} parameter.
32
33If {{file-or-port}} is a port, it is not closed.
34
35<procedure>(write-ini alist [file-or-port])</procedure>
36
37Writes {{alist}} as INI directives to {{file-or-port}}.
38
39A symbol at the head of {{alist}} signifies a section of that name.
40The write order of {{alist}}'s properties is reverse that of {{alist}}.
41
42The {{property-separator}} parameter specifies the character or
43string with which to separate property names & values.
44
45If {{file-or-port}} is a port, it is not closed.
46
47==== Parameters
48
49<parameter>(default-section [name])</parameter>
50
51Specifies the default section name (usually a symbol) under
52which properties without a section label will be placed when read
53by {{read-ini}}. Defaults to {{'default}}.
54
55<parameter>(property-separator [char-or-string])</parameter>
56
57Specifies the character or string to be used by {{write-ini}}
58to separate property names & values. Defaults to {{#\=}}.
59
60=== Example
61
62Git uses INI syntax for its configuration files. From {{man git-config}}:
63
64    #
65    # This is the config file, and
66    # a '#' or ';' character indicates
67    # a comment
68    #
69   
70    ; core variables
71    [core]
72            ; Don't trust file modes
73            filemode = false
74   
75    ; Our diff algorithm
76    [diff]
77            external = /usr/local/bin/diff-wrapper
78            renames = true
79   
80    ; Proxy settings
81    [core]
82            gitproxy="proxy-command" for kernel.org
83            gitproxy=default-proxy ; for all the rest
84
85    (use ini-file)
86    (read-ini ".git/config")
87    ; => ((core (gitproxy . "default-proxy")
88    ;           (gitproxy . "\"proxy-command\" for kernel.org"))
89    ;     (diff (renames  . "true")
90    ;           (external . "/usr/local/bin/diff-wrapper"))
91    ;     (core (filemode . "false")))
92
93Note that separate sections of the same name are not merged.
94
95=== History
96
97* 0.1 Initial release
98
99=== Author
100
101Evan Hanson
102
103=== License
104
105  Copyright (c) 2011, Evan Hanson
106  All rights reserved.
107 
108  Redistribution and use in source and binary forms, with or without
109  modification, are permitted provided that the following conditions
110  are met:
111 
112    * Redistributions of source code must retain the above copyright
113      notice, this list of conditions and the following disclaimer.
114    * Redistributions in binary form must reproduce the above copyright
115      notice, this list of conditions and the following disclaimer in the
116      documentation and/or other materials provided with the distribution.
117    * The name of the author may not be used to endorse or promote products
118      derived from this software without specific prior written permission.
119 
120  THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
121  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
122  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
123  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
124  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
125  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
126  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
127  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
128  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
129  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.