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:

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)

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.
TxmlOutputBuffer  
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
DescriptionGlobal setting, indicate that the parser should work in validating mode.
InformationDisabled by default.

Global xmlGetWarningsDefaultValue:Int
DescriptionGlobal setting, indicate that the parser should provide warnings.
InformationActivated by default.

Global xmlIndentTreeOutput:Int
DescriptionGlobal setting, asking the serializer to indent the output tree by default.
InformationEnabled by default.

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

Global xmlLoadExtDtdDefaultValue:Int
DescriptionGlobal setting, indicate that the parser should load DTD while not validating.
InformationDisabled by default.

Global xmlParserDebugEntities:Int
DescriptionGlobal setting, asking the parser to print out debugging informations while handling entities.
InformationDisabled by default.

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

Functions

Function xmlCleanupParser()
DescriptionCleanup function for the XML library.
InformationIt 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()
ReturnsNull if no error occured ora TxmlError object.
DescriptionGet the last global error registered.

Function xmlGetPredefinedEntity:TxmlEntity(name:String)
ReturnsNull if not, otherwise the entity.
DescriptionCheck whether this name is an predefined entity.
InformationParameters:
  • name : the entity name

Function xmlSetErrorFunction(callback(data:Object, error:TxmlError), data:Object = Null)
DescriptionSets the callback handler for errors.
InformationThe 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)
ReturnsThe last value for 0 for no substitution, 1 for substitution.
DescriptionSet and return the previous value for default entity support.
InformationInitially 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
DescriptionAn XML Attribute.
Methods Summary
getAttributeType The attribute type, if validating.
getNameSpace Returns the associated Namespace.
getValue Returns the attribute value.
Method getAttributeType:Int()
ReturnsThe attribute type.
DescriptionThe attribute type, if validating.
InformationPossible 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()
ReturnsThe associated namespace, or Null if none.
DescriptionReturns the associated Namespace.
Method getValue:String()
DescriptionReturns 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
DescriptionThe 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)
DescriptionReturns a list of child nodes of a given node type.
InformationParameters:
  • nodeType : the type of node to return, or 0 for any.
See getType for a list of node types.
Method getDocument:TxmlDoc()
DescriptionReturns the document for this object.
Method getFirstChild:TxmlBase(nodeType:Int = XML_ELEMENT_NODE)
ReturnsThe first child or Null if none.
DescriptionGet 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)
ReturnsThe last child or Null if none.
DescriptionGet 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:Int()
ReturnsThe line number if successful, or -1 otherwise.
DescriptionGet the line number of the element.
Method getName:String()
DescriptionReturns the node name.
Method GetParent:TxmlBase()
ReturnsThe parent to this object.
DescriptionGet 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()
DescriptionReturns the type of this xml object.
InformationThe 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()
ReturnsThe next node or Null if there are none.
DescriptionGet 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()
ReturnsThe previous node or Null if there are none.
DescriptionGet 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
DescriptionXml 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()
DescriptionExtract the content of a buffer.
Function CreateStatic:TxmlBuffer(mem:Byte Ptr, size:Int)
DescriptionRoutine to create an XML buffer from an immutable memory area.
InformationThe area won't be modified nor copied, and is expected to be present until the end of the buffer lifetime.

Type TxmlCatalog
DescriptionAn 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)
Returns0 if successful, -1 otherwise.
DescriptionAdd an entry in the catalog, it may overwrite existing but different entries.
InformationParameters:
  • 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()
ReturnsThe number of entries converted if successful, -1 otherwise.
DescriptionConvert all the SGML catalog entries as XML ones.
Method dump(file:Int)
DescriptionDump the catalog to the given file.
Method free()
DescriptionFree the memory allocated to a Catalog.
Method isEmpty:Int()
Returns1 if the catalog is empty, 0 if not, and -1 in case of error.
DescriptionCheck is a catalog is empty.
Method remove:Int(value:String)
ReturnsThe number of entries removed if successful, -1 otherwise.
DescriptionRemove an entry from the catalog.
InformationParameters:
  • value : the value to remove
Method resolve:String(pubID:String, sysID:String)
ReturnsThe URI of the resource or Null if not found.
DescriptionDo a complete resolution lookup of an External Identifier.
InformationParameters:
  • pubID : the public ID string
  • sysID : the system ID string
Method resolvePublic:String(pubID:String)
ReturnsThe local resource if found or Null otherwise.
DescriptionTry to lookup the catalog local reference associated to a public ID in that catalog.
InformationParameters:
  • pubID : the public ID string
Method resolveSystem:String(sysID:String)
ReturnsThe resource if found or Null otherwise.
DescriptionTry to lookup the catalog resource for a system ID.
InformationParameters:
  • sysID : the system ID string
Function addDefault:Int(rtype:String, orig:String, rep:String)
Returns0 if successful, -1 otherwise.
DescriptionAdd an entry in the catalog.
InformationIt 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()
DescriptionConvert all the SGML catalog entries as XML ones.
Function defaultRemove:Int(value:String)
ReturnsThe number of entries removed if successful, -1 otherwise.
DescriptionRemove an entry from the catalog.
InformationParameters:
  • value : the value to remove
Function defaultResolve:String(pubID:String, sysID:String)
ReturnsThe URI of the resource or Null if not found.
DescriptionDo a complete resolution lookup of an External Identifier.
InformationParameters:
  • pubID : the public ID string
  • sysID : the system ID string
Function defaultResolvePublic:String(pubID:String)
ReturnsThe resource if found or Null otherwise.
DescriptionTry to lookup the catalog reference associated to a public ID.
InformationParameters:
  • pubID : the public ID string
Function defaultResolveSystem:String(sysID:String)
ReturnsThe resource if found or Null otherwise.
DescriptionTry to lookup the catalog resource for a system ID.
InformationParameters:
  • sysID : the system ID string
Function defaultResolveURI:String(uri:String)
ReturnsThe URI of the resource or Null if not found.
DescriptionDo a complete resolution lookup of an URI.
InformationParameters:
  • uri : the URI
Function getDefaults:Int()
ReturnsThe current xmlCatalogAllow value. See setDefaults for more information.
DescriptionUsed to get the user preference w.r.t. to what catalogs should be accepted.
Function loadCatalog:TxmlCatalog(filename:String)
ReturnsThe catalog parsed or Null in case of error.
DescriptionLoad the catalog and build the associated data structures.
InformationThis 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)
Returns0 in case of success -1 in case of error.
DescriptionLoad the catalog and makes its definitions effective for the default external entity loader.
InformationIt will recurse in SGML CATALOG entries.

Parameters:

  • filename : a file path

Function loadSGMLSuperCatalog:TxmlCatalog(filename:String)
ReturnsThe catalog parsed or Null in case of error.
DescriptionLoad an SGML super catalog.
InformationIt 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)
ReturnsA new catalog or Null in case of error.
DescriptionCreate a new Catalog.
InformationParameters:
  • sgml : should this create an SGML catalog
Function setDebug:Int(level:Int)
ReturnsThe previous value of the catalog debugging level.
DescriptionUsed to set the debug level for catalog operation.
Information0 disable debugging, 1 enable it.

Parameters:

  • level : the debug level of catalogs required

Function setDefaultPrefer:Int(prefer:Int)
ReturnsThe previous value of the default preference for delegation.
DescriptionAllows 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)
DescriptionUsed to set the user preference w.r.t. to what catalogs should be accepted.
InformationThe 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
DescriptionAn 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)
setEncoding Sets the document encoding.
setRootElement Set the root element of the document (doc->children is a list containing possibly comments, PIs, etc ...)
setStandalone Sets document to standalone (or not).
ToString Returns a string representation of the document.
ToStringFormat Returns a string representation of the document, optionally formatting the output.
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)
ReturnsThe entity reference or Null in case of error.
DescriptionRegister a new entity for this document.
InformationParameters:
  • 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)
ReturnsThe entity reference or Null in case of error.
DescriptionRegister a new entity for this document DTD external subset.
InformationParameters:
  • 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)
ReturnsThe new node object.
DescriptionCreation of a processing instruction element.
InformationNote - 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)
ReturnsThe new attribute object.
DescriptionCreate a new property carried by the document.
InformationNote - 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)
ReturnsA new normalized string if normalization is needed, Null otherwise.
DescriptionDoes the validation related extra step of the normalization of attribute values.
InformationIf 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)
Returnsa new TxmlDoc, or Null in case of error.
DescriptionDo a copy of the document info.
InformationParameters:
  • 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)
Returnsa new TxmlDtd object.
DescriptionCreation of a new DTD for the external subset.
InformationTo 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)
Returnsa new TxmlDtd object.
DescriptionCreate the internal subset of a document.
InformationParameters:
  • name : the DTD name.
  • externalID : the external (PUBLIC) ID.
  • systemID : the system ID.
Method encodeEntities:String(text:String)
ReturnsA new string with the substitution done.
DescriptionDo a global encoding of a string.
InformationReplaces 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)
ReturnsA newly allocated string with the substitution done.
DescriptionDo a global encoding of a string.
InformationReplaces 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)
ReturnsA newly allocated string with the substitution done.
DescriptionDo a global encoding of a string, replacing the predefined entities.
InformationParameters:
  • inp : a string to convert to XML
Method free()
DescriptionFree up all the structures used by a document, tree included.
Method freeDocElementContent(content:TxmlElementContent)
DescriptionFree an element content structure.
InformationThe whole subtree is removed.

Parameters:

  • content : the element content tree to free

Method getCompressMode:Int()
Returns0 (uncompressed) to 9 (max compression)
DescriptionGet 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)
ReturnsReturns the entity structure or Null if not found.
DescriptionDo an entity lookup in the document entity hash table and return the corresponding entity, otherwise a lookup is done in the predefined entities too.
InformationParameters:
  • name : the entity name
Method getDtdEntity:TxmlEntity(name:String)
ReturnsReturns the entity structure or Null if not found.
DescriptionDo an entity lookup in the internal and external subsets and return the corresponding parameter entity, if found.
InformationParameters:
  • name : the entity name
Method getEncoding:String()
DescriptionThe external initial encoding, if any.
Method getID:TxmlAttribute(id:String)
ReturnsNull if not found, otherwise the TxmlAttrribute defining the ID.
DescriptionSearch the attribute declaring the given ID.
InformationParameters:
  • id : the ID value
Method getInternalSubset:TxmlDtd()
Returnsthe DTD structure or Null if not found.
DescriptionGet the internal subset of a document.
Method getParameterEntity:TxmlEntity(name:String)
ReturnsReturns the entity structure or Null if not found.
DescriptionDo an entity lookup in the internal and external subsets and return the corresponding parameter entity, if found.
InformationParameters:
  • name : the entity name
Method getRootElement:TxmlNode()
DescriptionReturns 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()
DescriptionThe document URI.
Method getVersion:String()
DescriptionThe XML version string.
Method isID:Int(node:TxmlNode, attr:TxmlAttribute)
Returns0 or 1 depending on the lookup result.
DescriptionDetermine whether an attribute is of type ID.
InformationIn 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)
Returns0 if no, 1 if yes, and -1 if no element description is available.
DescriptionSearch in the DTDs whether an element accept Mixed content (or ANY) basically if it is supposed to accept text childs.
InformationParameters:
  • name : the element name
Method isRef:Int(node:TxmlNode, attr:TxmlAttribute)
Returns0 or 1 depending on the lookup result.
DescriptionDetermine whether an attribute is of type Ref.
InformationIn 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()
ReturnsTrue if the document has no external refs.
DescriptionIs this document standalone?
Method newDocElementContent:TxmlElementContent(name:String, contentType:Int)
ReturnsNull if not, otherwise the new element content structure.
DescriptionAllocate an element content structure for the document.
InformationParameters:
  • 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()
DescriptionCreate a new TxmlXPathContext.
Method normalizeAttributeValue:String(elem:TxmlNode, name:String, value:String)
ReturnsA new normalized string if normalization is needed, Null otherwise.
DescriptionDoes the validation related extra step of the normalization of attribute values.
InformationIf 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.
DescriptionRemove the given attribute from the ID table maintained internally.
InformationParameters:
  • attr : the attribute
Method removeRef:Int(attr:TxmlAttribute)
Returns-1 if the lookup failed and 0 otherwise.
DescriptionRemove the given attribute from the Ref table maintained internally.
InformationParameters:
  • attr : the attribute
Method saveFile:Int(filename:String)
Returnsthe number of bytes written or -1 in case of failure.
DescriptionDump an XML document to a file.
InformationWill 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)
Returnsthe number of bytes written or -1 in case of failure.
DescriptionDump an XML document to a file.
InformationWill 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)
DescriptionSet the default compression mode used, ZLIB based Correct values: 0 (uncompressed) to 9 (max compression)
InformationParameters:
  • 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 setEncoding(encoding:String)
DescriptionSets the document encoding.
Method setRootElement:TxmlNode(root:TxmlNode)
Returnsthe old root element if any was found.
DescriptionSet the root element of the document (doc->children is a list containing possibly comments, PIs, etc ...)
InformationParameters:
  • root : the new document root element
Method setStandalone(value:Int)
DescriptionSets document to standalone (or not).
Method ToString:String()
DescriptionReturns a string representation of the document.
Method ToStringFormat:String(format:Int = False)
DescriptionReturns a string representation of the document, optionally formatting the output.
Method XIncludeProcess:Int()
Returns0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
DescriptionImplement the XInclude substitution on the XML document.
Method XIncludeProcessFlags:Int(flags:Int)
Returns0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
DescriptionImplement the XInclude substitution on the XML document.
InformationParameters:
  • flags : a set of xml Parser Options used for parsing XML includes (see fromFile for option details)
Method XPathOrderElements:Long()
ReturnsThe number of elements found in the document or -1 in case of error.
DescriptionCall this routine to speed up XPath computation on static documents.
InformationThis 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)
DescriptionCreates a new XML document.
InformationParameters:
  • 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)
ReturnsThe resulting document tree or Null in case of error.
DescriptionParse an XML file and build a tree.
InformationIt's like parseFile() except it bypasses all catalog lookups. Note: Doesn't support "incbin::".

Parameters:

  • filename : the filename

Function parseDoc:TxmlDoc(text:String)
ReturnsThe resulting document tree or Null if error.
DescriptionParse an XML string and build a tree.
InformationParameters:
  • 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)
ReturnsThe resulting document tree or Null if error.
DescriptionParse an XML file and build a tree.
InformationAutomatic 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
DescriptionAn 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()
ReturnsA new TxmlDtd object, or Null in case of error.
DescriptionDo a copy of the dtd.
Method free()
DescriptionFree the DTD structure.
Method getAttrDesc:TxmlDtdAttribute(elem:String, name:String)
ReturnsThe TxmlDtdAttribute if found or Null.
DescriptionSearch the DTD for the description of this attribute on this element.
InformationParameters:
  • elem : the element name
  • name : the attribute name
Method getElementDesc:TxmlDtdElement(name:String)
ReturnsThe TxmlDtdElement if found or Null.
DescriptionSearch the DTD for the description of this element.
InformationParameters:
  • name : the element name
Method getExternalID:String()
DescriptionReturns the external identifier for PUBLIC DTD.
Method getNotationDesc:TxmlNotation(name:String)
ReturnsThe TxmlNotation if found or Null.
DescriptionSearch the DTD for the description of this notation.
InformationParameters:
  • name : the notation name
Method getQAttrDesc:TxmlDtdAttribute(elem:String, name:String, prefix:String)
ReturnsThe TxmlDtdAttribute if found or Null.
DescriptionSearch the DTD for the description of this qualified attribute on this element.
InformationParameters:
  • elem : the element name
  • name : the attribute name
  • prefix : the attribute namespace prefix
Method getQElementDesc:TxmlDtdElement(name:String, prefix:String)
ReturnsThe TxmlDtdElement if found or Null.
DescriptionSearch the DTD for the description of this qualified element.
InformationParameters:
  • name : the element name
  • prefix : the element namespace prefix
Method getSystemID:String()
DescriptionReturns the URI for a SYSTEM or PUBLIC DTD.

Type TxmlDtdAttribute Extends TxmlBase
DescriptionAn XML Attribute Decl.
Methods Summary
getDefaultValue Returns the attribute default value.
Method getDefaultValue:String()
DescriptionReturns the attribute default value.

Type TxmlDtdElement Extends TxmlBase
DescriptionAn XML Element.
Methods Summary
getElementType Returns the element type.
getPrefix Returns the namespace prefix, if any.
Method getElementType:Int()
DescriptionReturns the element type.
InformationThe 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()
DescriptionReturns the namespace prefix, if any.

Type TxmlElementContent
DescriptionAn 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()
DescriptionReturns the element name.
Method getOccur:Int()
DescriptionReturns the content occurance.
InformationThe 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()
DescriptionReturns the namespace prefix.
Method getType:Int()
DescriptionReturns the content type.
InformationThe 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
DescriptionAn XML Entity.

Type TxmlError
DescriptionAn 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()
DescriptionReturns the column number of the error or 0 if not available.
Method getErrorCode:Int()
DescriptionReturns the error code.
Method getErrorDomain:Int()
DescriptionReturns the part of the library that raised the error.
InformationThe following lists possible domains:
ConstantMeaning
XML_FROM_NONEFrom none
XML_FROM_PARSERThe XML parser
XML_FROM_TREEThe tree module
XML_FROM_NAMESPACEThe XML Namespace module
XML_FROM_DTDThe XML DTD validation with parser contex
XML_FROM_HTMLThe HTML parser
XML_FROM_MEMORYThe memory allocator
XML_FROM_OUTPUTThe serialization code
XML_FROM_IOThe Input/Output stack
XML_FROM_FTPThe FTP module
XML_FROM_HTTPThe HTTP module
XML_FROM_XINCLUDEThe XInclude processing
XML_FROM_XPATHThe XPath module
XML_FROM_XPOINTERThe XPointer module
XML_FROM_REGEXPThe regular expressions module
XML_FROM_DATATYPEThe W3C XML Schemas Datatype module
XML_FROM_SCHEMASPThe W3C XML Schemas parser module
XML_FROM_SCHEMASVThe W3C XML Schemas validation module
XML_FROM_RELAXNGPThe Relax-NG parser module
XML_FROM_RELAXNGVThe Relax-NG validator module
XML_FROM_CATALOGThe Catalog module
XML_FROM_C14NThe Canonicalization module
XML_FROM_XSLTThe XSLT engine from libxslt
XML_FROM_VALIDThe XML DTD validation with valid context
XML_FROM_CHECKThe error checking module
XML_FROM_WRITERThe xmlwriter module
XML_FROM_MODULEThe dynamically loaded module
XML_FROM_I18NThe module handling character conversion
Method getErrorLevel:Int()
DescriptionReturns the error level.
InformationThe following is a list of error levels:
ConstantMeaning
XML_ERR_NONENo error
XML_ERR_WARNINGA simple warning
XML_ERR_ERRORA recoverable error
XML_ERR_FATALA fatal error
Method getErrorMessage:String()
DescriptionReturns the error message text.
Method getErrorNode:TxmlNode()
DescriptionReturns the node in the tree, if available.
Method getExtraText:String[]()
DescriptionReturns extra error text information, if available.
Method getFilename:String()
DescriptionReturns the filename.
Method getLine:Int()
DescriptionReturns the error line, if available.

Type TxmlLocationSet
DescriptionAn 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)
DescriptionAdd a new TxmlXPathObject to an existing LocationSet.
InformationIf the location already exist in the set value is freed.

Parameters:

  • value : a new TxmlXPathObject

Method del(value:TxmlXPathObject)
DescriptionRemoves a TxmlXPathObject from the LocationSet.
Method free()
DescriptionFree the LocationSet compound (not the actual ranges !).
Method merge:TxmlLocationSet(value:TxmlLocationSet)
ReturnsThis set once extended or Null in case of error.
DescriptionMerges two rangesets.
InformationAll ranges from value are added to this set.

Parameters:

  • value : a location set to merge

Method remove(index:Int)
DescriptionRemoves an entry from an existing LocationSet list.
InformationParameters:
  • index : the index to remove
Function Create:TxmlLocationSet()
ReturnsThe newly created object.
DescriptionCreate a new xmlLocationSetPtr of type double.

Type TxmlNode Extends TxmlBase
DescriptionAn 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 = "")
ReturnsThe Attribute object.
DescriptionCreate a new attribute.
InformationParameters:
  • 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)
Returnsthe new node object.
DescriptionCreation of a new node containing a CDATA block.
InformationParameters:
  • content : the CDATA block content
Method addChild:TxmlNode(name:String, namespace:TxmlNs = Null, content:String = Null)
DescriptionCreation of a new child element.
InformationAdded 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)
Returnsthe last child or Null in case of error.
DescriptionAdd a list of nodes at the end of the child list of this node, merging adjacent TEXT nodes.
InformationParameters:
  • list : the list of nodes.
Method addComment:TxmlNode(comment:String)
Returnsthe new node object.
DescriptionCreation of a new node containing a comment.
InformationParameters:
  • 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)
DescriptionAppend the extra substring to the node content.
InformationParameters:
  • 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)
Returnsthe new node or Null in case of error.
DescriptionAdd a new node node as the next sibling.
InformationIf 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)
Returnsthe new node or Null in case of error.
DescriptionAdd a new node node as the previous sibling, merging adjacent TEXT nodes.
InformationIf 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)
Returnsthe new node or Null in case of error.
DescriptionAdd a new element node to the list of siblings, merging adjacent TEXT nodes.
InformationIf 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)
ReturnsThe new child node.
DescriptionCreation of a new child text element.
InformationAdded 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.
DescriptionConcat the given string at the end of the existing node content.
InformationParameters:
  • content : the content.
Method copy:TxmlNode(extended:Int = 1)
Returnsa new TxmlNode, or Null in case of error.
DescriptionDo a copy of the node.
InformationParameters:
  • 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)
Returnsa new TxmlNode, or Null in case of error.
DescriptionDo a copy of the node to a given document.
InformationParameters:
  • 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()
DescriptionFrees a node.
InformationThe node should be unlinked before being freed. See unlinkNode.
Method getAttribute:String(name:String)
ReturnsThe attribute value or Null if not found.
DescriptionSearch and get the value of an attribute associated to the node.
InformationThis 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()
ReturnsThe list of attributes or Null if the node has none.
DescriptionReturns 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()
ReturnsThe base URL, or Null if not found.
DescriptionSearches for the BASE URL.
InformationThe 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()
ReturnsThe node content.
DescriptionRead the value of a node.
InformationThis 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)
ReturnsThe first child or Null if none.
DescriptionGet 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()
Returnsthe language value, or Null if not found.
DescriptionSearches 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)
ReturnsThe last child or Null if none.
DescriptionGet 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()
DescriptionReturns the associated namespace.
Method getNodePath:String()
ReturnsThe path or Null in case of error.
DescriptionBuild 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)
Returnsthe attribute value or Null if not found.
DescriptionSearch and get the value of an attribute associated to the node.
InformationThis 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)
Returnsthe attribute value or Null if not found.
DescriptionSearch and get the value of an attribute associated to a node.
InformationThis 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()
DescriptionSearches 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()
DescriptionReturn the string equivalent to the text contained in the child nodes made of TEXTs and ENTITY_REFs.
Method hasAttribute:TxmlAttribute(name:String)
Returnsthe attribute or Null if not found.
DescriptionSearch an attribute associated to the node.
InformationThis 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)
Returnsthe attribute or Null if not found.
DescriptionSearch for an attribute associated to the node.
InformationThis 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()
DescriptionChecks whether this node is an empty or whitespace only (and possibly ignorable) text-node.
Method isText:Int()
DescriptionIs this node a Text node ?
Method nextNode:TxmlNode()
ReturnsThe next node or Null if there are none.
DescriptionGet the next sibling node.
InformationEquivalent to TxmlNode( nextSibling() ).
Method previousNode:TxmlNode()
ReturnsThe previous node or Null if there are none.
DescriptionGet the previous sibling node.
InformationEquivalent to TxmlNode( previousSibling() ).
Method replaceNode:TxmlNode(withNode:TxmlNode)
ReturnsThe removed node.
DescriptionUnlink the old node from its current context.
InformationPrune 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)
Returnsthe namespace or Null.
DescriptionSearch a Namespace registered under a given name space for a document.
InformationRecurse 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)
ReturnsThe namespace or Null.
DescriptionSearch a Namespace aliasing a given URI.
InformationRecurse 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 = "")
ReturnsThe attribute object.
DescriptionSet (or reset) an attribute carried by a node.
InformationParameters:
  • 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)
DescriptionSet (or reset) the base URI of a node, i.e. the value of the xml:base attribute.
InformationParameters:
  • uri : the new base URI.
Method setContent(content:String)
DescriptionReplace the content of a node.
InformationParameters:
  • 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)
DescriptionSet the language of a node, i.e. the values of the xml:lang attribute.
InformationParameters:
  • lang : the language description.
Method setName(name:String)
DescriptionSet (or reset) the name of a node.
InformationParameters:
  • 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)
DescriptionAssociate a namespace to a node, a posteriori.
InformationParameters:
  • namespace : a namespace.
Method setNsAttribute:TxmlAttribute(namespace:TxmlNs, name:String, value:String = "")
ReturnsThe attribute object.
DescriptionSet (or reset) an attribute carried by a node.
InformationThe 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)
DescriptionSet (or reset) the space preserving behaviour of a node, i.e. the value of the xml:space attribute.
InformationParameters:
  • value : the xml:space value ("0": default, 1: "preserve").
Method setTreeDoc(doc:TxmlDoc)
DescriptionUpdate all nodes under the tree to point to the right document.
InformationParameters:
  • doc : the document.
Method textMerge:TxmlNode(node:TxmlNode)
DescriptionMerge two text nodes into one.
InformationParameters:
  • node : the second text node being merged.
Method toString:String()
DescriptionReturns a string representation of the node and its children.
Method unlinkNode()
DescriptionUnlinks a node from the document.
InformationAfter unlinking, and the node is no longer required, it should be freed using freeNode.
Method unsetAttribute:Int(name:String)
Returns0 if successful, -1 if not found.
DescriptionRemove an attribute carried by the node.
InformationParameters:
  • 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)
Returns0 if successful, -1 if not found.
DescriptionRemove an attribute carried by the node.
InformationParameters:
  • namespace : the namespace definition.
  • name : the attribute name.
Method XIncludeProcessTree:Int()
Returns0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
DescriptionImplement the XInclude substitution for the subtree.
Method XIncludeProcessTreeFlags:Int(flags:Int)
Returns0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
DescriptionImplement the XInclude substitution for the subtree.
InformationParameters:
  • 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)
DescriptionCreation of a new node element.
Informationnamespace 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
DescriptionAn 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()
ReturnsThe boolean value.
DescriptionConverts the node set to its boolean value.
Method castToNumber:Double()
ReturnsThe number value.
DescriptionConverts the node set to its number value.
Method castToString:String()
ReturnsThe string value.
DescriptionConverts the node set to its string value.
Method free()
DescriptionFree the node set compound (not the actual nodes !).
Method getNodeCount:Int()
DescriptionThe count of nodes in the node set.
Method getNodeList:TList()
DescriptionThe list of nodes in the node set.
Method isEmpty:Int()
DescriptionChecks whether the node set is empty or not.

Type TxmlNotation
DescriptionAn 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()
DescriptionReturns the notation name.
Method getPublicID:String()
DescriptionReturns the public identifier, if any.
Method getSystemID:String()
DescriptionReturns the system identifier, if any.

Type TxmlNs
DescriptionAn 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()
DescriptionFree up the structures associated to the namespace.
Method getHref:String()
DescriptionReturns the URL for the namespace.
Method getPrefix:String()
DescriptionReturns the prefix for the namespace.
Method getType:Int()
DescriptionReturns the type... global or local.

Type TxmlOutputBuffer

Type TxmlTextReader
DescriptionAn XML Streaming Text Reader.
InformationText 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()
Returns0 if no attributes, -1 in case of error or the attribute count.
DescriptionProvides the number of attributes of the current node.
Method baseUri:String()
DescriptionThe base URI of the node.
Method constBaseUri:String()
ReturnsThe base URI or Null if not available.
DescriptionThe base URI of the node.
Method constEncoding:String()
ReturnsA string containing the encoding of the document or Null in case of error.
DescriptionDetermine the encoding of the document being read.
Method constLocalName:String()
ReturnsThe local name or Null if not available.
DescriptionThe local name of the node.
Method constName:String()
ReturnsThe local name or Null if not available.
DescriptionThe qualified name of the node, equal to Prefix :LocalName.
Method constNamespaceUri:String()
ReturnsThe namespace URI or Null if not available.
DescriptionThe URI defining the namespace associated with the node.
Method constPrefix:String()
ReturnsThe prefix or Null if not available.
DescriptionA shorthand reference to the namespace associated with the node.
Method constValue:String()
Returnsthe string or Null if not available.
DescriptionProvides the text value of the node if present.
Method constXmlLang:String()
ReturnsThe xml:lang value or Null if none exists.
DescriptionThe xml:lang scope within which the node resides.
Method constXmlVersion:String()
ReturnsA string containing the XML version of the document or Null in case of error.
DescriptionDetermine the XML version of the document being read.
Method currentDoc:TxmlDoc()
ReturnsThe TxmlDoc or Null in case of error.
DescriptionHacking interface allowing to get the TxmlDoc correponding to the current document being accessed by the TxmlTextReader.
InformationNOTE: 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()
Returnsthe depth or -1 in case of error.
DescriptionThe depth of the node in the tree.
Method expand:TxmlNode()
DescriptionReads the contents of the current node and the full subtree.
InformationIt 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()
DescriptionDeallocate all the resources associated to the reader.
Method getAttribute:String(name:String)
ReturnsA string containing the value of the specified attribute, or Null in case of error.
DescriptionProvides the value of the attribute with the specified qualified name.
InformationParameters:
  • 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)
ReturnsA string containing the value of the specified attribute, or Null in case of error.
DescriptionProvides the value of the attribute with the specified index relative to the containing element.
InformationParameters:
  • index : the zero-based index of the attribute relative to the containing element.
Method getAttributeByNamespace:String(localName:String, namespaceURI:String)
ReturnsA string containing the value of the specified attribute, or Null in case of error.
DescriptionProvides the value of the specified attribute.
InformationParameters:
  • localName : the local name of the attribute.
  • namespaceURI : the namespace URI of the attribute.
Method getParserColumnNumber:Int()
ReturnsAn int or 0 if not available.
DescriptionProvide the column number of the current parsing point.
Method getParserLineNumber:Int()
ReturnsAn int or 0 if not available.
DescriptionProvide the line number of the current parsing point.
Method getParserProperty:Int(prop:Int)
ReturnsThe value, usually 0 or 1, or -1 in case of error.
DescriptionRead the parser internal property.
InformationThe 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()
Returns1 if true, 0 if false, and -1 in case or error.
DescriptionWhether the node has attributes.
Method hasValue:Int()
Returns1 if true, 0 if false, and -1 in case or error.
DescriptionWhether the node can have a text value.
Method isDefault:Int()
Returns0 if not defaulted, 1 if defaulted, and -1 in case of error.
DescriptionWhether an Attribute node was generated from the default value defined in the DTD or schema.
Method isEmptyElement:Int()
Returns1 if empty, 0 if not and -1 in case of error.
DescriptionCheck if the current node is empty.
Method isNamespaceDecl:Int()
Returns1 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.
DescriptionDetermine whether the current node is a namespace declaration rather than a regular attribute.
Method isValid:Int()
DescriptionRetrieve the validity status from the parser context.
InformationThe flag value 1 if valid, 0 if no, and -1 in case of error.
Method localName:String()
Returnsthe local name or Null if not available.
DescriptionThe local name of the node.
Method lookupNamespace:String(prefix:String)
ReturnsA string containing the namespace URI to which the prefix maps or Null in case of error.
DescriptionResolves a namespace prefix in the scope of the current element.
InformationParameters:
  • prefix : the prefix whose namespace URI is to be resolved. To return the default namespace, specify Null.
Method moveToAttribute:Int(name:String)
Returns1 in case of success, -1 in case of error, 0 if not found.
DescriptionMoves the position of the current instance to the attribute with the specified qualified name.
InformationParameters:
  • name : the qualified name of the attribute.
Method moveToAttributeByIndex:Int(index:Int)
Returns1 in case of success, -1 in case of error, 0 if not found.
DescriptionMoves the position of the current instance to the attribute with the specified index relative to the containing element.
InformationParameters:
  • index : the zero-based index of the attribute relative to the containing element.
Method moveToAttributeByNamespace:Int(localName:String, namespaceURI:String)
Returns1 in case of success, -1 in case of error, 0 if not found.
DescriptionMoves the position of the current instance to the attribute with the specified local name and namespace URI.
InformationParameters:
  • localName : the local name of the attribute.
  • namespaceURI : the namespace URI of the attribute.
Method moveToElement:Int()
Returns1 in case of success, -1 in case of error, 0 if not moved.
DescriptionMoves the position of the current instance to the node that contains the current Attribute node.
Method moveToFirstAttribute:Int()
Returns1 in case of success, -1 in case of error, 0 if not found.
DescriptionMoves the position of the current instance to the first attribute associated with the current node.
Method moveToNextAttribute:Int()
Returns1 in case of success, -1 in case of error, 0 if not found.
DescriptionMoves the position of the current instance to the next attribute associated with the current node.
Method name:String()
Returnsthe local name or Null if not available.
DescriptionThe qualified name of the node, equal to Prefix :LocalName.
Method namespaceUri:String()
Returnsthe namespace URI or Null if not available.
DescriptionThe URI defining the namespace associated with the node.
Method nextNode:Int()
Returns1 if the node was read successfully, 0 if there is no more nodes to read, or -1 in case of error.
DescriptionSkip to the node following the current one in document order while avoiding the subtree if any.
Method nodeType:Int()
ReturnsThe xmlNodeType of the current node or -1 in case of error.
DescriptionGet the node type of the current node.
Method normalization:Int()
Returns1 or -1 in case of error.
DescriptionThe value indicating whether to normalize white space and attribute values.
InformationSince 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()
ReturnsThe prefix or Null if not available.
DescriptionA shorthand reference to the namespace associated with the node.
Method preserve:TxmlNode()
ReturnsThe TxmlNode or Null in case of error.
DescriptionThis tells the XML Reader to preserve the current node.
InformationThe 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.
DescriptionThe quotation mark character used to enclose the value of an attribute.
Method read:Int()
Returns1 if the node was read successfully, 0 if there is no more nodes to read, or -1 in case of error.
DescriptionMoves the position of the current instance to the next node in the stream, exposing its properties.
Method readAttributeValue:Int()
DescriptionParses an attribute value into one or more Text and EntityReference nodes.
Information1 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()
ReturnsA string containing the XML content, or Null if the current node is neither an element nor attribute, or has no child nodes.
DescriptionReads the contents of the current node, including child nodes and markup.
Method readOuterXml:String()
ReturnsA string containing the XML content, or NULL if the current node is neither an element nor attribute, or has no child nodes.
DescriptionReads the contents of the current node, including child nodes and markup.
Method readState:Int()
DescriptionGets the read state of the reader.
InformationThe state value, or -1 in case of error.
Method ReadString:String()
DescriptionReads the contents of an element or a text node as a string.
InformationA 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)
Returns0 in case the RelaxNG validation could be (des)activated and -1 in case of error.
DescriptionUse RelaxNG to validate the document as it is processed.
InformationActivation 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)
Returns0 in case the schemas validation could be (de)activated and -1 in case of error.
DescriptionUse W3C XSD schema to validate the document as it is processed.
InformationActivation 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)
Returns0 if the call was successful, or -1 in case of error.
DescriptionChange the parser processing behaviour by changing some of its internal properties.
InformationNote 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()
Returns1 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.
DescriptionDetermine the standalone status of the document being read.
Method value:String()
ReturnsThe string or Null if not available.
DescriptionProvides the text value of the node if present.
Method xmlLang:String()
Returnsthe xml:lang value or Null if none exists.
DescriptionThe xml:lang scope within which the node resides.
Function fromDoc:TxmlTextReader(text:String, url:String, encoding:String, options:Int)
ReturnsThe new reader or Null in case of error.
DescriptionCreate an TxmlTextReader for an XML in-memory document.
InformationThe 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)
DescriptionParse an XML file from the filesystem or the network.
InformationThe parsing flags options are a combination of the following:
ConstantMeaning
XML_PARSE_RECOVERrecover on errors
XML_PARSE_NOENTsubstitute entities
XML_PARSE_DTDLOADload the external subset
XML_PARSE_DTDATTRdefault DTD attributes
XML_PARSE_DTDVALIDvalidate with the DTD
XML_PARSE_NOERRORsuppress error reports
XML_PARSE_NOWARNINGsuppress warning reports
XML_PARSE_PEDANTICpedantic error reporting
XML_PARSE_NOBLANKSremove blank nodes
XML_PARSE_SAX1use the SAX1 interface internally
XML_PARSE_XINCLUDEImplement XInclude substitition
XML_PARSE_NONETForbid network access
XML_PARSE_NODICTDo not reuse the context dictionnary
XML_PARSE_NSCLEANremove redundant namespaces declarations
XML_PARSE_NOCDATAmerge CDATA as text nodes
XML_PARSE_NOXINCNODEdo not generate XINCLUDE START/END nodes
XML_PARSE_COMPACTcompact 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
DescriptionA URI.
InformationProvides 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()
DescriptionFree up the TxmlURI object.
Method getAuthority:String()
DescriptionReturns the authority part.
Method getFragment:String()
DescriptionReturns the fragment identifier.
Method getOpaque:String()
DescriptionReturns the opaque part.
Method getPath:String()
DescriptionReturns the path string.
Method getPort:Int()
DescriptionReturns the port number.
Method getQuery:String()
DescriptionReturns the query string.
Method getScheme:String()
DescriptionReturns the URI scheme.
Method getServer:String()
DescriptionReturns the server part.
Method getUser:String()
DescriptionReturns the user part.
Method parseURIReference:Int(uri:String)
Returns0 or the error code.
DescriptionParse an URI reference string and fills in the appropriate fields of the URI structure.
InformationURI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]

Parameters:

  • uri : the string to analyze

Method saveURI:String()
ReturnsA new string.
DescriptionSave the URI as an escaped string.
Function buildURI:String(uri:String, base:String)
ReturnsA new URI string or Null in case of error.
DescriptionComputes the final URI of the reference done by checking that the given URI is valid, and building the final URI using the base URI.
InformationThis 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)
ReturnsA new canonic path, or a duplicate of the path parameter if the construction fails.
DescriptionConstructs a canonic path from the specified path.
InformationParameters:
  • path : the resource locator in a filesystem notation
Function createURI:TxmlURI()
ReturnsThe new structure or Null in case of error.
DescriptionSimply creates an empty TxmlURI.
Function normalizeURIPath:String(path:String)
ReturnsThe normalized string.
DescriptionApplies the 5 normalization steps to a path string.
InformationThat is, RFC 2396 Section 5.2, steps 6.c through 6.g.

Parameters:

  • path : the path string

Function parseURI:TxmlURI(uri:String)
ReturnsA newly built TxmlURI or Null in case of error.
DescriptionParse a URI.
InformationURI-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)
ReturnsA newly built TxmlURI or Null in case of error.
DescriptionParse an URI but allows to keep intact the original fragments.
InformationURI-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)
ReturnsA copy of the string, but escaped.
DescriptionEscaping routine, does not do validity checks !
InformationIt 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)
ReturnsA new escaped string or Null in case of error.
DescriptionThis routine escapes a string to hex, ignoring reserved characters (a-z) and the characters in the exception list.
InformationParameters:
  • 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)
ReturnsA copy of the string, but unescaped.
DescriptionUnescaping routine.
InformationDoes 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
DescriptionXML 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)
Returns1 in case of success, 0 in case of error.
Description(Re)Build the automata associated to the content model of the element.
InformationParameters:
  • elem : an element declaration node
Method free()
DescriptionFree the validation context structure.
Method getDocument:TxmlDoc()
DescriptionReturns the document for this object.
Method isFinishedDtd:Int()
DescriptionReturns true if finished validating the DTD.
Method isValid:Int()
DescriptionReturns the temporary validity check result state.
Method validateAttributeDecl:Int(doc:TxmlDoc, attr:TxmlDtdAttribute)
Returns1 if valid or 0 otherwise.
DescriptionTry to validate a single attribute definition.
InformationBasically 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)
Returns1 if valid or 0 otherwise.
DescriptionTry to validate the document instance.
Method validateDocumentFinal:Int(doc:TxmlDoc)
Returns1 if valid or 0 otherwise.
DescriptionDoes the final step for the document validation once all the incremental validation steps have been completed.
InformationBasically 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)
Returns1 if valid or 0 otherwise.
DescriptionTry to validate the document against the dtd instance.
InformationBasically 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)
Returns1 if valid or 0 if invalid and -1 if not well-formed.
DescriptionDoes the final step for the dtds validation once all the subsets have been parsed.
InformationBasically 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)
Returns1 if valid or 0 otherwise.
DescriptionTry to validate the subtree under an element.
InformationParameters:
  • doc : a document instance
  • elem : an element instance
Method validateElementDecl:Int(doc:TxmlDoc, elem:TxmlDtdElement)
DescriptionTry to validate a single element definition.
InformationBasically 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)
Returns1 if valid or 0 otherwise.
DescriptionTry to validate a the root element.
InformationBasically 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()
ReturnsNull if not, otherwise the new validation context structure.
DescriptionAllocate a validation context structure.
Function validateAttributeValue:Int(attributeType:Int, value:String)
Returns1 if valid or 0 otherwise.
DescriptionValidate 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)
Returns1 if valid or 0 otherwise.
DescriptionValidate that the given value match Names production.
InformationParameters:
  • value : a Names value
Function validateNameValue:Int(value:String)
Returns1 if valid or 0 otherwise.
DescriptionValidate that the given value match Name production.
InformationParameters:
  • value : an Name value
Function validateNmtokensValue:Int(value:String)
Returns1 if valid or 0 otherwise.
DescriptionValidate that the given value match Nmtokens production.
Information[ VC: Name Token ]

Parameters:

  • value : an Nmtokens value

Function validateNmtokenValue:Int(value:String)
Returns1 if valid or 0 otherwise.
DescriptionValidate that the given value match Nmtoken production.
Information[ VC: Name Token ]

Parameters:

  • value : an Nmtoken value


Type TxmlXIncludeCtxt
DescriptionAn 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()
DescriptionFree the XInclude context.
Method processNode:Int(node:TxmlNode)
Returns0 if no substitution were done, -1 if some processing failed or the number of substitutions done.
DescriptionImplement the XInclude substitution for the given subtree reusing the informations and data coming from the given context.
InformationParameters:
  • node : a node in an XML document
Method setFlags:Int(flags:Int)
Returns0 in case of success and -1 in case of error.
DescriptionSet the flags used for further processing of XML resources.
InformationParameters:
  • flags : a set of xml Parser Options used for parsing XML includes. (see fromFile for details on available options)
Function newContext:TxmlXIncludeCtxt(doc:TxmlDoc)
ReturnsThe new context.
DescriptionCreates a new XInclude context.
InformationParameters:
  • doc : an XML Document

Type TxmlXPathCompExpr
DescriptionA 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)
ReturnsThe TxmlXPathObject resulting from the evaluation or Null.
DescriptionEvaluate the precompiled XPath expression in the given context.
InformationParameters:
  • context : the XPath context
Method free()
DescriptionFree up the allocated memory.
Function Compile:TxmlXPathCompExpr(expr:String)
ReturnsThe TxmlXPathCompExpr resulting from the compilation or Null.
DescriptionCompile an XPath expression.
InformationParameters:
  • expr : the XPath expression

Type TxmlXPathContext
DescriptionAn XML XPath Context.
InformationExpression 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()
DescriptionReturns the number of defined types.
Method eval:TxmlXPathObject(text:String)
ReturnsA TxmlXPathObject resulting from the evaluation or Null.
DescriptionEvaluate the XPath Location Path in the context.
InformationParameters:
  • text : the XPath expression
Method evalExpression:TxmlXPathObject(text:String)
ReturnsA TxmlXPathObject resulting from the evaluation or Null.
DescriptionEvaluate the XPath expression in the context.
InformationParameters:
  • text : the XPath expression
Method evalPredicate:Int(res:TxmlXPathObject)
DescriptionEvaluate a predicate result for the current node.
InformationA 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()
DescriptionFree up the TxmlXPathContext.
Method getContextSize:Int()
DescriptionReturns the context size.
Method getDocument:TxmlDoc()
DescriptionReturn the TxmlDoc associated to this XPath context.
Method getFunction:String()
DescriptionReturns the function name when calling a function.
Method getFunctionURI:String()
DescriptionReturns the function URI when calling a function.
Method getHere:TxmlNode()
DescriptionReturns the XPointer for here.
Method getMaxTypes:Int()
DescriptionReturns the max number of types.
Method GetNode:TxmlNode()
DescriptionReturn the current TxmlNode associated with this XPath context.
Method GetOrigin:TxmlNode()
DescriptionReturns the XPointer for origin.
Method getProximityPosition:Int()
DescriptionReturns the proximity position.
Method isXPointerContext:Int()
DescriptionReturns whether this is an XPointer context or not.
Method registerNamespace:Int(prefix:String, uri:String)
DescriptionRegister a new namespace.
InformationIf uri is Null it unregisters the namespace.
Method XPointerEval:TxmlXPathObject(expr:String)
ReturnsThe TxmlXPathObject resulting from the evaluation or Null. The caller has to free the object.
DescriptionEvaluate the XPath Location Path in the context.
Function XPointerNewContext:TxmlXPathContext(doc:TxmlDoc, here:TxmlNode, origin:TxmlNode)
ReturnsThe TxmlXPathContext just allocated.
DescriptionCreate a new XPointer context.
InformationParameters:
  • 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
DescriptionAn 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()
ReturnsThe boolean value.
DescriptionConverts the XPath object to its boolean value.
Method castToNumber:Double()
ReturnsThe number value.
DescriptionConverts the XPath object to its number value.
Method castToString:String()
ReturnsThe string value.
DescriptionConverts the XPath object to its string value.
Method convertBoolean:TxmlXPathObject()
Returnsthe new object, this one is freed.
DescriptionConverts an existing object to its boolean() equivalent.
Method convertNumber:TxmlXPathObject()
Returnsthe new object, this one is freed.
DescriptionConverts an existing object to its number() equivalent.
Method convertString:TxmlXPathObject()
Returnsthe new object, this one is freed.
DescriptionConverts an existing object to its string() equivalent.
Method copy:TxmlXPathObject()
ReturnsThe newly created object.
DescriptionAllocate a new copy of a given object.
Method free()
DescriptionFree up the TxmlXPathObject.
Method getNodeSet:TxmlNodeSet()
DescriptionReturns the node set for the xpath.
Method getStringValue:String()
DescriptionReturns the xpath object string value.
Method getType:Int()
DescriptionThe XPath object type.
InformationThe 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()
DescriptionWhether the node set is empty or not.
Method XPointerBuildNodeList:TxmlNode()
ReturnsAn node list or Null. The caller has to free the node tree.
DescriptionBuild a node list tree copy of the XPointer result.
InformationThis will drop Attributes and Namespace declarations.
Method XPointerLocationSetCreate:TxmlLocationSet()
ReturnsThe newly created object.
DescriptionCreate a new TxmlLocationSet of type double and value of this XPathObject.
Function XPointerNewCollapsedRange:TxmlXPathObject(node:TxmlNode)
ReturnsThe newly created object.
DescriptionCreate a new TxmlXPathObject of type range using a single node.
InformationParameters:
  • node : the starting and ending node
Function XPointerNewLocationSetNodes:TxmlXPathObject(startnode:TxmlNode, endnode:TxmlNode)
Returnsthe newly created object.
DescriptionCreate a new TxmlXPathObject of type LocationSet and initialize it with the single range made of the two nodes startnode and endnode.
InformationParameters:
  • startnode : the start Node value
  • endnode : the end Node value or Null
Function XPointerNewLocationSetNodeSet:TxmlXPathObject(nodeset:TxmlNodeSet)
ReturnsThe newly created object.
DescriptionCreate a new TxmlXPathObject of type LocationSet and initialize it with all the nodes from nodeset.
InformationParameters:
  • nodeset : a node set
Function XPointerNewRange:TxmlXPathObject(startnode:TxmlNode, startindex:Int, endnode:TxmlNode, endindex:Int)
ReturnsThe newly created object.
DescriptionCreate a new TxmlXPathObject of type range.
InformationParameters:
  • startnode : the starting node
  • startindex : the start index
  • endnode : the ending node
  • endindex : the ending index
Function XPointerNewRangeNodeObject:TxmlXPathObject(startnode:TxmlNode, endobj:TxmlXPathObject)
ReturnsThe newly created object.
DescriptionCreate a new TxmlXPathObject of type range from a node to an object.
InformationParameters:
  • startnode : the starting node
  • endobj : the ending object
Function XPointerNewRangeNodePoint:TxmlXPathObject(startnode:TxmlNode, endpoint:TxmlXPathObject)
ReturnsThe newly created object.
DescriptionCreate a new TxmlXPathObject of type range from a node to a point.
InformationParameters:
  • startnode : the starting node
  • endpoint : the ending point
Function XPointerNewRangeNodes:TxmlXPathObject(startnode:TxmlNode, endnode:TxmlNode)
ReturnsThe newly created object.
DescriptionCreate a new TxmlXPathObject of type range using 2 nodes.
InformationParameters:
  • startnode : the starting node
  • endnode : the ending node
Function XPointerNewRangePointNode:TxmlXPathObject(startpoint:TxmlXPathObject, endnode:TxmlNode)
ReturnsThe newly created object.
DescriptionCreate a new TxmlXPathObject of type range from a point to a node.
InformationParameters:
  • startpoint : the starting point
  • endnode : the ending node
Function XPointerNewRangePoints:TxmlXPathObject(startpoint:TxmlXPathObject, endpoint:TxmlXPathObject)
ReturnsThe newly created object.
DescriptionCreate a new xmlXPathObjectPtr of type range using 2 Points.
InformationParameters:
  • startpoint : the starting point
  • endpoint : the ending point
Function XPointerWrapLocationSet:TxmlXPathObject(value:TxmlLocationSet)
ReturnsThe newly created object.
DescriptionWrap the LocationSet value in a new TxmlXPathObject.
InformationParameters:
  • value : the LocationSet value

Module Information

Version1.13
LicenseMIT
Copyright(libxml2) 1998-2007 Daniel Veillard
Copyright(wrapper) 2006-2008 Bruce A Henderson
ModserverBRL
History1.13
HistoryFixed getLineNumber() returning wrong type.
HistoryAdded TxmlDoc ToString() and ToStringFormat() methods.
HistorysetContent() now accepts empty string.
HistoryAdded TxmlDoc SetEncoding() and SetStandalone() methods.
History1.12
HistoryImproved error handling/capture.
HistoryFixed xmlGetLastError calling wrong api.
HistoryAdded new xmlSetErrorFunction() function to allow capture of all errors.
HistoryMore error information available via new TxmlError methods().
History1.11
HistoryAdded unlinkNode and freeNode methods to TxmlNode.
History1.10
HistoryUpdated to Libxml 2.6.27.
HistoryFixed Null byte ptr handling on UTF8 conversion.
HistoryFixed several memory issues.
History1.09
HistoryAdded automatic libxml UTF-to-Max and Max-To-UTF String conversion. Fixes non-ascii string issues.
HistoryAdded getLineNumber method to TxmlBase.
History1.08
HistoryExposed some XPathContext properties.
HistoryFixed TxmlBuffer getContent not returning anything.
HistoryAPI change - Renamed TxmlURI URIEscapeStr() to URIEscapeString().
HistoryDocs tidy up.
HistoryMany more examples.
History1.07
HistoryAdded TxmlNode getAttributeList method.
HistoryAdded TxmlAttribute getAttributeType, getNameSpace methods.
HistoryFixed attribute getValue returning nothing.
HistoryAdded TxmlDoc getVersion, getEncoding, isStandalone methods.
HistoryAdded TxmlBase getParent method.
HistorygetFirstChild and getLastChild now accept types.
HistoryAdded more document examples.
History1.06
HistorySplit out extern/const to libxml_base.
HistoryAdded more globals.
HistoryAdded validation API.
HistoryAdded TxmlDtdAttribute, TxmlDtdElement, TxmlNotation, TxmlValidCtxt, TxmlElementContent, TxmlXPathCompExpr.
History1.05
HistoryFixed TxmlNodeSet.getNodeList.
HistoryAPI change - Added TxmlBase (for shared methods). Extended Node, Doc, Dtd, Attribute, Entity from it. Should be backwards compatible.
HistoryImplemented debug-time assertion checking.
HistoryIncbin support added for TxmlDoc and TxmlTextReader.
HistoryAdded more XPath functionality.
HistoryAdded libxml globals.
HistoryAdded Entities API, XInclude API, XPointer API.
HistoryAdded XML catalogs and SGML catalogs API.
HistoryAdded TxmlURI, TxmlCatalog, TxmlEntity, TxmlIncludeCtxt, TxmlLocationSet.
History1.04
HistoryRemoved small memory leak.
HistoryFixed typo - addProcessingInstruction(), and added some missing docs.
HistoryAdded newNode() function for TxmlNode.
History1.03
HistoryAdded TxmlTextReader API.
HistoryRemoved ansidecl.h use for linux - not always present.
History1.02
HistoryRemoved xmlmodule.c
HistoryChanged references of xmllasterror to xmllasterror1 for Mac compile.
HistoryDisabled thread support and made static build - removed lots of warnings.
History1.01
HistoryAdded Linux and Mac support. Still some Mac issues to resolve.
History1.00 Initial Release (Libxml 2.6.23)