# Class document

- Defined in File document.hpp

## Inheritance Relationships

### Base Type

- `public zeem::element_container` (Class element_container)

## Class Documentation

class document : public zeem::element_container

  zeem::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 parsing a string or an std::istream containing XML.

  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 zeem::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 can have only one zeem::element child node even though it is derived from zeem::element_container. The document object itself is the so-called root-node.

  Public Functions

  inline virtual node_type type() const override

    node_type of a document

  document()

    Constructor for an empty document.

  document(const document &doc)

    Copy constructor.

  inline document(document &&other) noexcept

    Move constructor.

  inline document &operator=(document doc) noexcept

    operator=

  explicit document(std::string_view s)

    Constructor that will parse the XML passed in argument s using default settings.

  explicit document(std::istream &is)

    Constructor that will parse the XML passed in argument is using default settings.

  document(std::istream &is, std::string 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() override = default
  inline bool is_validating() const

    options for parsing validating uses a DTD if it is defined

  inline void set_validating(bool validate)
  inline bool is_validating_ns() const

    validating_ns: when validating take the NS 1.0 specification into account

  inline void set_validating_ns(bool validate)
  inline bool preserves_cdata() const

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

  inline void set_preserve_cdata(bool p)

    if p is true, the CDATA sections will be preserved when parsing XML, if p is false, the content of the CDATA will be treated as text

  inline bool collapses_empty_tags() const

    collapse means replacing e.g. `<foo></foo>` with `<foo/>`

  inline void set_collapse_empty_tags(bool c)

    if c is true, empty tags will be replaced, i.e. write `<foo/>` instead of `<foo></foo>`

  inline bool write_html() const

    collapse ‘empty elements’ according to HTML rules

  inline void set_write_html(bool f)

    if c is true, ‘empty elements’ will be collapsed according to HTML rules

  inline bool suppresses_comments() const

    whether to write out comments

  inline void set_suppress_comments(bool s)

    if s is true, comments will not be written

  inline bool escapes_white_space() const

    whether to escape white space

  inline void set_escape_white_space(bool e)

    if e is true, white space will be written as XML entities

  inline bool escapes_double_quote() const

    whether to escape double quotes

  inline void set_escape_double_quote(bool e)

    if e is true, double quotes will be written as “

  inline bool wraps_prolog() const

    whether to place a newline after a prolog

  inline void set_wrap_prolog(bool w)

    if w is true, a newline will be written after the XML prolog

  inline doc_type get_doctype() const

    Get the doctype as parsed.

  inline void set_doctype(std::string root, std::string pubid, std::string dtd)

    Set the doctype to write out.

  inline void set_doctype(const doc_type &doctype)

    Set the doctype to write out.

  inline bool writes_xml_decl() const

    whether to write a XML prolog

  inline void set_write_xml_decl(bool w)

    if w is true, an XML prolog will be written

  inline bool writes_doctype() const

    whether to write a DOCTYPE

  inline void set_write_doctype(bool f)

    if f is true a DOCTYPE will be written

  bool is_html5() const

    Check the doctype to see if this is supposed to be HTML5.

  bool operator==(const document &doc) const

    Compare two xml documents.

  void set_base_dir(std::string path)

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

  template<typename Callback>
  inline void set_entity_loader(Callback &&cb)

    Set a callback for loading external entities.

    The default for ZEEM 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.

  encoding_type get_encoding() const

    The text encoding as detected in the input.

  void set_encoding(encoding_type enc)

    The text encoding to use for output.

  version_type get_version() const

    XML version, should be either 1.0 or 1.1.

  void set_version(version_type v)

    XML version, should be either 1.0 or 1.1.

  inline virtual element_container *root() override

    The root node, which is the document of course.

  inline virtual const element_container *root() const override

    The root node, which is the document of course.

  inline element *child()

    Return the single child, or nullptr in case the document is empty.

  inline const element *child() const

    Return the single child, or nullptr in case the document is empty.

  template<typename ...Args>
  inline auto emplace(Args&&... args)

    Emplace a single element using args for the construction.

  virtual std::string str() const override

    Return the concatenation of all contained text nodes.

  Friends

  friend void swap(document &a, document &b) noexcept
  friend std::ostream &operator<<(std::ostream &os, const document &doc)

    Write out the document.

  friend std::istream &operator>>(std::istream &is, document &doc)

    Read in a document.