boost/property_tree/xml_parser.hpp

0001 // ----------------------------------------------------------------------------
0002 // Copyright (C) 2002-2006 Marcin Kalicinski
0003 // Copyright (C) 2009 Sebastian Redl
0004 //
0005 // Distributed under the Boost Software License, Version 1.0.
0006 // (See accompanying file LICENSE_1_0.txt or copy at
0007 // http://www.boost.org/LICENSE_1_0.txt)
0008 //
0009 // For more information, see www.boost.org
0010 // ----------------------------------------------------------------------------
0011 #ifndef BOOST_PROPERTY_TREE_XML_PARSER_HPP_INCLUDED
0012 #define BOOST_PROPERTY_TREE_XML_PARSER_HPP_INCLUDED
0013
0014 #include <boost/property_tree/ptree.hpp>
0015 #include <boost/property_tree/detail/xml_parser_write.hpp>
0016 #include <boost/property_tree/detail/xml_parser_error.hpp>
0017 #include <boost/property_tree/detail/xml_parser_writer_settings.hpp>
0018 #include <boost/property_tree/detail/xml_parser_flags.hpp>
0019 #include <boost/property_tree/detail/xml_parser_read_rapidxml.hpp>
0020
0021 #include <fstream>
0022 #include <string>
0023 #include <locale>
0024
0025 namespace boost { namespace property_tree { namespace xml_parser
0026 {
0027
0028     /**
0029      * Reads XML from an input stream and translates it to property tree.
0030      * @note Clears existing contents of property tree.  In case of error the
0031      *       property tree unmodified.
0032      * @note XML attributes are placed under keys named @c \<xmlattr\>.
0033      * @throw xml_parser_error In case of error deserializing the property tree.
0034      * @param stream Stream from which to read in the property tree.
0035      * @param[out] pt The property tree to populate.
0036      * @param flags Flags controlling the behaviour of the parser.
0037      *              The following flags are supported:
0038      * @li @c no_concat_text -- Prevents concatenation of text nodes into
0039      *                          datastring of property tree.  Puts them in
0040      *                          separate @c \<xmltext\> strings instead.
0041      * @li @c no_comments -- Skip XML comments.
0042      * @li @c trim_whitespace -- Trim leading and trailing whitespace from text,
0043      *                           and collapse sequences of whitespace.
0044      */
0045     template<class Ptree>
0046     void read_xml(std::basic_istream<
0047                       typename Ptree::key_type::value_type
0048                   > &stream,
0049                   Ptree &pt,
0050                   int flags = 0)
0051     {
0052         read_xml_internal(stream, pt, flags, std::string());
0053     }
0054
0055     /**
0056      * Reads XML from a file using the given locale and translates it to
0057      * property tree.
0058      * @note Clears existing contents of property tree.  In case of error the
0059      *       property tree unmodified.
0060      * @note XML attributes are placed under keys named @c \<xmlattr\>.
0061      * @throw xml_parser_error In case of error deserializing the property tree.
0062      * @param filename The file from which to read in the property tree.
0063      * @param[out] pt The property tree to populate.
0064      * @param flags Flags controlling the bahviour of the parser.
0065      *              The following flags are supported:
0066      * @li @c no_concat_text -- Prevents concatenation of text nodes into
0067      *                          datastring of property tree.  Puts them in
0068      *                          separate @c \<xmltext\> strings instead.
0069      * @li @c no_comments -- Skip XML comments.
0070      * @param loc The locale to use when reading in the file contents.
0071      */
0072     template<class Ptree>
0073     void read_xml(const std::string &filename,
0074                   Ptree &pt,
0075                   int flags = 0,
0076                   const std::locale &loc = std::locale())
0077     {
0078         BOOST_ASSERT(validate_flags(flags));
0079         std::basic_ifstream<typename Ptree::key_type::value_type>
0080             stream(filename.c_str());
0081         if (!stream)
0082             BOOST_PROPERTY_TREE_THROW(xml_parser_error(
0083                 "cannot open file", filename, 0));
0084         stream.imbue(loc);
0085         read_xml_internal(stream, pt, flags, filename);
0086     }
0087
0088     /**
0089      * Translates the property tree to XML and writes it the given output
0090      * stream.
0091      * @throw xml_parser_error In case of error translating the property tree to
0092      *                         XML or writing to the output stream.
0093      * @param stream The stream to which to write the XML representation of the
0094      *               property tree.
0095      * @param pt The property tree to tranlsate to XML and output.
0096      * @param settings The settings to use when writing out the property tree as
0097      *                 XML.
0098      */
0099     template<class Ptree>
0100     void write_xml(std::basic_ostream<
0101                        typename Ptree::key_type::value_type
0102                    > &stream,
0103                    const Ptree &pt,
0104                    const xml_writer_settings<
0105                        typename Ptree::key_type
0106                    > & settings = xml_writer_settings<
0107                                     typename Ptree::key_type>() )
0108     {
0109         write_xml_internal(stream, pt, std::string(), settings);
0110     }
0111
0112     /**
0113      * Translates the property tree to XML and writes it the given file.
0114      * @throw xml_parser_error In case of error translating the property tree to
0115      *                         XML or writing to the output stream.
0116      * @param filename The file to which to write the XML representation of the
0117      *                 property tree.
0118      * @param pt The property tree to tranlsate to XML and output.
0119      * @param loc The locale to use when writing the output to file.
0120      * @param settings The settings to use when writing out the property tree as
0121      *                 XML.
0122      */
0123     template<class Ptree>
0124     void write_xml(const std::string &filename,
0125                    const Ptree &pt,
0126                    const std::locale &loc = std::locale(),
0127                    const xml_writer_settings<
0128                        typename Ptree::key_type
0129                    > & settings = xml_writer_settings<typename Ptree::key_type>())
0130     {
0131         std::basic_ofstream<typename Ptree::key_type::value_type>
0132             stream(filename.c_str());
0133         if (!stream)
0134             BOOST_PROPERTY_TREE_THROW(xml_parser_error(
0135                 "cannot open file", filename, 0));
0136         stream.imbue(loc);
0137         write_xml_internal(stream, pt, filename, settings);
0138     }
0139
0140 } } }
0141
0142 namespace boost { namespace property_tree
0143 {
0144     using xml_parser::read_xml;
0145     using xml_parser::write_xml;
0146     using xml_parser::xml_parser_error;
0147
0148     using xml_parser::xml_writer_settings;
0149     using xml_parser::xml_writer_make_settings;
0150 } }
0151
0152 #endif