boost/property_tree
2
0
Fork 0
mirror of https://github.com/boostorg/property_tree.git synced 2026-02-21 15:22:12 +00:00
Code Issues Projects Releases Wiki Activity

Apply doxygen docs patch by Ryan Gallagher, with minor corrections

Browse Source 
[SVN r51750]
This commit is contained in:
Sebastian Redl
2009-03-13 16:03:25 +00:00
parent 7c9eef0cbf
commit a86f93cc86
7 changed files with 930 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
include/boost/property_tree/info_parser.hpp
View File

@@ -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 @@ namespace boost { namespace property_tree { namespace info_parser
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 @@ namespace boost { namespace property_tree { namespace info_parser
}
}
// 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 @@ namespace boost { namespace property_tree { namespace info_parser
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 @@ namespace boost { namespace property_tree { namespace info_parser
}
}
// 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 @@ namespace boost { namespace property_tree { namespace info_parser
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,

66
include/boost/property_tree/ini_parser.hpp
View File

@@ -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 @@ namespace boost { namespace property_tree { namespace ini_parser
}
};
//! 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 @@ namespace boost { namespace property_tree { namespace ini_parser
}
//! 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 @@ namespace boost { namespace property_tree { namespace ini_parser
}
}
//! 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 @@ namespace boost { namespace property_tree { namespace ini_parser
}
// 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,

54
include/boost/property_tree/json_parser.hpp
View File

@@ -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 @@ namespace boost { namespace property_tree { namespace json_parser
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 @@ namespace boost { namespace property_tree { namespace json_parser
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 @@ namespace boost { namespace property_tree { namespace json_parser
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,

697
include/boost/property_tree/ptree.hpp
View File

@@ -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 @@ namespace boost { namespace property_tree
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 @@ namespace boost { namespace property_tree
///////////////////////////////////////////////////////////////////////////
// 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 @@ namespace boost { namespace property_tree
///////////////////////////////////////////////////////////////////////
// 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 @@ namespace boost { namespace property_tree
{
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 @@ namespace boost { namespace property_tree
///////////////////////////////////////////////////////////////////////////
// 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();
/// 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

41
include/boost/property_tree/ptree_fwd.hpp
View File

@@ -31,22 +31,61 @@ namespace boost { namespace property_tree
///////////////////////////////////////////////////////////////////////////
// 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);
} }

30
include/boost/property_tree/ptree_serialization.hpp
View File

@@ -24,6 +24,18 @@ namespace boost { namespace property_tree
///////////////////////////////////////////////////////////////////////////
// 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 @@ namespace boost { namespace property_tree
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 @@ namespace boost { namespace property_tree
}
/**
* 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,

52
include/boost/property_tree/xml_parser.hpp
View File

@@ -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 @@ namespace boost { namespace property_tree { namespace xml_parser
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 @@ namespace boost { namespace property_tree { namespace xml_parser
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 @@ namespace boost { namespace property_tree { namespace xml_parser
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,