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.

Valid XHTML 1.0!