boost/property_tree/xml_parser.hpp

   1 // ----------------------------------------------------------------------------
   2 // Copyright (C) 2002-2006 Marcin Kalicinski
   3 // Copyright (C) 2009 Sebastian Redl
   4 //
   5 // Distributed under the Boost Software License, Version 1.0.
   6 // (See accompanying file LICENSE_1_0.txt or copy at
   7 // http://www.boost.org/LICENSE_1_0.txt)
   8 //
   9 // For more information, see www.boost.org
  10 // ----------------------------------------------------------------------------
  11 #ifndef BOOST_PROPERTY_TREE_XML_PARSER_HPP_INCLUDED
  12 #define BOOST_PROPERTY_TREE_XML_PARSER_HPP_INCLUDED
  13
  14 #include <boost/property_tree/ptree.hpp>
  15 #include <boost/property_tree/detail/xml_parser_write.hpp>
  16 #include <boost/property_tree/detail/xml_parser_error.hpp>
  17 #include <boost/property_tree/detail/xml_parser_writer_settings.hpp>
  18 #include <boost/property_tree/detail/xml_parser_flags.hpp>
  19 #include <boost/property_tree/detail/xml_parser_read_rapidxml.hpp>
  20
  21 #include <fstream>
  22 #include <string>
  23 #include <locale>
  24
  25 namespace boost { namespace property_tree { namespace xml_parser
  26 {
  27
  28     /**
  29      * Reads XML from an input stream and translates it to property tree.
  30      * @note Clears existing contents of property tree.  In case of error the
  31      *       property tree unmodified.
  32      * @note XML attributes are placed under keys named @c \<xmlattr\>.
  33      * @throw xml_parser_error In case of error deserializing the property tree.
  34      * @param stream Stream from which to read in the property tree.
  35      * @param[out] pt The property tree to populate.
  36      * @param flags Flags controlling the behaviour of the parser.
  37      *              The following flags are supported:
  38      * @li @c no_concat_text -- Prevents concatenation of text nodes into
  39      *                          datastring of property tree.  Puts them in
  40      *                          separate @c \<xmltext\> strings instead.
  41      * @li @c no_comments -- Skip XML comments.
  42      * @li @c trim_whitespace -- Trim leading and trailing whitespace from text,
  43      *                           and collapse sequences of whitespace.
  44      */
  45     template<class Ptree>
  46     void read_xml(std::basic_istream<
  47                       typename Ptree::key_type::value_type
  48                   > &stream,
  49                   Ptree &pt,
  50                   int flags = 0)
  51     {
  52         read_xml_internal(stream, pt, flags, std::string());
  53     }
  54
  55     /**
  56      * Reads XML from a file using the given locale and translates it to
  57      * property tree.
  58      * @note Clears existing contents of property tree.  In case of error the
  59      *       property tree unmodified.
  60      * @note XML attributes are placed under keys named @c \<xmlattr\>.
  61      * @throw xml_parser_error In case of error deserializing the property tree.
  62      * @param filename The file from which to read in the property tree.
  63      * @param[out] pt The property tree to populate.
  64      * @param flags Flags controlling the bahviour of the parser.
  65      *              The following flags are supported:
  66      * @li @c no_concat_text -- Prevents concatenation of text nodes into
  67      *                          datastring of property tree.  Puts them in
  68      *                          separate @c \<xmltext\> strings instead.
  69      * @li @c no_comments -- Skip XML comments.
  70      * @param loc The locale to use when reading in the file contents.
  71      */
  72     template<class Ptree>
  73     void read_xml(const std::string &filename,
  74                   Ptree &pt,
  75                   int flags = 0,
  76                   const std::locale &loc = std::locale())
  77     {
  78         BOOST_ASSERT(validate_flags(flags));
  79         std::basic_ifstream<typename Ptree::key_type::value_type>
  80             stream(filename.c_str());
  81         if (!stream)
  82             BOOST_PROPERTY_TREE_THROW(xml_parser_error(
  83                 "cannot open file", filename, 0));
  84         stream.imbue(loc);
  85         read_xml_internal(stream, pt, flags, filename);
  86     }
  87
  88     /**
  89      * Translates the property tree to XML and writes it the given output
  90      * stream.
  91      * @throw xml_parser_error In case of error translating the property tree to
  92      *                         XML or writing to the output stream.
  93      * @param stream The stream to which to write the XML representation of the
  94      *               property tree.
  95      * @param pt The property tree to tranlsate to XML and output.
  96      * @param settings The settings to use when writing out the property tree as
  97      *                 XML.
  98      */
  99     template<class Ptree>
 100     void write_xml(std::basic_ostream<
 101                        typename Ptree::key_type::value_type
 102                    > &stream,
 103                    const Ptree &pt,
 104                    const xml_writer_settings<
 105                        typename Ptree::key_type::value_type
 106                    > & settings = xml_writer_settings<
 107                                     typename Ptree::key_type::value_type>() )
 108     {
 109         write_xml_internal(stream, pt, std::string(), settings);
 110     }
 111
 112     /**
 113      * Translates the property tree to XML and writes it the given file.
 114      * @throw xml_parser_error In case of error translating the property tree to
 115      *                         XML or writing to the output stream.
 116      * @param filename The file to which to write the XML representation of the
 117      *                 property tree.
 118      * @param pt The property tree to tranlsate to XML and output.
 119      * @param loc The locale to use when writing the output to file.
 120      * @param settings The settings to use when writing out the property tree as
 121      *                 XML.
 122      */
 123     template<class Ptree>
 124     void write_xml(const std::string &filename,
 125                    const Ptree &pt,
 126                    const std::locale &loc = std::locale(),
 127                    const xml_writer_settings<
 128                        typename Ptree::key_type::value_type
 129                    > & settings = xml_writer_settings<
 130                                     typename Ptree::key_type::value_type>())
 131     {
 132         std::basic_ofstream<typename Ptree::key_type::value_type>
 133             stream(filename.c_str());
 134         if (!stream)
 135             BOOST_PROPERTY_TREE_THROW(xml_parser_error(
 136                 "cannot open file", filename, 0));
 137         stream.imbue(loc);
 138         write_xml_internal(stream, pt, filename, settings);
 139     }
 140
 141 } } }
 142
 143 namespace boost { namespace property_tree
 144 {
 145     using xml_parser::read_xml;
 146     using xml_parser::write_xml;
 147     using xml_parser::xml_parser_error;
 148
 149     using xml_parser::xml_writer_settings;
 150     using xml_parser::xml_writer_make_settings;
 151 } }
 152
 153 #endif