| [/ |
| / Copyright (c) 2008 Marcin Kalicinski (kalita <at> poczta dot onet dot pl) |
| / Copyright (c) 2009 Sebastian Redl (sebastian dot redl <at> getdesigned dot at) |
| / |
| / Distributed under the Boost Software License, Version 1.0. (See accompanying |
| / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| /] |
| [section INI Parser] |
| [def __ini__ [@http://en.wikipedia.org/wiki/INI INI format]] |
| The __ini__ was once widely used in the world of Windows. It is now deprecated, |
| but is still used by a surprisingly large number of applications. The reason is |
| probably its simplicity, plus that Microsoft recommends using the registry as |
| a replacement, which not all developers want to do. |
| |
| INI is a simple key-value format with a single level of sectioning. It is thus |
| less rich than the property tree dataset, which means that not all property |
| trees can be serialized as INI files. |
| |
| The INI parser creates a tree node for every section, and a child node for |
| every property in that section. All properties not in a section are directly |
| added to the root node. Empty sections are ignored. (They don't round-trip, as |
| described below.) |
| |
| The INI serializer reverses this process. It first writes out every child of the |
| root that contains data, but no child nodes, as properties. Then it creates a |
| section for every child that contains child nodes, but no data. The children of |
| the sections must only contain data. It is an error if the root node contains |
| data, or any child of the root contains both data and content, or there's more |
| than three levels of hierarchy. There must also not be any duplicate keys. |
| |
| An empty tree node is assumed to be an empty property. There is no way to create |
| empty sections. |
| |
| Since the Windows INI parser discards trailing spaces and does not support |
| quoting, the property tree parser follows this example. This means that |
| property values containing trailing spaces do not round-trip. |
| [endsect] [/ini_parser] |