File XmlBuffer.lua
Functions
Attributes:addAttr (name, value) | Add an attribute as name/value pair. |
Attributes:getAttrText (name) | Get specified attribute by name. |
Attributes:getAttrValue (name) | Get specified attribute (string) value. |
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:getAttributes () | Get attributes object. |
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. |
XmlBuffer:new (t) | Constructor for new instance. |
XmlBuffer:newClass (t) | Constructor for extending class. |
XmlBuffer:newDocument (xml, includePreamble) | Load xml string into xml table. |
XmlBuffer:parseToLua (xmlString, expectDecl) | Converts serialized xml string to lua table (or simple variable). |
XmlBuffer:parseXml (x, decl) | Parse xml string. |
XmlBuffer:serialize (xdoc, initialIndentationSpaceString, numberOfSpacesPerIndentLevel) | Convert xml document to string. |
XmlBuffer: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, else calling error is thrown.
-
- 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:getAttrValue (name)
-
Get specified attribute (string) value.
Parameters:
-
name
:
-
- 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:getAttributes ()
-
Get attributes object.
Return value:
- Attributes.
- 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
-
- XmlBuffer:new (t)
-
Constructor for new instance.
Parameters:
-
t
:
-
- XmlBuffer:newClass (t)
-
Constructor for extending class.
Parameters:
-
t
:
-
- XmlBuffer: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.
-
- XmlBuffer: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
-
- XmlBuffer: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.
-
- XmlBuffer: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...
-
- XmlBuffer: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.
-