Parsing Options
===============

.. currentmodule:: pugixml.pugi

These flags control the contents of the resulting tree for all loading functions.

.. note::

   This is a bitmask that customizes the parsing process:
   to enable a flag, use ``mask | flag``; to disable a flag, use ``mask & ~flag``.

.. seealso::

   :meth:`XMLDocument.load_buffer`
   :meth:`XMLDocument.load_file`
   :meth:`XMLDocument.load_string`
   :meth:`XMLNode.append_buffer`

.. rubric:: Attributes

.. autoattribute:: pugixml.pugi.PARSE_CDATA

   This flag determines if CDATA sections (:attr:`NODE_CDATA`) are added to the DOM tree. This flag is on by default.

.. autoattribute:: pugixml.pugi.PARSE_COMMENTS

   This flag determines if comments (:attr:`NODE_COMMENT`) are added to the DOM tree. This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_DECLARATION

   This flag determines if document declaration (:attr:`NODE_DECLARATION`) is added to the DOM tree.
   This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_DEFAULT

   The default parsing mode.
   Elements, PCDATA and CDATA sections are added to the DOM tree, character/reference entities are expanded,
   End-of-Line characters are normalized, attribute values are normalized using CDATA normalization rules.

.. autoattribute:: pugixml.pugi.PARSE_DOCTYPE

   This flag determines if document type declaration (:attr:`NODE_DOCTYPE`) is added to the DOM tree. This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_EMBED_PCDATA

   This flag determines if plain character data is be stored in the parent element's value.
   This significantly changes the structure of the document;
   this flag is only recommended for parsing documents with many PCDATA nodes in memory-constrained environments.
   This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_EOL

   This flag determines if EOL characters are normalized (converted to #xA) during parsing. This flag is on by default.

.. autoattribute:: pugixml.pugi.PARSE_ESCAPES

   This flag determines if character and entity references are expanded during parsing. This flag is on by default.

.. autoattribute:: pugixml.pugi.PARSE_FRAGMENT

   This flag determines if plain character data that does not have a parent node is added to the DOM tree,
   and if an empty document is a valid document. This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_FULL

   The full parsing mode.
   Nodes of all types are added to the DOM tree, character/reference entities are expanded,
   End-of-Line characters are normalized, attribute values are normalized using CDATA normalization rules.

.. autoattribute:: pugixml.pugi.PARSE_MERGE_PCDATA

   This flag determines whether determines whether the the two PCDATA should be merged or not, if no intermediatory data are parsed in the document.
   This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_MINIMAL

   Minimal parsing mode (equivalent to turning all other flags off).
   Only elements and PCDATA sections are added to the DOM tree, no text conversions are performed.

.. autoattribute:: pugixml.pugi.PARSE_PI

   This flag determines if processing instructions (:attr:`NODE_PI`) are added to the DOM tree. This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_TRIM_PCDATA

   This flag determines if leading and trailing whitespace is to be removed from plain character data.
   This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_WCONV_ATTRIBUTE

   This flag determines if attribute values are normalized using CDATA normalization rules during parsing.
   This flag is on by default.

.. autoattribute:: pugixml.pugi.PARSE_WNORM_ATTRIBUTE

   This flag determines if attribute values are normalized using NMTOKENS normalization rules during parsing.
   This flag is off by default.

.. autoattribute:: pugixml.pugi.PARSE_WS_PCDATA

   This flag determines if plain character data (:attr:`NODE_PCDATA`) that consist only of whitespace are added to the DOM tree.
   This flag is off by default; turning it on usually results in slower parsing and more memory consumption.

.. autoattribute:: pugixml.pugi.PARSE_WS_PCDATA_SINGLE

   This flag determines if plain character data (:attr:`NODE_PCDATA`) that is the only child of the parent node and that consists only
   of whitespace is added to the DOM tree.
   This flag is off by default; turning it on may result in slower parsing and more memory consumption.