Squashed 'third_party/boostorg/property_tree/' content from commit bdfe275
Change-Id: I075a5e242aaddc356ecc81e756c4a0907fc38130
git-subtree-dir: third_party/boostorg/property_tree
git-subtree-split: bdfe275d172ac30bc5e89a6375a5a64dea20b3c0
diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2
new file mode 100644
index 0000000..47e1ebe
--- /dev/null
+++ b/doc/Jamfile.v2
@@ -0,0 +1,57 @@
+# 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>toc.max.depth=3
+ <xsl:param>toc.section.depth=2
+ <xsl:param>chunk.section.depth=3
+ <dependency>autodoc
+ <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/property_tree/doc/html
+ ;
+
+###############################################################################
+alias boostdoc
+ : property_tree
+ :
+ : <dependency>autodoc
+ : ;
+explicit boostdoc ;
+alias boostrelease ;
+explicit boostrelease ;
diff --git a/doc/accessing.qbk b/doc/accessing.qbk
new file mode 100644
index 0000000..20f0bc4
--- /dev/null
+++ b/doc/accessing.qbk
@@ -0,0 +1,94 @@
+[/
+ / 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: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 a 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 a separator character other than default '[^.]', you need to construct
+a path object explicitly. The path type for a __ptree__ is a string_path
+instantiation, so the easiest way to refer to it is __ptree__::path_type.
+This way you can use trees that have dots in their keys:
+
+ typedef ptree::path_type path;
+ pt.get<float>(path("p.a.t.h/t.o/v.a.l.u.e", '/'));
+ pt.get(path("p.a.t.h/t.o/v.a.l.u.e", '/'), 0, NULL);
+ pt.get_optional<std::string>(path("p.a.t.h/t.o/v.a.l.u.e", '/'));
+
+Note: the special overloads of __ptree_get__ and __ptree_get_optional__ taking
+a separator character that existed in pre-release versions of PropertyTree have
+been removed. This is because the overloads conflicted with using per-call data
+translators.
+
+[heading Two Ways of Putting Data]
+
+To complement __ptree_get__, there are __ptree_put__ and __ptree_add__. Contrary to __ptree_get__, they have only one variant each. This is because there is no need to deal with missing values when adding data. If the supplied value cannot be converted to the tree's data type, the functions will throw __ptree_bad_data__.
+
+ __ptree__ pt;
+ pt.__ptree_put__("a.path.to.float.value", 3.14f);
+ // Overwrites the value
+ pt.__ptree_put__("a.path.to.float.value", 2.72f);
+ // Adds a second node with the new value.
+ pt.__ptree_add__("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.
+The difference between __ptree_put__ and __ptree_add__ is that put will overwrite existing values if there are any, while add will create a new node to hold the value even if the specified path references an existing node.
+
+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 receive a __path__:
+
+ __ptree__ pt;
+ pt.__ptree_put_value__(3.14f);
+
+There is no add_value function.
+
+[endsect]
diff --git a/doc/cmd_line_parser.qbk b/doc/cmd_line_parser.qbk
new file mode 100644
index 0000000..5ae64fa
--- /dev/null
+++ b/doc/cmd_line_parser.qbk
@@ -0,0 +1,80 @@
+[/
+ / 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: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]
diff --git a/doc/container.qbk b/doc/container.qbk
new file mode 100644
index 0000000..ea545d1
--- /dev/null
+++ b/doc/container.qbk
@@ -0,0 +1,33 @@
+[/
+ / 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:container Property Tree as a Container]
+[/ __ptree_*__ macros expected from property_tree.qbk]
+Every property tree node models the ReversibleSequence concept, providing
+access to its immediate children. This means that iterating over a __ptree__
+(which is the same as its root node - every __ptree__ node is also the
+subtree it starts) iterates only a single level of the hierarchy. There is no
+way to iterate over the entire tree.
+
+It is very important to remember that the property sequence is *not* ordered by
+the key. It preserves the order of insertion. It closely resembles a std::list.
+Fast access to children by name is provided via a separate lookup structure. Do
+not attempt to use algorithms that expect an ordered sequence (like
+binary_search) on a node's children.
+
+The property tree exposes a second container-like interface, called the
+associative view. Its iterator type is the nested type assoc_iterator (and its
+const counterpart const_assoc_iterator). You can get an ordered view of all
+children by using ordered_begin() and ordered_end().
+
+The associative view also provides find() and equal_range() members, which
+return assoc_iterators, but otherwise have the same semantics as the members
+of std::map of the same name.
+
+You can get a normal iterator from an assoc_iterator by using the to_iterator()
+member function. Converting the other way is not possible.
+[endsect] [/container]