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>Five Minute Tutorial</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="../property_tree.html" title="Chapter 31. Boost.PropertyTree"> 11<link rel="next" href="container.html" title="Property Tree as a Container"> 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="../property_tree.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="container.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.tutorial"></a><a class="link" href="tutorial.html" title="Five Minute Tutorial">Five Minute Tutorial</a> 29</h2></div></div></div> 30<p> 31 This tutorial uses XML. Note that the library is not specifically bound to 32 XML, and any other supported format (such as INI or JSON) could be used instead. 33 XML was chosen because the author thinks that a wide range of people is familiar 34 with it. 35 </p> 36<p> 37 Suppose we are writing a logging system for some application, and need to read 38 log configuration from a file when the program starts. The file with the log 39 configuration looks like this: 40 </p> 41<pre class="programlisting"><debug> 42 <filename>debug.log</filename> 43 <modules> 44 <module>Finance</module> 45 <module>Admin</module> 46 <module>HR</module> 47 </modules> 48 <level>2</level> 49</debug> 50</pre> 51<p> 52 It contains the log filename, a list of modules where logging is enabled, and 53 the debug level value. 54 </p> 55<p> 56 First we need some includes: 57 </p> 58<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">property_tree</span><span class="special">/</span><span class="identifier">ptree</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 59<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">property_tree</span><span class="special">/</span><span class="identifier">xml_parser</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 60<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">foreach</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 61<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> 62<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">set</span><span class="special">></span> 63<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">exception</span><span class="special">></span> 64<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 65<span class="keyword">namespace</span> <span class="identifier">pt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">property_tree</span><span class="special">;</span> 66</pre> 67<p> 68 To store the logging configuration in the program we create a debug_settings 69 structure: 70 </p> 71<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">debug_settings</span> 72<span class="special">{</span> 73 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">m_file</span><span class="special">;</span> <span class="comment">// log filename</span> 74 <span class="keyword">int</span> <span class="identifier">m_level</span><span class="special">;</span> <span class="comment">// debug level</span> 75 <span class="identifier">std</span><span class="special">::</span><span class="identifier">set</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">m_modules</span><span class="special">;</span> <span class="comment">// modules where logging is enabled</span> 76 <span class="keyword">void</span> <span class="identifier">load</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&</span><span class="identifier">filename</span><span class="special">);</span> 77 <span class="keyword">void</span> <span class="identifier">save</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&</span><span class="identifier">filename</span><span class="special">);</span> 78<span class="special">};</span> 79</pre> 80<p> 81 All that needs to be done now is to write implementations of load() and save() 82 member functions. Let's first deal with load(). It contains just 7 lines of 83 code, although it does all the necessary things, including error reporting: 84 </p> 85<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">debug_settings</span><span class="special">::</span><span class="identifier">load</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&</span><span class="identifier">filename</span><span class="special">)</span> 86<span class="special">{</span> 87 <span class="comment">// Create empty property tree object</span> 88 <span class="identifier">pt</span><span class="special">::</span><span class="identifier">ptree</span> <span class="identifier">tree</span><span class="special">;</span> 89 90 <span class="comment">// Parse the XML into the property tree.</span> 91 <span class="identifier">pt</span><span class="special">::</span><span class="identifier">read_xml</span><span class="special">(</span><span class="identifier">filename</span><span class="special">,</span> <span class="identifier">tree</span><span class="special">);</span> 92 93 <span class="comment">// Use the throwing version of get to find the debug filename.</span> 94 <span class="comment">// If the path cannot be resolved, an exception is thrown.</span> 95 <span class="identifier">m_file</span> <span class="special">=</span> <span class="identifier">tree</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">>(</span><span class="string">"debug.filename"</span><span class="special">);</span> 96 97 <span class="comment">// Use the default-value version of get to find the debug level.</span> 98 <span class="comment">// Note that the default value is used to deduce the target type.</span> 99 <span class="identifier">m_level</span> <span class="special">=</span> <span class="identifier">tree</span><span class="special">.</span><span class="identifier">get</span><span class="special">(</span><span class="string">"debug.level"</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span> 100 101 <span class="comment">// Use get_child to find the node containing the modules, and iterate over</span> 102 <span class="comment">// its children. If the path cannot be resolved, get_child throws.</span> 103 <span class="comment">// A C++11 for-range loop would also work.</span> 104 <span class="identifier">BOOST_FOREACH</span><span class="special">(</span><span class="identifier">pt</span><span class="special">::</span><span class="identifier">ptree</span><span class="special">::</span><span class="identifier">value_type</span> <span class="special">&</span><span class="identifier">v</span><span class="special">,</span> <span class="identifier">tree</span><span class="special">.</span><span class="identifier">get_child</span><span class="special">(</span><span class="string">"debug.modules"</span><span class="special">))</span> <span class="special">{</span> 105 <span class="comment">// The data function is used to access the data stored in a node.</span> 106 <span class="identifier">m_modules</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">second</span><span class="special">.</span><span class="identifier">data</span><span class="special">());</span> 107 <span class="special">}</span> 108 109<span class="special">}</span> 110</pre> 111<p> 112 Now the save() function. It is also 7 lines of code: 113 </p> 114<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">debug_settings</span><span class="special">::</span><span class="identifier">save</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&</span><span class="identifier">filename</span><span class="special">)</span> 115<span class="special">{</span> 116 <span class="comment">// Create an empty property tree object.</span> 117 <span class="identifier">pt</span><span class="special">::</span><span class="identifier">ptree</span> <span class="identifier">tree</span><span class="special">;</span> 118 119 <span class="comment">// Put the simple values into the tree. The integer is automatically</span> 120 <span class="comment">// converted to a string. Note that the "debug" node is automatically</span> 121 <span class="comment">// created if it doesn't exist.</span> 122 <span class="identifier">tree</span><span class="special">.</span><span class="identifier">put</span><span class="special">(</span><span class="string">"debug.filename"</span><span class="special">,</span> <span class="identifier">m_file</span><span class="special">);</span> 123 <span class="identifier">tree</span><span class="special">.</span><span class="identifier">put</span><span class="special">(</span><span class="string">"debug.level"</span><span class="special">,</span> <span class="identifier">m_level</span><span class="special">);</span> 124 125 <span class="comment">// Add all the modules. Unlike put, which overwrites existing nodes, add</span> 126 <span class="comment">// adds a new node at the lowest level, so the "modules" node will have</span> 127 <span class="comment">// multiple "module" children.</span> 128 <span class="identifier">BOOST_FOREACH</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">m_modules</span><span class="special">)</span> 129 <span class="identifier">tree</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="string">"debug.modules.module"</span><span class="special">,</span> <span class="identifier">name</span><span class="special">);</span> 130 131 <span class="comment">// Write property tree to XML file</span> 132 <span class="identifier">pt</span><span class="special">::</span><span class="identifier">write_xml</span><span class="special">(</span><span class="identifier">filename</span><span class="special">,</span> <span class="identifier">tree</span><span class="special">);</span> 133<span class="special">}</span> 134</pre> 135<p> 136 The full program <a href="../../../libs/property_tree/examples/debug_settings.cpp" target="_top">debug_settings.cpp</a> 137 is included in the examples directory. 138 </p> 139</div> 140<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 141<td align="left"></td> 142<td align="right"><div class="copyright-footer">Copyright © 2008-2010 Marcin Kalicinski<br>Copyright © 2010-2013 Sebastian 143 Redl<p> 144 Distributed under the Boost Software License, Version 1.0. (See accompanying 145 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>) 146 </p> 147</div></td> 148</tr></table> 149<hr> 150<div class="spirit-nav"> 151<a accesskey="p" href="../property_tree.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="container.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 152</div> 153</body> 154</html> 155
