libxml2 XML parsing object

Usage:

OBJECT x = CREATE "dynamic", "klibxml"

If an application wishes to use the libxml2 XML parsing object then it should load it once and keep it loaded. Loading it each time it is used is very inefficient.

The writeToString method as implemented in KCML 6.20 has a memory leak. See the notes on the method on how to avoid it.

For further information see http://xmlsoft.org

Root
Parser
Document
Element
Node
XPath
NamedNodeMap
NodeList
MemBufInputSource
Implementation
Comment
CDATASection
ProcessingInstruction
Text
CharacterData
DocumentFragment
EntityReference
Attr
Writer
WriterFilter
MemBufOutput
SAXParser
ContentHandler
Namespaces
Attributes
ScanToken
NodeFilter
NodeIterator
TreeWalker
TextReader
Transformer

Root

XML root object

This software contains code developed by the Gnome XML project (http://xmlsoft.org) (Daniel Veillard et al.) and is licensed under an MIT license.

Method	Returns	Purpose
CreateTransformer()	KXML_TRANSFORM	Creates transformer object	KCML
HasFeature(feature)	BOOL	Return TRUE if a feature was compiled into libxml2
createParser()	Parser	Creates DOM parser object	KCML
createSAXParser()	SAXParser	Creates a SAX2 parser object	KCML
createXMLTextReader()	TextReader	Creates an XmlTextReader object	KCML
getDOMImplementation(name$)	Implementation	Return an Implementation ref from DOM Implementation Registry	KCML

Property	Type	Returns	Purpose
Implementation	R	Implementation	Return an Implementation ref	KCML

Parser

Parser object

Method	Returns	Purpose
MemBufInputSource(buf, buflen, id)	MemBufInputSource	Constructor for a memory buffer input stream
ParseMemory(buf, buflen)	void	Parse from a string	KCML
ProcessXInclude()	integer	Process any XInclude directives in the parsed document, returns the number of substitutions done or -1 for error
parse(URI$)	void	Parse a URI
parseIS(OBJECT stream)	void	Parse from an inputstream	KCML
reset()	void	Reset parser state ready for another parse
resetDocumentPool()	void	Free any documents associated with the parser

Property	Type	Returns	Purpose
CreateEntityReferenceNodes	RW	BOOL	Get/set flag controlling expansion of entities
DoNamespaces	RW	BOOL	Get/set process namespaces flag
DoSchema	RW	BOOL	Get/set Process schemas flag
Document	R	Document	Return document object
ErrorCount	R	int	Get error count from last parse
ExitOnFirstFatalError	RW	BOOL	Get/set Exit On First Fatal Error flag
IncludeIgnorableWhitespace	RW	BOOL	Get/set flag controlling how whitespace is treated (requires DTD)
LoadExternalDTD	RW	BOOL	Get/set flag to control loading of an external DTD. If the DTD is referenced only for consistency checking and is not needed during the parse, say to supply entities, then set this flag to FALSE.
ValidationConstraintFatal	RW	BOOL	Get/set Validation Constraint Fatal flag
ValidationScheme	RW	ValScheme	Get/set validation scheme

Document

DOM Document object

Extends Node

Method	Returns	Purpose
ProcessXInclude()	integer	Process any XInclude directives in the document, returns the number of substitutions done or -1 for error
createAttribute(name$)	Attr	Create a new attribute node with given name
createAttributeNS(pszURI$, pszQName$)	Attr	Create a new attribute node with given qualified name
createCDATASection(data$)	CDATASection	Create a new CDATA node for given data
createComment(text$)	Comment	Create a new Comment node for given text
createDocumentFragment()	DocumentFragment	Create an empty DocumentFragment object
createElement(tagname$)	Element	Create a new Element node
createElementNS(pszURI$, pszQName$)	Element	Create a new Element node
createEntityReference(pszName$)	EntityReference	Create a new Entity reference node
createNodeFilter()	NodeFilter	Create a node filter object	KCML
createNodeIterator(OBJECT root, nWhatToShow, OBJECT filter, bExpandEntities)	NodeIterator	Create a flat tree NodeIterator
createProcessingInstruction(target$, data$)	ProcessingInstruction	Create a new Processing Instruction node
createTextNode(data$)	Element	Create a new Text node
createTreeWalker(OBJECT root, nWhatToShow, OBJECT filter, bExpandEntities)	TreeWalker	Create a flat tree DOM walker
createWriterFilter()	WriterFilter	Create a serialization WriterFilter object	KCML
createXPath()	XPath	Create an XPath object
getElementById(id$)	Node	Return element matching an ID
getElementsByTagName(pattern$)	NodeList	Make node list of elements matching a tag name or '*'.
getElementsByTagNameNS(NsURI$, localname$)	NodeList	Get a node list of elements matching by NS URI and local name
importNode(OBJECT importnode, deep)	Node	Import a node from another document
normalizeDocument()	void	Normalize a document as if it had been saved and loaded again

Property	Type	Returns	Purpose
ActualEncoding$	RW	string	Get/set actual encoding of document
Doctype	R	DocumentType	Returns the document type declaration
DocumentElement	R	Element	Returns the documents root element
DocumentURI$	RW	string	Get/set document location, NULL if undefined
Encoding$	RW	string	Get/set document encoding
Implementation	R	Implementation	Returns the implementation object that handles the doc
Standalone	RW	BOOL	Get/set standalone
StrictErrorChecking	RW	BOOL	Get/set error checking on node operations
Version$	RW	string	Get/set document version string

Element

DOM Element object

Extends Node

Method	Returns	Purpose
getAttribute$(name$)	string	Get attribute of element by name
getAttributeNS$(NsURI$, localname$)	string	Get attribute of element by name
getAttributeNode(name$)	Attr	Get a Attr node object by name
getAttributeNodeNS(NsURI$, localname$)	Attr	Get a Attr node object by name
getElementsByTagName(pattern$)	NodeList	Make node list of elements under this element matching a tag name or '*'.
getElementsByTagNameNS(NsURI$, localname$)	NodeList	Get a node list of elements under this element matching by NS URI and local name
removeAttribute(name$)	void	Remove attribute of element by name
removeAttributeNS(NsURI$, localname$)	void	Remove attribute of element by name
removeAttributeNode(OBJECT name)	Attr	Remove specified Attr node
setAttribute(name$, value$)	void	Set attribute of element by name
setAttributeNS(NsURI$, qualname$, value$)	void	Set attribute of element by name
setAttributeNode(OBJECT newattr)	Attr	Adds or replaces an Attr node
setAttributeNodeNS(OBJECT newattr)	Attr	Adds or replaces an Attr node

Property	Type	Returns	Purpose
TagName$	R	string	Return name of the element

Node

DOM Node object

Downcastable from the following interfaces:

Text
Element
CharacterData
Document
Attr

Method	Returns	Purpose
appendChild(OBJECT newChild)	Node	Add child to list of children
cloneNode(deep)	Node	Clone this node
hasChildNodes()	BOOL	Return true if node has children
insertBefore(OBJECT newChild, OBJECT refChild)	Node	Insert node before existing child node
normalize()	void	Normalize children
release()	void	Free resources	Xerces
removeChild(OBJECT oldChild)	Node	Delete child oldchild from the list of children and return it
replaceChild(OBJECT newChild, OBJECT oldChild)	Node	Replace existing child with newchild and return oldChild

Property	Type	Returns	Purpose
Attributes	R	NamedNodeMap	Return a NamedNodeMap of the attributes of the node or NULL
ChildNodes	R	NodeList	Return all children in a nodelist
FirstChild	R	Node	Return first child of a node
LastChild	R	Node	Return last child of a node
LocalName$	R	string	Return local part of the qualified name of this node
NamespaceURI$	R	string	Return namespace URI for node tag
NextSibling	R	Node	Return next sibling of a node
NodeName$	R	string	Return name of a node (with NS prefix if applicable)
NodeType	R	int	Return type of a node
NodeValue$	R	string	Return value of a node, depending on type
OwnerDocument	R	Document	Get the document associated with this node
ParentNode	R	Node	Return parent of a node
Prefix$	RW	string	Get/set namespace prefix of this node
PreviousSibling	R	Node	Return previous sibling of a node

XPath

XPath object

Method	Returns	Purpose
RegisterNS(pszPrefix$, pszURI$)	void	Register the NS URI that goes with a prefix used in the expression. You can use a blank URI for the default namespace.
SetCurrentNode(node)	void	Set the current node for relative XPath expressions
evaluate(expr$)	NodeList	Evaluate an XPath expression returning a list of nodes

Property	Type	Returns	Purpose
CurrentNode	R	Node	The current node for relative XPath expressions

NamedNodeMap

DOM Named Node Map object used for attributes

This collection can be iterated with FOR OBJECT ... NEXT OBJECT

Method	Returns	Purpose
getNamedItem(name$)	Node	Return node with given name
item(index)	Node	Return node with given index (zero based)

Property	Type	Returns	Purpose
Length	R	unsigned int	Return count of nodes in the map

NodeList

DOM Node List object

This collection can be iterated with FOR OBJECT ... NEXT OBJECT

Method	Returns	Purpose
item(index)	Node	Return node with given index (zero based)

Property	Type	Returns	Purpose
Length	R	int	Return count of nodes in a node list

MemBufInputSource

Memory buffer based input stream object

Implementation

DOM Implementation object

Method	Returns	Purpose
createDOMWriter()	Writer	Create a Writer serializing object	DOM3
createDocument(NamespaceURI$, qualifiedName$, OBJECT doctype)	Document	Creates a new XML Document object
createDocument()	Document	Creates a nameless XML document object
createDocumentType(qualifiedName$, publicId$, systemId$)	DocumentType	Creates a new XML DocumentType node i.e. a DTD ref
hasFeature(feature$, version$)	BOOL	returns TRUE if a feature is supported

Property	Type	Returns	Purpose
Implementation	R	Implementation	Return a Implementation ref for this object

Comment

DOM Comment object

Extends CharacterData

CDATASection

DOM CDATA object

Extends Text

ProcessingInstruction

DOM ProcessingInstruction object

Extends Node

Property	Type	Returns	Purpose
Data$	R	string	Get/set data of the element
Target$	R	string	Return target of the element

Text

DOM Text object

Extends Node

Method	Returns	Purpose
isIgnorableWhitespace()	BOOL	Returns TRUE if node contains only ignorable whitespace (requires a DTD)
isWhitespace()	BOOL	Returns TRUE if node is empty or contains only whitespace	KCML

CharacterData

DOM Character object

Extends Node

DocumentFragment

DOM DocumentFragment object

Extends Node

EntityReference

DOM EntityReference object

Extends Node

Attr

DOM Attribute object

Extends Node

Property	Type	Returns	Purpose
Name$	R	string	Return name of the attribute
OwnerElement	R	Element	Return Element node the attribute is attached to or NULL if none
Specified	R	BOOL	Return TRUE if the attribute was explicitly specified rather than assumed from the DTD default
Value$	RW	string	Get/set value of the attribute

Writer

Used to serialize a document

Method	Returns	Purpose
canSetFeature(feature$, value)	bool	Indicates whether setting a feature to a particular value will be supported	DOM3
getFeature(feature$)	bool	Get the value of a standardized feature	DOM3
setFeature(feature$, value)	void	Set the value of a standardized feature	DOM3
setFilter(OBJECT filter)	void	Apply a WriterFilter object to filter the serialized output	DOM3
writeDocToFile(OBJECT doc, file$)	integer	Serialize a UTF-8 encoded document to a file. Returns number of bytes written or -1 for an error.	KCML
writeDocToString(OBJECT doc)	MemBufOutput	Serialize a UTF-8 encoded document to a string object	KCML
writeToString(OBJECT node)	MemBufOutput	Serialize a node to a string object	DOM3

Property	Type	Returns	Purpose
Encoding$	RW	string	Get/Set encoding to use when serializing. NULL means UTF-8.	DOM3
NewLine$	RW	string	Get/Set end-of-line sequence to use when serializing. Only HEX(0A), HEX(0D) and HEX(0D0A) are acceptable. NULL means OS default.	DOM3

WriterFilter

Object that receives filter callbacks during serialization

The acceptNode() callback function returns the same enumeration as the NodeFilter callbacks namely
DIM _FILTER_ACCEPT=1, _FILTER_REJECT=2, _FILTER_SKIP=3

Method	Returns	Purpose
SetFilter(fn)	void	Set KCML callback for filtering a node

Callback	Returns	Purpose
acceptNode(node)	integer

Property	Type	Returns	Purpose
WhatToShow	RW	integer	Get/Set types of nodes to be serialized

MemBufOutput

String object

Property	Type	Returns	Purpose
Text$	R	string	Return UTF-8 text	KCML

SAXParser

SAX2 Parser object

Method	Returns	Purpose
ContentHandler()	ContentHandler	Constructor for a SAX2 ContentHandler object	KCML
createScanToken()	ScanToken	Allocate a ScanToken for use in a progressive parse	KCML
parse(URI$)	void	Parse a URI
parseFirst(URI$, OBJECT token)	BOOL	Start a progressive parse of a URI
parseFirstIS(OBJECT stream, OBJECT token)	BOOL	Start a progressive parse of an InputStream
parseIS(OBJECT stream)	void	Parse from an InputStream
parseNext(OBJECT token)	BOOL	Continue a progressive parse
parseReset(OBJECT token)	void	Reset the parser after a progressive parse
setContentHandler(OBJECT handler)	void	Specify the SAX2 ContentHandler

Property	Type	Returns	Purpose
ErrorCount	R	int	Get error count from last parse
ExitOnFirstFatalError	RW	BOOL	Get/set Exit On First Fatal Error flag
ValidationConstraintFatal	RW	BOOL	Get/set Validation Constraint Fatal flag

ContentHandler

Object that receives callbacks from SAX2 events

Method	Returns	Purpose
SetCharacters(fn)	void	Set KCML handler subroutine for characters
SetEndDocument(fn)	void	Set KCML handler subroutine for end of document
SetEndElement(fn)	void	Set KCML handler subroutine for end of element
SetIgnorableWhitespace(fn)	void	Set KCML handler subroutine for DTD defined ignorable whitespace
SetResetDocument(fn)	void	Set KCML handler subroutine for restart of document
SetStartDocument(fn)	void	Set KCML handler subroutine for start of document
SetStartElement(fn)	void	Set KCML handler subroutine for start of element

Callback	Returns	Purpose
characters(text$, length)	void	Receive notification of text. Note that the length is the number of bytes in the UTF-8 string. This handler may be called more than once for a text string which contains entities.
endDocument()	void	Receive notification of end of document
endElement(URI$, localname$, qname$)	void	Receive notification of end of every element
ignorableWhitespace(text$, length)	void	Receive notification of DTD defined ignorable whitespace
startDocument()	void	Receive notification of start of document
startElement(uri$, localname$, qname$, atts)	void	Receive notification of start of every element, uri$ is the combination of the NS and the tag as a URI, localname$ is the bare tag name, qname$ is the tag with its prefix,attributes is an object containing any attributes for the tag

Property	Type	Returns	Purpose
ObjDef	R	const DYN_DEF *

Namespaces

Namespaces collection returned by SAX2 with an element node

Property	Type	Returns	Purpose
ObjDef	R	const DYN_DEF *

Attributes

Attributes collection returned by SAX2 with an element node

Method	Returns	Purpose
LocalName$(index)	string	Returns the local name of an attribute in the list by index (0 based)
QName$(index)	string	Returns the qualified name of an attribute in the list by index (0 based)
URI$(index)	string	Returns the namespace URI of an attribute in the list by index (0 based)
Value$(index)	string	Returns the value of an attribute in the list by position
Value$(qname$)	string	Returns the value of an attribute in the list by qualified name
Index(qname$)	integer	Returns the index of an attribute in the list by qualified name
Index(uri$, localpart$)	integer	Returns the index of an attribute in the list by namespace name

Property	Type	Returns	Purpose
DefaultedAttributes	R	int	Returns the number of attributes for the element defaulted by the DTD
Length	R	int	Returns the number of attributes for the element
ObjDef	R	const DYN_DEF *

ScanToken

Scan state token for progressive parsing

NodeFilter

Object that receives filter callbacks from NodeIterator and TreeWalker

The acceptNode() callback function returns one of the following enumeration
DIM _FILTER_ACCEPT=1, _FILTER_REJECT=2, _FILTER_SKIP=3

Method	Returns	Purpose
SetFilter(fn)	void	Set KCML callback for filtering a node

Callback	Returns	Purpose
acceptNode(node)	integer

NodeIterator

DOM NodeIterator object

Method	Returns	Purpose
nextNode()	Node	Return next node in list
previousNode()	Node	Return previous node in list

Property	Type	Returns	Purpose
ExpandEntityReferences	R	BOOL	Return original ExpandEntityReferences flag
Root	R	Node	Original root node specified when list was created
WhatToShow	R	integer	Return bitmap of node types included

TreeWalker

DOM TreeWalker object

Method	Returns	Purpose
firstChild()	Node	Moves to first child and returns the node
getCurrentNode()	Node	Get node at which the NodeWalker is positioned
lastChild()	Node	Moves to last child and returns the node
nextNode()	Node	Moves to and returns next node in list
nextSibling()	Node	Moves to next sibling and returns the node
parentNode()	Node	Moves to and returns the closest visible ancestor node of the current node in list
previousNode()	Node	Moves to and returns previous node in list
previousSibling()	Node	Moves to previous sibling and returns the node
setCurrentNode(OBJECT node)	void	Set node at which the NodeWalker is positioned

Property	Type	Returns	Purpose
ExpandEntityReferences	R	BOOL	Return original ExpandEntityReferences flag
Root	R	Node	Original root node specified when list was created
WhatToShow	R	integer	Return bitmap of node types included

TextReader

TextReader object for progressive parsing

Method	Returns	Purpose
Expand()	Node	Expand the DOM tree below the current node and return that node
GetAttributeByName$(name$)	string	Get attribute using qualified name
GetAttributeByNameNS$(localname$, URI$)	string	Get attribute using name and namespace
GetAttributeByindex$(index)	string	Get attribute using a zero based index
ParseFile(File$)	void	Parse document from a file or URI
PreserveNode()	Node	Preserve the current node in the document
PreservePattern(Pattern$)	int	Preserve the nodes matching the XPath pattern
Read()	int	Read the next node in the document
Skip()	int	Skip to the next peer node in the document avoiding any subtree

Property	Type	Returns	Purpose
AttributeCount	R	int	Get the number of attributes for a node
CurrentDoc	R	Document	Keep document being parsed in this object
CurrentNode	R	Node	return the temporary node being parsed in this object
DefaultAttributes	RW	BOOL	Get/set flag controlling defaulting of attributes using a DTD
Depth	R	int	Get the tree depth of a node
Encoding$	R	string	Get/set document encoding
ErrorCount	R	int	Get error count from last parse
ExpandEntityReferenceNodes	RW	BOOL	Get/set flag controlling expansion of entities using a DTD
HasAttributes	R	BOOL	True iff the node has attributes
HasValue	R	BOOL	True iff the node can have a text value
IncludeIgnorableWhitespace	RW	BOOL	Get/set flag controlling how whitespace is treated (requires DTD)
IsValid	R	BOOL	Is the parsing context valid
LastErr$	R	string	Get last error message
LoadExternalDTD	RW	BOOL	Get/set flag to control loading of an external DTD. If the DTD is referenced only for consistency checking and is not needed during the parse, say to supply entities, then set this flag to FALSE.
NodeLocalName$	R	string	Return local name of a node
NodeName$	R	string	Return name of a node (with NS prefix if applicable)
NodeNamespaceURI$	R	string	Return the namespace URI of a node
NodePrefix$	R	string	Return prefix of a node
NodeType	R	int	Get the DOM node type of a node
NodeValue$	R	string	Get the text value of a node, if applicable
ParserColumNumber	R	int	Get the column number of the current parsing point
ParserLineNumber	R	int	Get the line number of the current parsing point
Validate	RW	BOOL	Get/set flag controlling validation against a DTD

Transformer

XSL tranformer object

Method	Returns	Purpose
AddParameter(name$, value$)	void	Add a parameter	KCML
AddStringParameter(name$, value$)	void	Add a string parameter that will be quoted	KCML
ClearParameters()	void	Drop all parameters	KCML
TransformFile(src$, xsl$, dst$)	integer	Transform using files	KCML
TransformFile(src$, dst$)	integer	Transform using files and an embedded stylesheet	KCML

Property	Type	Returns	Purpose
LastError$	R	string	Return text of last error