| BaH.LibXml: | Globals | Functions | Types | Modinfo | Source |

# Libxml

Libxml is the XML parser and toolkit developed for the Gnome project.
This is the BlitzMax implementation of the libxml library.

XML itself is a metalanguage to design markup languages, i.e. text language where semantic and structure are added to the content using extra "markup" information enclosed between angle brackets. HTML is the most well-known markup language.

Here are some key points about libxml:

- Libxml exports Push (progressive) and Pull (blocking) type parser interfaces for both XML and HTML.
- Libxml can do DTD validation at parse time, using a parsed document instance, or with an arbitrary DTD.
- Libxml includes complete XPath, XPointer and XInclude implementations.
- Basic support for HTTP and FTP client allowing applications to fetch remote resources.

## Guides

The following are some pages that should help you gain a better understanding of XML and how to use it with the Libxml module. (written by Daniel Veillard and adapted for BlitzMax by Bruce Henderson)

- XML
- Validation & DTDs
- Namespaces

## Tutorials

See the Libxml Tutorial for an introduction to using the libxml module.
And the Libxml TxmlTextReader Tutorial for a guide to using the TxmlTextReader API.

## Examples

A quick example of creating an XML document from scratch : newxml_example.bmx

## Globals Summary

xmlDoValidityCheckingDefaultValue , xmlGetWarningsDefaultValue , xmlIndentTreeOutput , xmlLineNumbersDefaultValue , xmlLoadExtDtdDefaultValue , xmlParserDebugEntities , xmlSaveNoEmptyTags

## Functions Summary

xmlCleanupParser | Cleanup function for the XML library.
xmlGetLastError | Get the last global error registered.
xmlGetPredefinedEntity | Check whether this name is an predefined entity.
xmlSetErrorFunction | Sets the callback handler for errors.
xmlSubstituteEntitiesDefault | Set and return the previous value for default entity support.

## Types Summary

TxmlAttribute | An XML Attribute.
TxmlBase | The base Type for TxmlDoc, TxmlNode, TxmlAttribute, TxmlEntity, TxmlDtd, TxmlDtdElement and TxmlDtdAttribute.
TxmlBuffer | Xml Buffer.
TxmlCatalog | An XML Catalog.
TxmlDoc | An XML Document.
TxmlDtd | An XML DTD.
TxmlDtdAttribute | An XML Attribute Decl.
TxmlDtdElement | An XML Element.
TxmlElementContent | An XML element content tree.
TxmlEntity | An XML Entity.
TxmlError | An XML Error.
TxmlLocationSet | An XML Location Set.
TxmlNode | An XML Node.
TxmlNodeSet | An XML Node set.
TxmlNotation | An XML Notation.
TxmlNs | An XML Namespace.
TxmlTextReader | An XML Streaming Text Reader.
TxmlURI | A URI.
TxmlValidCtxt | XML validation context.
TxmlXIncludeCtxt | An XML XInclude context.
TxmlXPathCompExpr | A compiled XPath expression.
TxmlXPathContext | An XML XPath Context.
TxmlXPathObject | An XML XPath Object.

## Globals

Global xmlDoValidityCheckingDefaultValue:Int
Description | Global setting, indicate that the parser should work in validating mode.
Information | Disabled by default.

Global xmlGetWarningsDefaultValue:Int
Description | Global setting, indicate that the parser should provide warnings.
Information | Activated by default.

Global xmlIndentTreeOutput:Int
Description | Global setting, asking the serializer to indent the output tree by default.
Information | Enabled by default.

Global xmlLineNumbersDefaultValue:Int
Description | Global setting, indicate that the parser should store the line number in the content field of elements in the DOM tree.
Information | Disabled by default since this may not be safe for old classes of applicaton.

Global xmlLoadExtDtdDefaultValue:Int
Description | Global setting, indicate that the parser should load DTD while not validating.
Information | Disabled by default.

Global xmlParserDebugEntities:Int
Description | Global setting, asking the parser to print out debugging informations while handling entities.
Information | Disabled by default.

Global xmlSaveNoEmptyTags:Int
Description | Global setting, asking the serializer to not output empty tags as but .
Information | Those two forms are undistinguishable once parsed. Disabled by default.

## Functions

Function xmlCleanupParser()
Description | Cleanup function for the XML library.
Information | It tries to reclaim all parsing related global memory allocated for the library processing. It doesn't deallocate any document related memory. Calling this function should not prevent reusing the library but one should call xmlCleanupParser only when the process has finished using the library or XML document built with it.

Function xmlGetLastError:TxmlError()
Returns | Null if no error occured ora TxmlError object.
Description | Get the last global error registered.

Function xmlGetPredefinedEntity:TxmlEntity(name:String)
Returns | Null if not, otherwise the entity.
Description | Check whether this name is an predefined entity.
Information | Parameters: name : the entity name

Function xmlSetErrorFunction(callback(data:Object, error:TxmlError), data:Object = Null)
Description | Sets the callback handler for errors.
Information | The function will be called passing the optional user data and the error details.
Example |
    SuperStrict

    Framework BaH.Libxml

    Local s:String = "~n" + ..
    	" ~n" + ..
    	"~n" + ..
    	"	~n" + ..
    	"		~n" + ..
    	"	~n" + ..
    	"~n"

    xmlSetErrorFunction(errorCallback)

    Local xmldoc:TxmlDoc = TxmlDoc.parseDoc(s)
    DebugLog "Loaded"
    If xmldoc Then
    	DebugLog "XML Valid"
    	Local root:TxmlNode = xmldoc.getRootElement()
    	DebugLog root.getName()

    	Local children:TList = root.getChildren()
    	For Local node:TxmlNode = EachIn children
    		DebugLog " =>" + node.getname()
    	Next
    Else
    	DebugLog "** Invalid XML Syntax **"
    End If

    DebugLog "DONE"

    End

    Function errorCallback(data:Object, error:TxmlError)
    	DebugLog "+++++++++  Callback :-) ++++++++"
    	DebugLog "message: " + error.getErrorMessage()
    	DebugLog "level  : " + error.getErrorLevel()
    	DebugLog "file   : " + error.getFilename()
    	DebugLog "line   : " + error.getLine()
    	Local s:String[] = error.getExtraText()
    	If s Then
    		For Local i:Int = 0 Until s.length
    			DebugLog "xtra   : " + s[i]
    		Next
    	End If
    	DebugLog "column : " + error.getColumn()
    	Local node:TxmlNode = error.getErrorNode()
    	If node Then
    		DebugLog "node   : " + node.getName()
    	End If
    End Function

Function xmlSubstituteEntitiesDefault:Int(value:Int)
Returns | The last value for 0 for no substitution, 1 for substitution.
Description | Set and return the previous value for default entity support.
Information | Initially the parser always keep entity references instead of substituting entity values in the output. This function has to be used to change the default parser behavior. Parameters: value : the value to set

## Types

Type TxmlAttribute Extends TxmlBase
Description | An XML Attribute.

Methods Summary
getAttributeType | The attribute type, if validating.
getNameSpace | Returns the associated Namespace.
getValue | Returns the attribute value.

Method getAttributeType:Int()
Returns | The attribute type.
Description | The attribute type, if validating.
Information | Possible attribute types are:
Constant
XML_ATTRIBUTE_CDATA
XML_ATTRIBUTE_ID
XML_ATTRIBUTE_IDREF
XML_ATTRIBUTE_IDREFS
XML_ATTRIBUTE_ENTITY
XML_ATTRIBUTE_ENTITIES
XML_ATTRIBUTE_NMTOKEN
XML_ATTRIBUTE_NMTOKENS
XML_ATTRIBUTE_ENUMERATION
XML_ATTRIBUTE_NOTATION

Method getNameSpace:TxmlNs()
Returns | The associated namespace, or Null if none.
Description | Returns the associated Namespace.

Method getValue:String()
Description | Returns the attribute value.
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.parseFile("attributes.xml")

    If doc Then

    	' output the document to stdout
    	doc.saveFile("-")

    	' print first child attributes
    	For Local attribute:TxmlAttribute = EachIn TxmlNode(doc.getRootElement().getFirstChild()).getAttributeList()

    		Print attribute.getName() + " : " + attribute.getValue()

    	Next
    End If

Type TxmlBase Abstract
Description | The base Type for TxmlDoc, TxmlNode, TxmlAttribute, TxmlEntity, TxmlDtd, TxmlDtdElement and TxmlDtdAttribute.

Methods Summary
getChildren | Returns a list of child nodes of a given node type.
getDocument | Returns the document for this object.
getFirstChild | Get the first child.
getLastChild | Get the last child.
getLineNumber | Get the line number of the element.
getName | Returns the node name.
GetParent | Get the parent.
getType | Returns the type of this xml object.
nextSibling | Get the next sibling node.
previousSibling | Get the previous sibling node.

Method getChildren:TList(nodeType:Int = XML_ELEMENT_NODE)
Description | Returns a list of child nodes of a given node type.
Information | Parameters: nodeType : the type of node to return, or 0 for any. See getType for a list of node types.

Method getDocument:TxmlDoc()
Description | Returns the document for this object.

Method getFirstChild:TxmlBase(nodeType:Int = XML_ELEMENT_NODE)
Returns | The first child or Null if none.
Description | Get the first child.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "../examples/file2.xml"
    Local doc:TxmlDoc

    doc = TxmlDoc.parseFile(docname)
    If doc Then
    	Local root:TxmlNode = doc.getRootElement()

    	Print "First child is - " + root.getFirstChild().getName()

    End If

Method getLastChild:TxmlBase(nodeType:Int = XML_ELEMENT_NODE)
Returns | The last child or Null if none.
Description | Get the last child.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "../examples/file2.xml"
    Local doc:TxmlDoc

    doc = TxmlDoc.parseFile(docname)
    If doc Then
    	Local root:TxmlNode = doc.getRootElement()

    	Print "Last child is - " + root.getLastChild().getName()

    End If

Method getLineNumber:Long()
Returns | The line number if successful, or -1 otherwise.
Description | Get the line number of the element.

Method getName:String()
Description | Returns the node name.

Method GetParent:TxmlBase()
Returns | The parent to this object.
Description | Get the parent.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "../examples/file1.xml"
    Local doc:TxmlDoc

    doc = TxmlDoc.parseFile(docname)
    If doc Then
    	Local root:TxmlNode = doc.getRootElement()

    	Print root.getName() + " has " + root.getChildren().count() + " children...~n"

    	For Local node:TxmlNode = EachIn root.getChildren()
    		Print "  " + node.getName() + " has parent '" + node.getParent().getName() + "'"
    	Next
    End If

Method getType:Int()
Description | Returns the type of this xml object.
Information | The following lists possible types:
Constant
XML_ELEMENT_NODE
XML_ATTRIBUTE_NODE
XML_TEXT_NODE
XML_CDATA_SECTION_NODE
XML_ENTITY_REF_NODE
XML_ENTITY_NODE
XML_PI_NODE
XML_COMMENT_NODE
XML_DOCUMENT_NODE
XML_DOCUMENT_TYPE_NODE
XML_DOCUMENT_FRAG_NODE
XML_NOTATION_NODE
XML_HTML_DOCUMENT_NODE
XML_DTD_NODE
XML_ELEMENT_DECL
XML_ATTRIBUTE_DECL
XML_ENTITY_DECL
XML_NAMESPACE_DECL
XML_XINCLUDE_START
XML_XINCLUDE_END
XML_DOCB_DOCUMENT_NODE

Method nextSibling:TxmlBase()
Returns | The next node or Null if there are none.
Description | Get the next sibling node.
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.parseFile("catalog.xml")

    If doc Then

    	Local root:TxmlNode = doc.getRootElement()

    	Local cd:TxmlNode = TxmlNode(root.getFirstChild())

    	While cd

    		' print element node details
    		If cd.getType() = XML_ELEMENT_NODE Then
    			Print cd.toString()
    		End If

    		' get the next sibling
    		cd = TxmlNode(cd.nextSibling())
    	Wend

    End If

Method previousSibling:TxmlBase()
Returns | The previous node or Null if there are none.
Description | Get the previous sibling node.
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.parseFile("catalog.xml")

    If doc Then

    	Local root:TxmlNode = doc.getRootElement()

    	Local cd:TxmlNode = TxmlNode(root.getLastChild())

    	While cd

    		' print element node details
    		If cd.getType() = XML_ELEMENT_NODE Then
    			Print cd.toString()
    		End If

    		' get the previous sibling
    		cd = TxmlNode(cd.previousSibling())
    	Wend

    End If

Type TxmlBuffer
Description | Xml Buffer.

Methods Summary
getContent | Extract the content of a buffer.

Functions Summary
createStatic | Routine to create an XML buffer from an immutable memory area.

Method getContent:String()
Description | Extract the content of a buffer.

Function createStatic:TxmlBuffer(mem:Byte Ptr, size:Int)
Description | Routine to create an XML buffer from an immutable memory area.
Information | The area won't be modified nor copied, and is expected to be present until the end of the buffer lifetime.

Type TxmlCatalog
Description | An XML Catalog.

Methods Summary
add | Add an entry in the catalog, it may overwrite existing but different entries.
convertSGML | Convert all the SGML catalog entries as XML ones.
dump | Dump the catalog to the given file.
free | Free the memory allocated to a Catalog.
isEmpty | Check is a catalog is empty.
remove | Remove an entry from the catalog.
resolve | Do a complete resolution lookup of an External Identifier.
resolvePublic | Try to lookup the catalog local reference associated to a public ID in that catalog.
resolveSystem | Try to lookup the catalog resource for a system ID.

Functions Summary
addDefault | Add an entry in the catalog.
convertDefault | Convert all the SGML catalog entries as XML ones.
defaultRemove | Remove an entry from the catalog.
defaultResolve | Do a complete resolution lookup of an External Identifier.
defaultResolvePublic | Try to lookup the catalog reference associated to a public ID.
defaultResolveSystem | Try to lookup the catalog resource for a system ID.
defaultResolveURI | Do a complete resolution lookup of an URI.
getDefaults | Used to get the user preference w.r.t. to what catalogs should be accepted.
loadCatalog | Load the catalog and build the associated data structures.
loadDefaultCatalg | Load the catalog and makes its definitions effective for the default external entity loader.
loadSGMLSuperCatalog | Load an SGML super catalog.
newCatalog | Create a new Catalog.
setDebug | Used to set the debug level for catalog operation.
setDefaultPrefer | Allows to set the preference between public and system for deletion in XML Catalog resolution.
setDefaults | Used to set the user preference w.r.t. to what catalogs should be accepted.

Method add:Int(rtype:String, orig:String, rep:String)
Returns | 0 if successful, -1 otherwise.
Description | Add an entry in the catalog, it may overwrite existing but different entries.
Information | Parameters: rtype : the type of record to add to the catalog orig : the system, public or prefix to match rep : the replacement value for the match

Method convertSGML:Int()
Returns | The number of entries converted if successful, -1 otherwise.
Description | Convert all the SGML catalog entries as XML ones.

Method dump(file:Int)
Description | Dump the catalog to the given file.

Method free()
Description | Free the memory allocated to a Catalog.

Method isEmpty:Int()
Returns | 1 if the catalog is empty, 0 if not, and -1 in case of error.
Description | Check is a catalog is empty.

Method remove:Int(value:String)
Returns | The number of entries removed if successful, -1 otherwise.
Description | Remove an entry from the catalog.
Information | Parameters: value : the value to remove

Method resolve:String(pubID:String, sysID:String)
Returns | The URI of the resource or Null if not found.
Description | Do a complete resolution lookup of an External Identifier.
Information | Parameters: pubID : the public ID string sysID : the system ID string

Method resolvePublic:String(pubID:String)
Returns | The local resource if found or Null otherwise.
Description | Try to lookup the catalog local reference associated to a public ID in that catalog.
Information | Parameters: pubID : the public ID string

Method resolveSystem:String(sysID:String)
Returns | The resource if found or Null otherwise.
Description | Try to lookup the catalog resource for a system ID.
Information | Parameters: sysID : the system ID string

Function addDefault:Int(rtype:String, orig:String, rep:String)
Returns | 0 if successful, -1 otherwise.
Description | Add an entry in the catalog.
Information | It may overwrite existing but different entries. If called before any other catalog routine, allows to override the default shared catalog put in place by initializeCatalog. Parameters: rtype : the type of record to add to the catalog orig : the system, public or prefix to match rep : the replacement value for the match, if any

Function convertDefault:Int()
Description | Convert all the SGML catalog entries as XML ones.

Function defaultRemove:Int(value:String)
Returns | The number of entries removed if successful, -1 otherwise.
Description | Remove an entry from the catalog.
Information | Parameters: value : the value to remove

Function defaultResolve:String(pubID:String, sysID:String)
Returns | The URI of the resource or Null if not found.
Description | Do a complete resolution lookup of an External Identifier.
Information | Parameters: pubID : the public ID string sysID : the system ID string

Function defaultResolvePublic:String(pubID:String)
Returns | The resource if found or Null otherwise.
Description | Try to lookup the catalog reference associated to a public ID.
Information | Parameters: pubID : the public ID string

Function defaultResolveSystem:String(sysID:String)
Returns | The resource if found or Null otherwise.
Description | Try to lookup the catalog resource for a system ID.
Information | Parameters: sysID : the system ID string

Function defaultResolveURI:String(uri:String)
Returns | The URI of the resource or Null if not found.
Description | Do a complete resolution lookup of an URI.
Information | Parameters: uri : the URI

Function getDefaults:Int()
Returns | The current xmlCatalogAllow value. See setDefaults for more information.
Description | Used to get the user preference w.r.t. to what catalogs should be accepted.

Function loadCatalog:TxmlCatalog(filename:String)
Returns | The catalog parsed or Null in case of error.
Description | Load the catalog and build the associated data structures.
Information | This can be either an XML Catalog or an SGML Catalog. It will recurse in SGML Catalog entries. On the other hand XML Catalogs are not handled recursively. Parameters: filename : a file path

Function loadDefaultCatalg:Int(filename:String)
Returns | 0 in case of success -1 in case of error.
Description | Load the catalog and makes its definitions effective for the default external entity loader.
Information | It will recurse in SGML CATALOG entries. Parameters: filename : a file path

Function loadSGMLSuperCatalog:TxmlCatalog(filename:String)
Returns | The catalog parsed or Null in case of error.
Description | Load an SGML super catalog.
Information | It won't expand CATALOG or DELEGATE references. This is only needed for manipulating SGML Super Catalogs like adding and removing CATALOG or DELEGATE entries. Parameters: filename : a file path

Function newCatalog:TxmlCatalog(sgml:Int)
Returns | A new catalog or Null in case of error.
Description | Create a new Catalog.
Information | Parameters: sgml : should this create an SGML catalog

Function setDebug:Int(level:Int)
Returns | The previous value of the catalog debugging level.
Description | Used to set the debug level for catalog operation.
Information | 0 disable debugging, 1 enable it. Parameters: level : the debug level of catalogs required

Function setDefaultPrefer:Int(prefer:Int)
Returns | The previous value of the default preference for delegation.
Description | Allows to set the preference between public and system for deletion in XML Catalog resolution.
Information | (C.f. section 4.1.1 of the spec) Values accepted are XML_CATA_PREFER_PUBLIC or XML_CATA_PREFER_SYSTEM. Parameters: prefer : the default preference for delegation

Function setDefaults(allow:Int)
Description | Used to set the user preference w.r.t. to what catalogs should be accepted.
Information | The following lists possible xmlCatalogAllow values:
Constant
XML_CATA_ALLOW_NONE
XML_CATA_ALLOW_GLOBAL
XML_CATA_ALLOW_DOCUMENT
XML_CATA_ALLOW_ALL

Type TxmlDoc Extends TxmlBase
Description | An XML Document.

Methods Summary
addDocEntity | Register a new entity for this document.
addDtdEntity | Register a new entity for this document DTD external subset.
addProcessingInstruction | Creation of a processing instruction element.
addProperty | Create a new property carried by the document.
contextNormalizeAttributeValue | Does the validation related extra step of the normalization of attribute values.
copy | Do a copy of the document info.
createExternalSubset | Creation of a new DTD for the external subset.
createInternalSubset | Create the internal subset of a document.
encodeEntities | Do a global encoding of a string.
encodeEntitiesReentrant | Do a global encoding of a string.
encodeSpecialChars | Do a global encoding of a string, replacing the predefined entities.
free | Free up all the structures used by a document, tree included.
freeDocElementContent | Free an element content structure.
getCompressMode | Get the compression ratio for a document.
getDocEntity | Do an entity lookup in the document entity hash table and return the corresponding entity, otherwise a lookup is done in the predefined entities too.
getDtdEntity | Do an entity lookup in the internal and external subsets and return the corresponding parameter entity, if found.
getEncoding | The external initial encoding, if any.
getID | Search the attribute declaring the given ID.
getInternalSubset | Get the internal subset of a document.
getParameterEntity | Do an entity lookup in the internal and external subsets and return the corresponding parameter entity, if found.
getRootElement | Returns the root element of the document.
getURL | The document URI.
getVersion | The XML version string.
isID | Determine whether an attribute is of type ID.
isMixedElement | Search in the DTDs whether an element accept Mixed content (or ANY) basically if it is supposed to accept text childs.
isRef | Determine whether an attribute is of type Ref.
isStandalone | Is this document standalone?
newDocElementContent | Allocate an element content structure for the document.
newXPathContext | Create a new TxmlXPathContext.
normalizeAttributeValue | Does the validation related extra step of the normalization of attribute values.
removeID | Remove the given attribute from the ID table maintained internally.
removeRef | Remove the given attribute from the Ref table maintained internally.
saveFile | Dump an XML document to a file.
saveFormatFile | Dump an XML document to a file.
setCompressMode | Set the default compression mode used, ZLIB based Correct values: 0 (uncompressed) to 9 (max compression)
setRootElement | Set the root element of the document (doc->children is a list containing possibly comments, PIs, etc ...)
XIncludeProcess | Implement the XInclude substitution on the XML document.
XIncludeProcessFlags | Implement the XInclude substitution on the XML document.
XPathOrderElements | Call this routine to speed up XPath computation on static documents.

Functions Summary
newDoc | Creates a new XML document.
parseCatalogFile | Parse an XML file and build a tree.
parseDoc | Parse an XML string and build a tree.
parseFile | Parse an XML file and build a tree.

Method addDocEntity:TxmlEntity(name:String, EntityType:Int, externalID:String, systemID:String, content:String)
Returns | The entity reference or Null in case of error.
Description | Register a new entity for this document.
Information | Parameters: name : the entity name entityType : the entity type (see above for details) externalID : the entity external ID, if available systemID : the entity system ID if available content : the entity content

Method addDtdEntity:TxmlEntity(name:String, EntityType:Int, externalID:String, systemID:String, content:String)
Returns | The entity reference or Null in case of error.
Description | Register a new entity for this document DTD external subset.
Information | Parameters: name : the entity name entityType : the entity type (see above for details) externalID : the entity external ID, if available systemID : the entity system ID if available content : the entity content

Method addProcessingInstruction:TxmlNode(name:String, content:String)
Returns | The new node object.
Description | Creation of a processing instruction element.
Information | Note - The processing instruction is only linked against the document, not the tree structure. You will need to additionally add it to the structure yourself. Parameters: name : the processing instruction name content : the processing instruction content

Method addProperty:TxmlAttribute(name:String, value:String)
Returns | The new attribute object.
Description | Create a new property carried by the document.
Information | Note - The property is only linked against the document, not the tree structure. You will need to additionally add it to the structure yourself. Parameters: name : the name of the attribute value : the value of the attribute

Method contextNormalizeAttributeValue:String(elem:TxmlNode, name:String, value:String, context:TxmlValidCtxt)
Returns | A new normalized string if normalization is needed, Null otherwise.
Description | Does the validation related extra step of the normalization of attribute values.
Information | If the declared value is not CDATA, then the XML processor must further process the normalized attribute value by discarding any leading and trailing space (#x20) characters, and by replacing sequences of space (#x20) characters by single space (#x20) character. Also check VC: Standalone Document Declaration in P32, and update ctxt->valid accordingly Parameters: elem : the parent name : the attribute name value : the attribute value context : the validation context or Null

Method copy:TxmlDoc(recursive:Int = True)
Returns | a new TxmlDoc, or Null in case of error.
Description | Do a copy of the document info.
Information | Parameters: recursive : if True, the content tree will be copied too as well as DTD, namespaces and entities.

Method createExternalSubset:TxmlDtd(name:String, externalID:String, systemID:String)
Returns | a new TxmlDtd object.
Description | Creation of a new DTD for the external subset.
Information | To create an internal subset, use createInternalSubset Parameters: name : the DTD name. externalID : the external ID. systemID : the system ID.

Method createInternalSubset:TxmlDtd(name:String, externalID:String, systemID:String)
Returns | a new TxmlDtd object.
Description | Create the internal subset of a document.
Information | Parameters: name : the DTD name. externalID : the external (PUBLIC) ID. systemID : the system ID.

Method encodeEntities:String(text:String)
Returns | A new string with the substitution done.
Description | Do a global encoding of a string.
Information | Replaces the predefined entities and non ASCII values with their entities and CharRef counterparts. Parameters: text : A string to convert to XML.

Method encodeEntitiesReentrant:String(inp:String)
Returns | A newly allocated string with the substitution done.
Description | Do a global encoding of a string.
Information | Replaces the predefined entities and non ASCII values with their entities and CharRef counterparts. Parameters: inp : a string to convert to XML

Method encodeSpecialChars:String(inp:String)
Returns | A newly allocated string with the substitution done.
Description | Do a global encoding of a string, replacing the predefined entities.
Information | Parameters: inp : a string to convert to XML

Method free()
Description | Free up all the structures used by a document, tree included.

Method freeDocElementContent(content:TxmlElementContent)
Description | Free an element content structure.
Information | The whole subtree is removed. Parameters: content : the element content tree to free

Method getCompressMode:Int()
Returns | 0 (uncompressed) to 9 (max compression)
Description | Get the compression ratio for a document.
Example |
    ' XML compression
    SuperStrict

    Framework BaH.Libxml
    Import BRL.standardio

    Local doc:TxmlDoc = TxmlDoc.newDoc("1.0")

    Print doc.getCompressMode()

    doc.setCompressMode(9)

    Print doc.getCompressMode()

Method getDocEntity:TxmlEntity(name:String)
Returns | Returns the entity structure or Null if not found.
Description | Do an entity lookup in the document entity hash table and return the corresponding entity, otherwise a lookup is done in the predefined entities too.
Information | Parameters: name : the entity name

Method getDtdEntity:TxmlEntity(name:String)
Returns | Returns the entity structure or Null if not found.
Description | Do an entity lookup in the internal and external subsets and return the corresponding parameter entity, if found.
Information | Parameters: name : the entity name

Method getEncoding:String()
Description | The external initial encoding, if any.

Method getID:TxmlAttribute(id:String)
Returns | Null if not found, otherwise the TxmlAttrribute defining the ID.
Description | Search the attribute declaring the given ID.
Information | Parameters: id : the ID value

Method getInternalSubset:TxmlDtd()
Returns | the DTD structure or Null if not found.
Description | Get the internal subset of a document.

Method getParameterEntity:TxmlEntity(name:String)
Returns | Returns the entity structure or Null if not found.
Description | Do an entity lookup in the internal and external subsets and return the corresponding parameter entity, if found.
Information | Parameters: name : the entity name

Method getRootElement:TxmlNode()
Description | Returns the root element of the document.
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.parseFile("catalog.xml")

    If doc Then

    	' get the document root node
    	Local root:TxmlNode = doc.getRootElement()

    	' output the node structure
    	Print root.toString()

    End If

Method getURL:String()
Description | The document URI.

Method getVersion:String()
Description | The XML version string.

Method isID:Int(node:TxmlNode, attr:TxmlAttribute)
Returns | 0 or 1 depending on the lookup result.
Description | Determine whether an attribute is of type ID.
Information | In case we have DTD(s) then this is done if DTD loading has been requested. In the case of HTML documents parsed with the HTML parser, then ID detection is done systematically. Parameters: node : the node carrying the attribute attr : the attribute

Method isMixedElement:Int(name:String)
Returns | 0 if no, 1 if yes, and -1 if no element description is available.
Description | Search in the DTDs whether an element accept Mixed content (or ANY) basically if it is supposed to accept text childs.
Information | Parameters: name : the element name

Method isRef:Int(node:TxmlNode, attr:TxmlAttribute)
Returns | 0 or 1 depending on the lookup result.
Description | Determine whether an attribute is of type Ref.
Information | In case we have DTD(s) then this is simple, otherwise we use an heuristic: name Ref (upper or lowercase). Parameters: node : the node carrying the attribute attr : the attribute

Method isStandalone:Int()
Returns | True if the document has no external refs.
Description | Is this document standalone?

Method newDocElementContent:TxmlElementContent(name:String, contentType:Int)
Returns | Null if not, otherwise the new element content structure.
Description | Allocate an element content structure for the document.
Information | Parameters: name : the subelement name or Null contentType : the type of element content decl (see below) The following lists the valid content types:
Constant
XML_ELEMENT_CONTENT_PCDATA
XML_ELEMENT_CONTENT_ELEMENT
XML_ELEMENT_CONTENT_SEQ
XML_ELEMENT_CONTENT_OR

Method newXPathContext:TxmlXPathContext()
Description | Create a new TxmlXPathContext.

Method normalizeAttributeValue:String(elem:TxmlNode, name:String, value:String)
Returns | A new normalized string if normalization is needed, Null otherwise.
Description | Does the validation related extra step of the normalization of attribute values.
Information | If the declared value is not CDATA, then the XML processor must further process the normalized attribute value by discarding any leading and trailing space (#x20) characters, and by replacing sequences of space (#x20) characters by single space (#x20) character. Parameters: elem : the parent name : the attribute name value : the attribute value

Method removeID:Int(attr:TxmlAttribute)
Returns | -1 if the lookup failed and 0 otherwise.
Description | Remove the given attribute from the ID table maintained internally.
Information | Parameters: attr : the attribute

Method removeRef:Int(attr:TxmlAttribute)
Returns | -1 if the lookup failed and 0 otherwise.
Description | Remove the given attribute from the Ref table maintained internally.
Information | Parameters: attr : the attribute

Method saveFile:Int(filename:String)
Returns | the number of bytes written or -1 in case of failure.
Description | Dump an XML document to a file.
Information | Will use compression if set. If filename is "-" the standard out (console) is used. Parameters: filename : the filename (or URL)

Method saveFormatFile:Int(filename:String, format:Int)
Returns | the number of bytes written or -1 in case of failure.
Description | Dump an XML document to a file.
Information | Will use compression if compiled in and enabled. If filename is "-" the standard out (console) is used. If format is set to true then the document will be indented on output. Parameters: filename : the filename (or URL) format : should formatting spaces been added

Method setCompressMode(mode:Int)
Description | Set the default compression mode used, ZLIB based Correct values: 0 (uncompressed) to 9 (max compression)
Information | Parameters: mode : the compression ratio
Example |
    ' XML compression
    SuperStrict

    Framework BaH.Libxml
    Import BRL.standardio

    Local doc:TxmlDoc = TxmlDoc.newDoc("1.0")

    Print doc.getCompressMode()

    doc.setCompressMode(9)

    Print doc.getCompressMode()

Method setRootElement:TxmlNode(root:TxmlNode)
Returns | the old root element if any was found.
Description | Set the root element of the document (doc->children is a list containing possibly comments, PIs, etc ...)
Information | Parameters: root : the new document root element

Method XIncludeProcess:Int()
Returns | 0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
Description | Implement the XInclude substitution on the XML document.

Method XIncludeProcessFlags:Int(flags:Int)
Returns | 0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
Description | Implement the XInclude substitution on the XML document.
Information | Parameters: flags : a set of xml Parser Options used for parsing XML includes (see fromFile for option details)

Method XPathOrderElements:Long()
Returns | The number of elements found in the document or -1 in case of error.
Description | Call this routine to speed up XPath computation on static documents.
Information | This stamps all the element nodes with the document order Like for line information, the order is kept in the element->content field, the value stored is actually - the node number (starting at -1) to be able to differentiate from line numbers.

Function newDoc:TxmlDoc(Version:String)
Description | Creates a new XML document.
Information | Parameters: version : string giving the version of XML "1.0".
Example |
    SuperStrict

    Framework BaH.Libxml

    ' Create a new document
    Local doc:TxmlDoc = TxmlDoc.newDoc("1.0")

    If doc Then

    	' output the document to stdout
    	doc.saveFile("-")

    End If

Function parseCatalogFile:TxmlDoc(filename:String)
Returns | The resulting document tree or Null in case of error.
Description | Parse an XML file and build a tree.
Information | It's like parseFile() except it bypasses all catalog lookups. Note: Doesn't support "incbin::". Parameters: filename : the filename

Function parseDoc:TxmlDoc(text:String)
Returns | The resulting document tree or Null if error.
Description | Parse an XML string and build a tree.
Information | Parameters: text : the string to be parsed.
Example |
    SuperStrict

    Framework BaH.Libxml

    Local xml:String = ""
    xml:+ "Hello Bob!"

    Local doc:TxmlDoc = TxmlDoc.parseDoc(xml)

    If doc Then

    	' output the document to stdout, with formatting
    	doc.saveformatFile("-", True)

    End If

Function parseFile:TxmlDoc(filename:String)
Returns | The resulting document tree or Null if error.
Description | Parse an XML file and build a tree.
Information | Automatic support for ZLIB/Compress compressed document is provided by default. Parameters: filename : the name of the file to be parsed. Supports "incbin::".
Example |
    SuperStrict

    Framework BaH.Libxml

    Local doc:TxmlDoc = TxmlDoc.parseFile("catalog.xml")

    If doc Then

    	' output the document to stdout
    	doc.saveFile("-")

    End If

Type TxmlDtd Extends TxmlBase
Description | An XML DTD.

Methods Summary
copyDtd | Do a copy of the dtd.
free | Free the DTD structure.
getAttrDesc | Search the DTD for the description of this attribute on this element.
getElementDesc | Search the DTD for the description of this element.
getExternalID | Returns the external identifier for PUBLIC DTD.
getNotationDesc | Search the DTD for the description of this notation.
getQAttrDesc | Search the DTD for the description of this qualified attribute on this element.
getQElementDesc | Search the DTD for the description of this qualified element.
getSystemID | Returns the URI for a SYSTEM or PUBLIC DTD.

Method copyDtd:TxmlDtd()
Returns | A new TxmlDtd object, or Null in case of error.
Description | Do a copy of the dtd.

Method free()
Description | Free the DTD structure.

Method getAttrDesc:TxmlDtdAttribute(elem:String, name:String)
Returns | The TxmlDtdAttribute if found or Null.
Description | Search the DTD for the description of this attribute on this element.
Information | Parameters: elem : the element name name : the attribute name

Method getElementDesc:TxmlDtdElement(name:String)
Returns | The TxmlDtdElement if found or Null.
Description | Search the DTD for the description of this element.
Information | Parameters: name : the element name

Method getExternalID:String()
Description | Returns the external identifier for PUBLIC DTD.

Method getNotationDesc:TxmlNotation(name:String)
Returns | The TxmlNotation if found or Null.
Description | Search the DTD for the description of this notation.
Information | Parameters: name : the notation name

Method getQAttrDesc:TxmlDtdAttribute(elem:String, name:String, prefix:String)
Returns | The TxmlDtdAttribute if found or Null.
Description | Search the DTD for the description of this qualified attribute on this element.
Information | Parameters: elem : the element name name : the attribute name prefix : the attribute namespace prefix

Method getQElementDesc:TxmlDtdElement(name:String, prefix:String)
Returns | The TxmlDtdElement if found or Null.
Description | Search the DTD for the description of this qualified element.
Information | Parameters: name : the element name prefix : the element namespace prefix

Method getSystemID:String()
Description | Returns the URI for a SYSTEM or PUBLIC DTD.

Type TxmlDtdAttribute Extends TxmlBase
Description | An XML Attribute Decl.

Methods Summary
getDefaultValue | Returns the attribute default value.

Method getDefaultValue:String()
Description | Returns the attribute default value.

Type TxmlDtdElement Extends TxmlBase
Description | An XML Element.

Methods Summary
getElementType | Returns the element type.
getPrefix | Returns the namespace prefix, if any.

Method getElementType:Int()
Description | Returns the element type.
Information | The following lists possible element types:
Constant
XML_ELEMENT_TYPE_UNDEFINED
XML_ELEMENT_TYPE_EMPTY
XML_ELEMENT_TYPE_ANY
XML_ELEMENT_TYPE_MIXED
XML_ELEMENT_TYPE_ELEMENT

Method getPrefix:String()
Description | Returns the namespace prefix, if any.

Type TxmlElementContent
Description | An XML element content tree.

Methods Summary
getName | Returns the element name.
getOccur | Returns the content occurance.
getPrefix | Returns the namespace prefix.
getType | Returns the content type.

Method getName:String()
Description | Returns the element name.

Method getOccur:Int()
Description | Returns the content occurance.
Information | The following lists the possible content occurances:
Constant
XML_ELEMENT_CONTENT_ONCE
XML_ELEMENT_CONTENT_OPT
XML_ELEMENT_CONTENT_MULT
XML_ELEMENT_CONTENT_PLUS

Method getPrefix:String()
Description | Returns the namespace prefix.

Method getType:Int()
Description | Returns the content type.
Information | The following lists the possible content types:
Constant
XML_ELEMENT_CONTENT_PCDATA
XML_ELEMENT_CONTENT_ELEMENT
XML_ELEMENT_CONTENT_SEQ
XML_ELEMENT_CONTENT_OR

Type TxmlEntity Extends TxmlBase
Description | An XML Entity.

Type TxmlError
Description | An XML Error.

Methods Summary
getColumn | Returns the column number of the error or 0 if not available.
getErrorCode | Returns the error code.
getErrorDomain | Returns the part of the library that raised the error.
getErrorLevel | Returns the error level.
getErrorMessage | Returns the error message text.
getErrorNode | Returns the node in the tree, if available.
getExtraText | Returns extra error text information, if available.
getFilename | Returns the filename.
getLine | Returns the error line, if available.

Method getColumn:Int()
Description | Returns the column number of the error or 0 if not available.

Method getErrorCode:Int()
Description | Returns the error code.

Method getErrorDomain:Int()
Description | Returns the part of the library that raised the error.
Information | The following lists possible domains:
Constant | Meaning
--- | ---
XML_FROM_NONE | From none
XML_FROM_PARSER | The XML parser
XML_FROM_TREE | The tree module
XML_FROM_NAMESPACE | The XML Namespace module
XML_FROM_DTD | The XML DTD validation with parser contex
XML_FROM_HTML | The HTML parser
XML_FROM_MEMORY | The memory allocator
XML_FROM_OUTPUT | The serialization code
XML_FROM_IO | The Input/Output stack
XML_FROM_FTP | The FTP module
XML_FROM_HTTP | The HTTP module
XML_FROM_XINCLUDE | The XInclude processing
XML_FROM_XPATH | The XPath module
XML_FROM_XPOINTER | The XPointer module
XML_FROM_REGEXP | The regular expressions module
XML_FROM_DATATYPE | The W3C XML Schemas Datatype module
XML_FROM_SCHEMASP | The W3C XML Schemas parser module
XML_FROM_SCHEMASV | The W3C XML Schemas validation module
XML_FROM_RELAXNGP | The Relax-NG parser module
XML_FROM_RELAXNGV | The Relax-NG validator module
XML_FROM_CATALOG | The Catalog module
XML_FROM_C14N | The Canonicalization module
XML_FROM_XSLT | The XSLT engine from libxslt
XML_FROM_VALID | The XML DTD validation with valid context
XML_FROM_CHECK | The error checking module
XML_FROM_WRITER | The xmlwriter module
XML_FROM_MODULE | The dynamically loaded module
XML_FROM_I18N | The module handling character conversion

Method getErrorLevel:Int()
Description | Returns the error level.
Information | The following is a list of error levels:
Constant | Meaning
--- | ---
XML_ERR_NONE | No error
XML_ERR_WARNING | A simple warning
XML_ERR_ERROR | A recoverable error
XML_ERR_FATAL | A fatal error

Method getErrorMessage:String()
Description | Returns the error message text.

Method getErrorNode:TxmlNode()
Description | Returns the node in the tree, if available.

Method getExtraText:String[]()
Description | Returns extra error text information, if available.

Method getFilename:String()
Description | Returns the filename.

Method getLine:Int()
Description | Returns the error line, if available.

Type TxmlLocationSet
Description | An XML Location Set.

Methods Summary
add | Add a new TxmlXPathObject to an existing LocationSet.
del | Removes a TxmlXPathObject from the LocationSet.
free | Free the LocationSet compound (not the actual ranges !).
merge | Merges two rangesets.
remove | Removes an entry from an existing LocationSet list.

Functions Summary
Create | Create a new xmlLocationSetPtr of type double.

Method add(value:TxmlXPathObject)
Description | Add a new TxmlXPathObject to an existing LocationSet.
Information | If the location already exist in the set value is freed. Parameters: value : a new TxmlXPathObject

Method del(value:TxmlXPathObject)
Description | Removes a TxmlXPathObject from the LocationSet.

Method free()
Description | Free the LocationSet compound (not the actual ranges !).

Method merge:TxmlLocationSet(value:TxmlLocationSet)
Returns | This set once extended or Null in case of error.
Description | Merges two rangesets.
Information | All ranges from value are added to this set. Parameters: value : a location set to merge

Method remove(index:Int)
Description | Removes an entry from an existing LocationSet list.
Information | Parameters: index : the index to remove

Function Create:TxmlLocationSet()
Returns | The newly created object.
Description | Create a new xmlLocationSetPtr of type double.

Type TxmlNode Extends TxmlBase
Description | An XML Node.

Methods Summary
addAttribute | Create a new attribute.
addCDataBlock | Creation of a new node containing a CDATA block.
addChild | Creation of a new child element.
addChildList | Add a list of nodes at the end of the child list of this node, merging adjacent TEXT nodes.
addComment | Creation of a new node containing a comment.
addContent | Append the extra substring to the node content.
addNextSibling | Add a new node node as the next sibling.
addPreviousSibling | Add a new node node as the previous sibling, merging adjacent TEXT nodes.
addSibling | Add a new element node to the list of siblings, merging adjacent TEXT nodes.
addTextChild | Creation of a new child text element.
concatText | Concat the given string at the end of the existing node content.
copy | Do a copy of the node.
copyToDoc | Do a copy of the node to a given document.
freeNode | Frees a node.
getAttribute | Search and get the value of an attribute associated to the node.
getAttributeList | Returns the list of node attributes.
getBase | Searches for the BASE URL.
getContent | Read the value of a node.
getFirstChild | Get the first child.
GetLanguage | Searches the language of a node, i.e. the values of the xml:lang attribute or the one carried by the nearest ancestor.
getLastChild | Get the last child.
getNamespace | Returns the associated namespace.
getNodePath | Build a structure based Path for the node.
getNoNsAttribute | Search and get the value of an attribute associated to the node.
getNsAttribute | Search and get the value of an attribute associated to a node.
getSpacePreserve | Searches the space preserving behaviour of a node, i.e. the values of the xml:space attribute or the one carried by the nearest ancestor.
GetText | Return the string equivalent to the text contained in the child nodes made of TEXTs and ENTITY_REFs.
hasAttribute | Search an attribute associated to the node.
hasNsAttribute | Search for an attribute associated to the node.
isBlankNode | Checks whether this node is an empty or whitespace only (and possibly ignorable) text-node.
isText | Is this node a Text node ?
nextNode | Get the next sibling node.
previousNode | Get the previous sibling node.
replaceNode | Unlink the old node from its current context.
searchNamespace | Search a Namespace registered under a given name space for a document.
searchNsByHref | Search a Namespace aliasing a given URI.
setAttribute | Set (or reset) an attribute carried by a node.
setBase | Set (or reset) the base URI of a node, i.e. the value of the xml:base attribute.
setContent | Replace the content of a node.
setLanguage | Set the language of a node, i.e. the values of the xml:lang attribute.
setName | Set (or reset) the name of a node.
setNamespace | Associate a namespace to a node, a posteriori.
setNsAttribute | Set (or reset) an attribute carried by a node.
setSpacePreserve | Set (or reset) the space preserving behaviour of a node, i.e. the value of the xml:space attribute.
setTreeDoc | Update all nodes under the tree to point to the right document.
textMerge | Merge two text nodes into one.
toString | Returns a string representation of the node and its children.
unlinkNode | Unlinks a node from the document.
unsetAttribute | Remove an attribute carried by the node.
unsetNsAttribute | Remove an attribute carried by the node.
XIncludeProcessTree | Implement the XInclude substitution for the subtree.
XIncludeProcessTreeFlags | Implement the XInclude substitution for the subtree.

Functions Summary
newNode | Creation of a new node element.

Method addAttribute:TxmlAttribute(name:String, value:String = "")
Returns | The Attribute object.
Description | Create a new attribute.
Information | Parameters: name : the attribute name. value : the attribute value.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "sample.xml"
    Local uri:String = "http://blitzmax.com"
    Local doc:TxmlDoc

    doc = parseDoc(docname, uri)
    If doc <> Null Then
    	doc.saveFormatFile("-", True)
    	doc.free()
    End If

    Function parseDoc:TxmlDoc(docname:String, uri:String)

            Local doc:TxmlDoc
            Local node:TxmlNode
            Local newnode:TxmlNode
            Local newattr:TxmlAttribute

            doc = TxmlDoc.parseFile(docname)

            If doc = Null Then
                    Print "Document not parsed successfully."
                    Return Null
            End If

            node = doc.getRootElement()

            If node = Null Then
                    Print "empty document"
                    doc.free()
                    Return Null
            End If

            If node.getName() <> "story" Then
                    Print "document of the wrong type, root node <> story"
                    doc.free()
                    Return Null
            End If

            newnode = node.addTextChild("reference", Null, Null)
            newattr = newnode.addAttribute("uri", uri)
            Return doc
    End Function

Method addCDataBlock:TxmlNode(content:String)
Returns | the new node object.
Description | Creation of a new node containing a CDATA block.
Information | Parameters: content : the CDATA block content

Method addChild:TxmlNode(name:String, namespace:TxmlNs = Null, content:String = Null)
Description | Creation of a new child element.
Information | Added at the end of child nodes list. namespace and content parameters are optional (Null). If namespace is Null, the newly created element inherits the namespace of the node. If content is non Null, a child list containing the TEXTs and ENTITY_REFs node will be created. NOTE: content is supposed to be a piece of XML CDATA, so it allows entity references. XML special chars must be escaped first by using doc.#encodeEntities, or #addTextChild should be used. Parameters: name : the name of the child. namespace : a namespace if any. content : the XML content of the child if any.
Example |
    SuperStrict

    Framework BaH.Libxml

    Local doc:TxmlDoc = TxmlDoc.parseFile("attributes.xml")

    If doc Then

    	Local node:TxmlNode = TxmlNode(doc.getRootElement().getFirstChild())

    	node.addChild("ID", Null, "C0122200")

    	doc.savefile("-")

    End If

Method addChildList:TxmlNode(list:TList)
Returns | the last child or Null in case of error.
Description | Add a list of nodes at the end of the child list of this node, merging adjacent TEXT nodes.
Information | Parameters: list : the list of nodes.

Method addComment:TxmlNode(comment:String)
Returns | the new node object.
Description | Creation of a new node containing a comment.
Information | Parameters: comment : the comment content
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.parseFile("catalog.xml")

    If doc Then

    	Local node:TxmlNode = TxmlNode(doc.getRootElement().getLastChild())

    	node.addComment("This CD rocks!")

    	Print node.toString()

    End If

Method addContent(content:String)
Description | Append the extra substring to the node content.
Information | Parameters: content : extra content
Example |
    SuperStrict

    Framework BaH.Libxml

    Local doc:TxmlDoc = TxmlDoc.parseFile("attributes.xml")

    If doc Then

    	Local node:TxmlNode = TxmlNode(doc.getRootElement().getFirstChild())

    	Local desc:TxmlNode = node.addChild("description", Null, Null)

    	desc.addContent("Some of the songs on this CD are awesome.~n")
    	desc.addContent("Tracks 5 & 6 put this CD up there...")

    	doc.savefile("-")

    End If

Method addNextSibling:TxmlNode(node:TxmlNode)
Returns | the new node or Null in case of error.
Description | Add a new node node as the next sibling.
Information | If the new node was already inserted in a document it is first unlinked from its existing context. If the new node is ATTRIBUTE, it is added into properties instead of children. If there is an attribute with equal name, it is first destroyed. Parameters: node : the new node.
Example |
    SuperStrict

    Framework BaH.Libxml

    Local doc:TxmlDoc = TxmlDoc.parseFile("attributes.xml")

    If doc Then

    	Local node:TxmlNode = TxmlNode(doc.getRootElement().getFirstChild())

    	' a new node for the document
    	Local newNode:TxmlNode = TxmlNode.newnode("cd")
    	newNode.addAttribute("title", "Together Alone")
    	newNode.addAttribute("artist", "Crowded House")
    	newNode.addChild("country", Null, "NZ")

    	' add new node to document as sibling of node.
    	node.addNextSibling(newNode)

    	' output the document to stdout
    	doc.saveFile("-")
    End If

Method addPreviousSibling:TxmlNode(node:TxmlNode)
Returns | the new node or Null in case of error.
Description | Add a new node node as the previous sibling, merging adjacent TEXT nodes.
Information | If the new node was already inserted in a document it is first unlinked from its existing context. If the new node is ATTRIBUTE, it is added into properties instead of children. If there is an attribute with equal name, it is first destroyed. Parameters: node : the new node.
Example |
    SuperStrict

    Framework BaH.Libxml

    Local doc:TxmlDoc = TxmlDoc.parseFile("attributes.xml")

    If doc Then

    	Local node:TxmlNode = TxmlNode(doc.getRootElement().getFirstChild())

    	' a new node for the document
    	Local newNode:TxmlNode = TxmlNode.newnode("cd")
    	newNode.addAttribute("title", "This is the Sea")
    	newNode.addAttribute("artist", "Waterboys")
    	newNode.addChild("country", Null, "UK")

    	' add new node to document as previous sibling of node.
    	node.addPreviousSibling(newNode)

    	' output the document to stdout
    	doc.saveFile("-")
    End If

Method addSibling:TxmlNode(node:TxmlNode)
Returns | the new node or Null in case of error.
Description | Add a new element node to the list of siblings, merging adjacent TEXT nodes.
Information | If the new element was already inserted in a document it is first unlinked from its existing context. Parameters: node : the new node.

Method addTextChild:TxmlNode(name:String, namespace:TxmlNs = Null, content:String = Null)
Returns | The new child node.
Description | Creation of a new child text element.
Information | Added at the end of parent children list. namespace and content parameters are optional (Null). If namespace is Null, the newly created element inherits the namespace of the parent. If content is non Null, a child TEXT node will be created containing the string content. NOTE: Use addChild if content will contain entities that need to be preserved. Use this function, addTextChild, if you need to ensure that reserved XML chars that might appear in content, such as the ampersand, greater-than or less-than signs, are automatically replaced by their XML escaped entity representations. Parameters: name : the name of the child. namespace : a namespace, if any. content : the text content of the child, if any.

Method concatText:Int(content:String)
Returns | -1 in case of error, 0 otherwise.
Description | Concat the given string at the end of the existing node content.
Information | Parameters: content : the content.

Method copy:TxmlNode(extended:Int = 1)
Returns | a new TxmlNode, or Null in case of error.
Description | Do a copy of the node.
Information | Parameters: extended : if 1 do a recursive copy (properties, namespaces and children when applicable) if 2 copy properties and namespaces (when applicable)

Method copyToDoc:TxmlNode(doc:TxmlDoc, extended:Int = 1)
Returns | a new TxmlNode, or Null in case of error.
Description | Do a copy of the node to a given document.
Information | Parameters: doc : the document. extended : if 1 do a recursive copy (properties, namespaces and children when applicable) if 2 copy properties and namespaces (when applicable)

Method freeNode()
Description | Frees a node.
Information | The node should be unlinked before being freed. See unlinkNode.

Method getAttribute:String(name:String)
Returns | The attribute value or Null if not found.
Description | Search and get the value of an attribute associated to the node.
Information | This does the entity substitution. This function looks in DTD attribute declaration for FIXED or default declaration values unless DTD use has been turned off. NOTE: this function acts independently of namespaces associated to the attribute. Use getNsAttribute or getNoNsAttribute for namespace aware processing. Parameters: name : the attribute name.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "sampleuri.xml"
    parseDoc(docname)

    Function getReference(doc:TxmlDoc, node:TxmlNode)

    	Local uri:String

    	Local list:TList = node.getChildren()
    	For node = EachIn list
    		If node.getName() = "reference" Then
    			uri = node.getAttribute("uri")
    			Print "uri: " + uri
    		End If
    	Next
    End Function

    Function parseDoc(docname:String)

            Local doc:TxmlDoc
            Local node:TxmlNode

            doc = TxmlDoc.parseFile(docname)

            If doc = Null Then
                    Print "Document not parsed successfully."
                    Return
            End If

            node = doc.getRootElement()

            If node = Null Then
                    Print "empty document"
                    doc.free()
                    Return
            End If

            If node.getName() <> "story" Then
                    Print "document of the wrong type, root node <> story"
                    doc.free()
                    Return
            End If

            getReference(doc, node)
            doc.free()
    End Function

Method getAttributeList:TList()
Returns | The list of attributes or Null if the node has none.
Description | Returns the list of node attributes.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "../examples/file1.xml"
    Local doc:TxmlDoc

    doc = TxmlDoc.parseFile(docname)
    If doc Then
    	Local root:TxmlNode = doc.getRootElement()

    	For Local node:TxmlNode = EachIn root.getChildren()
    		Print node.getName() + " : "

    		For Local attribute:TxmlAttribute = EachIn node.getAttributeList()
    			Print "    " + attribute.getName() + " : " + attribute.getValue()
    		Next

    		Print ""
    	Next
    End If

Method getBase:String()
Returns | The base URL, or Null if not found.
Description | Searches for the BASE URL.
Information | The code should work on both XML and HTML document even if base mechanisms are completely different. It returns the base as defined in RFC 2396 sections 5.1.1. Base URI within Document Content and 5.1.2. Base URI from the Encapsulating Entity However it does not return the document base (5.1.3), use TxmlDoc. getBase for this.

Method getContent:String()
Returns | The node content.
Description | Read the value of a node.
Information | This can be either the text carried directly by this node if it's a TEXT node or the aggregate string of the values carried by this node child's (TEXT and ENTITY_REF). Entity references are substituted.

Method getFirstChild:TxmlBase(nodeType:Int = XML_ELEMENT_NODE)
Returns | The first child or Null if none.
Description | Get the first child.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "../examples/file2.xml"
    Local doc:TxmlDoc

    doc = TxmlDoc.parseFile(docname)
    If doc Then
    	Local root:TxmlNode = doc.getRootElement()

    	Print "First child is - " + root.getFirstChild().getName()

    End If

Method GetLanguage:String()
Returns | the language value, or Null if not found.
Description | Searches the language of a node, i.e. the values of the xml:lang attribute or the one carried by the nearest ancestor.

Method getLastChild:TxmlNode(nodeType:Int = XML_ELEMENT_NODE)
Returns | The last child or Null if none.
Description | Get the last child.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "../examples/file2.xml"
    Local doc:TxmlDoc

    doc = TxmlDoc.parseFile(docname)
    If doc Then
    	Local root:TxmlNode = doc.getRootElement()

    	Print "Last child is - " + root.getLastChild().getName()

    End If

Method getNamespace:TxmlNs()
Description | Returns the associated namespace.

Method getNodePath:String()
Returns | The path or Null in case of error.
Description | Build a structure based Path for the node.
Example |
    ' output list of node paths
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.parseFile("attributes.xml")

    If doc Then

    	Local node:TxmlNode = TxmlNode(doc.getRootElement().getFirstChild())

    	For Local child:TxmlNode = EachIn node.getChildren()

    		' output the child Xpath value
    		Print child.getNodePath()

    	Next

    End If

Method getNoNsAttribute:String(name:String)
Returns | the attribute value or Null if not found.
Description | Search and get the value of an attribute associated to the node.
Information | This does the entity substitution. This function looks in DTD attribute declaration for FIXED or default declaration values unless DTD use has been turned off. This function is similar to getAttribute except it will accept only an attribute in no namespace. Parameters: name : the attribute name

Method getNsAttribute:String(name:String, namespace:String)
Returns | the attribute value or Null if not found.
Description | Search and get the value of an attribute associated to a node.
Information | This attribute has to be anchored in the namespace specified. This does the entity substitution. This function looks in DTD attribute declaration for FIXED or default declaration values unless DTD use has been turned off. Parameters: name : the attribute name namespace : the URI of the namespace

Method getSpacePreserve:Int()
Description | Searches the space preserving behaviour of a node, i.e. the values of the xml:space attribute or the one carried by the nearest ancestor.

Method GetText:String()
Description | Return the string equivalent to the text contained in the child nodes made of TEXTs and ENTITY_REFs.

Method hasAttribute:TxmlAttribute(name:String)
Returns | the attribute or Null if not found.
Description | Search an attribute associated to the node.
Information | This function also looks in DTD attribute declaration for FIXED or default declaration values unless DTD use has been turned off. Parameters: name : the attribute name
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.parseFile("attributes.xml")

    If doc Then

    	Local node:TxmlNode = TxmlNode(doc.getRootElement().getFirstChild())

    	Local attribute:TxmlAttribute = node.hasAttribute("artist")

    	If attribute Then

    		Print "Artist = " + attribute.getValue()

    	End If

    End If

Method hasNsAttribute:TxmlAttribute(name:String, namespace:String)
Returns | the attribute or Null if not found.
Description | Search for an attribute associated to the node.
Information | This attribute has to be anchored in the namespace specified. This does the entity substitution. This function looks in DTD attribute declaration for FIXED or default declaration values unless DTD use has been turned off. Note that a namespace of Null indicates to use the default namespace. Parameters: name : the attribute name namespace : the URI of the namespace

Method isBlankNode:Int()
Description | Checks whether this node is an empty or whitespace only (and possibly ignorable) text-node.

Method isText:Int()
Description | Is this node a Text node ?

Method nextNode:TxmlNode()
Returns | The next node or Null if there are none.
Description | Get the next sibling node.
Information | Equivalent to TxmlNode( nextSibling() ).

Method previousNode:TxmlNode()
Returns | The previous node or Null if there are none.
Description | Get the previous sibling node.
Information | Equivalent to TxmlNode( previousSibling() ).

Method replaceNode:TxmlNode(withNode:TxmlNode)
Returns | The removed node.
Description | Unlink the old node from its current context.
Information | Prune the new one at the same place. If withNode was already inserted in a document it is first unlinked from its existing context. Parameters: withNode : the replacing node.
Example |
    SuperStrict

    Framework BaH.Libxml

    Local doc:TxmlDoc = TxmlDoc.parseFile("attributes.xml")

    If doc Then

    	Local node:TxmlNode = TxmlNode(doc.getRootElement().getFirstChild())

    	' a new node for the document
    	Local newNode:TxmlNode = TxmlNode.newnode("cd")
    	newNode.addAttribute("title", "High on the Happy Side")
    	newNode.addAttribute("artist", "Wet Wet Wet")
    	newNode.addChild("country", Null, "UK")

    	' replace node with the new node
    	node.replaceNode(newNode)

    	' output the document to stdout
    	doc.saveFile("-")
    End If

Method searchNamespace:TxmlNs(namespace:String)
Returns | the namespace or Null.
Description | Search a Namespace registered under a given name space for a document.
Information | Recurse on the parents until it finds the defined namespace or return Null otherwise. nameSpace can be Null, this is a search for the default namespace. We don't allow to cross entities boundaries. If you don't declare the namespace within those you will be in troubles !!! A warning is generated to cover this case. Parameters: namespace : the namespace prefix.

Method searchNsByHref:TxmlNs(href:String)
Returns | The namespace or Null.
Description | Search a Namespace aliasing a given URI.
Information | Recurse on the parents until it finds the defined namespace or return Null otherwise. Parameters: href : the namespace value.

Method setAttribute:TxmlAttribute(name:String, value:String = "")
Returns | The attribute object.
Description | Set (or reset) an attribute carried by a node.
Information | Parameters: name : the attribute name. value : the attribute value.
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.newDoc("1.0")

    If doc Then

    	Local root:TxmlNode = TxmlNode.newNode("root")
    	doc.setRootElement(root)

    	' create a new empty node
    	Local node:TxmlNode = root.addChild("node", Null, Null)

    	Print node.toString()

    	' set an attribute
    	node.setAttribute("attr1", "a value")

    	Print node.toString()

    	' change the attribute value
    	node.setAttribute("attr1", "a new value")

    	Print node.toString()

    End If

Method setBase(uri:String)
Description | Set (or reset) the base URI of a node, i.e. the value of the xml:base attribute.
Information | Parameters: uri : the new base URI.

Method setContent(content:String)
Description | Replace the content of a node.
Information | Parameters: content : the new value of the content
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.newDoc("1.0")

    If doc Then

    	Local root:TxmlNode = TxmlNode.newNode("root")
    	doc.setRootElement(root)

    	' create a new empty node
    	Local node:TxmlNode = root.addChild("node", Null, Null)

    	Print node.toString()

    	' set the node content
    	node.setContent("Some text content for the node")

    	Print node.toString()

    	' change the node content
    	node.setContent("Modified content!")

    	Print node.toString()

    End If

Method setLanguage(lang:String)
Description | Set the language of a node, i.e. the values of the xml:lang attribute.
Information | Parameters: lang : the language description.

Method setName(name:String)
Description | Set (or reset) the name of a node.
Information | Parameters: name : the new tag name
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.newDoc("1.0")

    If doc Then

    	Local root:TxmlNode = TxmlNode.newNode("root")
    	doc.setRootElement(root)

    	' create a new empty node
    	Local node:TxmlNode = root.addChild("node", Null, Null)

    	Print node.toString()

    	' change the node name
    	node.setName("branch")

    	Print node.toString()

    End If

Method setNamespace(namespace:TxmlNs)
Description | Associate a namespace to a node, a posteriori.
Information | Parameters: namespace : a namespace.

Method setNsAttribute:TxmlAttribute(namespace:TxmlNs, name:String, value:String = "")
Returns | The attribute object.
Description | Set (or reset) an attribute carried by a node.
Information | The namespace must be in scope, this is not checked. Parameters: namespace : the namespace definition. name : the attribute name. value : the attribute value.

Method setSpacePreserve(value:Int = False)
Description | Set (or reset) the space preserving behaviour of a node, i.e. the value of the xml:space attribute.
Information | Parameters: value : the xml:space value ("0": default, 1: "preserve").

Method setTreeDoc(doc:TxmlDoc)
Description | Update all nodes under the tree to point to the right document.
Information | Parameters: doc : the document.

Method textMerge:TxmlNode(node:TxmlNode)
Description | Merge two text nodes into one.
Information | Parameters: node : the second text node being merged.

Method toString:String()
Description | Returns a string representation of the node and its children.

Method unlinkNode()
Description | Unlinks a node from the document.
Information | After unlinking, and the node is no longer required, it should be freed using freeNode.

Method unsetAttribute:Int(name:String)
Returns | 0 if successful, -1 if not found.
Description | Remove an attribute carried by the node.
Information | Parameters: name : the attribute name.
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local doc:TxmlDoc = TxmlDoc.newDoc("1.0")

    If doc Then

    	Local root:TxmlNode = TxmlNode.newNode("root")
    	doc.setRootElement(root)

    	' create a new empty node
    	Local node:TxmlNode = root.addChild("node", Null, Null)

    	Print node.toString()

    	' add some attributes
    	node.setAttribute("attr1", "Attribute value")
    	node.setAttribute("attr2", "Another value")

    	Print node.toString()

    	' remove an attribute
    	node.unsetAttribute("attr1")

    	Print node.toString()

    End If

Method unsetNsAttribute:Int(namespace:TxmlNs, name:String)
Returns | 0 if successful, -1 if not found.
Description | Remove an attribute carried by the node.
Information | Parameters: namespace : the namespace definition. name : the attribute name.

Method XIncludeProcessTree:Int()
Returns | 0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
Description | Implement the XInclude substitution for the subtree.

Method XIncludeProcessTreeFlags:Int(flags:Int)
Returns | 0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
Description | Implement the XInclude substitution for the subtree.
Information | Parameters: flags : a set of xml Parser Options used for parsing XML includes (see fromFile for details on available options)

Function newNode:TxmlNode(name:String, namespace:TxmlNs = Null)
Description | Creation of a new node element.
Information | namespace is optional. Parameters: name : the node name. namespace : namespace, if any.
Example |
    SuperStrict

    Framework BaH.Libxml

    Local doc:TxmlDoc = TxmlDoc.newDoc("1.0")

    If doc Then

    	' create a new node, initially not attached to the document
    	Local root:TxmlNode = TxmlNode.newNode("root")

    	' set the node as the document root node
    	doc.setRootElement(root)

    	' output the document to stdout
    	doc.saveFile("-")

    End If

Type TxmlNodeSet
Description | An XML Node set.

Methods Summary
castToBoolean | Converts the node set to its boolean value.
castToNumber | Converts the node set to its number value.
castToString | Converts the node set to its string value.
free | Free the node set compound (not the actual nodes !).
getNodeCount | The count of nodes in the node set.
getNodeList | The list of nodes in the node set.
isEmpty | Checks whether the node set is empty or not.

Method castToBoolean:Int()
Returns | The boolean value.
Description | Converts the node set to its boolean value.

Method castToNumber:Double()
Returns | The number value.
Description | Converts the node set to its number value.

Method castToString:String()
Returns | The string value.
Description | Converts the node set to its string value.

Method free()
Description | Free the node set compound (not the actual nodes !).

Method getNodeCount:Int()
Description | The count of nodes in the node set.

Method getNodeList:TList()
Description | The list of nodes in the node set.

Method isEmpty:Int()
Description | Checks whether the node set is empty or not.

Type TxmlNotation
Description | An XML Notation.

Methods Summary
getName | Returns the notation name.
getPublicID | Returns the public identifier, if any.
getSystemID | Returns the system identifier, if any.

Method getName:String()
Description | Returns the notation name.

Method getPublicID:String()
Description | Returns the public identifier, if any.

Method getSystemID:String()
Description | Returns the system identifier, if any.

Type TxmlNs
Description | An XML Namespace.

Methods Summary
free | Free up the structures associated to the namespace.
getHref | Returns the URL for the namespace.
getPrefix | Returns the prefix for the namespace.
getType | Returns the type... global or local.

Method free()
Description | Free up the structures associated to the namespace.

Method getHref:String()
Description | Returns the URL for the namespace.

Method getPrefix:String()
Description | Returns the prefix for the namespace.

Method getType:Int()
Description | Returns the type... global or local.

Type TxmlTextReader
Description | An XML Streaming Text Reader.
Information | Text Reader API provides a simpler, more standard and more extensible interface to handle large documents than a SAX-based reader. A TxmlTextReader object can be instantiated through its fromFile or fromDoc functions. For more insight into this parser, see the Text Reader Tutorial.

Methods Summary
attributeCount | Provides the number of attributes of the current node.
baseUri | The base URI of the node.
constBaseUri | The base URI of the node.
constEncoding | Determine the encoding of the document being read.
constLocalName | The local name of the node.
constName | The qualified name of the node, equal to Prefix :LocalName.
constNamespaceUri | The URI defining the namespace associated with the node.
constPrefix | A shorthand reference to the namespace associated with the node.
constValue | Provides the text value of the node if present.
constXmlLang | The xml:lang scope within which the node resides.
constXmlVersion | Determine the XML version of the document being read.
currentDoc | Hacking interface allowing to get the TxmlDoc correponding to the current document being accessed by the TxmlTextReader.
depth | The depth of the node in the tree.
expand | Reads the contents of the current node and the full subtree.
free | Deallocate all the resources associated to the reader.
getAttribute | Provides the value of the attribute with the specified qualified name.
getAttributeByIndex | Provides the value of the attribute with the specified index relative to the containing element.
getAttributeByNamespace | Provides the value of the specified attribute.
getParserColumnNumber | Provide the column number of the current parsing point.
getParserLineNumber | Provide the line number of the current parsing point.
getParserProperty | Read the parser internal property.
hasAttributes | Whether the node has attributes.
hasValue | Whether the node can have a text value.
isDefault | Whether an Attribute node was generated from the default value defined in the DTD or schema.
isEmptyElement | Check if the current node is empty.
isNamespaceDecl | Determine whether the current node is a namespace declaration rather than a regular attribute.
isValid | Retrieve the validity status from the parser context.
localName | The local name of the node.
lookupNamespace | Resolves a namespace prefix in the scope of the current element.
moveToAttribute | Moves the position of the current instance to the attribute with the specified qualified name.
moveToAttributeByIndex | Moves the position of the current instance to the attribute with the specified index relative to the containing element.
moveToAttributeByNamespace | Moves the position of the current instance to the attribute with the specified local name and namespace URI.
moveToElement | Moves the position of the current instance to the node that contains the current Attribute node.
moveToFirstAttribute | Moves the position of the current instance to the first attribute associated with the current node.
moveToNextAttribute | Moves the position of the current instance to the next attribute associated with the current node.
name | The qualified name of the node, equal to Prefix :LocalName.
namespaceUri | The URI defining the namespace associated with the node.
nextNode | Skip to the node following the current one in document order while avoiding the subtree if any.
nodeType | Get the node type of the current node.
normalization | The value indicating whether to normalize white space and attribute values.
prefix | A shorthand reference to the namespace associated with the node.
preserve | This tells the XML Reader to preserve the current node.
quoteChar | The quotation mark character used to enclose the value of an attribute.
read | Moves the position of the current instance to the next node in the stream, exposing its properties.
readAttributeValue | Parses an attribute value into one or more Text and EntityReference nodes.
readInnerXml | Reads the contents of the current node, including child nodes and markup.
readOuterXml | Reads the contents of the current node, including child nodes and markup.
readState | Gets the read state of the reader.
ReadString | Reads the contents of an element or a text node as a string.
relaxNGValidate | Use RelaxNG to validate the document as it is processed.
schemaValidate | Use W3C XSD schema to validate the document as it is processed.
setParserProp | Change the parser processing behaviour by changing some of its internal properties.
standalone | Determine the standalone status of the document being read.
value | Provides the text value of the node if present.
xmlLang | The xml:lang scope within which the node resides.

Functions Summary
fromDoc | Create an TxmlTextReader for an XML in-memory document.
fromFile | Parse an XML file from the filesystem or the network.

Method attributeCount:Int()
Returns | 0 if no attributes, -1 in case of error or the attribute count.
Description | Provides the number of attributes of the current node.

Method baseUri:String()
Description | The base URI of the node.

Method constBaseUri:String()
Returns | The base URI or Null if not available.
Description | The base URI of the node.

Method constEncoding:String()
Returns | A string containing the encoding of the document or Null in case of error.
Description | Determine the encoding of the document being read.

Method constLocalName:String()
Returns | The local name or Null if not available.
Description | The local name of the node.

Method constName:String()
Returns | The local name or Null if not available.
Description | The qualified name of the node, equal to Prefix :LocalName.

Method constNamespaceUri:String()
Returns | The namespace URI or Null if not available.
Description | The URI defining the namespace associated with the node.

Method constPrefix:String()
Returns | The prefix or Null if not available.
Description | A shorthand reference to the namespace associated with the node.

Method constValue:String()
Returns | the string or Null if not available.
Description | Provides the text value of the node if present.

Method constXmlLang:String()
Returns | The xml:lang value or Null if none exists.
Description | The xml:lang scope within which the node resides.

Method constXmlVersion:String()
Returns | A string containing the XML version of the document or Null in case of error.
Description | Determine the XML version of the document being read.

Method currentDoc:TxmlDoc()
Returns | The TxmlDoc or Null in case of error.
Description | Hacking interface allowing to get the TxmlDoc correponding to the current document being accessed by the TxmlTextReader.
Information | NOTE: as a result of this call, the reader will not destroy the associated XML document and calling free() on the TxmlDoc is needed once the reader parsing has finished.

Method depth:Int()
Returns | the depth or -1 in case of error.
Description | The depth of the node in the tree.

Method expand:TxmlNode()
Description | Reads the contents of the current node and the full subtree.
Information | It then makes the subtree available until the next read call. returns: A node, valid until the next read call or Null in case of error.

Method free()
Description | Deallocate all the resources associated to the reader.

Method getAttribute:String(name:String)
Returns | A string containing the value of the specified attribute, or Null in case of error.
Description | Provides the value of the attribute with the specified qualified name.
Information | Parameters: name : the qualified name of the attribute.
Example |
    SuperStrict

    Import BaH.Libxml

    Local docname:String = "sampleuri.xml"
    parseDoc(docname)

    Function getReference(doc:TxmlDoc, node:TxmlNode)

    	Local uri:String

    	Local list:TList = node.getChildren()
    	For node = EachIn list
    		If node.getName() = "reference" Then
    			uri = node.getAttribute("uri")
    			Print "uri: " + uri
    		End If
    	Next
    End Function

    Function parseDoc(docname:String)

            Local doc:TxmlDoc
            Local node:TxmlNode

            doc = TxmlDoc.parseFile(docname)

            If doc = Null Then
                    Print "Document not parsed successfully."
                    Return
            End If

            node = doc.getRootElement()

            If node = Null Then
                    Print "empty document"
                    doc.free()
                    Return
            End If

            If node.getName() <> "story" Then
                    Print "document of the wrong type, root node <> story"
                    doc.free()
                    Return
            End If

            getReference(doc, node)
            doc.free()
    End Function

Method getAttributeByIndex:String(index:Int)
Returns | A string containing the value of the specified attribute, or Null in case of error.
Description | Provides the value of the attribute with the specified index relative to the containing element.
Information | Parameters: index : the zero-based index of the attribute relative to the containing element.

Method getAttributeByNamespace:String(localName:String, namespaceURI:String)
Returns | A string containing the value of the specified attribute, or Null in case of error.
Description | Provides the value of the specified attribute.
Information | Parameters: localName : the local name of the attribute. namespaceURI : the namespace URI of the attribute.

Method getParserColumnNumber:Int()
Returns | An int or 0 if not available.
Description | Provide the column number of the current parsing point.

Method getParserLineNumber:Int()
Returns | An int or 0 if not available.
Description | Provide the line number of the current parsing point.

Method getParserProperty:Int(prop:Int)
Returns | The value, usually 0 or 1, or -1 in case of error.
Description | Read the parser internal property.
Information | The parser property can be one of the following values:
Constant
XXML_PARSER_LOADDTD
XXML_PARSER_DEFAULTATTRS
XXML_PARSER_VALIDATE
XXML_PARSER_SUBST_ENTITIES
Parameters: prop : the parser property.

Method hasAttributes:Int()
Returns | 1 if true, 0 if false, and -1 in case or error.
Description | Whether the node has attributes.

Method hasValue:Int()
Returns | 1 if true, 0 if false, and -1 in case or error.
Description | Whether the node can have a text value.

Method isDefault:Int()
Returns | 0 if not defaulted, 1 if defaulted, and -1 in case of error.
Description | Whether an Attribute node was generated from the default value defined in the DTD or schema.

Method isEmptyElement:Int()
Returns | 1 if empty, 0 if not and -1 in case of error.
Description | Check if the current node is empty.

Method isNamespaceDecl:Int()
Returns | 1 if the current node is a namespace declaration, 0 if it is a regular attribute or other type of node, or -1 in case of error.
Description | Determine whether the current node is a namespace declaration rather than a regular attribute.

Method isValid:Int()
Description | Retrieve the validity status from the parser context.
Information | The flag value 1 if valid, 0 if no, and -1 in case of error.

Method localName:String()
Returns | the local name or Null if not available.
Description | The local name of the node.

Method lookupNamespace:String(prefix:String)
Returns | A string containing the namespace URI to which the prefix maps or Null in case of error.
Description | Resolves a namespace prefix in the scope of the current element.
Information | Parameters: prefix : the prefix whose namespace URI is to be resolved. To return the default namespace, specify Null.

Method moveToAttribute:Int(name:String)
Returns | 1 in case of success, -1 in case of error, 0 if not found.
Description | Moves the position of the current instance to the attribute with the specified qualified name.
Information | Parameters: name : the qualified name of the attribute.

Method moveToAttributeByIndex:Int(index:Int)
Returns | 1 in case of success, -1 in case of error, 0 if not found.
Description | Moves the position of the current instance to the attribute with the specified index relative to the containing element.
Information | Parameters: index : the zero-based index of the attribute relative to the containing element.

Method moveToAttributeByNamespace:Int(localName:String, namespaceURI:String)
Returns | 1 in case of success, -1 in case of error, 0 if not found.
Description | Moves the position of the current instance to the attribute with the specified local name and namespace URI.
Information | Parameters: localName : the local name of the attribute. namespaceURI : the namespace URI of the attribute.

Method moveToElement:Int()
Returns | 1 in case of success, -1 in case of error, 0 if not moved.
Description | Moves the position of the current instance to the node that contains the current Attribute node.

Method moveToFirstAttribute:Int()
Returns | 1 in case of success, -1 in case of error, 0 if not found.
Description | Moves the position of the current instance to the first attribute associated with the current node.

Method moveToNextAttribute:Int()
Returns | 1 in case of success, -1 in case of error, 0 if not found.
Description | Moves the position of the current instance to the next attribute associated with the current node.

Method name:String()
Returns | the local name or Null if not available.
Description | The qualified name of the node, equal to Prefix :LocalName.

Method namespaceUri:String()
Returns | the namespace URI or Null if not available.
Description | The URI defining the namespace associated with the node.

Method nextNode:Int()
Returns | 1 if the node was read successfully, 0 if there is no more nodes to read, or -1 in case of error.
Description | Skip to the node following the current one in document order while avoiding the subtree if any.

Method nodeType:Int()
Returns | The xmlNodeType of the current node or -1 in case of error.
Description | Get the node type of the current node.

Method normalization:Int()
Returns | 1 or -1 in case of error.
Description | The value indicating whether to normalize white space and attribute values.
Information | Since attribute value and end of line normalizations are a MUST in the XML specification only the value true is accepted. The broken bahaviour of accepting out of range character entities like &#0; is of course not supported either.

Method prefix:Int()
Returns | The prefix or Null if not available.
Description | A shorthand reference to the namespace associated with the node.

Method preserve:TxmlNode()
Returns | The TxmlNode or Null in case of error.
Description | This tells the XML Reader to preserve the current node.
Information | The caller must also use currentDoc to keep an handle on the resulting document once parsing has finished.

Method quoteChar:String()
Returns | " or ' and Null in case of error.
Description | The quotation mark character used to enclose the value of an attribute.

Method read:Int()
Returns | 1 if the node was read successfully, 0 if there is no more nodes to read, or -1 in case of error.
Description | Moves the position of the current instance to the next node in the stream, exposing its properties.

Method readAttributeValue:Int()
Description | Parses an attribute value into one or more Text and EntityReference nodes.
Information | 1 in case of success, 0 if the reader was not positioned on an attribute node or all the attribute values have been read, or -1 in case of error.

Method readInnerXml:String()
Returns | A string containing the XML content, or Null if the current node is neither an element nor attribute, or has no child nodes.
Description | Reads the contents of the current node, including child nodes and markup.

Method readOuterXml:String()
Returns | A string containing the XML content, or NULL if the current node is neither an element nor attribute, or has no child nodes.
Description | Reads the contents of the current node, including child nodes and markup.

Method readState:Int()
Description | Gets the read state of the reader.
Information | The state value, or -1 in case of error.

Method ReadString:String()
Description | Reads the contents of an element or a text node as a string.
Information | A string containing the contents of the Element or Text node, or Null if the reader is positioned on any other type of node.

Method relaxNGValidate:Int(rng:String)
Returns | 0 in case the RelaxNG validation could be (des)activated and -1 in case of error.
Description | Use RelaxNG to validate the document as it is processed.
Information | Activation is only possible before the first read. if rng is Null, then RelaxNG validation is desactivated. Parameters: rng : the path to a RelaxNG schema or Null.

Method schemaValidate:Int(xsd:String)
Returns | 0 in case the schemas validation could be (de)activated and -1 in case of error.
Description | Use W3C XSD schema to validate the document as it is processed.
Information | Activation is only possible before the first read. If xsd is Null, then XML Schema validation is deactivated. Parameters: xsd : the path to a W3C XSD schema or Null.

Method setParserProp:Int(prop:Int, value:Int)
Returns | 0 if the call was successful, or -1 in case of error.
Description | Change the parser processing behaviour by changing some of its internal properties.
Information | Note that some properties can only be changed before any read has been done. Parameters: prop : the parser property to set. ( see getParserProperty ) value : usually 0 or 1 to (de)activate it.

Method standalone:Int()
Returns | 1 if the document was declared to be standalone, 0 if it was declared to be not standalone, or -1 if the document did not specify its standalone status or in case of error.
Description | Determine the standalone status of the document being read.

Method value:String()
Returns | The string or Null if not available.
Description | Provides the text value of the node if present.

Method xmlLang:String()
Returns | the xml:lang value or Null if none exists.
Description | The xml:lang scope within which the node resides.

Function fromDoc:TxmlTextReader(text:String, url:String, encoding:String, options:Int)
Returns | The new reader or Null in case of error.
Description | Create an TxmlTextReader for an XML in-memory document.
Information | The parsing flags options are a combination of the options listed in fromFile Parameters: text : the string to be parsed. url : the base URL to use for the document. encoding : the document encoding, or Null. options : a combination of xmlParserOption

Function fromFile:TxmlTextReader(filename:String, encoding:String = Null, options:Int = 0)
Description | Parse an XML file from the filesystem or the network.
Information | The parsing flags options are a combination of the following:
Constant | Meaning
--- | ---
XML_PARSE_RECOVER | recover on errors
XML_PARSE_NOENT | substitute entities
XML_PARSE_DTDLOAD | load the external subset
XML_PARSE_DTDATTR | default DTD attributes
XML_PARSE_DTDVALID | validate with the DTD
XML_PARSE_NOERROR | suppress error reports
XML_PARSE_NOWARNING | suppress warning reports
XML_PARSE_PEDANTIC | pedantic error reporting
XML_PARSE_NOBLANKS | remove blank nodes
XML_PARSE_SAX1 | use the SAX1 interface internally
XML_PARSE_XINCLUDE | Implement XInclude substitition
XML_PARSE_NONET | Forbid network access
XML_PARSE_NODICT | Do not reuse the context dictionnary
XML_PARSE_NSCLEAN | remove redundant namespaces declarations
XML_PARSE_NOCDATA | merge CDATA as text nodes
XML_PARSE_NOXINCNODE | do not generate XINCLUDE START/END nodes
XML_PARSE_COMPACT | compact small text nodes
Parameters: filename : a file or URL. Supports "incbin::" paths. encoding : the document encoding, or Null. options : the new reader or Null in case of error.

Type TxmlURI
Description | A URI.
Information | Provides some standards-savvy functions for URI handling.

Methods Summary
free | Free up the TxmlURI object.
getAuthority | Returns the authority part.
getFragment | Returns the fragment identifier.
getOpaque | Returns the opaque part.
getPath | Returns the path string.
getPort | Returns the port number.
getQuery | Returns the query string.
getScheme | Returns the URI scheme.
getServer | Returns the server part.
getUser | Returns the user part.
parseURIReference | Parse an URI reference string and fills in the appropriate fields of the URI structure.
saveURI | Save the URI as an escaped string.

Functions Summary
buildURI | Computes the final URI of the reference done by checking that the given URI is valid, and building the final URI using the base URI.
canonicPath | Constructs a canonic path from the specified path.
createURI | Simply creates an empty TxmlURI.
normalizeURIPath | Applies the 5 normalization steps to a path string.
parseURI | Parse a URI.
parseURIRaw | Parse an URI but allows to keep intact the original fragments.
URIEscape | Escaping routine, does not do validity checks !
URIEscapeString | This routine escapes a string to hex, ignoring reserved characters (a-z) and the characters in the exception list.
URIUnescapeString | Unescaping routine.

Method free()
Description | Free up the TxmlURI object.

Method getAuthority:String()
Description | Returns the authority part.

Method getFragment:String()
Description | Returns the fragment identifier.

Method getOpaque:String()
Description | Returns the opaque part.

Method getPath:String()
Description | Returns the path string.

Method getPort:Int()
Description | Returns the port number.

Method getQuery:String()
Description | Returns the query string.

Method getScheme:String()
Description | Returns the URI scheme.

Method getServer:String()
Description | Returns the server part.

Method getUser:String()
Description | Returns the user part.

Method parseURIReference:Int(uri:String)
Returns | 0 or the error code.
Description | Parse an URI reference string and fills in the appropriate fields of the URI structure.
Information | URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ] Parameters: uri : the string to analyze

Method saveURI:String()
Returns | A new string.
Description | Save the URI as an escaped string.

Function buildURI:String(uri:String, base:String)
Returns | A new URI string or Null in case of error.
Description | Computes the final URI of the reference done by checking that the given URI is valid, and building the final URI using the base URI.
Information | This is processed according to section 5.2 of the RFC 2396 5.2. Resolving Relative References to Absolute Form Parameters: uri : the URI instance found in the document base : the base value

Function canonicPath:String(path:String)
Returns | A new canonic path, or a duplicate of the path parameter if the construction fails.
Description | Constructs a canonic path from the specified path.
Information | Parameters: path : the resource locator in a filesystem notation

Function createURI:TxmlURI()
Returns | The new structure or Null in case of error.
Description | Simply creates an empty TxmlURI.

Function normalizeURIPath:String(path:String)
Returns | The normalized string.
Description | Applies the 5 normalization steps to a path string.
Information | That is, RFC 2396 Section 5.2, steps 6.c through 6.g. Parameters: path : the path string

Function parseURI:TxmlURI(uri:String)
Returns | A newly built TxmlURI or Null in case of error.
Description | Parse a URI.
Information | URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ] Parameters: uri : the URI string to analyze
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local s:String = "http://www.somesite.com:8080/stuff/index.php?count=1#second"

    Local uri:TxmlURI = TxmlURI.parseURI(s)

    Print "server   = " + uri.getServer()
    Print "port     = " + uri.getPort()
    Print "path     = " + uri.getPath()
    Print "query    = " + uri.getQuery()
    Print "fragment = " + uri.getFragment()

Function parseURIRaw:TxmlURI(uri:String, raw:Int)
Returns | A newly built TxmlURI or Null in case of error.
Description | Parse an URI but allows to keep intact the original fragments.
Information | URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ] Parameters: uri : the URI string to analyze raw : if 1 unescaping of URI pieces are disabled

Function URIEscape:String(uri:String)
Returns | A copy of the string, but escaped.
Description | Escaping routine, does not do validity checks !
Information | It will try to escape the chars needing this, but this is heuristic based it's impossible to be sure. Parameters: uri : the string of the URI to escape

Function URIEscapeString:String(uri:String, list:String)
Returns | A new escaped string or Null in case of error.
Description | This routine escapes a string to hex, ignoring reserved characters (a-z) and the characters in the exception list.
Information | Parameters: uri : the string to escape list : exception list string of chars not to escape, if any
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local s:String = "a b c !£$%^&*(_09<>?"

    ' print original string
    Print s
    ' print escaped string
    Print TxmlURI.URIEscapeString(s, Null)

Function URIUnescapeString:String(str:String)
Returns | A copy of the string, but unescaped.
Description | Unescaping routine.
Information | Does not do validity checks. Output is direct unsigned char translation of XX values (no encoding) Parameters: str : the string to unescape
Example |
    SuperStrict

    Framework BaH.Libxml
    Import BRL.StandardIO

    Local s:String = "a%20b%20c%20!%A3%24%25%5E%26*(_09%3C%3E%3F"

    ' print original escaped string
    Print s
    ' print unescaped string
    Print TxmlURI.URIUnescapeString(s)

Type TxmlValidCtxt
Description | XML validation context.

Methods Summary
buildContentModel | (Re)Build the automata associated to the content model of the element.
free | Free the validation context structure.
getDocument | Returns the document for this object.
isFinishedDtd | Returns true if finished validating the DTD.
isValid | Returns the temporary validity check result state.
validateAttributeDecl | Try to validate a single attribute definition.
validateDocument | Try to validate the document instance.
validateDocumentFinal | Does the final step for the document validation once all the incremental validation steps have been completed.
validateDtd | Try to validate the document against the dtd instance.
validateDtdFinal | Does the final step for the dtds validation once all the subsets have been parsed.
validateElement | Try to validate the subtree under an element.
validateElementDecl | Try to validate a single element definition.
validateRoot | Try to validate a the root element.

Functions Summary
newValidCtxt | Allocate a validation context structure.
validateAttributeValue | Validate that the given attribute value match the proper production.
validateNamesValue | Validate that the given value match Names production.
validateNameValue | Validate that the given value match Name production.
validateNmtokensValue | Validate that the given value match Nmtokens production.
validateNmtokenValue | Validate that the given value match Nmtoken production.

Method buildContentModel:Int(elem:TxmlDtdElement)
Returns | 1 in case of success, 0 in case of error.
Description | (Re)Build the automata associated to the content model of the element.
Information | Parameters: elem : an element declaration node

Method free()
Description | Free the validation context structure.

Method getDocument:TxmlDoc()
Description | Returns the document for this object.

Method isFinishedDtd:Int()
Description | Returns true if finished validating the DTD.

Method isValid:Int()
Description | Returns the temporary validity check result state.

Method validateAttributeDecl:Int(doc:TxmlDoc, attr:TxmlDtdAttribute)
Returns | 1 if valid or 0 otherwise.
Description | Try to validate a single attribute definition.
Information | Basically it does the following checks as described by the XML-1.0 recommendation: [ VC: Attribute Default Legal ] [ VC: Enumeration ] [ VC: ID Attribute Default ] The ID/IDREF uniqueness and matching are done separately. Parameters: doc : a document instance attr : an attribute definition

Method validateDocument:Int(doc:TxmlDoc)
Returns | 1 if valid or 0 otherwise.
Description | Try to validate the document instance.

Method validateDocumentFinal:Int(doc:TxmlDoc)
Returns | 1 if valid or 0 otherwise.
Description | Does the final step for the document validation once all the incremental validation steps have been completed.
Information | Basically it does the following checks described by the XML Rec. Check all the IDREF/IDREFS attributes definition for validity. Parameters: doc : a document instance

Method validateDtd:Int(doc:TxmlDoc, dtd:TxmlDtd)
Returns | 1 if valid or 0 otherwise.
Description | Try to validate the document against the dtd instance.
Information | Basically it does check all the definitions in the DtD. Note the the internal subset (if present) is de-coupled (i.e. not used), which could give problems if ID or IDREF is present. Parameters: doc : a document instance dtd : a DTD instance

Method validateDtdFinal:Int(doc:TxmlDoc, dtd:TxmlDtd)
Returns | 1 if valid or 0 if invalid and -1 if not well-formed.
Description | Does the final step for the dtds validation once all the subsets have been parsed.
Information | Basically it does the following checks described by the XML Rec Check that ENTITY and ENTITIES type attributes default or possible values matches one of the defined entities. Check that NOTATION type attributes default or possible values matches one of the defined notations. Parameters: doc : a document instance

Method validateElement:Int(doc:TxmlDoc, elem:TxmlNode)
Returns | 1 if valid or 0 otherwise.
Description | Try to validate the subtree under an element.
Information | Parameters: doc : a document instance elem : an element instance

Method validateElementDecl:Int(doc:TxmlDoc, elem:TxmlDtdElement)
Description | Try to validate a single element definition.
Information | Basically it does the following checks as described by the XML-1.0 recommendation: [ VC: One ID per Element Type ] [ VC: No Duplicate Types ] [ VC: Unique Element Type Declaration ] Parameters: doc : a document instance elem : an element definition

Method validateRoot:Int(doc:TxmlDoc)
Returns | 1 if valid or 0 otherwise.
Description | Try to validate a the root element.
Information | Basically it does the following check as described by the XML-1.0 recommendation: [ VC: Root Element Type ] it doesn't try to recurse or apply other check to the element Parameters: doc : a document instance

Function newValidCtxt:TxmlValidCtxt()
Returns | Null if not, otherwise the new validation context structure.
Description | Allocate a validation context structure.

Function validateAttributeValue:Int(attributeType:Int, value:String)
Returns | 1 if valid or 0 otherwise.
Description | Validate that the given attribute value match the proper production.
Information | [ VC: ID ] Values of type ID must match the Name production.... [ VC: IDREF ] Values of type IDREF must match the Name production, and values of type IDREFS must match Names ... [ VC: Entity Name ] Values of type ENTITY must match the Name production, values of type ENTITIES must match Names ... [ VC: Name Token ] Values of type NMTOKEN must match the Nmtoken production; values of type NMTOKENS must match Nmtokens. Parameters: attributeType : an attribute type (see below) value : an attribute value The following lists possible attribute types:
Constant
XML_ATTRIBUTE_CDATA
XML_ATTRIBUTE_ID
XML_ATTRIBUTE_IDREF
XML_ATTRIBUTE_IDREFS
XML_ATTRIBUTE_ENTITY
XML_ATTRIBUTE_ENTITIES
XML_ATTRIBUTE_NMTOKEN
XML_ATTRIBUTE_NMTOKENS
XML_ATTRIBUTE_ENUMERATION
XML_ATTRIBUTE_NOTATION

Function validateNamesValue:Int(value:String)
Returns | 1 if valid or 0 otherwise.
Description | Validate that the given value match Names production.
Information | Parameters: value : a Names value

Function validateNameValue:Int(value:String)
Returns | 1 if valid or 0 otherwise.
Description | Validate that the given value match Name production.
Information | Parameters: value : an Name value

Function validateNmtokensValue:Int(value:String)
Returns | 1 if valid or 0 otherwise.
Description | Validate that the given value match Nmtokens production.
Information | [ VC: Name Token ] Parameters: value : an Nmtokens value

Function validateNmtokenValue:Int(value:String)
Returns | 1 if valid or 0 otherwise.
Description | Validate that the given value match Nmtoken production.
Information | [ VC: Name Token ] Parameters: value : an Nmtoken value

Type TxmlXIncludeCtxt
Description | An XML XInclude context.

Methods Summary
free | Free the XInclude context.
processNode | Implement the XInclude substitution for the given subtree reusing the informations and data coming from the given context.
setFlags | Set the flags used for further processing of XML resources.

Functions Summary
newContext | Creates a new XInclude context.

Method free()
Description | Free the XInclude context.

Method processNode:Int(node:TxmlNode)
Returns | 0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
Description | Implement the XInclude substitution for the given subtree reusing the informations and data coming from the given context.
Information | Parameters: node : a node in an XML document

Method setFlags:Int(flags:Int)
Returns | 0 in case of success and -1 in case of error.
Description | Set the flags used for further processing of XML resources.
Information | Parameters: flags : a set of xml Parser Options used for parsing XML includes. (see fromFile for details on available options)

Function newContext:TxmlXIncludeCtxt(doc:TxmlDoc)
Returns | The new context.
Description | Creates a new XInclude context.
Information | Parameters: doc : an XML Document

Type TxmlXPathCompExpr
Description | A compiled XPath expression.

Methods Summary
eval | Evaluate the precompiled XPath expression in the given context.
free | Free up the allocated memory.

Functions Summary
Compile | Compile an XPath expression.

Method eval:TxmlXPathObject(context:TxmlXPathContext)
Returns | The TxmlXPathObject resulting from the evaluation or Null.
Description | Evaluate the precompiled XPath expression in the given context.
Information | Parameters: context : the XPath context

Method free()
Description | Free up the allocated memory.

Function Compile:TxmlXPathCompExpr(expr:String)
Returns | The TxmlXPathCompExpr resulting from the compilation or Null.
Description | Compile an XPath expression.
Information | Parameters: expr : the XPath expression

Type TxmlXPathContext
Description | An XML XPath Context.
Information | Expression evaluation occurs with respect to a context. The context consists of: a node (the context node) a node list (the context node list) a set of variable bindings a function library the set of namespace declarations in scope for the expression

Methods Summary
countDefinedTypes | Returns the number of defined types.
eval | Evaluate the XPath Location Path in the context.
evalExpression | Evaluate the XPath expression in the context.
evalPredicate | Evaluate a predicate result for the current node.
free | Free up the TxmlXPathContext.
getContextSize | Returns the context size.
getDocument | Return the TxmlDoc associated to this XPath context.
getFunction | Returns the function name when calling a function.
getFunctionURI | Returns the function URI when calling a function.
getHere | Returns the XPointer for here.
getMaxTypes | Returns the max number of types.
GetNode | Return the current TxmlNode associated with this XPath context.
GetOrigin | Returns the XPointer for origin.
getProximityPosition | Returns the proximity position.
isXPointerContext | Returns whether this is an XPointer context or not.
registerNamespace | Register a new namespace.
XPointerEval | Evaluate the XPath Location Path in the context.

Functions Summary
XPointerNewContext | Create a new XPointer context.

Method countDefinedTypes:Int()
Description | Returns the number of defined types.

Method eval:TxmlXPathObject(text:String)
Returns | A TxmlXPathObject resulting from the evaluation or Null.
Description | Evaluate the XPath Location Path in the context.
Information | Parameters: text : the XPath expression

Method evalExpression:TxmlXPathObject(text:String)
Returns | A TxmlXPathObject resulting from the evaluation or Null.
Description | Evaluate the XPath expression in the context.
Information | Parameters: text : the XPath expression

Method evalPredicate:Int(res:TxmlXPathObject)
Description | Evaluate a predicate result for the current node.
Information | A PredicateExpr is evaluated by evaluating the Expr and converting the result to a boolean. If the result is a number, the result will be converted to true if the number is equal to the position of the context node in the context node list (as returned by the position function) and will be converted to false otherwise; if the result is not a number, then the result will be converted as if by a call to the boolean function.

Method free()
Description | Free up the TxmlXPathContext.

Method getContextSize:Int()
Description | Returns the context size.

Method getDocument:TxmlDoc()
Description | Return the TxmlDoc associated to this XPath context.

Method getFunction:String()
Description | Returns the function name when calling a function.

Method getFunctionURI:String()
Description | Returns the function URI when calling a function.

Method getHere:TxmlNode()
Description | Returns the XPointer for here.

Method getMaxTypes:Int()
Description | Returns the max number of types.

Method GetNode:TxmlNode()
Description | Return the current TxmlNode associated with this XPath context.

Method GetOrigin:TxmlNode()
Description | Returns the XPointer for origin.

Method getProximityPosition:Int()
Description | Returns the proximity position.

Method isXPointerContext:Int()
Description | Returns whether this is an XPointer context or not.

Method registerNamespace:Int(prefix:String, uri:String)
Description | Register a new namespace.
Information | If uri is Null it unregisters the namespace.

Method XPointerEval:TxmlXPathObject(expr:String)
Returns | The TxmlXPathObject resulting from the evaluation or Null. The caller has to free the object.
Description | Evaluate the XPath Location Path in the context.

Function XPointerNewContext:TxmlXPathContext(doc:TxmlDoc, here:TxmlNode, origin:TxmlNode)
Returns | The TxmlXPathContext just allocated.
Description | Create a new XPointer context.
Information | Parameters: doc : the XML document here : the node that directly contains the XPointer being evaluated or Null origin : the element from which a user or program initiated traversal of the link, or Null

Type TxmlXPathObject
Description | An XML XPath Object.

Methods Summary
castToBoolean | Converts the XPath object to its boolean value.
castToNumber | Converts the XPath object to its number value.
castToString | Converts the XPath object to its string value.
convertBoolean | Converts an existing object to its boolean() equivalent.
convertNumber | Converts an existing object to its number() equivalent.
convertString | Converts an existing object to its string() equivalent.
copy | Allocate a new copy of a given object.
free | Free up the TxmlXPathObject.
getNodeSet | Returns the node set for the xpath.
getStringValue | Returns the xpath object string value.
getType | The XPath object type.
nodeSetIsEmpty | Whether the node set is empty or not.
XPointerBuildNodeList | Build a node list tree copy of the XPointer result.
XPointerLocationSetCreate | Create a new TxmlLocationSet of type double and value of this XPathObject.

Functions Summary
XPointerNewCollapsedRange | Create a new TxmlXPathObject of type range using a single node.
XPointerNewLocationSetNodes | Create a new TxmlXPathObject of type LocationSet and initialize it with the single range made of the two nodes startnode and endnode.
XPointerNewLocationSetNodeSet | Create a new TxmlXPathObject of type LocationSet and initialize it with all the nodes from nodeset.
XPointerNewRange | Create a new TxmlXPathObject of type range.
XPointerNewRangeNodeObject | Create a new TxmlXPathObject of type range from a node to an object.
XPointerNewRangeNodePoint | Create a new TxmlXPathObject of type range from a node to a point.
XPointerNewRangeNodes | Create a new TxmlXPathObject of type range using 2 nodes.
XPointerNewRangePointNode | Create a new TxmlXPathObject of type range from a point to a node.
XPointerNewRangePoints | Create a new xmlXPathObjectPtr of type range using 2 Points.
XPointerWrapLocationSet | Wrap the LocationSet value in a new TxmlXPathObject.

Method castToBoolean:Int()
Returns | The boolean value.
Description | Converts the XPath object to its boolean value.

Method castToNumber:Double()
Returns | The number value.
Description | Converts the XPath object to its number value.

Method castToString:String()
Returns | The string value.
Description | Converts the XPath object to its string value.

Method convertBoolean:TxmlXPathObject()
Returns | the new object, this one is freed.
Description | Converts an existing object to its boolean() equivalent.

Method convertNumber:TxmlXPathObject()
Returns | the new object, this one is freed.
Description | Converts an existing object to its number() equivalent.

Method convertString:TxmlXPathObject()
Returns | the new object, this one is freed.
Description | Converts an existing object to its string() equivalent.

Method copy:TxmlXPathObject()
Returns | The newly created object.
Description | Allocate a new copy of a given object.

Method free()
Description | Free up the TxmlXPathObject.

Method getNodeSet:TxmlNodeSet()
Description | Returns the node set for the xpath.

Method getStringValue:String()
Description | Returns the xpath object string value.

Method getType:Int()
Description | The XPath object type.
Information | The following lists possible XPath object types:
Constant
XPATH_UNDEFINED
XPATH_NODESET
XPATH_BOOLEAN
XPATH_NUMBER
XPATH_STRING
XPATH_POINT
XPATH_RANGE
XPATH_LOCATIONSET
XPATH_USERS
XPATH_XSLT_TREE

Method nodeSetIsEmpty:Int()
Description | Whether the node set is empty or not.

Method XPointerBuildNodeList:TxmlNode()
Returns | An node list or Null. The caller has to free the node tree.
Description | Build a node list tree copy of the XPointer result.
Information | This will drop Attributes and Namespace declarations.

Method XPointerLocationSetCreate:TxmlLocationSet()
Returns | The newly created object.
Description | Create a new TxmlLocationSet of type double and value of this XPathObject.

Function XPointerNewCollapsedRange:TxmlXPathObject(node:TxmlNode)
Returns | The newly created object.
Description | Create a new TxmlXPathObject of type range using a single node.
Information | Parameters: node : the starting and ending node

Function XPointerNewLocationSetNodes:TxmlXPathObject(startnode:TxmlNode, endnode:TxmlNode)
Returns | the newly created object.
Description | Create a new TxmlXPathObject of type LocationSet and initialize it with the single range made of the two nodes startnode and endnode.
Information | Parameters: startnode : the start Node value endnode : the end Node value or Null

Function XPointerNewLocationSetNodeSet:TxmlXPathObject(nodeset:TxmlNodeSet)
Returns | The newly created object.
Description | Create a new TxmlXPathObject of type LocationSet and initialize it with all the nodes from nodeset.
Information | Parameters: nodeset : a node set

Function XPointerNewRange:TxmlXPathObject(startnode:TxmlNode, startindex:Int, endnode:TxmlNode, endindex:Int)
Returns | The newly created object.
Description | Create a new TxmlXPathObject of type range.
Information | Parameters: startnode : the starting node startindex : the start index endnode : the ending node endindex : the ending index

Function XPointerNewRangeNodeObject:TxmlXPathObject(startnode:TxmlNode, endobj:TxmlXPathObject)
Returns | The newly created object.
Description | Create a new TxmlXPathObject of type range from a node to an object.
Information | Parameters: startnode : the starting node endobj : the ending object

Function XPointerNewRangeNodePoint:TxmlXPathObject(startnode:TxmlNode, endpoint:TxmlXPathObject)
Returns | The newly created object.
Description | Create a new TxmlXPathObject of type range from a node to a point.
Information | Parameters: startnode : the starting node endpoint : the ending point

Function XPointerNewRangeNodes:TxmlXPathObject(startnode:TxmlNode, endnode:TxmlNode)
Returns | The newly created object.
Description | Create a new TxmlXPathObject of type range using 2 nodes.
Information | Parameters: startnode : the starting node endnode : the ending node

Function XPointerNewRangePointNode:TxmlXPathObject(startpoint:TxmlXPathObject, endnode:TxmlNode)
Returns | The newly created object.
Description | Create a new TxmlXPathObject of type range from a point to a node.
Information | Parameters: startpoint : the starting point endnode : the ending node

Function XPointerNewRangePoints:TxmlXPathObject(startpoint:TxmlXPathObject, endpoint:TxmlXPathObject)
Returns | The newly created object.
Description | Create a new xmlXPathObjectPtr of type range using 2 Points.
Information | Parameters: startpoint : the starting point endpoint : the ending point

Function XPointerWrapLocationSet:TxmlXPathObject(value:TxmlLocationSet)
Returns | The newly created object.
Description | Wrap the LocationSet value in a new TxmlXPathObject.
Information | Parameters: value : the LocationSet value

## Module Information

Version | 1.12
License | MIT
Copyright | (libxml2) 1998-2007 Daniel Veillard
Copyright | (wrapper) 2006-2007 Bruce A Henderson
Modserver | BRL
History | 1.12
History | Improved error handling/capture.
History | Fixed xmlGetLastError calling wrong api.
History | Added new xmlSetErrorFunction() function to allow capture of all errors.
History | More error information available via new TxmlError methods().
History | 1.11
History | Added unlinkNode and freeNode methods to TxmlNode.
History | 1.10
History | Updated to Libxml 2.6.27.
History | Fixed Null byte ptr handling on UTF8 conversion.
History | Fixed several memory issues.
History | 1.09
History | Added automatic libxml UTF-to-Max and Max-To-UTF String conversion. Fixes non-ascii string issues.
History | Added getLineNumber method to TxmlBase.
History | 1.08
History | Exposed some XPathContext properties.
History | Fixed TxmlBuffer getContent not returning anything.
History | API change - Renamed TxmlURI URIEscapeStr() to URIEscapeString().
History | Docs tidy up.
History | Many more examples.
History | 1.07
History | Added TxmlNode getAttributeList method.
History | Added TxmlAttribute getAttributeType, getNameSpace methods.
History | Fixed attribute getValue returning nothing.
History | Added TxmlDoc getVersion, getEncoding, isStandalone methods.
History | Added TxmlBase getParent method.
History | getFirstChild and getLastChild now accept types.
History | Added more document examples.
History | 1.06
History | Split out extern/const to libxml_base.
History | Added more globals.
History | Added validation API.
History | Added TxmlDtdAttribute, TxmlDtdElement, TxmlNotation, TxmlValidCtxt, TxmlElementContent, TxmlXPathCompExpr.
History | 1.05
History | Fixed TxmlNodeSet.getNodeList.
History | API change - Added TxmlBase (for shared methods). Extended Node, Doc, Dtd, Attribute, Entity from it. Should be backwards compatible.
History | Implemented debug-time assertion checking.
History | Incbin support added for TxmlDoc and TxmlTextReader.
History | Added more XPath functionality.
History | Added libxml globals.
History | Added Entities API, XInclude API, XPointer API.
History | Added XML catalogs and SGML catalogs API.
History | Added TxmlURI, TxmlCatalog, TxmlEntity, TxmlIncludeCtxt, TxmlLocationSet.
History | 1.04
History | Removed small memory leak.
History | Fixed typo - addProcessingInstruction(), and added some missing docs.
History | Added newNode() function for TxmlNode.
History | 1.03
History | Added TxmlTextReader API.
History | Removed ansidecl.h use for linux - not always present.
History | 1.02
History | Removed xmlmodule.c
History | Changed references of xmllasterror to xmllasterror1 for Mac compile.
History | Disabled thread support and made static build - removed lots of warnings.
History | 1.01
History | Added Linux and Mac support. Still some Mac issues to resolve.
History | 1.00 Initial Release (Libxml 2.6.23)