File XmlMutable.lua
Functions
| Attributes:addAttr (name, value) | Add an attribute as name/value pair. |
| Attributes:getArray () | Get array of attributes. |
| Attributes:getAttrText (name) | Get specified attribute by name. |
| Attributes:getLookup () | Get attributes as lookup table. |
| Attributes:new (attrTable) | Create an object that represents an xml element's attributes. |
| Attributes:serialize (ind) | Serialize attributes. |
| Document:getDecl () | Get xml declaration header as text string. |
| Document:getRoot () | Get root element. |
| Document:new (t) | Create an xml document, which is essentially just an xml element, plus an optional preamble, and encoding. |
| Document:serialize () | Serialize xml document. |
| Element:addChild (elem) | Add child element. |
| Element:getAttributeArray () | Gets attributes as array. |
| Element:getAttributeLookup () | Get attributes as lookup table. |
| Element:getChildAtIndex (i) | Get child element node specified by index. |
| Element:getChildCount () | Get number of children. |
| Element:getChildren () | Get array of child element nodes. |
| Element:getName () | Get element name - excluding namespace. |
| Element:getNamespace () | Get element namespace. |
| Element:getText () | Get textual content, if any. |
| Element:new (t) | Create an xml element. |
| Element:serialize (initialIndentation, spacesPerIndent) | Serialize element, and all its children. |
| Element:setText (text) | Set textual content. |
| XmlMutable:new (t) | Constructor for new instance. |
| XmlMutable:newClass (t) | Constructor for extending class. |
| XmlMutable:newDocument (xml, includePreamble) | Load xml string into xml table. |
| XmlMutable:parseToLua (xmlString, expectDecl) | Converts serialized xml string to lua table (or simple variable). |
| XmlMutable:parseXml (x, decl) | Parse xml string. |
| XmlMutable:serialize (xdoc, initialIndentationSpaceString, numberOfSpacesPerIndentLevel) | Convert xml document to string. |
| XmlMutable:serializeLua (luaT, includeDecl, nSpaces) | Converts lua table (or simple variable) to string, typically for writing to a file upon return. |
Functions
- Attributes:addAttr (name, value)
-
Add an attribute as name/value pair.
Parameters:
-
name: (string, required) name of attribute. -
value: (any, required) any serializable value (serialized by global lua tostring function, tostring method in metatable, or toString class method if available).
Usage:
attribute must NOT already exist.
-
- Attributes:getArray ()
-
Get array of attributes.
Return value:
- array (table(array)) items are tables with named items: name/text.
- Attributes:getAttrText (name)
-
Get specified attribute by name.
Parameters:
-
name: (string, required) attribute name
Return value:
- value (string) attribute value as string, or nil if no attribute with specifed name.
-
- Attributes:getLookup ()
- Get attributes as lookup table.
- Attributes:new (attrTable)
-
Create an object that represents an xml element's attributes.
Parameters:
-
attrTable: (table, optional) array of items with a name and text member for each attribute, or a name/text lookup table.
-
- Attributes:serialize (ind)
-
Serialize attributes.
Parameters:
-
ind:
Return value:
- s (string) blank string if none, else name="value"... (space separated).
-
- Document:getDecl ()
- Get xml declaration header as text string.
- Document:getRoot ()
- Get root element.
- Document:new (t)
-
Create an xml document, which is essentially just an xml element, plus an optional preamble, and encoding.
Parameters:
-
t: (table, optional) initial members.
-
- Document:serialize ()
- Serialize xml document.
- Element:addChild (elem)
-
Add child element.
Parameters:
-
elem: (Element, required) element to add.
-
- Element:getAttributeArray ()
-
Gets attributes as array.
Return value:
- attribueArray (table(array)) empty if no attributes, else elements are tables containing name/text members.
- Element:getAttributeLookup ()
-
Get attributes as lookup table.
Return value:
- attributeLookupTable (table(named members)) key is attribute name, value is string.
- Element:getChildAtIndex (i)
-
Get child element node specified by index.
Parameters:
-
i:
-
- Element:getChildCount ()
- Get number of children.
- Element:getChildren ()
- Get array of child element nodes.
- Element:getName ()
- Get element name - excluding namespace.
- Element:getNamespace ()
- Get element namespace.
- Element:getText ()
-
Get textual content, if any.
Usage:
Content may need to be unescaped externally. CDATA not supported.
- Element:new (t)
-
Create an xml element.
Parameters:
-
t: (table, optional) default members.
-
- Element:serialize (initialIndentation, spacesPerIndent)
-
Serialize element, and all its children.
Parameters:
-
initialIndentation: -
spacesPerIndent:
Usage:
indentation presently hardcoded to start at zero
-
- Element:setText (text)
-
Set textual content.
Parameters:
-
text:
Usage:
Does not support CDATA, and escaping must be done externally, if required. ###2
-
- XmlMutable:new (t)
-
Constructor for new instance.
Parameters:
-
t:
-
- XmlMutable:newClass (t)
-
Constructor for extending class.
Parameters:
-
t:
-
- XmlMutable:newDocument (xml, includePreamble)
-
Load xml string into xml table.
Parameters:
-
xml: (string, optional) Typically as read from file, but could be manufactured, or nil to create blank document. -
includePreamble:
Usage:
returned table can be modified, then re-written.
Return value:
- xmlDocument (Document) xml document instance.
-
- XmlMutable:parseToLua (xmlString, expectDecl)
-
Converts serialized xml string to lua table (or simple variable).
Parameters:
-
xmlString: (string, required) xml string - if blank returns empty table (if nil returns nil). -
expectDecl: (boolean, default=false) if true, parse fails if no decl.
Usage:
does not support generic xml, only as serialized by this module.
reminder: attributes are only used for storing index value & type, and only string and number types are supported,
since the whole point of this exercise is serialization/de-serialization, it hardly makes sense to have a table object as index.
Return value:
- lua table - sans decl
-
- XmlMutable:parseXml (x, decl)
-
Parse xml string.
Parameters:
-
x: (string, required) xml string. -
decl: (boolean, default=false) expect decl.
Return value:
- xmlDocument (private 'Document' class) accessed via methods.
-
- XmlMutable:serialize (xdoc, initialIndentationSpaceString, numberOfSpacesPerIndentLevel)
-
Convert xml document to string.
Parameters:
-
xdoc: (private 'Document' class) initially gotten by parsing xml string - may be since modified. -
initialIndentationSpaceString: (string, default = "") spaces to indent root. -
numberOfSpacesPerIndentLevel: (number, default = 2) number of additional spaces per nesting level.
Usage:
throws errors if problems.
Return value:
- s (string) for display or disk storage...
-
- XmlMutable:serializeLua (luaT, includeDecl, nSpaces)
-
Converts lua table (or simple variable) to string, typically for writing to a file upon return.
Parameters:
-
luaT: (lua table, required) actually can be a simple variable too, but in practice is nearly always a table. -
includeDecl: (boolean, default=false) include declaration prefix -
nSpaces: (number, default=2) number of spaces per indent.
Usage:
Serializes in multi-line format, like xmp files.
Return value:
- xml string, with optional decl sans char encoding, unix-style eol.
-