## Class document

zeep::xml::document

## Synopsis

    // In header: </home/maarten/projects/libzeep/zeep/xml/document.hpp>

    class document {
    public:
      // construct/copy/destruct
      document();
      document(const std::string &);
      document(std::istream &);
      document(std::istream &, const boost::filesystem::path &);

      // public member functions
      void read(const std::string &);
      void read(std::istream &);
      void read(std::istream &, const boost::filesystem::path &);
      void write(writer &) const;
      template<typename T> void serialize(const char *, const T &);
      template<typename T> void deserialize(const char *, T &);
      root_node * root() const;
      element * child() const;
      void child(element *);
      element_set find(const std::string &) const;
      element * find_first(const std::string &) const;
      element_set find(const char *) const;
      element * find_first(const char *) const;
      void find(const char *, node_set &) const;
      void find(const char *, element_set &) const;
      node * find_first_node(const char *) const;
      bool operator==(const document &) const;
      bool operator!=(const document &) const;
      void base_dir(const boost::filesystem::path &);
      encoding_type encoding() const;
      void encoding(encoding_type);
      int indent() const;
      void indent(int);
      bool wrap() const;
      void wrap(bool);
      bool trim() const;
      void trim(bool);
      bool no_comment() const;
      void no_comment(bool);
      void set_validating(bool);
      void set_preserve_cdata(bool);

      // public data members
      boost::function< std::istream *(const std::string &base, const std::string &pubid, const std::string &sysid)> external_entity_ref_handler;
    };

## Description

zeep::xml::document is the class that contains a parsed XML file. You can create an empty document and add nodes to it, or you can create it by specifying a string containing XML or an std::istream to parse.

If you use an std::fstream to read a file, be sure to open the file ios::binary. Otherwise, the detection of text encoding might go wrong or the content can become corrupted.

Default is to parse CDATA sections into zeep::xml::text nodes. If you want to preserve CDATA sections in the DOM tree, you have to call set_preserve_cdata before reading the file.

By default a document is not validated. But you can turn on validation by using the appropriate constructor or read method, or by setting set_validating explicitly. The DTD's will be loaded from the base dir specified, but you can change this by assigning a external_entity_ref_handler.

A document has one zeep::xml::root_node element. This root element can have only one zeep::xml::element child node.

### `document` public construct/copy/destruct

1.     document();

   Constructor for an empty document.

2.     document(const std::string & s);

   Constructor that will parse the XML passed in argument s.

3.     document(std::istream & is);

   Constructor that will parse the XML passed in argument is.

4.     document(std::istream & is, const boost::filesystem::path & base_dir);

   Constructor that will parse the XML passed in argument is. This constructor will also validate the input using DTD's found in base_dir.

### `document` public member functions

1.     void read(const std::string & s);

   Replace the content of the document with the parsed XML in s.

2.     void read(std::istream & is);

   Replace the content of the document with the parsed XML in is.

3.     void read(std::istream & is, const boost::filesystem::path & base_dir);

   Replace the content of the document with the parsed XML in is and use validation based on DTD's found in base_dir.

4.     void write(writer & w) const;

   Write the contents of the document as XML using `zeep::xml::writer` object w.

5.     template<typename T> void serialize(const char * name, const T & data);

   Serialization support.

   Serialize data into a document containing name as root node

6.     template<typename T> void deserialize(const char * name, T & data);

   Deserialize root node with name name into data.

7.     root_node * root() const;

   A valid xml document contains exactly one `zeep::xml::root_node` element.

8.     element * child() const;

   The root has one child `zeep::xml::element`.

9.     void child(element * e);

10.     element_set find(const std::string & path) const;

    < Return all zeep::xml::elements that match the XPath query path

11.     element * find_first(const std::string & path) const;

    < Return the first `zeep::xml::element` that matches the XPath query path

12.     element_set find(const char * path) const;

    Return all zeep::xml::elements that match the XPath query path.

13.     element * find_first(const char * path) const;

    Return the first `zeep::xml::element` that matches the XPath query path.

14.     void find(const char * path, node_set & nodes) const;

    Return all zeep::xml::nodes (attributes or elements) that match the XPath query path.

15.     void find(const char * path, element_set & elements) const;

    Return all zeep::xml::elements that match the XPath query path.

16.     node * find_first_node(const char * path) const;

    Return the first `zeep::xml::node` (attribute or element) that matches the XPath query path.

17.     bool operator==(const document & doc) const;

    Compare two xml documents.

18.     bool operator!=(const document & doc) const;

19.     void base_dir(const boost::filesystem::path & path);

    If you want to validate the document using DTD files stored on disk, you can specifiy this directory prior to reading the document.

20.     encoding_type encoding() const;

    The text encoding as detected in the input.

21.     void encoding(encoding_type enc);

    The text encoding to use for output.

22.     int indent() const;

    get number of spaces to indent elements:

23.     void indent(int indent);

    set number of spaces to indent elements:

24.     bool wrap() const;

    get wrap flag, whether elements will appear on their own line or not

25.     void wrap(bool wrap);

    set wrap flag, whether elements will appear on their own line or not

26.     bool trim() const;

    get trim flag, strips white space in #PCDATA sections

27.     void trim(bool trim);

    set trim flag, strips white space in #PCDATA sections

28.     bool no_comment() const;

    get no_comment flag, suppresses the output of XML comments

29.     void no_comment(bool no_comment);

    get no_comment flag, suppresses the output of XML comments

30.     void set_validating(bool validate);

    options for parsing validating uses a DTD if it is defined

31.     void set_preserve_cdata(bool preserve_cdata);

    preserve cdata, preserves CDATA sections instead of converting them into text nodes.

### `document` public public data members

1.     boost::function< std::istream *(const std::string &base, const std::string &pubid, const std::string &sysid)> external_entity_ref_handler;

   The default for libzeep is to locate the external reference based on sysid and base_dir. Only local files are loaded this way. You can specify a entity loader here if you want to be able to load DTD files from another source.