classDocs / XMLNode

XMLNode

classsharedsource

Object → XMLNode

A XML node object, representing a node in an XML document.

Can be converted to string using :toString() or tostring().

Usage:

lua

local root = XMLNode.fromString( [[
<root>
    <child>
        <title>Test Title</title>
    </child>
</root>
]] )

print( root:toString( false ) ) -- <root><child><title>Test Title</title></child></root>

Constructor

XMLNode(name: string, attributes: ( table<string, string> | nil ), parent: ( XMLNode | nil )): XMLNode

Fields

Name	Type	Description
`name`	`string`	The name of the node.
`attributes`	`nil \| table<string, (string \| nil)>`	The attributes of the node.
`parent`	`XMLNode \| nil`	The parent node.
`data`	`nil \| string \| table<string, (string \| XMLNode \| XMLNode.Value[])>`	The data of the node.
`order`	`nil \| (string \| integer)[]`	The document order of the children, element names and indices of `texts`, maintained automatically.
`texts`	`nil \| string[]`	The text chunks in document order, together they are the text slot `[1]`, maintained automatically.

Static functions

`fromString`	Converts an XML string to an XML node structure.
`fromTable`	Converts a table to an XML node structure.

#XMLNode.fromString

sharednodiscardsource

function XMLNode.fromString(xml_str: string, keep_whitespace?: boolean): XMLNode | nil

Converts an XML string to an XML node structure.

By default the text of text-only elements is trimmed, in mixed content only indentation (whitespace with line breaks) is removed and whitespace-only text is skipped.

With keep_whitespace or xml:space="preserve" all text is kept exactly as written.

Line breaks are normalized to \n, attribute values are normalized as XML requires, character references and entities declared in the internal DOCTYPE subset are decoded.

Parameters

Name	Type	Description
`xml_str`	`string`	The XML string to parse.
`keep_whitespace`optional	`boolean`	Whether to keep all whitespace in text, defaults to `false`.

Returns

Type	Name	Description
`XMLNode \| nil`	`root_node`	The root node, or `nil` if the string has no elements.

#XMLNode.fromTable

sharednodiscardsource

function XMLNode.fromTable(tbl: table, name?: string): XMLNode

Converts a table to an XML node structure.

Parameters

Name	Type	Description
`tbl`	`table`	The table to convert to an XML node.
`name`optional	`string`	The name of the root node.

Returns

Type	Name	Description
`XMLNode`	`root_node`	The root node of the XML tree.

Methods

`children`	Returns an iterator over the children of the node at the given key in document order, supporting dot-separated keys for…
`contains`	Checks if the node contains a value at the given key, supporting dot-separated keys for nested values.
`containsList`	Checks if the node contains a list at the given key, supporting dot-separated keys for nested values.
`containsNode`	Checks if the node contains a node at the given key, supporting dot-separated keys for nested values.
`containsString`	Checks if the node contains a string at the given key, supporting dot-separated keys for nested values.
`get`	Returns the value of the node at the given key or nil if not found.
`getAttribute`	Returns the value of the attribute with the given name or nil if not found.
`getLength`	Returns the length of the list at the given key, supporting dot-separated keys for nested values.
`isEmpty`	Checks whether the node is empty.
`iterator`	Returns an iterator function for the node at the given key, supporting dot-separated keys for nested values.
`pop`	Pops a value from the list at the given key, supporting dot-separated keys for nested values.
`push`	Pushes a value to the list at the given key, supporting dot-separated keys for nested values.
`remove`	Removes the value at the given key, supporting dot-separated keys for nested values.
`set`	Sets the value of the node at the given key, supporting dot-separated keys for nested values.
`setAttribute`	Sets the value of the attribute with the given name.
`toString`	Returns the XML string representation of this node.
`toTable`	Converts XML node structure to a Lua table.

#XMLNode:children

sharednodiscardsource

function XMLNode:children(key?: string): fun(): ( ( string | integer | nil ), ( string | XMLNode ) )

Returns an iterator over the children of the node at the given key in document order, supporting dot-separated keys for nested values.

Text is returned with key 1 and elements with their name, values are strings or nodes.

Usage:

lua

local root = XMLNode.fromString( "<p>Hello <b>big</b> world</p>" )

for name, value in root:children() do
    print( name, value ) -- 1 "Hello ", b "big", 1 " world"
end

Parameters

Name	Type	Description
`key`optional	`string`	The key of the node to iterate over, with dot-separated keys for nested values.

Returns

Type	Name	Description
`fun(): ( ( string \| integer \| nil ), ( string \| XMLNode ) )`	`fn`	The iterator function.

#XMLNode:contains

sharednodiscardsource

function XMLNode:contains(key: string): boolean

Checks if the node contains a value at the given key, supporting dot-separated keys for nested values.

Parameters

Name	Type	Description
`key`	`string`	The key to check, with dot-separated keys for nested values.

Returns

Type	Name	Description
`boolean`	`is_contains`	Whether the node contains a value at the given key.

#XMLNode:containsList

sharednodiscardsource

function XMLNode:containsList(key: string): boolean

Checks if the node contains a list at the given key, supporting dot-separated keys for nested values.

Parameters

Name	Type	Description
`key`	`string`	The key to check, with dot-separated keys for nested values.

Returns

Type	Name	Description
`boolean`	`is_contains`	Whether the node contains a list at the given key.

#XMLNode:containsNode

sharednodiscardsource

function XMLNode:containsNode(key: string): boolean

Checks if the node contains a node at the given key, supporting dot-separated keys for nested values.

Parameters

Name	Type	Description
`key`	`string`	The key to check, with dot-separated keys for nested values.

Returns

Type	Name	Description
`boolean`	`is_contains`	Whether the node contains a node at the given key.

#XMLNode:containsString

sharednodiscardsource

function XMLNode:containsString(key: string): boolean

Checks if the node contains a string at the given key, supporting dot-separated keys for nested values.

Parameters

Name	Type	Description
`key`	`string`	The key to check, with dot-separated keys for nested values.

Returns

Type	Name	Description
`boolean`	`is_contains`	Whether the node contains a string at the given key.

#XMLNode:get

sharednodiscardsource

function XMLNode:get(key: string): nil | string | XMLNode | XMLNode.Value[]

Returns the value of the node at the given key or nil if not found.

Each key segment can be indexed with [n], e.g. child[2].title, key "1" returns the text next to child nodes and an empty key "" returns the text of a text-only node.

Parameters

Name	Type	Description
`key`	`string`	The key to look up in the node's data, with dot-separated keys for nested values.

Returns

Type	Name	Description
`nil \| string \| XMLNode \| XMLNode.Value[]`	`value`	The value of the node at the given key, or `nil` if not found.

#XMLNode:getAttribute

sharednodiscardsource

function XMLNode:getAttribute(name: string): nil | string

Returns the value of the attribute with the given name or nil if not found.

Parameters

Name	Type	Description
`name`	`string`	The name of the attribute to get.

Returns

Type	Name	Description
`nil \| string`	`value`	The value of the attribute or `nil` if not found.

#XMLNode:getLength

sharednodiscardsource

function XMLNode:getLength(key: string): integer

Returns the length of the list at the given key, supporting dot-separated keys for nested values.

Parameters

Name	Type	Description
`key`	`string`	The key to get the length of, with dot-separated keys for nested values.

Returns

Type	Name	Description
`integer`	`length`	The length of the list at the given key.

#XMLNode:isEmpty

sharednodiscardsource

function XMLNode:isEmpty(): boolean

Checks whether the node is empty.

Returns

Type	Name	Description
`boolean`	`is_empty`

#XMLNode:iterator

sharednodiscardsource

function XMLNode:iterator(key?: string): fun(): ( ( string | nil ), ( string | XMLNode ) )

Returns an iterator function for the node at the given key, supporting dot-separated keys for nested values.

Values are returned in map order, use :children() for document order.

Text of a text-only node is returned with an empty key "", text next to child nodes with key 1, list items are returned one by one with the list key.

Parameters

Name	Type	Description
`key`optional	`string`	The key to iterate over, with dot-separated keys for nested values.

Returns

Type	Name	Description
`fun(): ( ( string \| nil ), ( string \| XMLNode ) )`	`fn`	The iterator function, which returns key-value pairs for the node at the given key.

#XMLNode:pop

sharedsource

function XMLNode:pop(key: string): nil | string | XMLNode

Pops a value from the list at the given key, supporting dot-separated keys for nested values.

Parameters

Name	Type	Description
`key`	`string`	The key to pop the value from, with dot-separated keys for nested values.

Returns

Type	Name	Description
`nil \| string \| XMLNode`		The popped value, or `nil` if the key does not exist or the value is not a node.

#XMLNode:push

sharedsource

function XMLNode:push(key: string, value: string | XMLNode)

Pushes a value to the list at the given key, supporting dot-separated keys for nested values.

Pushing a string to the text slot "1" appends it to the text.

Parameters

Name	Type	Description
`key`	`string`	The key to push the value to, with dot-separated keys for nested values.
`value`	`string \| XMLNode`	The value to push to the list.

#XMLNode:remove

sharedsource

function XMLNode:remove(key: string): boolean

Removes the value at the given key, supporting dot-separated keys for nested values.

Parameters

Name	Type	Description
`key`	`string`	The key to remove, with dot-separated keys for nested values.

Returns

Type	Name	Description
`boolean`	`success`	Returns `true` if the value was removed, `false` otherwise (e.g. key not found).

#XMLNode:set

sharedsource

function XMLNode:set(key: string, value: XMLNode.Value | XMLNode.Value[] | nil)

Sets the value of the node at the given key, supporting dot-separated keys for nested values.

Missing or non-node intermediate values are replaced with new empty nodes.

Parameters

Name	Type	Description
`key`	`string`	The key to set, with dot-separated keys for nested values.
`value`	`XMLNode.Value \| XMLNode.Value[] \| nil`	The value to set, which can be a string or a node, or `nil` to remove the value.

#XMLNode:setAttribute

sharedsource

function XMLNode:setAttribute(name: string, value: string | nil)

Sets the value of the attribute with the given name.

Parameters

Name	Type	Description
`name`	`string`	The name of the attribute to set.
`value`	`string \| nil`	The value to set for the attribute, or `nil` to remove the attribute.

#XMLNode:toString

sharednodiscardsource

function XMLNode:toString(pretty?: boolean, name?: string, level?: number): string

Returns the XML string representation of this node.

Children are written in document order, pretty formatting adds whitespace to the text, so use compact output for exact data.

Parameters

Name	Type	Description
`pretty`optional	`boolean`	Whether to use pretty formatting (indentation and newlines).
`name`optional	`string`	The name of the node.
`level`optional	`number`	The indentation level.

Returns

Type	Name	Description
`string`	`str`	The XML string representation of this node.

#XMLNode:toTable

sharednodiscardsource

function XMLNode:toTable(): table

Converts XML node structure to a Lua table.

Text content is stored in slot [1], attributes and document order are not included.

Returns

Type	Name	Description
`table`