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>")
require "tprint"
tprint (a)
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 ...
Lua functions
utils.activatenotepad - Actvitates the specified notepad window
utils.appendtonotepad - Appends text to the specified notepad window
utils.base64decode - Decode a string which was base-64 encoded
utils.base64encode - Encode a string with base-64 encoding
utils.callbackslist - Returns a table of plugin callback function names
utils.choose - Display a combo box with choices in it
utils.colourcube - Changes the colour cube used by 256-colour ANSI codes
utils.compress - Compress a string
utils.decompress - Decompress a string
utils.directorypicker - Invokes the Windows standard "directory picker" dialog box
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.filterpicker - Display a dialog box which filters its contents as you type
utils.fontpicker - Invokes the Windows standard "font picker" dialog box
utils.fromhex - Convert a string from hex
utils.functionlist - Returns a table of MUSHclient world function names
utils.getfontfamilies - Returns all fonts available to Windows
utils.glyph_available - Returns the glyph index of a glyph (character) in a font
utils.hash - Hash a string, returning the hex codes
utils.info - Information about directories, locale, etc.
utils.infotypes - Returns a table of all GetInfo type selectors
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.menufontsize - Alters the size of the font used in menus
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.reload_global_prefs - Forces global preferences file to be reloaded
utils.sendtofront - Bring a window to the front
utils.sha256 - Hash a string using a 256-bit hash
utils.shellexecute - Executes a Windows "shell" command
utils.spellcheckdialog - Spell-checker dialog
utils.split - Split a delimited string into a table
utils.timer - Returns the high-resolution timer output
utils.tohex - Convert a string into hex
utils.umsgbox - Display a message box and get a response (Unicode)
utils.utf8convert - Encodes a string into a UTF-8 string
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.utf8sub - Returns a substring of a UTF-8 string
utils.utf8valid - Checks if a UTF-8 string is valid
Topics
Lua base functions
Lua bc (big number) functions
Lua bit manipulation functions
Lua coroutine functions
Lua debug functions
Lua io functions
Lua LPEG library
Lua math functions
Lua os functions
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua string functions
Lua syntax
Lua table functions
Lua utilities
Scripting
Scripting callbacks - plugins
(Help topic: lua=utils.xmlread)