Xml Class

The Xml class enables to manipulation of data in XML format. It is often used in conjunction with the XmlParser and with the XML functions.

An XML object contains three parts:

name -- the start of the tag which defines what type of object it is
attributes -- the body of the tag which is a list of attribute/value pairs
content -- the data between the start and end tags

For example:


    <error class='1' code='17'>something bad happened</error>

gives:

name = error
attributes = ( ("class" "1") ("code" "17") )
content = "something bad happened"

Xml Creation

Defined within the script xml.cpl, the create function is used to create an un-named Xml object:

    (create Xml)

Once created, the object is manipulated via its properties and methods.

Xml Properties

property name	property type	description
`name`	String	the name (type) of the XML object
`attributes`	List	the list of attribute/value pairs
`content`	Object	the content -- can be of any type

Xml Methods

method name	description
`addAttribute`	add the supplied attribute/value pair to the contained list of attributes
`setAttribute`	set the supplied attribute -- adding it if necessary
`getAttribute`	get the supplied attribute
`copyAttributes`	copy the named attributes from the supplied object
`contentList`	return the XML content as a `List`
`print`	print the XML object within the Carapace application
`encode`	encode the XML object onto the supplied `Stream`
`encodeAux`	encode the XML object onto the supplied `Stream` and format it for readability
`string`	return a `String` representation of the XML data
`stringAux`	return a `String` representation of the XML data formatted for readability
`list`	return a `List` representation of the XML data
`fromError`	fill the XML object with information from the supplied `Error` object
`throw`	throw an `Error` if this XML object represents an error

`addAttribute`

Add the supplied attribute/value pair to the contained list of attributes -- the supplied value is converted to a String.

Arguments:

attribute	`String`
value	`Object`

Return type: the empty List ()

`setAttribute`

Set the supplied attribute, adding it if necessary -- the supplied value is converted to a String.

Arguments:

attribute	`String`
value	`Object`

Return type: the empty List ()

`getAttribute`

Get the supplied attribute.

Arguments:

attribute	`String`
value	`Object`

Return type: returns the String value or the empty List () if no such attribute.

`contentList`

Return the XML content as a List. This is useful if the XML object can contain zero or more other XML objects -- the content could be a single XML object or a list of them. This function returns the content as a list.

Arguments: none

Return type: the empty List ()

`print`

Print the XML object within the Carapace application.

Arguments:

optional indent Integer

Return type: the empty List ()

`encode`

Encode the XML object onto the supplied Stream.

Arguments:

strm Stream

Return type: the empty List ()

`encodeAux`

Encode the XML object onto the supplied Stream and format it for readability.

Arguments:

strm	`Stream`
indent	`Integer`

Return type: the empty List ()

`string`

Return a String representation of the XML data.

Arguments: none

Return type: String

`stringAux`

Return a String representation of the XML data formatted for readability.

Arguments:

indent Integer

Return type: String

`list`

Return a List representation of the XML data. An XML object is converted to a list as follows:

the XML object name is the first item in the list
the second item in the list is the List of attribute/value pairs -- each pair is a List of two Strings
the remainder of the list is formed from the list of XML objects or strings in the XML object content -- each contained XML object is itself converted to a List

Arguments: none

Return type: List

`fromError`

Fill the XML object with information from the supplied Error object -- the XML object name is set to error.

The error text is forms the XML content. All other information is held as XML attributes:

class -- the class of error
code -- the error code
file -- optional file where the error was raised
line -- optional line within the file where the error was raised

Arguments:

err Error

Return type: the empty List ()

`throw`

Throw an Error if this XML object represents an error.

Arguments: none

Return type: the empty List ()

Contents

Index

Current topic: objects