MUSHclient documentation: utils.xmlread

utils.xmlread

utils.xmlread
Lua function utils.xmlread Summary Parses an XML string into a nested table Prototype `t = utils.xmlread (s)` Description The function utils.xmlread uses MUSHclient's internal XML parser to parse an XML string you supply. This effectively would let you parse triggers, aliases etc. that you have copied to the clipboard as text (or created with ExportXML script routine), and see exactly what each value is set to. Or, by reading a MUSHclient world file into memory as a string, you could parse that. The XML parser is not necessarily 100% industry-standard XML parsing, however it is the method MUSHclient uses for its own XML documents, and should be reasonably compatible with standard XML unless you use some of the more fancy XML extensions. It should certainly parse the XML output by MUSHclient itself (eg. triggers, aliases, world files, plugins) as that is the same routine it uses to read them in. You pass to the parser a single string, which is the XML to be parsed. If the parsing is successful three results are returned: The root node (all other nodes are children of this node) The root document name (eg. "muclient") A table of custom entities in the document, or nil if no custom entities If the parsing fails, three results are returned: nil - to indicate failure The error reason The line the error occurred at You can pass the first 2 results to "assert" to quickly check if the parsing was successful. Each node consists of a table with the following entries: name - name of the node (eg. <trigger>foo</trigger> - the name is "trigger") content - contents of the node (eg. <trigger>foo</trigger> - the content is "foo") empty - boolean to indicate if the node is empty. (eg. <br/> is an empty node) line - which line in the XML string the node occurred on (eg. line 5) attributes - a table of attributes for this node, keyed by the attribute name (eg. "world_file_version"="15"). Attribute names have to be unique so we can used a keyed lookup to find them. The attributes table is not present if there are no attributes defined. nodes - a table of child nodes, keyed by ascending number (the order they appeared in). Each child node has the same contents as described above. Children are not necessarily unique (eg. there may be more than one <trigger> node in a document) so they are keyed by number, and not by node name. The nodes table is not present if there are no children of this node. Example: a, b, c = utils.xmlread ("<foo><bar x='2'/></foo>") Output: "line"=1 "name"="" "nodes": 1: "line"=1 "name"="foo" "nodes": 1: "line"=1 "name"="bar" "empty"=true "content"="" "attributes": "x"="2" "content"="" "content"="" You can see from the above that the "root" node is really just an unnamed node which is the placeholder for the top level nodes (ie. the first "real" node is a child of the root node). In this case the node "foo" is the first child of the root node. See Also ... Topics Lua base functions Lua bc (big number) functions Lua bit manipulation functions Lua coroutine functions Lua debug functions Lua io functions Lua math functions Lua os functions Lua package functions Lua PCRE regular expression functions Lua script extensions Lua string functions Lua table functions Lua utilities Scripting Lua functions utils.base64decode (Decode a string which was base-64 encoded) utils.base64encode (Encode a string with base-64 encoding) utils.choose (Display a combo box with choices in it) utils.compress (Compress a string) utils.decompress (Decompress a string) utils.editbox (Display a large message box and get free-format reply) utils.edit_distance (Returns the Levenshtein Edit Distance between two words) utils.filepicker (Invokes the Windows standard "file picker" dialog box) utils.fromhex (Convert a string from hex) utils.functionlist (Returns a table of MUSHclient world function names) utils.hash (Hash a string, returning the hex codes) utils.info (Information about directories) utils.inputbox (Display a message box and get free-format reply) utils.listbox (Display a dialog box with choices in it in a single selection list box) utils.md5 (Hash a string using the 128-bit MD5 algorithm) utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word) utils.msgbox (Display a message box and get a response) utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box) utils.readdir (Read a disk directory into a table) utils.sha256 (Hash a string using a 256-bit hash) utils.spellcheckdialog (Spell-checker dialog) utils.split (Split a delimited string into a table) utils.tohex (Convert a string into hex) utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string) utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string) utils.utf8valid (Checks if a UTF-8 string is valid) (Help topic: lua=utils.xmlread) Documentation contents page

Lua function

utils.xmlread

Summary

Parses an XML string into a nested table

Prototype

t = utils.xmlread (s)

Description

The function utils.xmlread uses MUSHclient's internal XML parser to parse an XML string you supply. This effectively would let you parse triggers, aliases etc. that you have copied to the clipboard as text (or created with ExportXML script routine), and see exactly what each value is set to. Or, by reading a MUSHclient world file into memory as a string, you could parse that.



The XML parser is not necessarily 100% industry-standard XML parsing, however it is the method MUSHclient uses for its own XML documents, and should be reasonably compatible with standard XML unless you use some of the more fancy XML extensions. It should certainly parse the XML output by MUSHclient itself (eg. triggers, aliases, world files, plugins) as that is the same routine it uses to read them in.



You pass to the parser a single string, which is the XML to be parsed. If the parsing is successful three results are returned:





The root node (all other nodes are children of this node)

The root document name (eg. "muclient")

A table of custom entities in the document, or nil if no custom entities





If the parsing fails, three results are returned:





nil - to indicate failure

The error reason

The line the error occurred at





You can pass the first 2 results to "assert" to quickly check if the parsing was successful.



Each node consists of a table with the following entries:





name - name of the node (eg. <trigger>foo</trigger> - the name is "trigger") 

content - contents of the node (eg. <trigger>foo</trigger> - the content is "foo")

empty - boolean to indicate if the node is empty. (eg. <br/> is an empty node)

line - which line in the XML string the node occurred on (eg. line 5)

attributes - a table of attributes for this node, keyed by the attribute name (eg. "world_file_version"="15"). 



Attribute names have to be unique so we can used a keyed lookup to find them.



The attributes table is not present if there are no attributes defined.



nodes - a table of child nodes, keyed by ascending number (the order they appeared in). Each child node has the same contents as described above.



Children are not necessarily unique (eg. there may be more than one <trigger> node in a document) so they are keyed by number, and not by node name.



The nodes table is not present if there are no children of this node.







Example:




a, b, c = utils.xmlread ("<foo><bar x='2'/></foo>")




Output:




"line"=1
"name"=""
"nodes":
  1:
    "line"=1
    "name"="foo"
    "nodes":
      1:
        "line"=1
        "name"="bar"
        "empty"=true
        "content"=""
        "attributes":
          "x"="2"
    "content"=""
"content"=""




You can see from the above that the "root" node is really just an unnamed node which is the placeholder for the top level nodes (ie. the first "real" node is a child of the root node). In this case the node "foo" is the first child of the root node.