Index: boost/property_tree/ini_parser.hpp =================================================================== --- boost/property_tree/ini_parser.hpp (revision 46158) +++ boost/property_tree/ini_parser.hpp (working copy) @@ -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 void read_ini(std::basic_istream &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 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 O(n log n) time. + */ template void write_ini(std::basic_ostream &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 O(n log n) time. + * @param loc The locale to use when writing the file. + */ template void write_ini(const std::string &filename, const Ptree &pt, Index: boost/property_tree/ptree_serialization.hpp =================================================================== --- boost/property_tree/ptree_serialization.hpp (revision 46158) +++ boost/property_tree/ptree_serialization.hpp (working copy) @@ -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 inline void save(Archive &ar, const basic_ptree &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 inline void load(Archive &ar, basic_ptree &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 inline void serialize(Archive &ar, basic_ptree &t, Index: boost/property_tree/xml_parser.hpp =================================================================== --- boost/property_tree/xml_parser.hpp (revision 46158) +++ boost/property_tree/xml_parser.hpp (working copy) @@ -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 . + * @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 + * strings instead. + * @li @c no_comments -- Skip XML comments. + */ template void read_xml(std::basic_istream &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 . + * @throw xml_parser_error In case of error deserializing the property tree. + * @param file 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 + * strings instead. + * @li @c no_comments -- Skip XML comments. + * @param loc The locale to use when reading in the file contents. + */ template 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 void write_xml(std::basic_ostream &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 file 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 void write_xml(const std::string &filename, const Ptree &pt, Index: boost/property_tree/ptree.hpp =================================================================== --- boost/property_tree/ptree.hpp (revision 46158) +++ boost/property_tree/ptree.hpp (working copy) @@ -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 #include -// 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 basic_ptree { +#if defined(BOOST_PROPERTY_TREE_DOXYGEN_INVOKED) + public: +#endif + // Internal types + /** + * Simpler way to refer to this basic_ptree type. + * Do not use in client code; exposed only for documentation purposes. + */ + typedef basic_ptree self_type; - private: - - // Internal types - typedef basic_ptree 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 value_type; private: - // Internal types typedef std::list 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 size() == 0 + * @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 O(log n). 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 O(log n). 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 O(m log n), 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 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 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 O(1). + * @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 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 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 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 bool translator_type::get_value(self_type const&, Type&). + * @return The extracted value as an instance of @c Type. + */ template 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 detaul_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 bool translator_type::get_value(self_type const&, Type&). + * @return The extracted value as an instance of @c Type if extraction succeeds. + * Otherwise it returns the @c default_value. + */ template 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 + * using the given translator. If extraction does not succeed then return the given default string. + * @param detaul_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 + * using bool translator_type::get_value(self_type const&, std::basic_string&). + * @return The extracted value as an instance of @c std::basic_string if extraction succeeds. + * Otherwise it returns the @c default_value. + */ template std::basic_string 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 detaul_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 bool translator_type::get_value(self_type const&, Type&). + * @return The extracted value as an instance of @c Type if extraction succeeds. + * Otherwise it returns an uninitialized @c boost::optional. + */ template optional 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 bool translator_type::get_value(self_type const&, Type&). + * @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 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 bool translator_type::get_value(self_type const&, Type&). + * @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 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 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 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 + * using bool translator_type::get_value(self_type const&, std::basic_string&). + * @return The child property tree's value as @c std::basic_string at + * the given path relative to this property tree or the @c default_value + * if that child is not found or translation fails. + */ template std::basic_string 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 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 + * 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 bool translator_type::get_value(self_type const&, Type&). + * @return The child property tree's value at the given path relative to this + * property tree or an unitialized @c boost::optional if that child is not + * found or translation fails. + */ template optional 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 bool translator_type::put_value(self_type&,Type const&). + */ template 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 bool translator_type::put_value(self_type&,Type const&). + * @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 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 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 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 &operator /=(const basic_path &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 basic_ptree, D, X> *get_child(basic_ptree, 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 const basic_ptree, D, X> *get_child(const basic_ptree, 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 basic_ptree, D, X> *put_child(basic_ptree, D, X> &root, const basic_ptree, D, X> &child, @@ -255,11 +830,34 @@ { public: + /** Default construct a translator instance. */ + translator(); - 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 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 bool put_value(Ptree &pt, const T &value) const; private: @@ -271,47 +869,55 @@ /////////////////////////////////////////////////////////////////////////// // 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(); - }; - // 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 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 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 ptree_bad_path(const std::string &what, const T &path); + ~ptree_bad_path() throw(); + + /// Retrieve the invalid path. template T path(); - private: - boost::any m_path; - }; } } Index: boost/property_tree/ptree_fwd.hpp =================================================================== --- boost/property_tree/ptree_fwd.hpp (revision 46158) +++ boost/property_tree/ptree_fwd.hpp (working copy) @@ -31,22 +31,61 @@ /////////////////////////////////////////////////////////////////////////// // Typedefs + /** Implements a path using a std::string as the key. */ typedef basic_path path; + + /** Implements a path using a std::wstring as the key. */ typedef basic_path 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::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, 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::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, std::wstring, wpath, std::wstring, translator> wiptree; #endif /////////////////////////////////////////////////////////////////////////// // Free functions - template void swap(basic_ptree &pt1, basic_ptree &pt2); + /** + * Swap two property tree instances. + * @param pt1 Reference to first property tree involved in swap. + * @param[in/out] pt2 Reference to second property tree involved in swap. + */ + template + void swap(basic_ptree &pt1, basic_ptree &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 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); } } Index: boost/property_tree/json_parser.hpp =================================================================== --- boost/property_tree/json_parser.hpp (revision 46158) +++ boost/property_tree/json_parser.hpp (working copy) @@ -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 void read_json(std::basic_istream &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 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 void write_json(std::basic_ostream &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 void write_json(const std::string &filename, const Ptree &pt, Index: boost/property_tree/info_parser.hpp =================================================================== --- boost/property_tree/info_parser.hpp (revision 46158) +++ boost/property_tree/info_parser.hpp (working copy) @@ -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 void read_info(std::basic_istream &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 void read_info(std::basic_istream &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 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 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 void write_info(std::basic_ostream &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 void write_info(const std::string &filename, const Ptree &pt,