ALPS Project

Header file parser/xmlstream.h

This header contains a stream class and helper functions to output a well-formatted XML document.

Synopsis

namespace alps {

class oxstream
{
public:
  oxstream();
  oxstream(std::ostream& os, boost::uint32_t incr = 2);
  oxstream(const boost::filesystem::path& file, boost::uint32_t incr = 2);

  oxstream& operator<<(const std::string& t);
  oxstream& operator<<(const char t);
  oxstream& operator<<(const char * t);
  oxstream& operator<<(const bool t);
  oxstream& operator<<(const signed char t);
  oxstream& operator<<(const unsigned char t);
  oxstream& operator<<(const short t);
  oxstream& operator<<(const unsigned short t);
  oxstream& operator<<(const int t);
  oxstream& operator<<(const unsigned int t);
  oxstream& operator<<(const long t);
  oxstream& operator<<(const unsigned long t);
  oxstream& operator<<(const long long t);
  oxstream& operator<<(const unsigned long long t);
  oxstream& operator<<(const float t);
  oxstream& operator<<(const double t);
  oxstream& operator<<(const long double t);

  oxstream& operator<<(const XMLAttribute& c);
  oxstream& operator<<(const XMLAttributes& c);

  // for manipulators
  template<class T> oxstream& operator<<(T (*fn)(const std::string&));
  oxstream& operator<<(oxstream& (*fn)(oxstream& oxs));

  std::ostream& stream();
};

// manipulator functions

detail::header_t header(const std::string& enc);
detail::start_tag_t start_tag(const std::string& name);
detail::stylesheet_t stylesheet(const std::string& url);
detail::end_tag_t end_tag(const std::string& name = "");
template<class T> detail::attribute_t attribute(const std::string& name, const T& value);
detail::pi_t processing_instruction(const std::string& name);
detail::attribute_t xml_namespace(const std::string& name, const std::string& url);
oxstream& start_comment(oxstream& oxs);
oxstream& end_comment(oxstream& oxs);
oxstream& start_cdata(oxstream& oxs);
oxstream& end_cdata(oxstream& oxs);
oxstream& no_linebreak(oxstream& oxs);

std::string convert(const std::string& str);

} // namespace alps

The oxmlstream class

The oxstream class is a stream class to output a well-formatted XML document. Normally the data output into the oxstream are simply redirected to the output stream (std::cout by default). The oxstream class also accepts various manipulators for printing tags, attributes, comments, etc in a well-formatted way.

Member functions

oxstream();
default constructor. By default, the output stream is std::cout.
oxstream(std::ostream& os, boost::uint32_t incr = 2);
constracts an oxstream with the output stream set to os. If incr is provided, the offset increment is set to incr.
oxstream(const boost::filesystem::path& file, boost::uint32_t incr = 2);
constracts an oxstream which outputs into a file file. If incr is provided, the offset increment is set to incr.
oxstream& operator<<(const std::string& t);
outputs a string to the stream. Note that special characters, such as "&"and "<", are not automatically replaced by the character entities. Use the convert helper function explicitly for escaping special characters.
oxstream& operator<<(const char t);
oxstream& operator<<(const char * t);
oxstream& operator<<(const bool t);
oxstream& operator<<(const signed char t);
oxstream& operator<<(const unsigned char t);
oxstream& operator<<(const short t);
oxstream& operator<<(const unsigned short t);
oxstream& operator<<(const int t);
oxstream& operator<<(const unsigned int t);
oxstream& operator<<(const long t);
oxstream& operator<<(const unsigned long t);
oxstream& operator<<(const long long t);
oxstream& operator<<(const unsigned long long t);
oxstream& operator<<(const float t);
oxstream& operator<<(const double t);
oxstream& operator<<(const long double t);
outputs POD data to the stream. Note that special characters, such as "&"and "<", are not automatically replaced by the character entities. Use the convert helper function explicitly for escaping special characters.
oxstream& operator<<(const XMLAttribute& c);
adds an attribute to the current start tag (see also Manipulators).
oxstream& operator<<(const XMLAttributes& c);
adds attribute tos the current start tag (see also Manipulators).

Functions

std::string convert(const std::string& str);

The convert helper function converts special characters (&, ', >, <, ") in the string into the character entities (&amp;, &apos;, &gt;, &lt;, &quot;).

template<class T> std::string precision(const T& d, int n)

The precision helper function generates a string with a given precision from a floating point number.

Manipulators

The following manipulators are provided for helping XML formating.

header

outputs a standard XML header, eg.
<?xml version="1.0"?>

header(const std::string& enc)

outputs a standard XML header with the attribute encoding, eg.
<?xml version="1.0" encoding="enc"?>

styleseet(const std::string& url)

outputs a styleseet tag, eg.
<?xml-stylesheet type="text/xsl" href="URL to my stylesheet"?>

processing_instruction(const std::string& name)

outputs a processing instruction, eg.
<?my-processing-instruction?>

start_tag(const std::string& name)

outputs a start tag with a given name.

template<class T> attribute(const std::string& name, const T& value)

adds an attribute with a given name and a value to the current start tag.

xml_namespace(const std::string& name, const std::string& url)

adds a namespace attribute to the current start tag, eg.
<mytag xmlns:MyNameSpace="MyURL">

end_tag

closes the current tag.

end_tag(const std::string& name)

closes the current tag, if name is not consistent with the start tag, an exception will be thrown.

start_comment

starts a comment. Texts until the next end_comment manipulator will be treated as a comment.

end_comment

ends the current comment.

start_cdata

starts a CDATA section.

end_cdata

ends the current CDATA section.

no_linebreak

By default, oxstream starts a new line after each start tag and before each end tag with a proper indent. This manipulator tells to oxstream that the contents of the current tag should be printed out on the same line without linebreaks.

Examples

double x = 3.14;
alps::oxstream oxs;
oxs << alps::header("MyEncoding");
oxs << alps::stylesheet("URL to my stylesheet")
    << alps::processing_instruction("my_pi");
oxs << alps::start_tag("tag0")
    << alps::attribute("name0", 1)
    << "this is a text"
    << alps::start_tag("tag1")
    << alps::start_tag("tag2")
    << alps::xml_namespace("MyNameSpace", "MyURL")
    << "text 2 "
    << "text 3 " << std::endl
    << alps::precision(3.14159265358979323846, 3) << ' '
    << alps::precision(3.14159265358979323846, 6) << '\n'
    << "text 4" << std::endl
    << alps::convert("text <&\">'")
    << alps::start_tag("tag3")
    << alps::end_tag
    << x
    << alps::start_tag("tag4") << alps::no_linebreak
    << "no linebreak"
    << alps::end_tag
    << alps::end_tag("tag2")
    << alps::end_tag("tag1")
    << alps::end_tag;
will print out the following XML to the standard output.
<?xml version="1.0" encoding="MyEncoding"?>
<?xml-stylesheet type="text/xsl" href="URL to my stylesheet"?>
<?my_pi?>
<tag0 name0="1">
  this is a text
  <tag1>
    <tag2 xmlns:MyNameSpace="MyURL">
      text 2 text 3 
      3.14 3.14159
      text 4
      text &lt;&amp;&quot;&gt;&apos;
      <tag3/>
      3.14
      <tag4>no linebreak</tag4>
    </tag2>
  </tag1>
</tag0>

copyright (c) 1994-2010 by Matthias Troyer

Distributed under the Boost Software License, Version 1.0. (See http://www.boost.org/LICENSE_1_0.txt)