This tutorial uses XML. Note that the library is not specifically bound to XML, and any other supported format (such as INI or JSON) could be used instead. XML was chosen because the author thinks that wide range of people is familiar with it.

Suppose we are writing a logging system for some application, and need to read log configuration from a file when the program starts. The file with the log configuration looks like this:

<debug>
    <filename>debug.log</filename>
    <modules>
        <module>Finance</module>
        <module>Admin</module>
        <module>HR</module>
    </modules>
    <level>2</level>
</debug>

It contains the log filename, a list of modules where logging is enabled, and the debug level value. To store the logging configuration in the program we created a debug_settings structure:

struct debug_settings
{
    std::string m_file;          // log filename
    int m_level;                 // debug level
    std::set<string> m_modules;  // modules where logging is enabled
    void load(const std::string &filename);
    void save(const std::string &filename);
};

All that needs to be done now is to write implementations of load() and save() member functions. Let's first deal with load(). It contains just 7 lines of code, although it does all the necessary things, including error reporting:

#include <boost/property_tree/ptree.hpp>
#include <boost/property_tree/xml_parser.hpp>

// Loads debug_settings structure from the specified XML file
void debug_settings::load(const std::string &filename)
{
    // Create an empty property tree object
    using boost::property_tree::ptree;
    ptree pt;

    // Load the XML file into the property tree. If reading fails
    // (cannot open file, parse error), an exception is thrown.
    read_xml(filename, pt);

    // Get the filename and store it in the m_file variable.
    // Note that we construct the path to the value by separating
    // the individual keys with dots. If dots appear in the keys,
    // a path type with a different separator can be used.
    // If the debug.filename key is not found, an exception is thrown.
    m_file = pt.get<std::string>("debug.filename");

    // Get the debug level and store it in the m_level variable.
    // This is another version of the get method: if the value is
    // not found, the default value (specified by the second
    // parameter) is returned instead. The type of the value
    // extracted is determined by the type of the second parameter,
    // so we can simply write get(...) instead of get<int>(...).
    m_level = pt.get("debug.level", 0);

    // Iterate over the debug.modules section and store all found
    // modules in the m_modules set. The get_child() function
    // returns a reference to the child at the specified path; if
    // there is no such child, it throws. Property tree iterators
    // are models of BidirectionalIterator.
    BOOST_FOREACH(ptree::value_type &v,
            pt.get_child("debug.modules"))
        m_modules.insert(v.second.data());
}

Now the save() function. It is also 7 lines of code:

// Saves the debug_settings structure to the specified XML file
void debug_settings::save(const std::string &filename)
{
   // Create an empty property tree object
   using boost::property_tree::ptree;
   ptree pt;

   // Put log filename in property tree
   pt.put("debug.filename", m_file);

   // Put debug level in property tree
   pt.put("debug.level", m_level);

   // Iterate over the modules in the set and put them in the
   // property tree. Note that the put function places the new
   // key at the end of the list of keys. This is fine most of
   // the time. If you want to place an item at some other place
   // (i.e. at the front or somewhere in the middle), this can
   // be achieved using a combination of the insert and put_own
   // functions.
   BOOST_FOREACH(const std::string &name, m_modules)
      pt.add("debug.modules.module", name);

   // Write the property tree to the XML file.
   write_xml(filename, pt);
}

The full program debug_settings.cpp is included in the examples directory.