Home | API | Appendix

Table of Contents

API: lxl.lua

lxl.lua is the main interface for the library.

lxl.fragmentToString

Converts the children of an element to an XML string fragment.

local str = lxl.fragmentToString(element)

Returns: An XML string fragment.

Notes

The returned string never includes element's own tags or the XML Declaration, and its encoding is always UTF-8.

See Also

lxl.load

Loads an XML file from disk and converts it to an XmlObject using the default parser settings.

local xml_obj = lxl.load(path)

  • path: The file path.

Returns: The XmlObject.

Notes

This function is intended for use from the console and the Lua interactive prompt. If your host application provides its own functions to load files (like LÖVE’s love.filesystem), then you should probably use those instead.

See Also

lxl.newParser

Makes a new XmlParser object.

local parser = lxl.newParser()

Returns: An XmlParser with default settings.

lxl.newXmlObject

Creates a new XmlObject with no nodes.

local xml_obj = lxl.newXmlObject()

Returns: The new XmlObject.

lxl.toString

Converts an XmlObject to an XML string, using the default parser settings.

local str = lxl.toString(xml_obj)

  • xml_obj: The XmlObject to convert.

Returns: An XML string.

See Also

lxl.toTable

Converts an XML string to an XmlObject, using the default parser settings.

local xml_obj = lxl.toTable(str, [name])

  • str: The XML string to convert.

  • [name]: (nil) A name to display in warnings and error messages.

Returns: An XmlObject.

See also

API: CharacterData

CharacterData nodes are the document’s actual text content.

CharacterData:getCdSect

Gets the CharacterData’s cd_sect flag.

local enabled = CharacterData:getCdSect()

Returns: true or false.

See Also

CharacterData:getText

Gets the CharacterData’s text.

local text = CharacterData:getText()

Returns: The CharacterData text.

See Also

CharacterData:setCdSect

Sets the CharacterData’s cd_sect flag.

CharacterData:setCdSect(enabled)

  • enabled: true to enable CDATA Section output for this node, false/nil otherwise.

See Also

CharacterData:setText

Sets the CharacterData’s text.

CharacterData:setText(text)

  • text: The text to assign.

See Also

API: Comment

XML comments are supposed to be ignored by your application, though they still occupy nodes in the document’s tree structure.

Comment:getText

Gets the comment’s text.

local text = Comment:getText()

Returns: The comment text.

See Also

Comment:setText

Sets the comment’s text.

Comment:setText(text)

  • text: The text to assign.

Notes

XML comments are not allowed to contain the substring --, or to end with -.

See Also

API: Doctype

Holds the DOCTYPE name, along with comments and processing instructions that are found in the DTD Internal Subset.

This node does not fully represent the DOCTYPE and DTD internal subset, and it is not included when serializing out.

There is almost no reason to create this node manually, so no creation method is attached to the XmlObject.

API: Element

Elements make up the structure of an XML document.

Element:getAttribute

Gets an attribute value.

local val = Element:getAttribute(key)

  • key: The attribute name.

Returns: The attribute value, or nil if the attribute was not found.

See Also

Element:getName

Gets the element’s name.

local name = Element:getName()

Returns: The element’s name.

See Also

Element:getNamespace

Gets the element’s current namespace mapping.

local ns_uri = Element:getNamespace()

Returns: The namespace URI associated with this element, or nil if there isn’t one.

Notes

This method always returns nil when no namespace mode is set.

Element:getNamespaceAttribute

Gets an attribute that is mapped to a namespace.

local value, prefix = Element:getNamespaceAttribute(ns_uri, ns_local)

  • ns_uri: The namespace URI.

  • ns_local: The namespace local part.

Returns: The attribute value (or nil if it’s not populated for this namespace), and the prefix (if bound at this scope).

Notes

This method is unreliable if two attributes with the same local name but different prefixes resolve to the same namespace. Such a state is forbidden by the XML Namespace spec.

If multiple prefixes are mapped to the URI, then there is no defined order as to which prefix is selected and returned by this method.

The default namespace is never used with attributes; unprefixed attributes do not belong to a namespace.

This method always returns nil when no namespace mode is set.

Element:getNamespaceBinding

Gets a bound prefix for a namespace URI.

local ns_prefix = Element:getNamespaceBinding(ns_uri)

  • ns_uri: The namespace URI to check.

Returns: A bound prefix for the namespace URI, or nil if there is no binding at this scope.

Notes

If multiple prefixes are mapped to the namespace URI, then there is no defined order as to which prefix is selected and returned by this method.

This method does not consider the predefined prefixes xml and xmlns.

This method always returns nil when no namespace mode is set.

Element:getNamespaceDeclarations

Returns a table containing all namespace declarations from this element and its ancestors.

local decl = Element:getNamespaceDeclarations([_decl])

  • [_decl]: An optional existing table. Used internally to cut down on garbage generation. Note that the table’s contents are deleted.

Returns: A table of all active namespace declarations for this element.

Notes

This method always returns an empty table when no namespace mode is set.

Element:getStableAttributesOrder

Gets a stable order of attribute keys using a simple string sort.

local order = Element:getStableAttributesOrder()

Returns: An array of keys that correspond to the attributes table.

Element:getXmlSpecialAttribute

Looks for a special XML attribute in the element and its ancestors, up to the root element. Intended for checking xml:space and xml:lang.

Element:getXmlSpecialAttribute(local_name)

  • local_name: The second part of the attribute name, after the colon: space, lang

Returns: The attribute value and the element in which it was found, or nil if there was no match.

Element:newCharacterData

Adds a new CharacterData node.

local char_data = Element:newCharacterData(text, [cd_sect], [i])

  • text: The CharacterData’s text.

  • [cd_sect]: (nil) true if this CharacterData node should be serialized out as a CDATA Section.

  • [i]: (#nodes + 1) Where to insert the CharacterData in the node’s array of children.

Returns: A new CharacterData, attached directly to the calling element.

Element:newComment

Adds a new Comment node.

local comment = Element:newComment(text, [i])

  • text: The Comment text.

  • [i]: (#nodes + 1) Where to insert the Comment in the node’s array of children.

Returns: A new Comment node.

Element:newElement

Adds a new element.

local element = Element:newElement(name, [i])

  • name: The element name.

  • [i]: (#nodes + 1) Where to insert the element in the node’s array of children.

Returns: A new element, attached directly to the calling element.

Element:newProcessingInstruction

Adds a new Pi (processing instruction) node.

local pi = Element:newProcessingInstruction(name, text, [i])

  • name: The processing instruction target.

  • text: The processing instruction text.

  • [i]: (#nodes + 1) Where to insert the processing instruction in the node’s array of children.

Returns: A new Pi node.

Element:setAttribute

Sets an attribute name and value.

Element:setAttribute(key, value)

  • key: The attribute name.

  • value: The value to set. Pass nil to delete the attribute. Otherwise, this must be a string.

See Also

Element:setName

Sets the element’s name.

Element:setName(name)

  • name: The name to set.

See Also

API: Node

All nodes in an XmlObject tree have these shared methods.

Node:destroy

"Destroys" the node and all of its descendants.

Node:destroy()

Notes

The following occurs when destroying a node:

  • If applicable, recursively destroy all descendants

  • If applicable, remove node from parent’s list of siblings

  • Unset metatable

  • Erase all table contents

Node:find

Looks for a node among the calling node’s children.

local result = Node:find(id, [name], [i])

  • id: The node’s ID tag (type): cdata, comment, doctype, element, pi, unexp, xml_object.

  • [name]: The node’s name, if applicable. Pass nothing or nil for node types which do not have a name.

  • i: (1) Index of the first child to check.

Returns: A node that matches the search criteria, plus the node’s sibling index, or nil if there was no match.

Notes

This method is not namespace-aware. See Node:findInNamespace for finding namespaced elements.

The search does not include grandchildren, great-grandchildren, etc.

Searches for the unnamed nodes (cdata, comment and xml_object) must use nil for the name argument.

Node:findInNamespace

Looks for a namespaced element among the calling node’s children.

local result = Node:findInNamespace(ns_uri, ns_local, [i])

  • ns_uri: The namespace URI (not the prefix).

  • ns_local: The local name.

  • i: (1) Index of the first child to check.

Returns: A node that matches the search criteria, plus the node’s sibling index, or nil if there was no match.

Notes

The search includes namespaced element nodes only, as XML Namespaces do not apply to any other node type.

This method always returns nil when no namespace mode is set.

Node:getChild

Gets a node’s child by index.

local child = Node:getChild(n)

n: The child index.

Returns: The node’s Nth child, or nil if there is no child at that index.

Node:getNextSibling

Gets the node’s next sibling.

local sibling = Node:getNextSibling()

Returns: The node’s next sibling, or nil if either the node does not have siblings or it is the last sibling in the table.

Node:getParent

Gets the node’s parent.

local parent = Node:getParent()

Returns: The node’s parent, or nil if the node does not have a parent.

Node:getPreviousSibling

Gets the node’s previous sibling.

local sibling = Node:getPreviousSibling()

Returns: The node’s previous sibling, or nil if either the node does not have siblings or it is the first sibling in the table.

Node:getSiblings

Gets the nodes table in which this node is placed.

local siblings = Node:getSiblings()

Returns: The table of siblings, or nil if the node is an XmlObject (which does not have a parent).

Notes

The returned table is the internal array of nodes, not a copy.

Node:getXmlObject

Gets the root node (the XmlObject, not the XML root element).

local xml_obj = Node:getXmlObject()

Returns: The root XmlObject in the tree.

Node:resolvePath

Looks for an element based on a path string. Paths are not namespace-aware.

local resolved = Node:resolvePath(path, [simple])

  • path: The path string.

  • [simple]: (false) When true, disables . (this node), .. (parent node), and the ability to anchor the searches to the root node (by starting with /).

Returns: On success, the resolved node. Upon failure, nil, an error string, and the position in the path string where the search failed.

Notes

The path string contains element names that are separated by slashes. The call Node:resolvePath("foo/bar/baz") would look for a child of Node named foo, and then a grandchild named bar, and finally a great-grandchild named baz. For each generation, the first matching name is selected.

Paths starting with a forward slash are absolute, always starting from the root XmlObject node (not the document root). In this case, the first name in the path must match the root element name: Node:resolvePath("/myroot/foo")

A single forward slash will select the XmlObject node: Node:resolvePath("/")

.. may be used to move up one level, though attempting to go above the XmlObject node will fail. . selects the current node.

Only elements and the XmlObject root can be selected by name, but Node:resolvePath() can be called by any node object that is attached to the tree. This includes comments and processing instructions from within the internal subset.

When the simple argument is set, the special names . and .. will be interpreted literally, and anchoring the path to the root (ie /myroot/foo) will always fail.

Backslashes may be used to escape characters. It is an error to end a path string with a single backslash.

API: Pi (Processing Instruction)

Processing Instructions are messages for your application. Like comments, they aren’t really part of the document as presented to users.

Pi:getTarget

Gets the processing instruction’s target (name).

local target = Pi:getTarget()

Returns: The processing instruction’s target.

See Also

Pi:getText

Gets the processing instruction’s text.

local text = Pi:getText()

Returns: The processing instruction’s text.

See Also

Pi:setTarget

Sets the processing instruction’s target (name).

Pi:setTarget(target)

  • target: The target to assign.

See Also

Pi:setText

Sets the processing instruction’s text.

Pi:setText(text)

  • text: The text to assign.

Notes

XML processing instructions cannot contain the substring ?>.

See Also

API: Unexp

An Unexpanded Entity Reference is a general entity reference (e.g. &foobar;) that could not be expanded into its replacement text. Unexpanded references are not part of the core XML spec, but they do have an entry in the XML InfoSet.

More about Unexp nodes can be found in the appendix, but generally speaking, you will rarely (if ever) encounter them.

Unexp:getName

Gets the unexpanded entity’s name. (If the reference is &foo;, then the name would be foo.)

local name = Unexp:getName()

Returns: The unexpanded entity’s name.

See Also

Unexp:setName

Sets the unexpanded entity’s name.

Unexp:setName(name)

  • name: The name to assign.

See Also

API: XmlObject

XmlObjects represent a document as a tree of nodes. They can be created from a string (lxl.toTable, XmlParser:toTable) or by API calls (lxl.newXmlObject).

XmlObject:checkNamespaceState

Checks the namespace state of the XmlObject node tree, raising an error if any problems are found.

XmlObject:checkNamespaceState()

Notes

This method does nothing when namespace mode is inactive. Otherwise, it performs the same checks as XmlParser when loading a string. For more info, see Appendix: Invalid Namespace State.

XmlObject:getDoctype

Gets the Doctype node, if populated.

local dt = XmlObject:getDoctype()

Returns: The Doctype node, or nil.

XmlObject:getNamespaceMode

Gets the XmlObject’s current XML Namespace mode.

local mode = XmlObject:getNamespaceMode()

Returns: The namespace mode: 1.0, 1.1, or nil (disabled).

See Also

XmlObject:getRootElement

Gets the document root element. If the XmlObject does not have any elements, raises an error.

local root = XmlObject:getRootElement()

Returns: The root element.

XmlObject:getXmlEncoding

Gets the XML declaration’s encoding string.

local e = XmlObject:getXmlEncoding()

Returns: The XML declaration’s encoding string, or nil if it was not set.

See Also

XmlObject:getXmlStandalone

Gets the XML declaration’s standalone string.

local s = XmlObject:getXmlStandalone()

Returns: The XML declaration’s standalone string, or nil if it was not set.

Notes

When not set, assume the default value is no.

See Also

XmlObject:getXmlVersion

Gets the XML declaration’s version string.

local v = XmlObject:getXmlVersion()

Returns: The XML declaration’s version string, or nil if it was not set.

See Also

XmlObject:mergeCharacterData

Merges all adjacent CharacterData nodes in the XmlObject tree.

XmlObject:mergeCharacterData()

Notes

Comment and Pi nodes will prevent text before and after the node from being merged.

All affected CharacterData nodes will have their cd_sect flag reset to false.

XmlObject:newComment

Adds a new comment node, outside of the Document root element.

local comment = XmlObject:newComment(text, [i])

  • text: The comment text.

  • [i]: (#nodes + 1) Where to insert the comment in the XmlObject’s array of children.

Returns: A new comment node.

XmlObject:newElement

Adds a new element.

local element = XmlObject:newElement(name, [i])

  • name: The element name.

  • [i]: (#nodes + 1) Where to insert the element in the XmlObject’s array of children.

Returns: A new element, attached directly to the XmlObject.

Notes

Attaching more than one top-level element is forbidden by the XML spec.

XmlObject:newProcessingInstruction

Adds a new Pi (processing instruction) node, outside of the Document root element.

local pi = XmlObject:newProcessingInstruction(name, text, [i])

  • name: The processing instruction target.

  • text: The processing instruction text.

  • [i]: (#nodes + 1) Where to insert the processing instruction in the XmlObject’s array of children.

Returns: A new Pi node.

XmlObject:pruneNodes

Removes nodes of a specified type from the XmlObject tree. Nodes that can contain children (Element, Doctype, XmlObject) cannot be pruned, but their descendants will be checked.

XmlObject:pruneNodes(...)

  • …​: The list of node IDs to remove: cdata, comment, pi, unexp

XmlObject:pruneSpace

Deletes all CharacterData nodes which contain only whitespace characters (\r\n\t\32).

XmlObject:pruneSpace(xml_space)

  • xml_space When true, do not delete CharacterData nodes where the special attribute xml:space="preserve" is in effect.

Notes

This includes CharacterData nodes marked as CDATA Sections.

XmlObject:setNamespaceMode

Default: nil

Sets the XmlObject’s namespace mode.

XmlObject:setNamespaceMode(mode)

  • mode: The XML Namespace mode string (1.0, 1.1), or nil to disable namespace features.

See Also

XmlObject:setXmlEncoding

Sets the XML declaration’s encoding string.

XmlObject:setXmlEncoding(e)

  • e: The XML declaration’s encoding string: UTF-8, UTF-16, or nil to clear the value.

Notes

When not set, assume the default value is UTF-8.

A value of UTF-16 makes XmlParser:toString encode the output as UTF-16. The endianness is controlled by XmlParser:setWriteBigEndian.

See Also

XmlObject:setXmlStandalone

Sets the XML declaration standalone string.

XmlObject:setXmlStandalone(s)

  • s: The XML declaration’s standalone string: yes, no, or pass in nil to clear the value.

See Also

XmlObject:setXmlVersion

Sets the XML declaration’s version string.

XmlObject:setXmlVersion(v)

  • v: The XML declaration’s version string. Use nil to clear the value.

Notes

When not set, assume the default value is 1.0.

See Also

API: XmlParser

Use an XmlParser object if you want to change the parsing settings.

XmlParser:fragmentToString

Converts the children of an element to an XML string fragment.

local str = XmlParser:fragmentToString(element)

Returns: An XML string fragment.

Notes

The returned string never includes element's own tags or the XML Declaration, and its encoding is always UTF-8.

See Also

XmlParser:getCheckCharacters

Checks if the XmlParser verifies the encoding of incoming XML strings.

local enabled = XmlParser:getCheckCharacters()

Returns: true or false.

See Also

XmlParser:getCheckEncodingMismatch

Checks if the XmlParser raises an error in the event of an encoding mismatch.

local enabled = XmlParser:getCheckEncodingMismatch()

Returns: true (mismatches raise errors) or false.

See Also

XmlParser:getCopyDoctype

Checks if the XmlParser makes a copy of the !DOCTYPE declaration.

local enabled = XmlParser:getCopyDoctype()

Returns: true (copy the substring) or false (don’t).

See Also

XmlParser:getCollectComments

Checks if the XmlParser collects comments.

local enabled = XmlParser:getCollectComments()

  • enabled: true (comments are collected) or false

See Also

XmlParser:getCollectProcessingInstructions

Checks if the XmlParser collects Pi nodes.

local enabled = XmlParser:getCollectProcessingInstructions()

  • enabled: true (processing instructions are collected) or false

See Also

XmlParser:getMaxEntityBytes

Gets the current Max Entity Bytes number.

local n = XmlParser:getMaxEntityBytes()

Returns: The Max Entity Bytes number.

See Also

XmlParser:getNamespaceMode

Gets the XmlParser’s XML Namespace mode.

local version = XmlParser:getNamespaceMode()

Returns: nil (namespace state is not active while parsing), 1.0 or 1.1.

See Also

XmlParser:getNormalizeLineEndings

Checks if the XmlParser normalizes line endings.

local enabled = XmlParser:getNormalizeLineEndings()

Returns: true if the parser normalizes line endings, false if not.

See Also

XmlParser:getRejectDoctype

Checks if the XmlParser rejects <!DOCTYPE>.

local rejecting = XmlParser:getRejectDoctype()

Returns: true (<!DOCTYPE> is being rejected) or false.

See Also

XmlParser:getRejectInternalSubset

Checks if the XmlParser rejects documents with an internal subset.

local rejecting = XmlParser:getRejectInternalSubset()

Returns: true if internal subsets are being rejected, false if not.

See Also

XmlParser:getRejectUnexpandedEntities

Checks if the XmlParser rejects Unexpanded Entities.

local enabled = XmlParser:getRejectUnexpandedEntities()

Returns: true (Unexpanded Entities are rejected) or false (they are included in the tree).

See Also

XmlParser:getTerseMode

Checks if the XmlParser’s Terse Mode setting is active.

local terse = XmlParser:getTerseMode()

Returns: true or false.

See Also

XmlParser:getWarnDuplicateEntityDeclarations

Checks if the XmlParser warns about duplicate entity declarations.

local enabled = XmlParser:getWarnDuplicateEntityDeclarations()

Returns: true (warnings are issued to the console) or false.

Notes

Terse Mode will override this setting.

See Also

XmlParser:getWriteBigEndian

Gets the XmlParser’s setting for UTF-16 endianness.

local enabled = XmlParser:getWriteBigEndian()

Returns: true (the serialized UTF-16 output is big endian) or false (little endian)

See Also

XmlParser:getWriteDoctype

Checks if the XmlParser writes out the DOCTYPE tag.

local enabled = XmlParser:getWriteDoctype()

Returns: true (DOCTYPE tag is being written) or false.

See Also

XmlParser:getWriteIndent

Gets the XmlParser’s indentation character and quantity for pretty-printing.

local ch, qty = XmlParser:getWriteIndent()

Returns: The whitespace character ( or \t) and the number of ch characters to write per indentation level.

See Also

XmlParser:getWritePretty

Gets the XmlParser state for pretty-printing.

local enabled = XmlParser:getWritePretty()

  • enabled: true (pretty-printing is active) or false.

See Also

XmlParser:getWriteXmlDeclaration

Checks if the XmlParser writes out XML declarations.

local enabled = XmlParser:getWriteXmlDeclaration()

Returns: true (XML declarations are written out) or false.

See Also

XmlParser:setCheckCharacters

Default: true

If enabled, the XmlParser checks incoming XML strings for UTF-8 encoding issues and for code points that are forbidden by the XML spec.

XmlParser:setCheckCharacters(enabled)

  • enabled: true to enable character checking, false/nil to disable it.

Returns: self, for method chaining.

Notes

This setting is required by the spec. You should only disable it if you can check the input ahead of time with an XML linter.

See Also

XmlParser:setCheckEncodingMismatch

Default: true

Makes the XmlParser raise an error if the perceived encoding (based on checking the first few bytes of the document) does not match the encoding specified in the XML declaration.

In other words: if the XmlParser sees <?xml version="1.0" encoding="UTF-8" …?> but the actual encoding is UTF-16, it raises an error.

XmlParser:setCheckEncodingMismatch(enabled)

  • enabled: true (mismatches raise errors) or false/nil.

Returns: self, for method chaining.

See Also

XmlParser:setCopyDoctype

Default: false

When enabled, if a !DOCTYPE declaration is present, the XmlParser stores a substring copy in XmlObject.doctype_str.

XmlParser:setCopyDoctype(enabled)

  • enabled: true to store !DOCTYPE substrings, false/nil otherwise.

Returns: self, for method chaining.

See Also

XmlParser:setCollectComments

Default: true

Makes the XmlParser collect or discard comments.

XmlParser:setCollectComments(enabled)

  • enabled: true to collect comments and attach them to the XmlObject output, false/nil to discard them.

Returns: self, for method chaining.

See Also

XmlParser:setCollectProcessingInstructions

Default: true

Makes the XmlParser collect or discard processing instructions.

XmlParser:setCollectProcessingInstructions(enabled)

  • enabled: true to collect processing instructions and attach them to the XmlObject output, false/nil to discard them.

Returns: self, for method chaining.

See Also

XmlParser:setMaxEntityBytes

Default: math.huge

Sets the Max Entity Bytes number.

XmlParser:setMaxEntityBytes(n)

  • n: The number of bytes to read. Use math.huge to disable the feature.

Returns: self, for method chaining.

See Also

XmlParser:setNamespaceMode

Default: nil

Sets the XmlParser’s XML Namespace mode.

XmlParser:setNamespaceVersion(mode)

  • mode: nil for no namespace functionality while parsing, or the XML Namespace version string (1.0, 1.1).

Returns: self, for method chaining.

Notes

This setting is copied to any XmlObjects created by the XmlParser.

See Also

XmlParser:setNormalizeLineEndings

Default: true

Sets if the XmlParser normalizes line endings.

XmlParser:setNormalizeLineEndings(enabled)

  • enabled: true to normalize newlines, false/nil to skip this step.

Returns: self, for method chaining.

See Also

XmlParser:setRejectDoctype

Default: false

Makes the XmlParser raise an error upon encountering <!DOCTYPE>. Some formats based on XML forbid this tag.

XmlParser:setRejectDoctype(enabled)

  • enabled: true to reject the DOCTYPE, false/nil to accept and parse it (in a non-validating manner).

Returns: self, for method chaining.

See Also

XmlParser:setRejectInternalSubset

Default: false

Makes the XmlParser raise an error upon encountering a DTD internal subset (the bit that’s enclosed in square brackets) within the DOCTYPE.

XmlParser:setRejectInternalSubset(enabled)

  • enabled: true to reject DOCTYPEs containing internal subsets, false/nil to accept and parse them.

Returns: self, for method chaining.

Notes

Some XML documents contain a harmless DOCTYPE tag that just specifies the root element name, like <!DOCTYPE foobar>. This has no effect in a non-validating processor.

See Also

XmlParser:setRejectUnexpandedEntities

Default: false

If enabled, halts processing when an Unexpanded entity node would be created and added to the tree.

XmlParser:setRejectUnexpandedEntities(enabled)

  • enabled: true to halt on Unexpanded Entities, false/nil to attach them to the output tree.

Returns: self, for method chaining.

See Also

XmlParser:setTerseMode

Sets Terse Mode.

local str = XmlParser:setTerseMode(enabled)

  • enabled: true or false.

XmlParser:setWarnDuplicateEntityDeclarations

Default: false

If enabled, prints a warning to the console when multiple !ENTITY declarations with the same name are encountered.

XmlParser:setWarnDuplicateEntityDeclarations(enabled)

  • enabled: true to warn about duplicate entity declarations, false/nil otherwise.

Returns: self, for method chaining.

Notes

When duplicate entity declarations appear in the internal subset, only the first-encountered declaration is registered.

Terse Mode overrides this setting.

See Also

XmlParser:setWriteBigEndian

Default: false (lttle endian)

Sets the endianness for serialized output when the encoding is UTF-16.

XmlParser:setWriteBigEndian(enabled)

  • enabled: true to order bytes as big endian, false/nil to order as little endian.

Returns: self, for method chaining.

See Also

XmlParser:setWriteDoctype

Default: false

Sets whether the XmlParser writes a DOCTYPE tag when serializing out an XmlObject.

XmlParser:setWriteDoctype(enabled)

  • enabled: true to serialize DOCTYPE, false/nil otherwise.

Returns: self, for method chaining.

Notes

XmlParsers and XmlObjects don’t fully track DOCTYPE state. Instead, if xml_object.doctype_str is a string, then its contents are inserted before the root element.

See Also

XmlParser:setWriteIndent

Default: " ", 1

Sets the indentation character and quantity for pretty-printing.

XmlParser:setWriteIndent(ch, [qty])

  • ch: The whitespace character to use: or \t.

  • [qty]: (1) The number of ch characters to write per indentation level.

Returns: self, for method chaining.

See Also

XmlParser:setWritePretty

Default: true

Sets the XmlParser state for pretty-printing (added line endings and indentations when serializing out).

XmlParser:setWritePretty(enabled)

  • enabled: true to insert line endings and indentations, false/nil otherwise.

Returns: self, for method chaining.

See Also

XmlParser:setWriteXmlDeclaration

Default: true

Sets whether the XML declaration is written when serializing out an XmlObject.

XmlParser:setWriteXmlDeclaration(enabled)

  • enabled: true to write out the XML declaration, false/nil to skip it.

Returns: self, for method chaining.

See Also

XmlParser:toString

Converts an XmlObject to an XML string.

local str = XmlParser:toString(xml_obj)

  • xml_obj: The XmlObject to convert.

Returns: An XML string.

Notes

The string encoding is controlled by the XmlObject’s encoding setting.

See Also

XmlParser:toTable

Converts an XML string to an XmlObject node tree.

local xml_obj = XmlParser:toTable(str, [name])

  • str: The XML string to convert.

  • [name]: An optional name to display in warnings and error messages.

Returns: An XmlObject.

See Also

Notes

CharacterData cd_sect flag

This is a hint to the serializer to output CharacterData in the form of a CDATA section: <![CDATA[…​]]>

A CharacterData’s cd_sect flag is reset when XmlObject:mergeCharacterData combines text from other nodes.

The substring ]]> cannot appear within a CDATA section. If this substring is encountered when serializing, the CDATA section will end, ]]> will be escaped as ]]&gt;, and a new CDATA section will begin.

Max Entity Bytes

This is a mitigation against the Billion laughs attack. It works by limiting the maximum number of bytes to read from the replacement text of General Entities. When this amount is exceeded, the XmlParser raises an error.

Predefined Entities do not contribute to the count. All other replacement text is included: any yet-to-be-processed markup that is nested within a just-expanded general entity will contribute to the total.

Line Ending Normalization

When enabled, XmlParsers convert instances of \r\n and \r to just \n before processing the document.

This step is required by the XML spec. You should only disable line ending normalization if your application already guarantees that the incoming strings have had this transformation applied.

Terse Mode

When enabled, XmlParsers will omit names and line + character counts from error messages. Warning messages will not be printed at all.

VERSION: 2.075