[Boost-commit] svn:boost r51751 - in trunk/libs/property_tree/doc: . images

Subject: [Boost-commit] svn:boost r51751 - in trunk/libs/property_tree/doc: . images
From: sebastian.redl_at_[hidden]
Date: 2009-03-13 12:06:50

Author: cornedbee
Date: 2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
New Revision: 51751
URL: http://svn.boost.org/trac/boost/changeset/51751

Log:
Apply quickbook docs patch by Ryan Gallagher, with minor corrections.
Added:
   trunk/libs/property_tree/doc/
   trunk/libs/property_tree/doc/Jamfile.v2   (contents, props changed)
   trunk/libs/property_tree/doc/accessing.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/cmd_line_parser.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/container.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/images/
   trunk/libs/property_tree/doc/images/ptree2code.png   (contents, props changed)
   trunk/libs/property_tree/doc/info_parser.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/ini_parser.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/intro.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/json_parser.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/parsers.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/property_tree.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/synopsis.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/system_environment_parser.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/tutorial.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/windows_registry_parser.qbk   (contents, props changed)
   trunk/libs/property_tree/doc/xml_parser.qbk   (contents, props changed)

Added: trunk/libs/property_tree/doc/Jamfile.v2
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/Jamfile.v2	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,58 @@
+# Boost.PropertyTree
+#
+# Copyright (c) 2006-2007 Matias Capeletto
+#
+# 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)
+
+
+# Quickbook
+# -----------------------------------------------------------------------------
+
+import doxygen ;
+import quickbook ;
+doxygen autodoc
+    :
+        [ glob ../../../boost/property_tree/*.hpp ]
+    :
+        <doxygen:param>EXTRACT_ALL=YES
+        <doxygen:param>"PREDEFINED=\"BOOST_PROPERTY_TREE_DOXYGEN_INVOKED\" \\
+                                   \"BOOST_DEDUCED_TYPENAME=typename\""
+        <doxygen:param>HIDE_UNDOC_MEMBERS=NO
+        <doxygen:param>EXTRACT_PRIVATE=NO
+        <doxygen:param>ENABLE_PREPROCESSING=YES
+        <doxygen:param>MACRO_EXPANSION=YES
+        <doxygen:param>EXPAND_ONLY_PREDEF=YES
+        <doxygen:param>SEARCH_INCLUDES=YES
+        <doxygen:param>INCLUDE_PATH=$(BOOST_ROOT)
+        <doxygen:param>EXAMPLE_PATH=$(BOOST_ROOT)/libs/property_tree/examples
+        <doxygen:param>BRIEF_MEMBER_DESC=YES
+        <doxygen:param>REPEAT_BRIEF=YES
+        <doxygen:param>ALWAYS_DETAILED_SEC=YES
+        <doxygen:param>MULTILINE_CPP_IS_BRIEF=YES
+    ;
+
+xml property_tree : property_tree.qbk ;
+
+boostbook standalone
+    : property_tree
+    : <xsl:param>boost.root=../../../..
+      <xsl:param>boost.libraries=../../../libraries.htm
+      <xsl:param>toc.max.depth=3
+      <xsl:param>toc.section.depth=4
+      <xsl:param>chunk.section.depth=3
+      <dependency>autodoc
+    ;
+
+install html 
+    : ../../../doc/src/boostbook.css
+      ../../../doc/src/reference.css
+      ../../../doc/src/docutils.css
+    ;
+
+#install ../
+#    : ../../../boost.png
+#      ../../../next.png
+#      ../../../prev.png
+#    ;

Added: trunk/libs/property_tree/doc/accessing.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/accessing.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,71 @@
+[section:accessing How to Access Data in a Property Tree]
+[/ __ptree_*__ macros expected from property_tree.qbk]
+[def __pi__ ['pi]] [/ mathematical constant]
+
+Property tree resembles (almost is) a standard container with value type of `pair<string, ptree>`. It has the usual member functions, such as __ptree_insert__, __ptree_push_back__, __ptree_find__, __ptree_erase__, etc. These can of course be used to populate and access the tree. For example the following code adds key `"pi"` with data (almost) equal to mathematical __pi__ value:
+
+ __ptree__ pt;
+ pt.__ptree_push_back__(__ptree__::__ptree_value_type__("pi", __ptree__("3.14159")));
+
+To find the value of `pi` we might do the following:
+
+ __ptree__::__ptree_const_iterator__ it = pt.__ptree_find__("pi");
+ double pi = boost::lexical_cast<double>(it->second._ptree_data__());
+
+This looks quite cumbersome, and would be even more so if `pi` value was not stored so near the top of the tree, and we cared just a little bit more about errors. Fortunately, there is another, correct way of doing it:
+
+ ptree pt;
+ pt.__ptree_put__("pi", 3.14159);                // put double
+ double pi = pt.__ptree_get__<double>("pi");     // get double
+
+It doesn't get simpler than that. Basically, there are 2 families of member functions, __ptree_get__ and __ptree_put__, which allow intuitive access to data stored in the tree (direct children or not).
+
+[heading Three Ways of Getting Data]
+
+There are three versions of get: get, get (default-value version), and get_optional, which differ by failure handling strategy. All versions take path specifier, which determines in which key to search for a value. It can be a single key, or a path to key, where path elements are separated with a special character (a '.' if not specified differently). For example debug.logging.errorlevel might be a valid path with dot as a separator.
+
+# The throwing version (__ptree_get__):
+``
+__ptree__ pt;
+/* ... */
+float v = pt.__ptree_get__<float>("a.path.to.float.value");
+``
+This call locates the proper node in the tree and tries to translate its data string to a float value. If that fails, exception is thrown. If path does not exist, it will be __ptree_bad_path__ exception. If value could not be translated, it will be __ptree_bad_data__. Both of them derive from __ptree_error__ to make common handling possible.
+# The default-value version (__ptree_get_defaulted__):
+``
+__ptree__ pt;
+/* ... */
+float v = pt.__ptree_get_defaulted__("a.path.to.float.value", -1.f);
+``
+It will do the same as above, but if it fails, it will return the default value specified by second parameter (here -1.f) instead of throwing. This is very useful in common situations where one wants to allow omitting of some keys. Note that type specification needed in throwing version is normally not necessary here, because type is determined by the default value parameter.
+# The optional version (__ptree_get_optional__):
+``
+__ptree__ pt;
+/* ... */
+boost::optional<float> v = pt.__ptree_get_optional__<float>("a.path.to.float.value");
+``
+This version uses boost::optional class to handle extraction failure. On successful extraction, it will return boost::optional initialized with extracted value. Otherwise, it will return uninitialized boost::optional.
+
+To retrieve value from this tree (not some subkey), use __ptree_get_value__, __ptree_get_value__ (default-value version), and __ptree_get_value_optional__. They have identical semantics to __ptree_get__ functions, except they don't take the __path__ parameter. Don't call __ptree_get__ with and empty __path__ to do this as it will try to extract contents of subkey with empty name.
+
+To use separator character other than default '[^.]', each of the __ptree_get__ versions has another form, which takes an additional parameter in front of path. This parameter of type `char/wchar_t` specifies the separating character. This is a lifesaving device for those who may have dots in their keys:
+
+ pt.get<float>('/', "p.a.t.h/t.o/v.a.l.u.e");
+ pt.get('/', "p.a.t.h/t.o/v.a.l.u.e", 0, NULL);
+ pt.get_optional<std::string>('/', "p.a.t.h/t.o/v.a.l.u.e");
+
+[heading One Way of Putting Data]
+
+To complement __ptree_get__, there is a __ptree_put__ function. Contrary to __ptree_get__, it has only one variant. The reason is, there is no need to handle put failures so often (normally, __ptree_put__ will only fail if conversion of the supplied value to __ptree_data_type__ fails or the system runs out of memory.  In the former case, __ptree_put__ will throw __ptree_bad_data__). Sample usage of __ptree_put__ might appear as:
+
+ __ptree__ pt;
+ pt.__ptree_put__("a.path.to.float.value", 3.14f);
+
+Calling __ptree_put__ will insert a new value at specified path, so that a call to __ptree_get__ specifying the same path will retrieve it.  Further, __ptree_put__ will insert any missing path elements during path traversal. For example, calling `__ptree_put__("key1.key2.key3", 3.14f)` on an empty tree will insert three new children: `key1`, `key1.key2` and `key1.key2.key3`. The last one will receive a string `"3.14"` as data, while the two former ones will have empty data strings. __ptree_put__ always inserts new keys at the back of the existing sequences.
+
+Similar to __ptree_get_value__, there is also a __ptree_put_value__ function.  It does the same for this property tree what __ptree_put__ does for its children. Thus, it does not require __path__:
+
+ __ptree__ pt;
+ pt.__ptree_put_own__(3.14f);
+
+[endsect]
\ No newline at end of file

Added: trunk/libs/property_tree/doc/cmd_line_parser.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/cmd_line_parser.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,73 @@
+[section:cmdline_parser Command Line Parser]
+[def __read_cmdline__ [funcref boost::property_tree::cmdline_parser::read_cmdline read_cmdline]]
+This is a simple parser that converts command line parameters (in form of standard `argc` and `argv` arguments) into a property tree. There is no write function. The parser correctly recognizes simple command line styles, both from Unix and Windows worlds.
+
+During parse, parameters are converted to __ptree__ keys and grouped by their prefix, if any. Grouping means that they are inserted as children of a key representing appropriate group. Prefix is a single character that comes directly after so called "metacharacter", which is usually a dash '-' (on Unix) or a slash '/' (on Windows). For example, parameter [^-I/usr/include/foobar] has prefix [^I] after metacharacter '[^-]'. Parameters that do not start with a metacharacter (e.g. source files given to gcc), are inserted as children of a special, unnamed group. Additionally, data of each group contains value of last parameter assigned to that group. For example, this command line:
+
+[pre myprogram.exe -c -I/usr/include -Lm -I/home/mammamia/stuff foo.c bar.c -g]
+
+will result in the following property tree being created:
+
+ "" bar.c                    ;"unnamed" group
+ {
+    "0" myprogram.exe        ;first argument is name of program
+    "1" foo.c
+    "2" bar.c
+ }
+ c                           ;no data
+ {
+    "0" ""                  ;no value associated with 'c' option
+ }
+ I /home/mammamia/stuff
+ {
+    "0" /usr/include
+    "1" /home/mammamia/stuff
+ }
+ L m
+ {
+    "0" m
+ }
+
+Within each group, parameters are numbered, starting from zero.
+
+Metacharacters can be specified as a parameter to read function. This code will parse command line using both dash and slash as metachatacters:
+
+ __ptree__ pt;
+ __read_cmdline__(argc, argv, "-/", pt);
+
+Once the command line is parsed into a __ptree__, the power of the __ptree_get__, __ptree_get_child__, and __ptree_get_value__ interfaces can be used to conveniently extract the values of options needed. In the simplest case, user only needs to query key with name of option to get its value. For example:
+
+ // default to 0 if -Nxx or /Nxx not specified on command line
+ int n = pt.__ptree_get_defaulted__("N", 0);
+
+or
+
+ // throw if -Nxx or /Nxx not specified on command line
+ int n = pt.__ptree_get__<int>("N");
+
+If there is more than one instance of 'N' in command line, they can be accessed as:
+
+ // Copy values of all -N arguments to vector
+ std::vector<int> vec;
+ BOOST_FOREACH(const __ptree__::__ptree_value_type__ &v, pt.__ptree_get_child__("N", empty_ptree()))
+    vec.push_back(v.second.__ptree_get_value__<int>());
+
+or:
+
+ // Use numbering to access specific instances of parameter -N
+ int first_n = pt.__ptree_get_defaulted__("N.0", default_n_value);
+ int second_n = pt.__ptree_get_defaulted__("N.1", default_n_value);
+ /* ... */
+ int tenth_n = pt.__ptree_get_defaulted__("N.9", default_n_value);
+
+If you want to know how many [^-N]'s were specified:
+
+ // Count -N parameters
+ size_t count = pt.__ptree_get_child__("N", empty_ptree<ptree>()).size();
+
+First argument, `argv[0]`, normally contains path to executable, which is rarely used for arguments parsing. To skip it, invoke the parser like in the following manner:
+
+ // Skip program path
+ __read_cmdline__(argc - 1, argv + 1, "-", pt)
+
+[endsect] [/cmd_line_parser]

Added: trunk/libs/property_tree/doc/container.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/container.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,8 @@
+[section:container Property Tree as a Container]
+[/ __ptree_*__ macros expected from property_tree.qbk]
+Standard containers implement a concept of sequence. What is the sequence in case of property tree? It is a list of immediate children of given __ptree__. So, iterating over a __ptree__ will only reveal one level in hierarchy, not the whole tree. There is no iterator to iterate over all the nodes in tree, but it is not needed, so don't worry. The actual type of values stored by property tree is __ptree_value_type__. Property tree provides bidirectional __ptree_iterator__, both normal and reverse, to allow iteration over its elements.
+
+The sequence is not ordered by key. It is an important fact, and many mistakes can be avoided by keeping it in mind. The order of sequence is determined by the place where elements were inserted, like in `std::list`. That's why there are __ptree_push_back__, __ptree_push_front__ and __ptree_insert__ functions. But __ptree_find__ function, which searches for elements by name, has time complexity [^O(log n)] like in `std::map` - there is an additional indexing data structure inside property tree that allows fast searches. The implication of property tree not being sorted is that you cannot use algorithms that require sorted range, like for example `std::binary_search`.
+
+Property tree allows multiple elements to have equivalent keys, and the __ptree_find__ member function will always return the first of them. It is tempting to use `std::lower_bound` and `std::upper_bound` algorithms to find a range that encompasses all elements with equivalent keys, but it is a mistake - the sequence is not sorted by key and such a range probably does not even exist! You need to sort the sequence first, using a __ptree_sort__ member function (though by doing so you lose original ordering of the elements). Note that `std::sort` cannot be used, because it requires random access iterators, and property tree only provides bidirectional iterators.
+[endsect] [/container]

Added: trunk/libs/property_tree/doc/images/ptree2code.png
==============================================================================
Binary file. No diff available.

Added: trunk/libs/property_tree/doc/info_parser.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/info_parser.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,46 @@
+[section INFO Parser]
+The INFO format is a file format created by myself at the time when I was working on property tree library. It is included here for completeness, although I do not suspect many people will use it. At the very least, it can be used for visualising property trees, because it is very intuitive and easy to read by humans. Some property tree examples in this documentation are written in this format, and I think they do not need any extra explanation to be understandable. The format has some advantages:
+
+* simplicity: just a "key value" string is a valid INFO,
+* efficiency: the hand-crafted parser is fast and small,
+* corresponds to property tree structure: what can be written in INFO, can be stored in property tree, and vice versa,
+* easy on programmers: has `#include`, curly brackets for nesting, C character escape sequences.
+
+And a disadvantage: it is just yet another file format. For formal grammar see [@../../examples/info_grammar_spirit.cpp infor_grammar_spirit.cpp] example file. Usually, INFO looks similar to this:
+
+ key1 value1
+ key2
+ {
+    key3 value3
+    {
+       key4 "value4 with spaces"
+    }
+    key5 value5
+ }
+
+Additionally, it supports comments, `#includes`, C escape sequences, multiline values. Quite unrealistic file using all of these might look like this:
+
+ ; A comment
+ key1 value1   ; Another comment
+ key2 "value with special characters in it {};#\n\t\"\0"
+ {
+    subkey "value split "\
+           "over three"\
+           "lines"
+    {
+       a_key_without_value ""
+       "a key with special characters in it {};#\n\t\"\0" ""
+       "" value    ; Empty key with a value
+       "" ""       ; Empty key with empty value!
+    }
+ }
+ #include "file.info"    ; included file
+
+INFO format may be also regarded as JSON with simplified semantics and relaxed syntax:
+
+* Does not support arrays, only objects
+* Does not support numeric values or literals (true, false, null), all data must be strings
+* If string does not contain whitespace or special characters, double quotes can be omitted
+* Whitespace is used instead of ':' and ',' characters: "a":"b", "c":"d" -> a b c d
+
+[endsect] [/info_parser]
\ No newline at end of file

Added: trunk/libs/property_tree/doc/ini_parser.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/ini_parser.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,6 @@
+[section INI Parser]
+[def __ini_wiki__ [@http://en.wikipedia.org/wiki/INI INI format]]
+The __ini_wiki__ 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. Contrary to XML, this format is actually less rich than property tree. Because of that, there is no translation needed when reading from it. On the other hand, not every property tree can be represented as INI file - it cannot have keys with data on root level, it cannot be deeper than two levels, and there cannot be duplicate keys on any level.  The write functions by default do check these conditions, and will throw when these conditions are not met. Because the check can take a fairly significant amount of time [^(O(n log n))], there is an option to disable it by using `flags` parameter.
+
+INI parser does not use Windows functions to read and write the file. Instead it uses a fast and small handcrafted parser. Not that I think anybody would like to parse gigabytes of INI files. But thanks to this it is portable and can be used even on non-Windows systems.
+[endsect] [/ini_parser]

Added: trunk/libs/property_tree/doc/intro.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/intro.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,31 @@
+[template ptree2codeImage[] [$images/ptree2code.png]]
+[section:intro What is Property Tree?]
+Property tree is a recursive data structure that stores a single data string,
+and an ordered list of [^(key, value)] pairs, where value is a property tree
+itself. It therefore forms a tree, hence the name. It is a versatile structure
+that can store in uniform way data coming from various sources, such as XML,
+INI or JSON files, as well as windows registry, program command line etc.
+The correspondence between a data source (here XML file) and property tree is
+illustrated in the following diagram:
+[ptree2codeImage]
+
+Each node of property tree may be conceptually treated as the following
+structure (note that due to recursive nature of the tree, nodes are property
+trees):
+
+   struct ptree
+   {
+      string data;                            // data associated with the node
+      list< pair<string, ptree> > children;   // ordered list of named children
+   };
+
+Both key type and data type are configurable.
+
+The property tree interface is similar to the interface of a standard C++
+container. It supports iterators, insertion, erasing, searching etc. One can
+think of it as a sort of Document Object Model, which is minimalistic, not
+bound to any specific file format, designed to be easy to use, and comes as
+Boost-compatible, headers only C++ library.  Many software projects develop a
+similar tool at some point of their lifetime, and property tree originated the
+same way.  I hope the library can save many from reinventing the wheel. 
+[endsect] [/intro]

Added: trunk/libs/property_tree/doc/json_parser.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/json_parser.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,49 @@
+[section JSON Parser]
+[def __json_wiki__ [@http://en.wikipedia.org/wiki/JSON JSON format]]
+The __json_wiki__ is a data interchange format which is a subset of Javascript language.  (JSON stands for JavaScript Object Notation.)  It is considerably simpler than XML, is usually more concise, easier to read by humans, and easier to parse by machines. It's not currently as widely used as XML, but if you think XML is bloated then this may be the format worth consideration.
+
+JSON structure is slightly different from that of property tree. The differences and the way they are dealt with are summarized below:
+
+* JSON contains 'objects' and 'arrays' - objects are collections of name-value pairs, while arrays contain only values. During parse, items of JSON arrays are translated into ptree keys with empty names. Members of objects are translated into named keys. During write, any ptree key containing only unnamed subkeys will be rendered as JSON array.
+* A JSON element cannot simultaneously have child items and data. Only one of these may be present. As a result, if property tree contains keys that have both subkeys and non-empty data, writing will fail.
+* JSON data can be a string, a numeric value, or one of literals "null", "true" and "false". During parse, any of the above is copied verbatim into ptree data string. This causes some type information to be lost, because if resulting ptree is written back into JSON format, it will only contain strings.
+
+For example this JSON:
+
+ {
+    "menu": 
+    {
+       "foo": true,
+       "bar": "true",
+       "value": 102.3E+06,
+       "popup": 
+       [
+          {"value": "New", "onclick": "CreateNewDoc()"},
+          {"value": "Open", "onclick": "OpenDoc()"},
+       ]
+    }
+ }
+
+will be translated into the following property tree:
+
+ menu
+ {
+    foo true
+    bar true
+    value 102.3E+06
+    popup
+    {
+       ""
+       {
+          value New
+          onclick CreateNewDoc()
+       }
+       ""
+       {
+          value Open
+          onclick OpenDoc()
+       }
+    }
+ }
+
+[endsect] [/json_parser]
\ No newline at end of file

Added: trunk/libs/property_tree/doc/parsers.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/parsers.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,16 @@
+[section:parsers How to Populate a Property Tree]
+[include xml_parser.qbk]
+
+[include ini_parser.qbk]
+
+[include json_parser.qbk]
+
+[include info_parser.qbk]
+
+[include cmd_line_parser.qbk]
+
+[include windows_registry_parser.qbk]
+
+[include system_environment_parser.qbk]
+
+[endsect] [/parsers]

Added: trunk/libs/property_tree/doc/property_tree.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/property_tree.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,119 @@
+[/
+ / 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)
+ /]
+
+[library Boost.PropertyTree
+    [quickbook 1.4]
+    [copyright 2008 Marcin Kalicinski]
+    [purpose Property Tree library]
+    [license
+        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])
+    ]
+    [authors [Kalicinski, Marcin]]
+    [id property_tree]
+    [dirname property_tree]
+    [category container]
+    [category template]
+]
+
+[/ Tried to use templates here but got errors expanding them in [classref ...] etc.]
+[/ types]
+[def __ptree__ [classref boost::property_tree::ptree ptree]]
+[def __ptree_value_type__ [classref boost::property_tree::basic_ptree::value_type value_type]]
+[def __ptree_data_type__ [classref boost::property_tree::basic_ptree::data_type data_type]]
+[def __ptree_iterator__ [classref boost::property_tree::basic_ptree::iterator iterator]]
+[def __ptree_const_iterator__ [classref boost::property_tree::basic_ptree::const_iterator const_iterator]]
+[def __path__ [classref boost::property_tree::path path]]
+[def __ptree_error__ [classref boost::property_tree::ptree_error ptree_error]]
+[def __ptree_bad_data__ [classref boost::property_tree::ptree_bad_data ptree_bad_data]]
+[def __ptree_bad_path__ [classref boost::property_tree::ptree_bad_path ptree_bad_path]]
+
+[/ members]
+[def __ptree_insert__ [memberref boost::property_tree::basic_ptree::insert insert]]
+[def __ptree_push_back__ [memberref boost::property_tree::basic_ptree::push_back push_back]]
+[def __ptree_find__ [memberref boost::property_tree::basic_ptree::find find]]
+[def __ptree_erase__ [memberref boost::property_tree::basic_ptree::erase erase]]
+[def __ptree_find__ [memberref boost::property_tree::basic_ptree::find find]]
+[def __ptree_data__ [memberref boost::property_tree::basic_ptree::data data]]
+[def __ptree_push_front__ [memberref boost::property_tree::basic_ptree::push_front push_front]]
+[def __ptree_sort__ [memberref boost::property_tree::basic_ptree::sort sort]]
+[def __ptree_get__ [memberref boost::property_tree::basic_ptree::get get]]
+[/ XXX: Don't know how to specify overloads]
+[def __ptree_get_defaulted__ [memberref boost::property_tree::basic_ptree::get get]]
+[def __ptree_get_optional__ [memberref boost::property_tree::basic_ptree::get_optional get_optional]]
+[def __ptree_get_value__ [memberref boost::property_tree::basic_ptree::get_value get_value]]
+[/ XXX: Don't know how to specify overloads]
+[def __ptree_get_value_defaulted__ [memberref boost::property_tree::basic_ptree::get_value get_value]]
+[def __ptree_get_value_optional__ [memberref boost::property_tree::basic_ptree::get_value_optional get_value_optional]]
+[def __ptree_get_child__ [memberref boost::property_tree::basic_ptree::get_child get_child]]
+[def __ptree_put__ [memberref boost::property_tree::basic_ptree::put put]]
+[def __ptree_put_value__ [memberref boost::property_tree::basic_ptree::put_value put_value]]
+
+[/ free-functions]
+[def __read_xml__ [funcref boost::property_tree::xml_parser::read_xml read_xml]]
+[def __write_xml__ [funcref boost::property_tree::xml_parser::write_xml write_xml]]
+
+[include intro.qbk]
+
+[include tutorial.qbk]
+
+[include container.qbk]
+
+[include synopsis.qbk]
+
+[include parsers.qbk]
+
+[include accessing.qbk]
+
+[section Appendices]
+[heading Compatibility]
+Property tree uses partial class template specialization. There has been no
+attempt to work around lack of support for this. The library will therefore
+most probably not work with Visual C++ 7.0 or earlier, or gcc 2.x.
+
+Property tree has been tested (regressions successfully compiled and run)
+with the following compilers:
+
+* Visual C++ 8.0
+* gcc 3.4.2 (MinGW)
+* gcc 3.3.5 (Linux)
+* gcc 3.4.4 (Linux)
+* gcc 4.3.3 (Linux)
+* Intel C++ 9.0 (Linux)
+
+[heading Rationale]
+# [*Why are there 3 versions of __ptree_get__? Couldn't there be just one?]
+The three versions reflect experience gathered during several of years of using
+property tree in several different applications. During that time I tried hard
+to come up with one, proper form of the get function, and failed. I know of
+these three basic patterns of usage:
+
+ * ['Just get the data and I do not care if it cannot be done.]  This is used
+   when the programmer is fairly sure that data exists. Or in homework
+   assignments. Or when tomorrow is final deadline for your project.
+ * ['Get the data and revert to default value if it cannot be done.]  Used when
+   you want to allow omitting the key in question. Implemented by some similar
+   tools (windows INI file access functions).
+ * ['Get the data, but I care more whether you succeeded than I do for the data
+   itself.] Used when you want to vary control flow depending on get
+   success/failure. Or to check for presence of a key.
+
+# [*Why does the separator character come before the path and not after
+    as one would expect?]
+It helps with overload resolution in some cases.
+
+[heading Future Development]
+* More parsers:  YAML, environment strings.
+* More robust XML parser.
+* Mathematical relations:  ptree difference, union, intersection.
+  Useful for finding configuration file changes etc.
+
+[endsect] [/ Appendices]
+
+[xinclude autodoc.xml]

Added: trunk/libs/property_tree/doc/synopsis.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/synopsis.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,18 @@
+[section:synopsis Property Tree Synopsis]
+[def __basic_ptree__ [classref boost::property_tree::basic_ptree basic_ptree]]
+[def __ptree__ [classref boost::property_tree::ptree ptree]]
+[def __wptree__ [classref boost::property_tree::wptree wptree]]
+[def __iptree__ [classref boost::property_tree::iptree iptree]]
+[def __wiptree__ [classref boost::property_tree::wiptree wiptree]]
+[/ basic_ptree members]
+[def __ptree_get__ [memberref boost::property_tree::basic_ptree::get get]]
+[def __ptree_put__ [memberref boost::property_tree::basic_ptree::put put]]
+[def __ptree_get_value__ [memberref boost::property_tree::basic_ptree::get_value get_value]]
+[def __ptree_put_value__ [memberref boost::property_tree::basic_ptree::put_value put_value]]
+[def __ptree_get_child__ [memberref boost::property_tree::basic_ptree::get_child get_child]]
+[def __ptree_put_child__ [memberref boost::property_tree::basic_ptree::put_child put_child]]
+[def __ptree_data__ [memberref boost::property_tree::basic_ptree::data data]]
+The central component of the library is __basic_ptree__ class template. Instances of this class are property trees. It is parametrized on character type and key comparison policy; __ptree__, __wptree__, __iptree__ and __wiptree__ are typedefs of __basic_ptree__ using predefined combinations of template parameters.  Property tree is basically a somewhat simplified standard container (the closest being std::list), plus a bunch of extra member functions. These functions allow easy and effective access to the data stored in property tree. They are various variants of __ptree_get__, __ptree_put__, __ptree_get_value__, __ptree_put_value__, __ptree_get_child__, __ptree_put_child__. Additionally, there is __ptree_data__ function to access node data directly.
+
+See the [classref boost::property_tree::basic_ptree basic_ptree class template synopsis] for more information.
+[endsect]

Added: trunk/libs/property_tree/doc/system_environment_parser.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/system_environment_parser.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,3 @@
+[section System Environment Parser]
+[note The system environment parser is not yet implemented.]
+[endsect] [/env_parser]

Added: trunk/libs/property_tree/doc/tutorial.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/tutorial.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,99 @@
+[section:tutorial Five Minute Tutorial]
+This tutorial uses XML file format. Note that the library is not specifically bound to XML, and any other supported format (such as INI or JSON) could be used as well. XML was chosen because 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 program starts. The file with log configuration looks like that:
+
+[pre
+<debug>
+    <filename>debug.log</filename>
+    <modules>
+        <module>Finance</module>
+        <module>Admin</module>
+        <module>HR</module>
+    </modules>
+    <level>2</level>
+</debug>
+]
+
+It contains log filename, list of modules where logging is enabled, and debug level value. To store logging configuration in the program we created 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 handling:
+
+   // Loads debug_settings structure from specified XML file
+   void debug_settings::load(const std::string &filename)
+   {
+       // Create empty property tree object
+       using boost::property_tree::__ptree__;
+       __ptree__ pt;
+   
+       // Load XML file and put its contents in property tree. 
+       // No namespace qualification is needed, because of Koenig 
+       // lookup on the second argument. If reading fails, exception
+       // is thrown.
+       __read_xml__(filename, pt);
+   
+       // Get filename and store it in m_file variable. Note that 
+       // we specify a path to the value using notation where keys 
+       // are separated with dots (different separator may be used 
+       // if keys themselves contain dots). If debug.filename key is
+       // not found, exception is thrown.
+       m_file = pt.__ptree_get__<std::string>("debug.filename");
+   
+       // Get debug level and store it in m_level variable. This is 
+       // another version of get method: if debug.level key is not 
+       // found, it will return default value (specified by second 
+       // parameter) instead of throwing. Type of the value extracted 
+       // is determined by type of second parameter, so we can simply 
+       // write get(...) instead of get<int>(...)
+       m_level = pt.__ptree_get__("debug.level", 0);
+   
+       // Iterate over debug.modules section and store all found 
+       // modules in m_modules set. get_child() function returns a 
+       // reference to child at specified path; if there is no such 
+       // child, it throws. Property tree iterator can be used in
+       // the same way as standard container iterator. Category 
+       // is bidirectional_iterator.
+       BOOST_FOREACH(__ptree__::__ptree_value_type__ &v, pt.__ptree_get_child__("debug.modules"))
+          m_modules.__ptree_insert__(v.second.data());
+   }
+
+Now save() function. It is also 7 lines of code:
+
+   // Saves debug_settings structure to specified XML file
+   void debug_settings::save(const std::string &filename)
+   {
+      // Create empty property tree object
+      using boost::property_tree::__ptree__;
+      __ptree__ pt;
+   
+      // Put log filename in property tree
+      pt.__ptree_put__("debug.filename", m_file);
+   
+      // Put debug level in property tree
+      pt.__ptree_put__("debug.level", m_level);
+   
+      // Iterate over modules in set and put them in property
+      // tree. Note that put function places new key at the
+      // end of list of keys. This is fine in most of the
+      // situations. If you want to place item at some other
+      // place (i.e. at front or somewhere in the middle),
+      // this can be achieved using combination of insert 
+      // and put_own functions
+      BOOST_FOREACH(const std::string &name, m_modules)
+         pt.__ptree_put__("debug.modules.module", name, true);
+   
+      // Write property tree to XML file
+      __write_xml__(filename, pt);
+   }
+
+The full program [@../../examples/debug_settings.cpp debug_settings.cpp] is included in examples directory.
+[endsect] [/tutorial]

Added: trunk/libs/property_tree/doc/windows_registry_parser.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/windows_registry_parser.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,38 @@
+[section:registry_parser Windows Registry Parser]
+[def __registry_parser.hpp__ [headerref boost/property_tree/registry_parser.hpp registry_parser.hpp]]
+[def __read_registry__ [funcref boost::property_tree::registry_parser::read_registry read_registry]]
+[def __translate__ [funcref boost::property_tree::registry_parser::translate translate]]
+[def __write_registry__ [funcref boost::property_tree::registry_parser::write_registry write_registry]]
+This parser supports reading and writing data from Windows registry. There is only a subset of registry functionality implemented, because property tree is not intended to replace registry API. For example, access rights are not supported, as well as some exotic value formats. Registry is a rich data source, providing hierarchy of keys, each of whose can have any number of named and typed values attached to it. Because of that - like in XML - some translation is necessary.
+
+[important This parser will only work on a Windows system because it uses Windows API to access the registry. You will need to link with [^advapi32.lib].  A minimalist version of the [^windows.h] Windows header file is included by __registry_parser.hpp__. If you want to include [^windows.h] header on your own, do it before including __registry_parser.hpp__.]
+
+[heading How Registry Keys are Translated to Property Trees (__read_registry__):]
+
+* Values of each registry key are stored in a subkey with name [^\values]. The preceding backslash is there to prevent name clashes with regular keys. Each subkey of [^\values] is one registry value. If [^\values] subkey does not exist or is empty, there are no values attached to that key.
+* Types of values of each registry key are stored in a subkey with name [^\types]. These subkeys contain an integer equal to type of data stored in its corresponding entry in [^\values] (correspondence is by name, not position).
+* So called "default value" (value attached to key itself), is translated directly to key data and is always assumed to be of type [^REG_SZ].
+* [^REG_BINARY] values are translated to textual format before placing in property tree. The format is the same as the one displayed by regedit application: a series of two-digit hexadecimal numbers representing bytes separated with spaces. To translate from this format to binary data, or vice versa, use the __translate__ function.
+* Supported value types are: [^REG_NONE], [^REG_SZ], [^REG_EXPAND_SZ], [^REG_DWORD], [^REG_QWORD], [^REG_BINARY].
+
+Translation of property tree back into registry (__write_registry__) assumes the same structure as outlined above. That means if you want to have named values, you need to create [^\values] and [^\types] subkeys, and put them there. Also, you have to convert all [^REG_BINARY] values to textual format. Passing "normal" property tree (i.e. not containing [^\types] and [^\values] keys) to the __write_registry__ function will put all data in "default value" section of each key. This is fine, especially if you intend to read this data using property tree, but is probably not a standard way of storing things in the registry.
+
+For example, when you read registry key [^HKEY_CURRENT_USER\Software\Microsoft\Notepad], under Windows XP, you will get property tree containing Notepad font settings (among other things):
+
+ Notepad
+ {
+    \values
+    {
+       lfFaceName  Courier
+       lfItalic    0
+       lfWeight    190
+    }
+    \types
+    {
+       lfFaceName  1  ; REG_SZ
+       lfItalic    4  ; REG_DWORD
+       lfWeight    4  ; REG_DWORD
+    }
+ }
+
+[endsect] [/win_reg_parser]

Added: trunk/libs/property_tree/doc/xml_parser.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/property_tree/doc/xml_parser.qbk	2009-03-13 12:06:47 EDT (Fri, 13 Mar 2009)
@@ -0,0 +1,15 @@
+[section XML Parser]
+[def __xml_wiki__ [@http://en.wikipedia.org/wiki/XML XML format]]
+[def __xml_parser.hpp__ [headerref boost/property_tree/xml_parser.hpp xml_parser.hpp]]
+[def __TinyXML__ [@http://sourceforge.net/projects/tinyxml TinyXML]]
+[def __boost_homepage__ [@http://www.boost.org Boost]]
+The __xml_wiki__ is an industry standard for storing information in textual form. Unfortunately, there is no XML parser in __boost_homepage__ as of the time of this writing. Therefore, a custom parser was created. It only supports a core subset of XML standard. For example, declarations and entity references are not supported. The parser is built with Spirit, and bases on XML grammar sample by Daniel Nuffer. As a reinforcement to it, a parser based on __TinyXML__ is also provided. To enable it define [^BOOST_PROPERTY_TREE_XML_PARSER_TINYXML] before including the __xml_parser.hpp__ file. __TinyXML__ library has to be obtained separately.
+
+How XML is translated to property tree (__read_xml__):
+
+* Attributes of each XML key are stored in a subkey with name [^<xmlattr>]. Each subkey of [^<xmlattr>] is one attribute. If [^<xmlattr>] subkey does not exist or is empty, there are no attributes.
+* XML comments are stored in keys named [^<xmlcomment>], unless a flag is specified that disables parsing of comments.
+* Data of XML node may be stored in two ways, depending on the flags parameter setting. The default way is to have all data nodes concatenated and put in data string of appropriate property tree key. The other way is to have them put in separate subkeys named [^<xmltext>] each.
+
+Translation of property tree back into XML (__write_xml__) assumes the same structure as outlined above. That means, for example, that if you want to have attributes, you need to create [^<xmlattr>] subkey and put them there. With appropriate flags setting, reading an XML file and writing it back will not change the contents (but may change formatting), unless XML file uses some unsupported constructs.
+[endsect] [/xml_parser]