# Standard xml reference

This appendix is a reference of the standard xml module objects.

XmlNode

The `XmlNode` class is the base class used to represent the xml tree. The tree is built as a vector of nodes. Each node owns as well its parent node. Walking in the tree is achieved by taking the child node and then moving to the child and/or next node. The node also manages an empty flags. It the empty flag is set, it is an error to add child nodes.

node-p
Object
to-text
String
none

The `to-text` method returns a text representation of the tree content. Unlike the write method, the tag are not generated, but rather the text content is accumulated. This method is useful tor read the node content. If a node does not have text, the nil string is returned.

write
none
none|OutputStream|Buffer

The `write` method write the node contents as well as the child nodes to an output stream argument or a buffer. When node is written, the method attempts to use the stream encoding in such way that the contents fits into the requested output encoding. Without argument, the node is written to the interpreter output stream. with one argument, the node is written to the specified stream or buffer.

name-p
Boolean
String

The `name-p` predicate checks if the name matches the node name. Care should be taken that not all node have a name, and in such case, the false value is returned. This method is useful when the node is a tag.

attribute-p
Boolean
String| String String

The `attribute-p` predicate checks if there is a node attribute that matches the string argument name. In the first form, the predicate returns true is an attribute exists with the name argument. In the second form, the predicate returns true if the attribute name and value matches the arguments. The first argument is the attribute name. The second argument is the attribute value. Not all nodes have attributes. In such case, the predicate always returns false.

parse
none
String

The `parse` method parses the string argument and adds the results as a set of child node to the calling node. If the node is an empty node, the method will almost fail. This method should be used when an attempt is made to add some text that may contain some xml tags.

get-parent
XmlNode
none

The `get-parent` method returns the parent node. If the node is the root node, nil is returned.

set-parent
none
XmlNode

The `set-parent` method sets the parent node.

copy
XmlNode
none

The `copy` method copy the node tree by regenerating a new tree.

clear-child
none
none

The `clear-child` method clear the child node list, leaving the node without child node.

add-child
none
XmlNode|XmlNode Integer

The `add-child` method adds a node argument as a child node to the calling node. In the first form, the node is added at the end of the node list. In the second form, the node is added by index and all subsequent nodes are shifted by one position.

get-child
XmlNode
Integer String

The `get-child` method returns a child node by index or by name. If the calling argument is an integer, the node is returned by index. If the calling argument is a string, the node is returned by name. If the node cannot be found, nil is returned raised.

get-index
Integer
XmlNode

The `gett-index` method returns a child node index. The node argument is the node to find as a child node. If the node is not found, an exception is raised.

merge
none
XmlNode Integer

The `merge` method merge an existing node with another one. The first argument is the source node used for merging. The second argument the child node index to merge. The method operates by first removing the child node at the specified index and then add in position, the child nodes of the source node.

nil-child-p
Boolean
none

The `nil-child-p` predicate returns true if the node does not have a child node.

lookup-child
XmlNode
String

The `lookup-child` method returns a child node by name. Unlike the `get-child` method, the method raises an exception if the node cannot be found.

child-length
Integer
none

The `child-length` method returns the number of children nodes.

get-source-line
Integer
none

The `get-source-line` method returns the node source line number if any.

set-source-line
none
Integer

The `set-source-line` method sets the node source line number.

get-source-name
String
none

The `get-source-name` method returns the node source name if any.

set-source-name
none
String

The `set-source-name` method sets the node source name.

XmlTag

The `XmlTag` class is the base class used to represent a xml tag. A tag is defined with a name and an attribute list. The tag is derived from the xml node class and is not marked empty by default.

tag-p
XmlNode
XmlTag
String

The `XmlTag` constructor creates a tag node. The node is not marked empty.

XmlTag
String Boolean

The `XmlTag` constructor creates a tag node. The first argument is the tag name. The second argument is the empty flag.

set-name
none
String

The `set-name` method sets the tag name.

get-name
String
none

The `get-name` method returns the tag name.

clear-attribute
none
node

The `clear-attribute` method clear the node attribute list.

add-attribute
none
Property

The `add-attribute` method adds a new attribute to the tag. The attribute must be new for this method to succeed. In doubt, the `set-attribute` is preferable.

set-attribute
none
String Literal

The `set-attribute` method sets an attribute to the tag. The first argument is the attribute name. The second argument is the attribute value. If the attribute already exists, the old value is replaced with the new one.

get-attribute
Property
Integer|String

The `get-attribute` method returns a tag attribute in the form o a property object. With an integer object, the attribute is returned by index. With a string object, the property is return by name. If the property is not found, nil is returned.

get-attribute-value
String
String

The `get-attribute-value` method returns a tag attribute value by name. The string argument is the attribute name. If the property is not found, an exception is raised.

lookup-attribute
Property
String

The `lookup-attribute` method returns a tag attribute by name in the form of a property. The string argument is the attribute name. If the property is not found, an exception is raised.

attribute-length
Integer
none

The `attribute-length` method returns the number of attributes.

XmlText

The `XmlText` class is the xml text node. A text node is directly built by the xml reader and the content placed into a string. By definition, a text node is an empty node.

text-p
XmlNode
XmlText
none

The `XmlText` constructor creates a default text node. By definition, a text node is an empty node.

XmlText
String

The `XmlText` constructor creates a text node with the string argument.

set-xval
none
String

The `set-xval` method sets the text node value.

get-xval
String
none

The `get-xval` method returns the text node value.

to-normal
String
none

The `to-normal` method returns the normalized text node value.

XmlData

The `XmlData` class is the xml CDATA node. A data node differs from the text node in the sense that the data node contains characters that could be reserved characters such like markup delimiters. The data node is most of the time used to hold text used for scripting. The data node is an empty node.

data-p
XmlNode
XmlData
none

The `XmlData` constructor creates a default data node. By definition, a data node is an empty node.

XmlData
String

The `XmlData` constructor creates a data node with the string argument.

set-xval
none
String

The `set-xval` method sets the data node value.

get-xval
String
none

The `get-xval` method returns the data node value.

XmlComment

The `XmlComment` class is the xml comment node. The comment node is a special node that holds the comment text. The comment node is an empty node.

comment-p
XmlNode
XmlComment
none

The `XmlComment` constructor creates a default comment node. By definition, a comment node is an empty node.

XmlComment
String

The `XmlComment` constructor creates a comment node with the string argument.

set-xval
none
String

The `set-xval` method sets the comment node value.

get-xval
String
none

The `get-xval` method returns the comment node value.

XmlDoctype

The `XmlDoctype` class is the xml document type node. In its simplest form, the document type has just a name which acts the starting tag for the document. The document type can also be associated with a system or a public identifier. Note also that a local root node can be attached to this node.

doctype-p
XmlNode
XmlDoctype
String

The `XmlDoctype` constructor creates a document type with a starting tag name as the string argument. This is the simplest form of a document type definition.

XmlDoctype
String String

The `XmlDoctype` constructor creates a document type with a starting tag name and a system identifier. The first string argument is the tag name. The second argument is the system identifier.

XmlDoctype
String String String

The `XmlDoctype` constructor creates a document type with a starting tag name, a public and a system identifier. The first string argument is the tag name. The second argument is the public identifier. The third argument is the system identifier.

get-xval
String
none

The `get-xval` method returns the document type starting tag name.

get-public-id
String
none

The `get-public-id` method returns the document type public identifier.

get-system-id
String
none

The `get-system-id` method returns the document type system identifier.

XmlPi

The `XmlPi` class is the xml processing node. The processing node is a tag node. Although a processing node is seen as tag with attributes, the specification describes the processing node as a special tag with a string value. The processing node is an empty node.

pi-p
XmlNode
XmlPi
String

The `XmlPi` constructor creates a processing node with the name string argument.

XmlPi
String String

The `XmlPi` constructor creates a processing node with the name string argument and the string value. The first argument is the tag name. The second argument is the processing node value.

set-name
none
String

The `set-name` method sets the xml pi node name.

get-name
String
none

The `get-name` method returns the pi node name.

set-xval
none
String

The `set-xval` method sets the processing node value.

get-xval
String
none

The `get-xval` method returns the processing node value.

map-xval
Plist
String

The `map-xval` method map the processing node value to a property list.

XmlDecl

The `XmlDecl` class is the xml declaration node. The declaration node is a processing node. A declaration node is defined with a version id, an encoding string and a standalone flag. Each value is represented by an attribute at the tag level.

decl-p
XmlPi
XmlDecl
none

The `XmlDecl` constructor creates a default declaration node. By default, the declaration node is set with the xml version 1.0, the UTF-8 encoding and the standalone flag is not set.

XmlDecl
String

The `XmlDecl` constructor creates a declaration node with a version. The string argument is the xml version version which must be a supported one.

XmlDecl
String String

The `XmlDecl` constructor creates a declaration node with a version and an encoding. The string argument is the xml version version which must be a supported one. The second argument is the xml encoding.

XmlDecl
String String String

The `XmlDecl` constructor creates a declaration node with a version, an encoding and a standalone flag. The string argument is the xml version version which must be a supported one. The second argument is the xml encoding. The third argument is the standalone flag.

XmlRef

The `XmlRef` class is the xml reference node class. This class is a base class which cannot be instantiated directly. The class is designed to hold reference, the only element which is in common is the string representation.

ref-p
XmlNode
set-xref
none
String

The `set-xref` method sets the node reference name.

get-xref
String
none

The `get-xref` method returns the node reference name.

XmlCref

The `XmlCref` class is the xml character reference node class. Normally this class should only be used when building a xml tree manually. During a parsing process, the character reference is automatically expanded.

cref-p
XmlRef
XmlCref
none

The `XmlCref` constructor creates a default character reference those value is the null character.

XmlCref
Character|Integer

The `XmlCref` constructor creates a character reference those value is the character or integer argument.

set-value
none
Character|Integer

The `set-value` method sets the character reference value by character or integer.

get-value
Character
none

The `get-value` method returns the character reference value.

XmlEref

The `XmlEref` class is the xml entity reference node class. The entity reference is defined with a reference name.

eref-p
XmlRef
XmlEref
none

The `XmlCref` constructor creates an empty entity reference.

XmlCref
String

The `XmlEref` constructor creates an entity reference those value is the string argument.

XmlSection

The `XmlSection` class is the xml section type node. A section node is used to model conditional section that are part of a DTD. The section value is a string that is evaluated by the xml processor. Most of the time, it is a parameter entity reference which corresponds to the keyword INCLUDE or IGNORE , but it could be anything else. A node is also attached to this section.

section-p
xmlNode
XmlSection
String

The `XmlSection` constructor creates a xml section node by value.

get-xval
String
none

The `get-xval` method returns the section node value.

XmlAttlist

The `XmlAttlist` class is the xml attribute list node class. A xml attribute list is primarily defined with two names. The first name is the element and the second name is the attribute name. There are 3 types of attribute list. The string type, the token type and the enumeration type. The class manages each type by associating a type descriptor which is detected at construction.

attlist-p
XmlNode
XmlAttlist
String String

The `XmlAttlist` constructor creates an attribute list by element name and attribute name. The first argument is the element name. The second argument is the attribute name.

set-element-name
none
String

The `set-element-name` method sets the attribute list element name.

get-element-name
String
none

The `get-element-name` method returns the attribute list element name.

set-attribute-name
none
String

The `set-attribute-name` method sets the attribute list name.

get-attribute-name
String
none

The `get-attribute-name` method returns the attribute list name.

set-type
none
String | Vector Boolean

The `set-type` method set the attribute type by string or enumeration vector. In its first form, the attribute type is defined by a string. The type can be either, "CDATA", "ID", "IDREF", "IDREFS", "ENTITY", "ENTITIES", "NMTOKEN" or "NMTOKENS". In the second form, the attribute type is an enumeration those values are defined in the argument vector. The boolean argument controls the notation flag for that enumeration.

set-default
none
String

The `set-default` method set the attribute value by string. The string can be any value or the special value "#IMPLIED" and "#REQUIRED". If the default value is fixed, the `set-fixed` is the preferred method.

set-fixed
none
String

The `set-fixed` method set the fixed attribute default value by string.

XmlRoot

The `XmlRoot` class is the top level root instantiated by the xml reader when starting to parse a stream. There should be only one root node in a tree. The root node does not have a parent node.

root-p
XmlNode
XmlRoot
none

The `XmlRoot` constructor creates a default xml root node which is empty.

dup-body
XmlBody
none

The `dup-body` method duplicates the root node by duplicating the root body without the declaration node.

declaration-p
Boolean
none

The `declaration-p` predicate returns true if a declaration node exists in the root node.

get-declaration
XmlDecl
none

The `get-declaration` method returns the declaration node associated with the root node. Normally, the declaration node is the first child node. If the declaration node does not exist, an exception is raised.

get-encoding
String
none

The `get-encoding` method returns the root encoding mode. The root encoding mode is extracted from the declaration node, if such node exists, or the default xml system encoding is returned.

XmlDocument

The `XmlDocument` class is the xml document class. The document class is the root document class that maintains a xml document along with its associated tree and other useful information. Generally the class is constructed with a file name or a name and an input stream that is used for parsing the input data. The document can also be designed by constructing manually the document tree. In that case, the document name must be set explicitly.

document-p
Nameable
XmlDocument
none

The `XmlDocument` constructor creates a default xml document.

XmlDocument
String

The `XmlDocument` constructor creates a xml document by parsing the file. The file name is the string argument.

XmlDocument
String InputStream

The `XmlDocument` constructor creates a xml document by name and by parsing the input stream. The first argument is the xml document name. The second argument is the input stream to parse.

XmlDocument
String XmlRoot

The `XmlDocument` constructor creates a xml document by name and root node. The first argument is the xml document name. The second argument is the xml root node.

set-name
none
String

The `set-name` method sets the xml document name. The `get-name` method is available from the `nameable` base class.

get-root
XmlRoot
none

The `get-root` method returns the document xml root node.

get-body
XmlRoot
none

The `get-body` method returns the document xml root node body without the declaration node.

XmlElement

The `XmlElement` class is the xml element class node. A xml element is represented with a name and a value. It is during the processing phase that the element value is interpreted. An element is built with a name and a value.

element-p
XmlNode
XmlElement
String String

The `XmlElement` constructor creates a xml element by name and value. The first argument is the element name. The second argument is the argument value.

set-name
none
String

The `set-name` method sets the xml element name.

get-name
String
none

The `get-name` method returns the element name.

set-xval
none
String

The `set-xval` method sets the xml element value.

get-xval
String
none

The `get-xval` method returns the element value.

XmlEntity

The `XmlEntity` class is the base class for the xml entity representation. A xml entity can be either a general entity or a parameter entity. They differ initially with the presence of the '%' character. Both entity model have a name which is path of the base class.

entity-p
XmlNode
set-name
none
String

The `set-name` method sets the entity name.

get-name
String
none

The `get-name` method returns the entity name.

XmlGe

The `XmlGe` class is the xml general entity node. In its simplest form, the general entity has a name and a value. The entity type can also be associated with a system or a public identifier with or without an extra type name.

ge-p
XmlEntity
XmlGe
String String

The `XmlGe` constructor creates a xml entity by name and value. The first argument is the entity name. The second argument is the entity value. Most of the time, the entity value is a parameter entity.

XmlGe
String String String

The `XmlGe` constructor creates a xml entity by name and identifier. The first argument is the entity name. The second argument is the entity public identifier. The third argument is the entity system identifier.

XmlGe
String String String String

The `XmlGe` constructor creates a xml entity by name, identifier and data type. The first argument is the entity name. The second argument is the entity public identifier. the third argument is the entity system identifier. The fourth argument is the entity type name.

get-xval
String
none

The `get-xval` method returns the entity value.

get-data
String
none

The `get-data` method returns the entity data type.

get-public-id
String
none

The `get-public-id` method returns the entity public identifier.

get-system-id
String
none

The `get-system-id` method returns the entity system identifier.

XmlPe

The `XmlPe` class is the xml parameter entity node. In its simplest form, the parameter entity has a name and a value. The entity type can also be associated with a system or a public identifier.

ge-p
XmlEntity
XmlPe
String String

The `XmlGe` constructor creates a xml entity by name and value. The first argument is the entity name. The second argument is the entity value.

XmlPe
String String String

The `XmlGe` constructor creates a xml entity by name and identifier. The first argument is the entity name. The second argument is the entity public identifier. The third argument is the entity system identifier.

get-xval
String
none

The `get-xval` method returns the entity value.

get-public-id
String
none

The `get-public-id` method returns the entity public identifier.

get-system-id
String
none

The `get-system-id` method returns the entity system identifier.

XmlReader

The `XmlReader` class is the xml parser that operates on an input stream. The reader creates a tree of nodes by reading the input stream and returns the root node when an end-of-stream is reached. Multiple read can be done sequentially. If the reset method is not called between multiple read passes, the reader will accumulate the nodes in the current tree.

reader-p
Object
XmlReader
none

The `XmlReader` constructor creates a default xml reader.

reset
none
none

The `reset` method resets the xml reader. In particular, the root node is restored to the nil node.

parse
none
InputStream|String

The `parse` method parses an input stream or a file. During the parsing process, the root node is filled with the parsed nodes.

get-root
XmlRoot
none

The `get-root` method returns the parsed root node.

get-node
XmlNode
String

The `get-node` method parse a string and returns a node.