|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r51750 - trunk/boost/property_tree
From: sebastian.redl_at_[hidden]
Date: 2009-03-13 12:03:26
Author: cornedbee
Date: 2009-03-13 12:03:25 EDT (Fri, 13 Mar 2009)
New Revision: 51750
URL: http://svn.boost.org/trac/boost/changeset/51750
Log:
Apply doxygen docs patch by Ryan Gallagher, with minor corrections
Text files modified:
trunk/boost/property_tree/info_parser.hpp | 55 ++
trunk/boost/property_tree/ini_parser.hpp | 66 +++
trunk/boost/property_tree/json_parser.hpp | 54 ++
trunk/boost/property_tree/ptree.hpp | 697 +++++++++++++++++++++++++++++++++++++--
trunk/boost/property_tree/ptree_fwd.hpp | 41 ++
trunk/boost/property_tree/ptree_serialization.hpp | 30 +
trunk/boost/property_tree/xml_parser.hpp | 52 ++
7 files changed, 930 insertions(+), 65 deletions(-)
Modified: trunk/boost/property_tree/info_parser.hpp
==============================================================================
--- trunk/boost/property_tree/info_parser.hpp (original)
+++ trunk/boost/property_tree/info_parser.hpp 2009-03-13 12:03:25 EDT (Fri, 13 Mar 2009)
@@ -20,7 +20,13 @@
namespace boost { namespace property_tree { namespace info_parser
{
- // Read info from stream
+ /**
+ * Read INFO from a the given stream and translate it to a property tree.
+ * @note Clears existing contents of property tree. In case of error the property tree unmodified.
+ * @throw info_parser_error On error translating the INFO stream to a property tree.
+ * @param stream Stream from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ */
template<class Ptree, class Ch>
void read_info(std::basic_istream<Ch> &stream,
Ptree &pt)
@@ -30,7 +36,13 @@
pt.swap(local);
}
- // Read info from stream with default
+ /**
+ * Read INFO from a the given stream and translate it to a property tree.
+ * @note Clears existing contents of property tree. In case of error the property tree unmodified.
+ * @param stream Stream from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ * @param default_ptree The property tree to which to set @c pt on error reading the INFO stream.
+ */
template<class Ptree, class Ch>
void read_info(std::basic_istream<Ch> &stream,
Ptree &pt,
@@ -46,7 +58,14 @@
}
}
- // Read info from file
+ /**
+ * Read INFO from a the given file and translate it to a property tree.
+ * @note Clears existing contents of property tree. In case of error the property tree unmodified.
+ * @throw info_parser_error On error translating the INFO stream to a property tree.
+ * @param filename Name of file from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ * @param loc The locale to use when reading in the file contents.
+ */
template<class Ptree>
void read_info(const std::string &filename,
Ptree &pt,
@@ -61,7 +80,14 @@
pt.swap(local);
}
- // Read info from file with default
+ /**
+ * Read INFO from a the given file and translate it to a property tree.
+ * @note Clears existing contents of property tree. In case of error the property tree unmodified.
+ * @param filename Name of file from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ * @param loc The locale to use when reading in the file contents.
+ * @param default_ptree The property tree to which to set @c pt on error reading the INFO stream.
+ */
template<class Ptree>
void read_info(const std::string &filename,
Ptree &pt,
@@ -78,7 +104,15 @@
}
}
- // Write info to stream
+ /**
+ * Translates the property tree to INFO and writes it the given output stream.
+ * @throw info_parser_error In case of error translating the property tree to INFO
+ * or writing to the output stream.
+ * @param stream The stream to which to write the INFO representation of the
+ * property tree.
+ * @param pt The property tree to tranlsate to INFO and output.
+ * @param settings The settings to use when writing the INFO data.
+ */
template<class Ptree, class Ch>
void write_info(std::basic_ostream<Ch> &stream,
const Ptree &pt,
@@ -87,7 +121,16 @@
write_info_internal(stream, pt, std::string(), settings);
}
- // Write info to file
+ /**
+ * Translates the property tree to INFO and writes it the given file.
+ * @throw info_parser_error In case of error translating the property tree to INFO
+ * or writing to the file.
+ * @param filename The name of the file to which to write the INFO representation
+ * of the property tree.
+ * @param pt The property tree to tranlsate to INFO and output.
+ * @param settings The settings to use when writing the INFO data.
+ * @param loc The locale to use when writing the file.
+ */
template<class Ptree>
void write_info(const std::string &filename,
const Ptree &pt,
Modified: trunk/boost/property_tree/ini_parser.hpp
==============================================================================
--- trunk/boost/property_tree/ini_parser.hpp (original)
+++ trunk/boost/property_tree/ini_parser.hpp 2009-03-13 12:03:25 EDT (Fri, 13 Mar 2009)
@@ -22,17 +22,29 @@
namespace boost { namespace property_tree { namespace ini_parser
{
- static const int skip_ini_validity_check = 1; // Skip check if ptree is a valid ini
+ /** Skip check if ptree is a valid ini */
+ static const int skip_ini_validity_check = 1;
+ /**
+ * Determines whether the @c flags are valid for use with the ini_parser.
+ * @param flags value to check for validity as flags to ini_parser.
+ * @return true if the flags are valid, false otherwise.
+ */
inline bool validate_flags(int flags)
{
return (flags & ~skip_ini_validity_check) == 0;
}
- //! Ini parser error
+ /** Indicates an error parsing INI formatted data. */
class ini_parser_error: public file_parser_error
{
public:
+ /**
+ * Construct an @c ini_parser_error
+ * @param message Message describing the parser error.
+ * @param filename The name of the file being parsed containing the error.
+ * @param line The line in the given file where an error was encountered.
+ */
ini_parser_error(const std::string &message,
const std::string &filename,
unsigned long line):
@@ -41,7 +53,13 @@
}
};
- //! Read ini from stream
+ /**
+ * Read INI from a the given stream and translate it to a property tree.
+ * @note Clears existing contents of property tree. In case of error the property tree unmodified.
+ * @throw ini_parser_error In case of error deserializing the property tree.
+ * @param stream Stream from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ */
template<class Ptree>
void read_ini(std::basic_istream<typename Ptree::key_type::value_type> &stream,
Ptree &pt)
@@ -108,7 +126,14 @@
}
- //! Read ini from file
+ /**
+ * Read INI from a the given file and translate it to a property tree.
+ * @note Clears existing contents of property tree. In case of error the property tree unmodified.
+ * @throw ini_parser_error In case of error deserializing the property tree.
+ * @param filename Name of file from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ * @param loc The locale to use when reading in the file contents.
+ */
template<class Ptree>
void read_ini(const std::string &filename,
Ptree &pt,
@@ -126,7 +151,21 @@
}
}
- //! Write ini to stream
+ /**
+ * Translates the property tree to INI and writes it the given output stream.
+ * @pre @e pt cannot have keys with data at its root level.
+ * @pre @e pt cannot be deaper than two levels.
+ * @pre There cannot be duplicate keys on any given level of @e pt.
+ * @throw ini_parser_error In case of error translating the property tree to INI
+ * or writing to the output stream.
+ * @param stream The stream to which to write the INI representation of the
+ * property tree.
+ * @param pt The property tree to tranlsate to INI and output.
+ * @param flags The flags to use when writing the INI file.
+ * The following flags are supported:
+ * @li @c skip_ini_validity_check -- Skip check if ptree is a valid ini. The
+ * validity check covers the preconditions but takes <tt>O(n log n)</tt> time.
+ */
template<class Ptree>
void write_ini(std::basic_ostream<typename Ptree::key_type::value_type> &stream,
const Ptree &pt,
@@ -165,7 +204,22 @@
}
- // Write ini to file
+ /**
+ * Translates the property tree to INI and writes it the given file.
+ * @pre @e pt cannot have keys with data at its root level.
+ * @pre @e pt cannot be deaper than two levels.
+ * @pre There cannot be duplicate keys on any given level of @e pt.
+ * @throw info_parser_error In case of error translating the property tree to INI
+ * or writing to the file.
+ * @param filename The name of the file to which to write the INI representation
+ * of the property tree.
+ * @param pt The property tree to tranlsate to INI and output.
+ * @param flags The flags to use when writing the INI file.
+ * The following flags are supported:
+ * @li @c skip_ini_validity_check -- Skip check if ptree is a valid ini. The
+ * validity check covers the preconditions but takes <tt>O(n log n)</tt> time.
+ * @param loc The locale to use when writing the file.
+ */
template<class Ptree>
void write_ini(const std::string &filename,
const Ptree &pt,
Modified: trunk/boost/property_tree/json_parser.hpp
==============================================================================
--- trunk/boost/property_tree/json_parser.hpp (original)
+++ trunk/boost/property_tree/json_parser.hpp 2009-03-13 12:03:25 EDT (Fri, 13 Mar 2009)
@@ -22,7 +22,19 @@
namespace boost { namespace property_tree { namespace json_parser
{
- // Read json from stream
+ /**
+ * Read JSON from a the given stream and translate it to a property tree.
+ * @note Clears existing contents of property tree. In case of error the
+ * property tree unmodified.
+ * @note Items of JSON arrays are translated into ptree keys with empty
+ * names. Members of objects are translated into named keys.
+ * @note 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.
+ * @throw json_parser_error In case of error deserializing the property tree.
+ * @param stream Stream from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ */
template<class Ptree>
void read_json(std::basic_istream<typename Ptree::key_type::value_type> &stream,
Ptree &pt)
@@ -30,7 +42,20 @@
read_json_internal(stream, pt, std::string());
}
- // Read json from file
+ /**
+ * Read JSON from a the given file and translate it to a property tree.
+ * @note Clears existing contents of property tree. In case of error the
+ * property tree unmodified.
+ * @note Items of JSON arrays are translated into ptree keys with empty
+ * names. Members of objects are translated into named keys.
+ * @note 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.
+ * @throw json_parser_error In case of error deserializing the property tree.
+ * @param filename Name of file from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ * @param loc The locale to use when reading in the file contents.
+ */
template<class Ptree>
void read_json(const std::string &filename,
Ptree &pt,
@@ -43,7 +68,17 @@
read_json_internal(stream, pt, filename);
}
- // Write json to stream
+ /**
+ * Translates the property tree to JSON and writes it the given output stream.
+ * @note Any property tree key containing only unnamed subkeys will be rendered
+ * as JSON arrays.
+ * @pre @e pt cannot contain keys that have both subkeys and non-empty data.
+ * @throw json_parser_error In case of error translating the property tree to JSON
+ * or writing to the output stream.
+ * @param stream The stream to which to write the JSON representation of the
+ * property tree.
+ * @param pt The property tree to tranlsate to JSON and output.
+ */
template<class Ptree>
void write_json(std::basic_ostream<typename Ptree::key_type::value_type> &stream,
const Ptree &pt)
@@ -51,7 +86,18 @@
write_json_internal(stream, pt, std::string());
}
- // Write json to file
+ /**
+ * Translates the property tree to JSON and writes it the given file.
+ * @note Any property tree key containing only unnamed subkeys will be rendered
+ * as JSON arrays.
+ * @pre @e pt cannot contain keys that have both subkeys and non-empty data.
+ * @throw json_parser_error In case of error translating the property tree to JSON
+ * or writing to the file.
+ * @param filename The name of the file to which to write the JSON representation
+ * of the property tree.
+ * @param pt The property tree to tranlsate to JSON and output.
+ * @param loc The locale to use when writing out to the output file.
+ */
template<class Ptree>
void write_json(const std::string &filename,
const Ptree &pt,
Modified: trunk/boost/property_tree/ptree.hpp
==============================================================================
--- trunk/boost/property_tree/ptree.hpp (original)
+++ trunk/boost/property_tree/ptree.hpp 2009-03-13 12:03:25 EDT (Fri, 13 Mar 2009)
@@ -7,6 +7,9 @@
//
// For more information, see www.boost.org
// ----------------------------------------------------------------------------
+
+/// This header contains definition of basic_ptree class template and supporting definitions.
+
#ifndef BOOST_PROPERTY_TREE_PTREE_HPP_INCLUDED
#define BOOST_PROPERTY_TREE_PTREE_HPP_INCLUDED
@@ -35,38 +38,61 @@
#include <vector>
#include <cstdlib>
-// Throwing macro to avoid no return warnings portably
-#define BOOST_PROPERTY_TREE_THROW(e) { throw_exception(e); std::exit(1); }
+#if !defined(BOOST_PROPERTY_TREE_DOXYGEN_INVOKED)
+ // Throwing macro to avoid no return warnings portably
+# define BOOST_PROPERTY_TREE_THROW(e) { throw_exception(e); std::exit(1); }
+#endif
namespace boost { namespace property_tree
{
+ /**
+ * Class template implementing property tree.
+ *
+ * A property tree can have data associated with it
+ * along with a sequence of @c (key,basic_ptree) children.
+ * Iterators provide bidirectional iterative access into children sequence.
+ *
+ * @tparam C Key comparison type
+ * @tparam K Key type
+ * @tparam P Path type
+ * @tparam D Data type
+ * @tparam X Translator type to use for converting values to and from std::string
+ */
template<class C, class K, class P, class D, class X>
class basic_ptree
{
-
- private:
-
- // Internal types
- typedef basic_ptree<C, K, P, D, X> self_type;
-
+#if defined(BOOST_PROPERTY_TREE_DOXYGEN_INVOKED)
public:
+#endif
+ // Internal types
+ /**
+ * Simpler way to refer to this basic_ptree<C,K,P,D,X> type.
+ * Do not use in client code; exposed only for documentation purposes.
+ */
+ typedef basic_ptree<C, K, P, D, X> self_type;
+ public:
// Basic types
typedef C key_compare;
typedef K key_type;
typedef P path_type;
typedef D data_type;
typedef X translator_type;
+
+ /**
+ * Property tree stores a sequence of values of this type.
+ *
+ * The first element is the key and the second is the child property tree
+ * stored at this key.
+ */
typedef std::pair<key_type, self_type> value_type;
private:
-
// Internal types
typedef std::list<value_type> container_type;
public:
-
// Container-related types
typedef typename container_type::size_type size_type;
typedef typename container_type::iterator iterator;
@@ -75,108 +101,602 @@
typedef typename container_type::const_reverse_iterator const_reverse_iterator;
public:
-
///////////////////////////////////////////////////////////////////////////
// Construction & destruction
+ /** Creates an empty property tree. */
basic_ptree();
+
+ /**
+ * Creates a property_tree with the given data.
+ * @param data Data to be assigned to the tree's data field.
+ */
explicit basic_ptree(const data_type &data);
+
+ /**
+ * Copy constructor from another property_tree.
+ * @param rhs The property tree to be copied.
+ */
basic_ptree(const self_type &rhs);
+
+ /** Destroys the property tree including recusively destoying all children. */
~basic_ptree();
///////////////////////////////////////////////////////////////////////////
// Iterator access
+ /**
+ * Access to the start of the direct children sequence.
+ * @return iterator pointing to the first element of the direct children sequence.
+ */
iterator begin();
+
+ /**
+ * Const access to the start of the direct children sequence.
+ * @return const_iterator pointing to the first element of the direct children sequence.
+ */
const_iterator begin() const;
+
+ /**
+ * Access to the end of the direct children sequence.
+ * @return iterator pointing just past the end of the direct children sequence.
+ */
iterator end();
+
+ /**
+ * Const access to the end of the direct children sequence.
+ * @return const_iterator pointing just past the end of the direct children sequence.
+ */
const_iterator end() const;
+
+ /**
+ * Access to the start of the reversed direct children sequence.
+ * @return reverse_iterator pointing to first element of the reversed direct children sequence.
+ */
reverse_iterator rbegin();
+
+ /**
+ * Const access to the start of the reversed direct children sequence.
+ * @return const_reverse_iterator pointing to first element of the reversed direct children sequence.
+ */
const_reverse_iterator rbegin() const;
+
+ /**
+ * Access to the end of the reverse direct children sequence.
+ * @return reverse_iterator pointing just past the end of the reversed direct children sequence.
+ */
reverse_iterator rend();
+
+ /**
+ * Const access to the end of the reverse direct children sequence.
+ * @return const_reverse_iterator pointing just past the end of the reversed direct children sequence.
+ */
const_reverse_iterator rend() const;
-
+
///////////////////////////////////////////////////////////////////////////
// Data access
- size_type size() const;
+ /**
+ * The size fo the direct children sequnce.
+ * @return Number of direct children of the property tree.
+ */
+ size_type size() const;
+
size_type max_size() const;
+
+ /**
+ * Determine whether the children sequence is empty.
+ * @note empty() should be prefered over <tt>size() == 0</tt>
+ * @retval true There are no direct children.
+ * @retval false There is at least one direct child.
+ */
bool empty() const;
-
+
+ /**
+ * Retruns a reference to the data of a property tree.
+ * @return Reference to the stored data which can be used to modify the data.
+ */
data_type &data();
+
+ /**
+ * Returns a const reference to the data of a property tree.
+ * @return Const reference to the stored data.
+ */
const data_type &data() const;
+ /**
+ * Returns a reference to the first element in the direct children sequence.
+ * @pre !(this->empty())
+ * @return Reference to the first element in the direct children sequence.
+ */
value_type &front();
+
+ /**
+ * Returns a const reference to the first element in the direct children sequence.
+ * @pre !(this->empty())
+ * @return Const reference to the first element in the direct children sequence.
+ */
const value_type &front() const;
+
+ /**
+ * Returns a reference to the last element in the direct children sequence.
+ * @pre !(this->empty())
+ * @return Reference to the last element in the direct children sequence.
+ */
value_type &back();
+
+ /**
+ * Returns a const reference to the last element in the direct children sequence.
+ * @pre !(this->empty())
+ * @return Const reference to the last element in the direct children sequence.
+ */
const value_type &back() const;
///////////////////////////////////////////////////////////////////////////
// Operators
+ /**
+ * Replaces current contents of this property tree with another's contents.
+ * @param rhs The property tree to assign to this property tree.
+ */
self_type &operator =(const self_type &rhs);
+ /**
+ * Check for equality of property trees.
+ * @retval true If both property trees contain the same data values and equivalent
+ * children sequences, recusively.
+ * @retval false Otherwise.
+ */
bool operator ==(const self_type &rhs) const;
+
+ /**
+ * Check for inequality of property trees.
+ * @return !(*this == rhs)
+ */
bool operator !=(const self_type &rhs) const;
///////////////////////////////////////////////////////////////////////////
// Container operations
+ /**
+ * Finds direct child stored at specified key.
+ *
+ * If there is more than one child with the same key, the first one is
+ * returned. Time complexity is <tt>O(log n)</tt>. Keys equivalence is
+ * tested with a predicate supplied as basic_ptree template parameter.
+ * If childe is not found, returns end(). Both const and non-const
+ * versions are provided. To find non-direct children use get_child
+ * function.
+ *
+ * @param key The key to search in the direct children sequence.
+ * @return iterator pointing to the found sequence element, or end()
+ * if no such element exists.
+ */
iterator find(const key_type &key);
+
+ /**
+ * Finds direct child stored at specified key.
+ *
+ * If there is more than one child with the same key, the first one is
+ * returned. Time complexity is <tt>O(log n)</tt>. Keys equivalence is
+ * tested with a predicate supplied as basic_ptree template parameter.
+ * If child is not found, returns end(). Both const and non-const
+ * versions are provided. To find non-direct children use get_child
+ * function.
+ *
+ * @param key The key to search in the direct children sequence.
+ * @return const_iterator pointing to the found sequence element,
+ * or end() if no such element exists.
+ */
const_iterator find(const key_type &key) const;
+ /**
+ * Count the number of direct children with the given key.
+ *
+ * Keys equivalence is tested with a predicate supplied as basic_ptree
+ * template parameter.
+ * @param key Key to count.
+ * @return Number of direct children with given key.
+ */
size_type count(const key_type &key) const;
+ /**
+ * Recursively deletes all children of the property tree and clears the
+ * data from the property tree.
+ */
void clear();
+ /**
+ * Inserts a new direct child into the property tree.
+ *
+ * @param where Iterator pointing at the position where new element will be
+ * inserted. Passing begin() will insert at the front of the
+ * list. Passing end() will insert at the back. Any other
+ * valid iterator will insert in the appropriate place in the
+ * middle.
+ * @param value value to be inserted.
+ * @return iterator pointing to newly inserted element of the sequence.
+ */
iterator insert(iterator where, const value_type &value);
+
+ /**
+ * Inserts a range of direct children into the property tree.
+ *
+ * Time complexity is <tt>O(m log n)</tt>, where @c m is number of inserted
+ * children, @c n is number of existing children.
+ *
+ * @param where Iterator pointing at the position where new elements will be
+ * inserted. Passing begin() will insert at the front of the
+ * list. Passing end() will insert at the back. Any other
+ * valid iterator will insert in the appropriate place in the
+ * middle.
+ * @param first Iterator designating the first element of range to be
+ * inserted.
+ * @param last Iterator referring to just past the end of the range to be
+ * inserted.
+ */
template<class It> void insert(iterator where, It first, It last);
+ /**
+ * Erases a direct child from the property tree.
+ *
+ * @param where Iterator pointing at the child to be erased from the property tree.
+ * @return Iterator pointing to the element after the erased element of the sequence,
+ * or end() if the element erased was the last in the sequence.
+ */
iterator erase(iterator where);
+
+ /**
+ * Erases direct children from the property tree matching the given key.
+ *
+ * @param key Key designating child or children to erase.
+ * @return Number of children that were erased.
+ */
size_type erase(const key_type &key);
+
+ /**
+ * Erases a range of direct children from the property tree.
+ *
+ * @param first Iterator designating the first element of range to be
+ * erased.
+ * @param last Iterator referring to just past the end of the range to be
+ * erased.
+ */
template<class It> iterator erase(It first, It last);
+ /**
+ * Inserts a new direct child at the front of the sequence.
+ *
+ * Equivalent to insert(begin(), value).
+ * @param value Value to be inserted.
+ * @return Iterator pointing to newly inserted element of the sequence.
+ */
iterator push_front(const value_type &value);
+
+ /**
+ * Inserts a new direct child at the back of the sequence.
+ *
+ * Equivalent to insert(end(), value)
+ * @param value Value to be inserted.
+ * @return Iterator pointing to newly inserted element of the sequence.
+ */
iterator push_back(const value_type &value);
+ /**
+ * Erases the first direct child in the sequence.
+ *
+ * Equivalent to erase(begin()).
+ * @pre !(this->empty())
+ */
void pop_front();
+
+ /**
+ * Erases the last direct child in the sequence.
+ *
+ * Equivalent to erase(boost::prior(end())).
+ * @pre !(this->empty())
+ */
void pop_back();
+ /**
+ * Swaps contents of this property tree with the contents of another.
+ *
+ * Time complexity is <tt>O(1)</tt>.
+ * @param rhs Property tree with which to swap.
+ */
void swap(self_type &rhs);
+ /** Reverses the order of direct children in the property tree. */
void reverse();
+
+ /**
+ * Sorts direct children of the property tree in ascending order.
+ * @param tr The binary predicate used to sort child values of type @c #value_type.
+ * @post For each adjacent child of the sequence, @c v1 followed by @c v2,
+ * @c tr(v1,v2) evaluates to true.
+ */
template<class SortTr> void sort(SortTr tr);
///////////////////////////////////////////////////////////////////////////
// ptree operations
- // Get child ptree with default separator
+ /**
+ * Get a reference to the child property tree at the given path.
+ *
+ * Traverses the tree using the given path and retrieves a child property tree
+ * stored there. This function will retrieve indirect children if the path contains
+ * at least one separator.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @throw ptree_bad_path if child property tree cannot be located.
+ * @return A reference to the child property tree at the given path relative to this
+ * property tree.
+ */
self_type &get_child(const path_type &path);
+
+ /**
+ * Get a const reference to the child property tree at the given path.
+ *
+ * Traverses the tree using the given path and retrieves a child property tree
+ * stored there. This function will retrieve indirect children if the path contains
+ * at least one separator.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @throw ptree_bad_path if child property tree cannot be located.
+ * @return A const reference to the child property tree at the given path relative to this
+ * property tree.
+ */
const self_type &get_child(const path_type &path) const;
+
+ /**
+ * Get a reference to the child property tree at the given path or a default if none found.
+ *
+ * Traverses the tree using the given path and retrieves a child property tree
+ * stored there. This function will retrieve indirect children if the path contains
+ * at least one separator. If child isn't found then the @c default_value will be returned.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @param default_value The value to be returned if no child is found at @c path.
+ * @return A reference to the child property tree at the given path relative to this
+ * property tree or the @c default_value if that child isn't found
+ */
self_type &get_child(const path_type &path, self_type &default_value);
+
+ /**
+ * Get a const reference to the child property tree at the given path or a default if none found.
+ *
+ * Traverses the tree using the given path and retrieves a child property tree
+ * stored there. This function will retrieve indirect children if the path contains
+ * at least one separator. If child isn't found then the @c default_value will be returned.
+ * @note One use of default value is to return a reference to empty property tree if the
+ * required one is not found. In many cases, the subsequent code using the return
+ * value can be then made simpler. @see boost::property_tree::empty_ptree.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @param default_value The value to be returned if no child is found at @c path.
+ * @return A const reference to the child property tree at the given path relative to this
+ * property tree or the @c default_value if that child isn't found
+ */
const self_type &get_child(const path_type &path, const self_type &default_value) const;
+
+ /**
+ * Get a reference to the child property tree at the given path if it exists.
+ *
+ * Traverses the tree using the given path and retrieves a child property tree
+ * stored there. This function will retrieve indirect children if the path contains
+ * at least one separator.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @return If the child is found, the function returns boost::optional initialized with
+ * a reference to it. Otherwise it returns uninitialized boost::optional.
+ */
optional<self_type &> get_child_optional(const path_type &path);
+
+ /**
+ * Get a const reference to the child property tree at the given path if it exists.
+ *
+ * Traverses the tree using the given path and retrieves a child property tree
+ * stored there. This function will retrieve indirect children if the path contains
+ * at least one separator.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @return If the child is found, the function returns boost::optional initialized with
+ * a const reference to it. Otherwise it returns uninitialized boost::optional.
+ */
optional<const self_type &> get_child_optional(const path_type &path) const;
- // Put child ptree with default separator
+ /**
+ * Traverses the tree using given path, and inserts a new property tree or replaces
+ * existing one. If any of the intermediate keys specified by path does not exist,
+ * it is inserted, with empty data and no children, at the back of existing sequence.
+ *
+ * For example, if @c path is "key1.key2.key3", the function will find a child designated
+ * by "key1.key2" path. This child will be checked for presence of "key3" subkey. If it
+ * exists, it will be replaced with the one specified by value parameter. If it does not
+ * exist, "key3" will be added at the back of existing sequence (if any). If either
+ * "key1" or "key1.key2" do not exist, the function will insert them as well.
+ *
+ * This function is a complement to @c #get_child. If @c put_child(path,value) was called,
+ * @c get_child(path) will return a reference to element inserted/replaced by put_child.
+ *
+ * @param path Location to place value. A sequence of keys with zero or more separator
+ * characters.
+ * @param value Property tree to be inserted as a child of this property tree.
+ * @param do_not_replace If set to true, causes function to always insert a new key,
+ * even if there already exists key with the same name.
+ * @return Reference to the inserted property tree.
+ */
self_type &put_child(const path_type &path, const self_type &value, bool do_not_replace = false);
- // Get value from data of ptree
+ /**
+ * Extracts value stored in property tree data and translates it to Type using
+ * the given translator.
+ * @throw ptree_bad_data If data cannot be translated to an instance of @c Type
+ * using the given translator_type.
+ * @param x Translator to use to extract and convert the contained #data_type to @c Type
+ * using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
+ * @return The extracted value as an instance of @c Type.
+ */
template<class Type> Type get_value(const translator_type &x = translator_type()) const;
+
+ /**
+ * Extracts value stored in property tree data and translates it to Type using the
+ * given translator. If extraction does not succeed then return the given default value.
+ * @param default_value The value to be returned if the the given translator cannot
+ * extract the data as an instance of @c Type.
+ * @param x Translator to use to extract and convert the contained #data_type to @c Type
+ * using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
+ * @return The extracted value as an instance of @c Type if extraction succeeds.
+ * Otherwise it returns the @c default_value.
+ */
template<class Type> Type get_value(const Type &default_value, const translator_type &x = translator_type()) const;
+
+ /**
+ * Extracts value stored in property tree data and translates it to @c std::basic_string<CharType>
+ * using the given translator. If extraction does not succeed then return the given default string.
+ * @param default_value The string to be returned if the the given translator cannot
+ * extract the data as an instance of @c Type.
+ * @param x Translator to use to extract and convert the contained #data_type to @c std::basic_string<CharType>
+ * using <tt>bool translator_type::get_value(self_type const&, std::basic_string<CharType>&)</tt>.
+ * @return The extracted value as an instance of @c std::basic_string<CharType> if extraction succeeds.
+ * Otherwise it returns the @c default_value.
+ */
template<class CharType> std::basic_string<CharType> get_value(const CharType *default_value, const translator_type &x = translator_type()) const;
+
+ /**
+ * Extracts value stored in property tree data and translates it to Type using the
+ * given translator.
+ * @param default_value The value to be returned if the the given translator cannot
+ * extract the data as an instance of @c Type.
+ * @param x Translator to use to extract and convert the contained #data_type to @c Type
+ * using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
+ * @return The extracted value as an instance of @c Type if extraction succeeds.
+ * Otherwise it returns an uninitialized @c boost::optional<Type>.
+ */
template<class Type> optional<Type> get_value_optional(const translator_type &x = translator_type()) const;
- // Get value from data of child ptree (default path separator)
+ /**
+ * Get the property tree value at the given path.
+ *
+ * Traverses the tree using the given path and retrieves the value stored there.
+ * This function will retrieve values of indirect children if the path contains at least
+ * one separator. The value will be converted to an instance of @c Type using the
+ * given translator.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @param x Translator to use to extract and convert the contained #data_type to @c Type
+ * using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
+ * @throw ptree_bad_path if child property tree cannot be located using the given path.
+ * @return The child property tree's value at the given path relative to this
+ * property tree.
+ */
template<class Type> Type get(const path_type &path, const translator_type &x = translator_type()) const;
+
+ /**
+ * Get the property tree value at the given path or a default if none found.
+ *
+ * Traverses the tree using the given path and retrieves the value stored there
+ * This function will retrieve values of indirect children if the path contains at least
+ * one separator. The value will be converted to an instance of @c Type using the
+ * given translator. If child isn't found then the @c default_value will be returned.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @param default_value The value to be returned if no child is found at @c path
+ * or translation fails.
+ * @param x Translator to use to extract and convert the contained #data_type to @c Type
+ * using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
+ * @return The child property tree's value at the given path relative to this
+ * property tree or the @c default_value if that child is not found.
+ */
template<class Type> Type get(const path_type &path, const Type &default_value, const translator_type &x = translator_type()) const;
+
+ /**
+ * Get the property tree value as @c std::basic_string<CharType> at the given path
+ * or a default if none found.
+ *
+ * Traverses the tree using the given path and retrieves the value stored there
+ * This function will retrieve values of indirect children if the path contains at least
+ * one separator. The value will be converted to an instance of
+ * @c std::basic_string<CharType> using the given translator. If child isn't
+ * found then the @c default_value will be returned.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @param default_value The string to be returned if no child is found at @c path
+ * or translation fails.
+ * @param x Translator to use to extract and convert the contained #data_type to @c std::basic_string<CharType>
+ * using <tt>bool translator_type::get_value(self_type const&, std::basic_string<CharType>&)</tt>.
+ * @return The child property tree's value as @c std::basic_string<CharType> at
+ * the given path relative to this property tree or the @c default_value
+ * if that child is not found or translation fails.
+ */
template<class CharType> std::basic_string<CharType> get(const path_type &path, const CharType *default_value, const translator_type &x = translator_type()) const;
+
+ /**
+ * Get the property tree value at the given path or an uninitialized
+ * @c boost::optional<Type> if none found.
+ *
+ * Traverses the tree using the given path and retrieves the value stored there
+ * This function will retrieve values of indirect children if the path contains at least
+ * one separator. The value will be converted to an instance of @c Type using the
+ * given translator. If child isn't found then an unitialized @c boost::optional<Type>
+ * will be returned.
+ * @param path A sequence of keys with zero or more separator characters.
+ * Can indicate indirect children if path contains at least one separator
+ * character.
+ * @param x Translator to use to extract and convert the contained #data_type to @c Type
+ * using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
+ * @return The child property tree's value at the given path relative to this
+ * property tree or an unitialized @c boost::optional<Type> if that child is not
+ * found or translation fails.
+ */
template<class Type> optional<Type> get_optional(const path_type &path, const translator_type &x = translator_type()) const;
- // Put value in data of ptree
+ /**
+ * Store the given value as the data of this property tree.
+ *
+ * Translates @c value from @c Type to @c #data_type using the given translator, and stores the
+ * result as the data value of this property tree.
+ * @throw ptree_bad_data If the given value cannot be translated to @c #data_type.
+ * @param value The parameter to store as the data of this property tree.
+ * @param x Translator to use to convert @c value to an instance of @c #data_type
+ * using <tt>bool translator_type::put_value(self_type&,Type const&)</tt>.
+ */
template<class Type> void put_value(const Type &value, const translator_type &x = translator_type());
- // Put value in data of child ptree (default path separator)
+ /**
+ * Traverses the tree using given path, and inserts a new value or replaces existing one.
+ * If any of the intermediate keys specified by path does not exist, it is inserted,
+ * with empty data and no children, at the back of existing sequence.
+ *
+ * For example, if @c path is "key1.key2.key3", the function will find a child designated
+ * by "key1.key2" path. This child will be checked for presence of "key3" subkey. If it
+ * exists, it will be replaced with the one specified by value parameter. If it does not
+ * exist, "key3" will be added at the back of existing sequence (if any). If either
+ * "key1" or "key1.key2" do not exist, the function will insert them as well.
+ *
+ * This function is a complement to @c #get. If @c put(path,value) was called,
+ * @c get(path) will return the value inserted by @c #put.
+ *
+ * @param path Location to place value. A sequence of keys with zero or more separator
+ * characters.
+ * @param value value to be inserted as the data of a child of this property tree.
+ * @param do_not_replace If set to true, causes function to always insert a new key,
+ * even if there already exists key with the same name.
+ * @param x Translator to use to convert @c value to an instance of @c #data_type
+ * using <tt>bool translator_type::put_value(self_type&,Type const&)</tt>.
+ * @return Reference to the property tree where the value was inserted. It is either a
+ * newly inserted property tree or an existing one if it was there prior to
+ * this call.
+ */
template<class Type> self_type &put(const path_type &path, const Type &value, bool do_not_replace = false, const translator_type &x = translator_type());
private:
@@ -200,12 +720,17 @@
///////////////////////////////////////////////////////////////////////////
// basic_path class template
+ /** Class template used to represent a path containing a sequence of Key instances. */
template<class Key>
class basic_path
{
-
- private:
-
+#if defined(BOOST_PROPERTY_TREE_DOXYGEN_INVOKED)
+ public:
+#endif
+ /**
+ * Simpler way to refer to the Key::value_type type.
+ * Do not use in client code; exposed only for documentation purposes.
+ */
typedef typename Key::value_type char_type;
public:
@@ -213,25 +738,75 @@
///////////////////////////////////////////////////////////////////////
// Construction & destruction
+ /** Constructs an empty basic_path<Key> instance */
basic_path();
+
+ /**
+ * Constructs an path using the given path using the given separator to split it.
+ * @param path The path to which to initialize the constructed instance.
+ * @param separator The separator to use to split the @c path parameter.
+ */
basic_path(const Key &path, char_type separator = char_type('.'));
+
+ /**
+ * Constructs an path using the given path using the given separator to split it.
+ * @param path The path to which to initialize the constructed instance. This
+ * path instance must be terminated with char_type('\\0');
+ * @param separator The separator to use to split the @c path parameter.
+ */
basic_path(const char_type *path, char_type separator = char_type('.'));
-
+
///////////////////////////////////////////////////////////////////////
// Path manipulation
+ /**
+ * Append the given path to this instance.
+ * @param rhs The path to append.
+ * @return A reference to this path instance after appending @c rhs.
+ */
basic_path<Key> &operator /=(const basic_path<Key> &rhs);
+
+ /**
+ * Convert this path instance to a @c std::string representation.
+ * @return A string representation of this path.
+ */
std::string to_string() const;
///////////////////////////////////////////////////////////////////////
// Operations
+ /**
+ * Extract the child subtree of the given property tree at the location indicated
+ * by this path instance.
+ * @param root The property tree from which to extract the child subtree.
+ * @return Pointer to the child subtree of the input property tree indicated by the
+ * location given by this path instance. If no child exists at the indicated
+ * location then NULL is returned.
+ */
template<class C, class D, class X>
basic_ptree<C, Key, basic_path<Key>, D, X> *get_child(basic_ptree<C, Key, basic_path<Key>, D, X> &root) const;
-
+
+ /**
+ * Extract the child subtree of the given property tree at the location indicated
+ * by this path instance.
+ * @param root The property tree from which to extract the child subtree.
+ * @return Pointer to the constant child subtree of the input property tree indicated by the
+ * location given by this path instance. If no child exists at the indicated
+ * location then NULL is returned.
+ */
template<class C, class D, class X>
const basic_ptree<C, Key, basic_path<Key>, D, X> *get_child(const basic_ptree<C, Key, basic_path<Key>, D, X> &root) const;
+ /**
+ * Insert or replace in the given property tree at the location indicated by this path
+ * instance the second given property tree as a child.
+ * @param root The property tree in which to insert or replace the child.
+ * @param child The property tree to insert within the tree given by that @c root parameter.
+ * @param do_not_replace If set to true, causes function to always insert a new key,
+ * even if there already exists key with the same name. Otherwise
+ * @return Pointer to the child property tree inserted at the given location
+ * location given by this path instance. If this path is empty then return NULL.
+ */
template<class C, class D, class X>
basic_ptree<C, Key, basic_path<Key>, D, X> *put_child(basic_ptree<C, Key, basic_path<Key>, D, X> &root,
const basic_ptree<C, Key, basic_path<Key>, D, X> &child,
@@ -255,11 +830,34 @@
{
public:
-
+ /** Default construct a translator instance. */
translator();
+
+ /**
+ * Construct a translator instance setting the internal locale state using
+ * the given input locale.
+ * @param loc The locale to use in this instance.
+ */
translator(const std::locale &loc);
+ /**
+ * Extract data value from the given property tree and convert it to an
+ * instance of type @c T.
+ * @param pt Property tree from which to retrieve the data value.
+ * @param[out] value The variable in which to store the retrieved data value.
+ * @return @c true If the data value was sucessfully converted and retrieved.
+ * Otherwise return @c false.
+ */
template<class Ptree, class T> bool get_value(const Ptree &pt, T &value) const;
+
+ /**
+ * Insert the given value as the data member in the given property tree after
+ * converting it to instance of type @c Ptree::data_type.
+ * @param pt Property tree in which to insert the given value as data.
+ * @param value The value to store as data in the given property tree.
+ * @return @c true If the data value was sucessfully converted and retrieved.
+ * Otherwise return @c false.
+ */
template<class Ptree, class T> bool put_value(Ptree &pt, const T &value) const;
private:
@@ -271,55 +869,66 @@
///////////////////////////////////////////////////////////////////////////
// exceptions
- // Base error class
+ /// Base class for all property tree errors. Derives from @c std::runtime_error.
+ /// Call member function @c what to get human readable message associated with the error.
class ptree_error: public std::runtime_error
{
-
public:
-
+ /// Instantiate a ptree_error instance with the given message.
+ /// @param what The message to associate with this error.
ptree_error(const std::string &what);
- ~ptree_error() throw();
+ ~ptree_error() throw();
};
- // Bad data
+
+ /// Error indicating that translation from given value to the property tree data_type
+ /// (or vice versa) failed. Derives from ptree_error.
class ptree_bad_data: public ptree_error
{
-
public:
-
+ /// Instantiate a ptree_bad_data instance with the given message and data.
+ /// @param what The message to associate with this error.
+ /// @param data The value associated with this error that was the source of the
+ /// translation failure.
template<class T> ptree_bad_data(const std::string &what, const T &data);
+
~ptree_bad_data() throw();
+
+ /// Retrieve the data associated with this error. This is the source value that
+ /// failed to be translated.
template<class T> T data();
-
private:
-
boost::any m_data;
-
};
-
- // Bad path
+
+
+ /// Error indicating that specified path does not exist. Derives from ptree_error.
class ptree_bad_path: public ptree_error
{
-
public:
-
+ /// Instantiate a ptree_bad_path with the given message and path data.
+ /// @param what The message to associate with this error.
+ /// @param path The path that could not be found in the property_tree.
template<class T> ptree_bad_path(const std::string &what, const T &path);
+
~ptree_bad_path() throw();
- template<class T> T path();
+ /// Retrieve the invalid path.
+ template<class T> T path();
private:
-
boost::any m_path;
-
};
} }
// Include implementations
#include <boost/property_tree/detail/ptree_implementation.hpp>
-#include <boost/property_tree/detail/exceptions_implementation.hpp>
+// FIXME: There's a very nasty order dependency between exceptions_impl and
+// the other two headers on compilers that do really compliant ADL, like
+// GCC 4.3.
#include <boost/property_tree/detail/path_implementation.hpp>
#include <boost/property_tree/detail/translator_implementation.hpp>
+#include <boost/property_tree/detail/exceptions_implementation.hpp>
#endif
Modified: trunk/boost/property_tree/ptree_fwd.hpp
==============================================================================
--- trunk/boost/property_tree/ptree_fwd.hpp (original)
+++ trunk/boost/property_tree/ptree_fwd.hpp 2009-03-13 12:03:25 EDT (Fri, 13 Mar 2009)
@@ -31,22 +31,61 @@
///////////////////////////////////////////////////////////////////////////
// Typedefs
+ /** Implements a path using a std::string as the key. */
typedef basic_path<std::string> path;
+
+ /** Implements a path using a std::wstring as the key. */
typedef basic_path<std::wstring> wpath;
+ /**
+ * A property tree that uses a path type based upon std::string.
+ * Comparisons of keys are performed in a case-sensitive manner.
+ */
typedef basic_ptree<std::less<std::string>, std::string, path, std::string, translator> ptree;
+
+ /**
+ * A property tree that uses a path type based upon std::string.
+ * Comparisons of keys are performed in a case-insensitive manner.
+ */
typedef basic_ptree<detail::less_nocase<std::string>, std::string, path, std::string, translator> iptree;
+
#ifndef BOOST_NO_CWCHAR
+ /**
+ * A property tree that uses a wide-character path type based upon std::wstring.
+ * Comparisons of keys are performed in a case-sensitive manner.
+ * @note The type only exists if the platform supports @c wchar_t.
+ */
typedef basic_ptree<std::less<std::wstring>, std::wstring, wpath, std::wstring, translator> wptree;
+
+ /**
+ * A property tree that uses a wide-character path type based upon std::wstring.
+ * Comparisons of keys are performed in a case-insensitive manner.
+ * @note The type only exists if the platform supports @c wchar_t.
+ */
typedef basic_ptree<detail::less_nocase<std::wstring>, std::wstring, wpath, std::wstring, translator> wiptree;
#endif
///////////////////////////////////////////////////////////////////////////
// Free functions
- template<class C, class K, class P, class D, class X> void swap(basic_ptree<C, K, P, D, X> &pt1, basic_ptree<C, K, P, D, X> &pt2);
+ /**
+ * Swap two property tree instances.
+ * @param pt1 Reference to first property tree involved in swap.
+ * @param pt2 Reference to second property tree involved in swap.
+ */
+ template<class C, class K, class P, class D, class X>
+ void swap(basic_ptree<C, K, P, D, X> &pt1, basic_ptree<C, K, P, D, X> &pt2);
+
+ /**
+ * Reference to empty property tree. Can be used as a default value of get_child.
+ * See empty_ptree_trick.cpp for example of usage.
+ */
template<class Ptree> const Ptree &empty_ptree();
+
+ /** Join two path objects. */
path operator /(const path &p1, const path &p2);
+
+ /** Join two wide-path objects. */
wpath operator /(const wpath &p1, const wpath &p2);
} }
Modified: trunk/boost/property_tree/ptree_serialization.hpp
==============================================================================
--- trunk/boost/property_tree/ptree_serialization.hpp (original)
+++ trunk/boost/property_tree/ptree_serialization.hpp 2009-03-13 12:03:25 EDT (Fri, 13 Mar 2009)
@@ -24,6 +24,18 @@
///////////////////////////////////////////////////////////////////////////
// boost::serialization support
+ /**
+ * Serialize the property tree to the given archive.
+ * @note In addition to serializing to regular archives, this supports serializing to
+ * archives requiring name-value pairs, e.g. XML archives. However, the output
+ * format in the XML archive is not guaranteed to be the same as that when using
+ * the Boost.PropertyTree library's @c boost::property_tree::xml_parser::write_xml.
+ * @param ar The archive to which to save the serialized property tree. This archive
+ * should conform to the concept laid out by the Boost.Serialization library.
+ * @param t The property tree to serialize.
+ * @param file_version file_version for the archive.
+ * @post @c ar will contain the serialized form of @c t.
+ */
template<class Archive, class C, class K, class P, class D, class X>
inline void save(Archive &ar,
const basic_ptree<C, K, P, D, X> &t,
@@ -33,6 +45,17 @@
ar << serialization::make_nvp("data", t.data());
}
+ /**
+ * De-serialize the property tree to the given archive.
+ * @note In addition to de-serializing from regular archives, this supports loading from
+ * archives requiring name-value pairs, e.g. XML archives. The format should be
+ * that used by boost::property_tree::save.
+ * @param ar The archive from which to load the serialized property tree. This archive
+ * should conform to the concept laid out by the Boost.Serialization library.
+ * @param t The property tree to de-serialize.
+ * @param file_version file_version for the archive.
+ * @post @c t will contain the de-serialized data from @c ar.
+ */
template<class Archive, class C, class K, class P, class D, class X>
inline void load(Archive &ar,
basic_ptree<C, K, P, D, X> &t,
@@ -53,6 +76,13 @@
}
+ /**
+ * Load or store the property tree using the given archive.
+ * @param ar The archive from which to load or save the serialized property tree.
+ * The type of this archive will determine whether saving or loading is performed.
+ * @param t The property tree to load or save.
+ * @param file_version file_version for the archive.
+ */
template<class Archive, class C, class K, class P, class D, class X>
inline void serialize(Archive &ar,
basic_ptree<C, K, P, D, X> &t,
Modified: trunk/boost/property_tree/xml_parser.hpp
==============================================================================
--- trunk/boost/property_tree/xml_parser.hpp (original)
+++ trunk/boost/property_tree/xml_parser.hpp 2009-03-13 12:03:25 EDT (Fri, 13 Mar 2009)
@@ -36,7 +36,20 @@
namespace boost { namespace property_tree { namespace xml_parser
{
- // Read XML from stream
+ /**
+ * Reads XML from an input stream and translates it to property tree.
+ * @note Clears existing contents of property tree. In case of error the property tree unmodified.
+ * @note XML attributes are placed under keys named @c \<xmlattr\>.
+ * @throw xml_parser_error In case of error deserializing the property tree.
+ * @param stream Stream from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ * @param flags Flags controlling the bahviour of the parser.
+ * The following flags are supported:
+ * @li @c no_concat_text -- Prevents concatenation of text nodes into datastring
+ * of property tree. Puts them in separate @c \<xmltext\>
+ * strings instead.
+ * @li @c no_comments -- Skip XML comments.
+ */
template<class Ptree>
void read_xml(std::basic_istream<typename Ptree::key_type::value_type> &stream,
Ptree &pt,
@@ -45,7 +58,21 @@
read_xml_internal(stream, pt, flags, std::string());
}
- // Read XML from file
+ /**
+ * Reads XML from a file using the given locale and translates it to property tree.
+ * @note Clears existing contents of property tree. In case of error the property tree unmodified.
+ * @note XML attributes are placed under keys named @c \<xmlattr\>.
+ * @throw xml_parser_error In case of error deserializing the property tree.
+ * @param filename The file from which to read in the property tree.
+ * @param[out] pt The property tree to populate.
+ * @param flags Flags controlling the bahviour of the parser.
+ * The following flags are supported:
+ * @li @c no_concat_text -- Prevents concatenation of text nodes into datastring
+ * of property tree. Puts them in separate @c \<xmltext\>
+ * strings instead.
+ * @li @c no_comments -- Skip XML comments.
+ * @param loc The locale to use when reading in the file contents.
+ */
template<class Ptree>
void read_xml(const std::string &filename,
Ptree &pt,
@@ -60,7 +87,15 @@
read_xml_internal(stream, pt, flags, filename);
}
- // Write XML to stream
+ /**
+ * Translates the property tree to XML and writes it the given output stream.
+ * @throw xml_parser_error In case of error translating the property tree to XML
+ * or writing to the output stream.
+ * @param stream The stream to which to write the XML representation of the
+ * property tree.
+ * @param pt The property tree to tranlsate to XML and output.
+ * @param settings The settings to use when writing out the property tree as XML.
+ */
template<class Ptree>
void write_xml(std::basic_ostream<typename Ptree::key_type::value_type> &stream,
const Ptree &pt,
@@ -69,7 +104,16 @@
write_xml_internal(stream, pt, std::string(), settings);
}
- // Write XML to file
+ /**
+ * Translates the property tree to XML and writes it the given file.
+ * @throw xml_parser_error In case of error translating the property tree to XML
+ * or writing to the output stream.
+ * @param filename The file to which to write the XML representation of the
+ * property tree.
+ * @param pt The property tree to tranlsate to XML and output.
+ * @param loc The locale to use when writing the output to file.
+ * @param settings The settings to use when writing out the property tree as XML.
+ */
template<class Ptree>
void write_xml(const std::string &filename,
const Ptree &pt,
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk