1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>How to Populate a Property Tree</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../property_tree.html" title="Chapter 31. Boost.PropertyTree"> 10<link rel="prev" href="synopsis.html" title="Property Tree Synopsis"> 11<link rel="next" href="accessing.html" title="How to Access Data in a Property Tree"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="synopsis.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../property_tree.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="accessing.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="property_tree.parsers"></a><a class="link" href="parsers.html" title="How to Populate a Property Tree">How to Populate a Property Tree</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="parsers.html#property_tree.parsers.xml_parser">XML Parser</a></span></dt> 32<dt><span class="section"><a href="parsers.html#property_tree.parsers.json_parser">JSON Parser</a></span></dt> 33<dt><span class="section"><a href="parsers.html#property_tree.parsers.ini_parser">INI Parser</a></span></dt> 34<dt><span class="section"><a href="parsers.html#property_tree.parsers.info_parser">INFO Parser</a></span></dt> 35</dl></div> 36<div class="section"> 37<div class="titlepage"><div><div><h3 class="title"> 38<a name="property_tree.parsers.xml_parser"></a><a class="link" href="parsers.html#property_tree.parsers.xml_parser" title="XML Parser">XML Parser</a> 39</h3></div></div></div> 40<p> 41 The <a href="http://en.wikipedia.org/wiki/XML" target="_top">XML format</a> is an 42 industry standard for storing information in textual form. Unfortunately, 43 there is no XML parser in <a href="http://www.boost.org" target="_top">Boost</a> 44 as of the time of this writing. The library therefore contains the fast and 45 tiny <a href="http://rapidxml.sourceforge.net/" target="_top">RapidXML</a> parser 46 (currently in version 1.13) to provide XML parsing support. RapidXML does 47 not fully support the XML standard; it is not capable of parsing DTDs and 48 therefore cannot do full entity substitution. 49 </p> 50<p> 51 By default, the parser will preserve most whitespace, but remove element 52 content that consists only of whitespace. Encoded whitespaces (e.g. &#32;) 53 does not count as whitespace in this regard. You can pass the trim_whitespace 54 flag if you want all leading and trailing whitespace trimmed and all continuous 55 whitespace collapsed into a single space. 56 </p> 57<p> 58 Please note that RapidXML does not understand the encoding specification. 59 If you pass it a character buffer, it assumes the data is already correctly 60 encoded; if you pass it a filename, it will read the file using the character 61 conversion of the locale you give it (or the global locale if you give it 62 none). This means that, in order to parse a UTF-8-encoded XML file into a 63 wptree, you have to supply an alternate locale, either directly or by replacing 64 the global one. 65 </p> 66<p> 67 XML / property tree conversion schema (<code class="computeroutput"><a class="link" href="../boost/property_tree/xml_parser/read__1_3_32_10_11_1_1_1_1.html" title="Function template read_xml">read_xml</a></code> 68 and <code class="computeroutput"><a class="link" href="../boost/property_tree/xml_parser/write_1_3_32_10_11_1_1_1_3.html" title="Function template write_xml">write_xml</a></code>): 69 </p> 70<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 71<li class="listitem"> 72 Each XML element corresponds to a property tree node. The child elements 73 correspond to the children of the node. 74 </li> 75<li class="listitem"> 76 The attributes of an XML element are stored in the subkey <code class="literal"><xmlattr></code>. 77 There is one child node per attribute in the attribute node. Existence 78 of the <code class="literal"><xmlattr></code> node is not guaranteed or necessary 79 when there are no attributes. 80 </li> 81<li class="listitem"> 82 XML comments are stored in nodes named <code class="literal"><xmlcomment></code>, 83 unless comment ignoring is enabled via the flags. 84 </li> 85<li class="listitem"> 86 Text content is stored in one of two ways, depending on the flags. The 87 default way concatenates all text nodes and stores them as the data of 88 the element node. This way, the entire content can be conveniently read, 89 but the relative ordering of text and child elements is lost. The other 90 way stores each text content as a separate node, all called <code class="literal"><xmltext></code>. 91 </li> 92</ul></div> 93<p> 94 The XML storage encoding does not round-trip perfectly. A read-write cycle 95 loses trimmed whitespace, low-level formatting information, and the distinction 96 between normal data and CDATA nodes. Comments are only preserved when enabled. 97 A write-read cycle loses trimmed whitespace; that is, if the origin tree 98 has string data that starts or ends with whitespace, that whitespace is lost. 99 </p> 100</div> 101<div class="section"> 102<div class="titlepage"><div><div><h3 class="title"> 103<a name="property_tree.parsers.json_parser"></a><a class="link" href="parsers.html#property_tree.parsers.json_parser" title="JSON Parser">JSON Parser</a> 104</h3></div></div></div> 105<p> 106 The <a href="http://en.wikipedia.org/wiki/JSON" target="_top">JSON format</a> is 107 a data interchange format derived from the object literal notation of JavaScript. 108 (JSON stands for JavaScript Object Notation.) JSON is a simple, compact format 109 for loosely structured node trees of any depth, very similar to the property 110 tree dataset. It is less structured than XML and has no schema support, but 111 has the advantage of being simpler, smaller and typed without the need for 112 a complex schema. 113 </p> 114<p> 115 The property tree dataset is not typed, and does not support arrays as such. 116 Thus, the following JSON / property tree mapping is used: 117 </p> 118<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 119<li class="listitem"> 120 JSON objects are mapped to nodes. Each property is a child node. 121 </li> 122<li class="listitem"> 123 JSON arrays are mapped to nodes. Each element is a child node with an 124 empty name. If a node has both named and unnamed child nodes, it cannot 125 be mapped to a JSON representation. 126 </li> 127<li class="listitem"> 128 JSON values are mapped to nodes containing the value. However, all type 129 information is lost; numbers, as well as the literals "null", 130 "true" and "false" are simply mapped to their string 131 form. 132 </li> 133<li class="listitem"> 134 Property tree nodes containing both child nodes and data cannot be mapped. 135 </li> 136</ul></div> 137<p> 138 JSON round-trips, except for the type information loss. 139 </p> 140<p> 141 For example this JSON: 142 </p> 143<pre class="programlisting"><span class="special">{</span> 144 <span class="string">"menu"</span><span class="special">:</span> 145 <span class="special">{</span> 146 <span class="string">"foo"</span><span class="special">:</span> <span class="keyword">true</span><span class="special">,</span> 147 <span class="string">"bar"</span><span class="special">:</span> <span class="string">"true"</span><span class="special">,</span> 148 <span class="string">"value"</span><span class="special">:</span> <span class="number">102.3E+06</span><span class="special">,</span> 149 <span class="string">"popup"</span><span class="special">:</span> 150 <span class="special">[</span> 151 <span class="special">{</span><span class="string">"value"</span><span class="special">:</span> <span class="string">"New"</span><span class="special">,</span> <span class="string">"onclick"</span><span class="special">:</span> <span class="string">"CreateNewDoc()"</span><span class="special">},</span> 152 <span class="special">{</span><span class="string">"value"</span><span class="special">:</span> <span class="string">"Open"</span><span class="special">,</span> <span class="string">"onclick"</span><span class="special">:</span> <span class="string">"OpenDoc()"</span><span class="special">},</span> 153 <span class="special">]</span> 154 <span class="special">}</span> 155<span class="special">}</span> 156</pre> 157<p> 158 will be translated into the following property tree: 159 </p> 160<pre class="programlisting"><span class="identifier">menu</span> 161<span class="special">{</span> 162 <span class="identifier">foo</span> <span class="keyword">true</span> 163 <span class="identifier">bar</span> <span class="keyword">true</span> 164 <span class="identifier">value</span> <span class="number">102.3E+06</span> 165 <span class="identifier">popup</span> 166 <span class="special">{</span> 167 <span class="string">""</span> 168 <span class="special">{</span> 169 <span class="identifier">value</span> <span class="identifier">New</span> 170 <span class="identifier">onclick</span> <span class="identifier">CreateNewDoc</span><span class="special">()</span> 171 <span class="special">}</span> 172 <span class="string">""</span> 173 <span class="special">{</span> 174 <span class="identifier">value</span> <span class="identifier">Open</span> 175 <span class="identifier">onclick</span> <span class="identifier">OpenDoc</span><span class="special">()</span> 176 <span class="special">}</span> 177 <span class="special">}</span> 178<span class="special">}</span> 179</pre> 180</div> 181<div class="section"> 182<div class="titlepage"><div><div><h3 class="title"> 183<a name="property_tree.parsers.ini_parser"></a><a class="link" href="parsers.html#property_tree.parsers.ini_parser" title="INI Parser">INI Parser</a> 184</h3></div></div></div> 185<p> 186 The <a href="http://en.wikipedia.org/wiki/INI" target="_top">INI format</a> was 187 once widely used in the world of Windows. It is now deprecated, but is still 188 used by a surprisingly large number of applications. The reason is probably 189 its simplicity, plus that Microsoft recommends using the registry as a replacement, 190 which not all developers want to do. 191 </p> 192<p> 193 INI is a simple key-value format with a single level of sectioning. It is 194 thus less rich than the property tree dataset, which means that not all property 195 trees can be serialized as INI files. 196 </p> 197<p> 198 The INI parser creates a tree node for every section, and a child node for 199 every property in that section. All properties not in a section are directly 200 added to the root node. Empty sections are ignored. (They don't round-trip, 201 as described below.) 202 </p> 203<p> 204 The INI serializer reverses this process. It first writes out every child 205 of the root that contains data, but no child nodes, as properties. Then it 206 creates a section for every child that contains child nodes, but no data. 207 The children of the sections must only contain data. It is an error if the 208 root node contains data, or any child of the root contains both data and 209 content, or there's more than three levels of hierarchy. There must also 210 not be any duplicate keys. 211 </p> 212<p> 213 An empty tree node is assumed to be an empty property. There is no way to 214 create empty sections. 215 </p> 216<p> 217 Since the Windows INI parser discards trailing spaces and does not support 218 quoting, the property tree parser follows this example. This means that property 219 values containing trailing spaces do not round-trip. 220 </p> 221</div> 222<div class="section"> 223<div class="titlepage"><div><div><h3 class="title"> 224<a name="property_tree.parsers.info_parser"></a><a class="link" href="parsers.html#property_tree.parsers.info_parser" title="INFO Parser">INFO Parser</a> 225</h3></div></div></div> 226<p> 227 The INFO format was created specifically for the property tree library. It 228 provides a simple, efficient format that can be used to serialize property 229 trees that are otherwise only stored in memory. It can also be used for any 230 other purpose, although the lack of widespread existing use may prove to 231 be an impediment. 232 </p> 233<p> 234 INFO provides several features that make it familiar to C++ programmers and 235 efficient for medium-sized datasets, especially those used for test input. 236 It supports C-style character escapes, nesting via curly braces, and file 237 inclusion via #include. 238 </p> 239<p> 240 INFO is also used for visualization of property trees in this documentation. 241 </p> 242<p> 243 A typical INFO file might look like this: 244 </p> 245<pre class="programlisting"><span class="identifier">key1</span> <span class="identifier">value1</span> 246<span class="identifier">key2</span> 247<span class="special">{</span> 248 <span class="identifier">key3</span> <span class="identifier">value3</span> 249 <span class="special">{</span> 250 <span class="identifier">key4</span> <span class="string">"value4 with spaces"</span> 251 <span class="special">}</span> 252 <span class="identifier">key5</span> <span class="identifier">value5</span> 253<span class="special">}</span> 254</pre> 255<p> 256 Here's a more complicated file demonstrating all of INFO's features: 257 </p> 258<pre class="programlisting"><span class="special">;</span> <span class="identifier">A</span> <span class="identifier">comment</span> 259<span class="identifier">key1</span> <span class="identifier">value1</span> <span class="special">;</span> <span class="identifier">Another</span> <span class="identifier">comment</span> 260<span class="identifier">key2</span> <span class="string">"value with special characters in it {};#\n\t\"\0"</span> 261<span class="special">{</span> 262 <span class="identifier">subkey</span> <span class="string">"value split "</span><span class="special">\</span> 263 <span class="string">"over three"</span><span class="special">\</span> 264 <span class="string">"lines"</span> 265 <span class="special">{</span> 266 <span class="identifier">a_key_without_value</span> <span class="string">""</span> 267 <span class="string">"a key with special characters in it {};#\n\t\"\0"</span> <span class="string">""</span> 268 <span class="string">""</span> <span class="identifier">value</span> <span class="special">;</span> <span class="identifier">Empty</span> <span class="identifier">key</span> <span class="identifier">with</span> <span class="identifier">a</span> <span class="identifier">value</span> 269 <span class="string">""</span> <span class="string">""</span> <span class="special">;</span> <span class="identifier">Empty</span> <span class="identifier">key</span> <span class="identifier">with</span> <span class="identifier">empty</span> <span class="identifier">value</span><span class="special">!</span> 270 <span class="special">}</span> 271<span class="special">}</span> 272<span class="preprocessor">#include</span> <span class="string">"file.info"</span> <span class="special">;</span> <span class="identifier">included</span> <span class="identifier">file</span> 273</pre> 274<p> 275 INFO round-trips except for the loss of comments and include directives. 276 </p> 277</div> 278</div> 279<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 280<td align="left"></td> 281<td align="right"><div class="copyright-footer">Copyright © 2008-2010 Marcin Kalicinski<br>Copyright © 2010-2013 Sebastian 282 Redl<p> 283 Distributed under the Boost Software License, Version 1.0. (See accompanying 284 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 285 </p> 286</div></td> 287</tr></table> 288<hr> 289<div class="spirit-nav"> 290<a accesskey="p" href="synopsis.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../property_tree.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="accessing.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 291</div> 292</body> 293</html> 294
