Class document

Inheritance Relationships

Base Type

Class Documentation

class document : public mxml::element_container

mxml::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 mxml::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 mxml::element child node even though it is derived from mxml::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=

document(std::string_view s)

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

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() = 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 MXML 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.