1 # `ini` - Read and write INI configuration files
3 [INI files](https://en.wikipedia.org/wiki/INI_file) are simple text files with
4 a basic structure composed of sections, properties and values used to store
5 configuration parameters.
7 Here's an example from the `package.ini` of this package:
15 desc=Read and write INI configuration files.
17 git=https://github.com/nitlang/nit.git
18 git.directory=lib/ini/
24 `IniFile` is used to parse INI strings and access their content:
27 var ini = new IniFile.from_string(package_ini)
28 assert ini["package.name"] == "ini"
29 assert ini["upstream.git.directory"] == "lib/ini/"
30 assert ini["unknown.unknown"] == null
33 `IniFile` can also load INI configuration from a file:
36 package_ini.write_to_file("my_package.ini")
38 ini = new IniFile.from_file("my_package.ini")
39 assert ini["package.name"] == "ini"
40 assert ini["upstream.git.directory"] == "lib/ini/"
42 "my_package.ini".to_path.delete
45 INI content can be added or edited through the `IniFile` API then written to
49 ini["package.name"] = "new name"
50 ini["upstream.git.directory"] = "/dev/null"
51 ini["section.key"] = "value"
53 var stream = new StringWriter
56 assert stream.to_s == """
59 desc=Read and write INI configuration files.
61 git=https://github.com/nitlang/nit.git
62 git.directory=/dev/null
72 Properties are the basic element of the INI format.
73 Every property correspond to a *key* associated to a *value* thanks to the equal (`=`) sign.
76 ini = new IniFile.from_string("""
80 assert ini["key1"] == "value1"
81 assert ini["key2"] == "value2"
82 assert ini.length == 2
85 Accessing an unknown property returns `null`:
88 assert ini["unknown"] == null
91 Properties can be iterated over:
95 for key, value in ini do
96 assert key == "key{i}"
97 assert value == "value{i}"
102 Property keys cannot contain the character `=`.
103 Values can contain any character.
107 ini = new IniFile.from_string("""
110 property3=value3 ; with semicolon
112 assert ini[";property1"] == null
113 assert ini["prop=erty1"] == null
114 assert ini["prop"] == "erty1=value1"
115 assert ini["property2"] == "value2"
116 assert ini[" property2 "] == "value2"
117 assert ini["property3"] == "value3 ; with semicolon"
120 Both keys and values are case sensitive.
123 ini = new IniFile.from_string("""
127 assert ini["property1"] == null
128 assert ini["Property1"] == "value1"
129 assert ini["property2"] != "value2"
130 assert ini["property2"] == "Value2"
135 Properties may be grouped into arbitrary sections.
136 The section name appears on a line by itself between square brackets (`[` and `]`).
138 All keys after the section declaration are associated with that section.
139 The is no explicit "end of section" delimiter; sections end at the next section
140 declaration or the end of the file.
141 Sections cannot be nested.
154 ini = new IniFile.from_string(content)
155 assert ini["key1"] == "value1"
156 assert ini["unknown"] == null
157 assert ini["section1.key1"] == "value3"
158 assert ini["section1.unknown"] == null
159 assert ini["section2.key1"] == "value5"
162 Sections can be iterated over:
166 for section in ini.sections do
167 assert section.name == "section{i}"
168 assert section["key1"].has_prefix("value")
173 When iterating over a file properties, only properties at root are returned.
174 `flatten` can be used to iterate over all properties including the one from
178 assert ini.join(", ", ": ") == "key1: value1, key2: value2"
179 assert ini.flatten.join(", ", ": ") ==
180 "key1: value1, key2: value2, section1.key1: value3, section1.key2: value4, section2.key1: value5"
183 for key, value in ini do
185 assert key == "key{i}" and value == "value{i}"
191 Sections name may contain any character including brackets (`[` and `]`).
195 ini = new IniFile.from_string("""
203 assert ini.sections.length == 3
204 assert ini["[section1].key"] == "value1"
205 assert ini["section 2.key"] == "value2"
206 assert ini["section1.section3.key"] == "value3"
207 assert ini.sections.last.name == "section1.section3"
210 The dot `.` notation is used to create new sections with `[]=`.
211 Unknown sections will be created on the fly.
215 ini["key"] = "value1"
216 ini["section1.key"] = "value2"
217 ini["section2.key"] = "value3"
219 stream = new StringWriter
221 assert stream.to_s == """
230 Sections can also be created manually:
234 ini["key"] = "value1"
236 var section = new IniSection("section1")
237 section["key"] = "value2"
238 ini.sections.add section
240 stream = new StringWriter
242 assert stream.to_s == """
251 Comments are indicated by semicolon (`;`) or a number sign (`#`) at the begining
252 of the line. Commented lines are ignored as well as empty lines.
255 ini = new IniFile.from_string("""
259 # This is another comment.
267 INI files support Unicode:
270 ini = new IniFile.from_string("""
273 assert ini["property❤"] == "héhé"
278 By default `IniFile` does not stop when it cannot parse a line in a string (loaded
279 by `from_string` or `load_string`) or a file (loaded by `from_file` or `load_file`).
282 ini = new IniFile.from_string("""
288 assert ini.length == 2
289 assert ini["key1"] == "value1"
290 assert ini["key2"] == null
291 assert ini["key3"] == "value3"
295 This behaviour can be modified by setting `stop_on_first_error` to `true`.
298 ini = new IniFile.from_string("""
302 """, stop_on_first_error = true)
304 assert ini.length == 1
305 assert ini["key1"] == "value1"
306 assert ini["key2"] == null
307 assert ini["key3"] == null
310 Wathever the value set for `stop_on_first_error`, errors can be checked thanks
311 to the `errors` array:
314 assert ini.errors.length == 1
315 assert ini.errors.first.message == "Unexpected string `key2` at line 2."