|
xmlreader
o=new("xmlreader"[,filename$|content$])
The xmlreader class provides XML parsing capabilities to rule set code blocks. XML is a common file format for transmitting data between applications. It is a tag-based data format, where tags are used to identify data elements, as well as data attributes. Data is arranged in hierarchical fashion, where content contains other content, such as a report, which contains customers, which contain invoices, which contain shipping and order details, and so on.
The xmlreader navigates through this hierarchy using slash delimiters, similar to a file system directory, return data for a particular tag sequence. The data may be atomic data, a complete element, an element attribute, or it may be addition XML fragments that can be further parsed. For example, if the root element is "documents", and it contains a number of "document" elements, each of which contains an "invno" tag, you can navigate to an invoice number as "/documents/document/invno". If there are multiple occurrences of a particular element, you can get a count, and retrieve a particular element using a sequence number.
Elements with sequences can be referenced using a sequence number in many methods (referring to the last element tag), or can be referenced with [n] suffixes anywhere in the path chain. For example, "/documents/document[2]/invno" refers to the second document element's invno tag.
Element references can also be designed to match attributes or values, using one of two syntaxes:
For example, "/documents/document[OrderID=12345]/Address[<Type>=ShipTo]/City" would locate the document with an attribute "OrderID" of "12345", then find the Address element of that document with a tag <Type> whose value was "ShipTo", then locate the Address element's City tag.
If a valid filename$ value is supplied, the file is loaded when the object is first instantiated. Alternatively, the argument can be an XML document string (if the value doesn't exist as a file, it is assumed to be XML content). At any time, a new file can be loaded or the XML content provided directly as a string.
Properties
body$ contains the non-header portion of the file, with any comments removed.
|
content$ is the string representation of the XML data. When a file is loaded, content$ is filled with its data.
|
encoding$ contains the character encoding of the file. The default encoding is utf-8, which is a compressed version of unicode, but files may be encoded using other character sets, such as unicode or iso8859-1. Since UnForm's normal character set is iso8859-1 (or the 9J symbol set), it is often necessary to specify a target encoding when retrieving values for UnForm printing.
|
filename$ is the name of the most recently loaded file.
|
header$ contains the header portion of the file, similar to "<?xml version="1.0"?>".
|
root$ contains the name of the root element. All XML documents have a root element that is the parent of all other elements.
|
version$ contains the XML version number from the header.
|
Methods
getattr$(element$[,sequence],attrname$) returns the attribute value of the specified element. If a sequence is provided, the specified occurrence of the element is used.
|
getattrs$(element$[,sequence]) returns a list of element attributes, which are name-value pairs. Each pair is delimited by a linefeed ($0A$), and the name and value are delimited by a tab ($09$). If a sequence is provided, the specified occurrence of the element is used.
|
getchild$(element$[,sequence],child) returns a specified child element (which may itself contain nested child elements). If the sequence is provided, then it applies to the selection of the parent element, not the child element. The child argument is used to determine which child element to return. getchild$("/documents/document",5,1) returns the 1st child element of the 5th documents/document element.
|
getchildname$(element$[,sequence],child) returns a specified child element name. If the sequence is provided, then it applies to the selection of the parent element, not the child element. The child argument is used to determine which child element to return. getchild$("/documents/document",5,1) returns the 1st child element of the 5th documents/document element.
Note this method was added in 9.0.21 to assist with updates due to a former bug in the getchild$() method, which was returning a name, rather than the correct, and documented, full element. If you relied on getchild$() to return just a name, use getchildname$() instead.
|
getchildren$(element$[,sequence]) returns a linefeed ($0A$) delimited list of element names that are children of the element provided. If there are no children, then null is returned, and the value of the element is an atomic data value. If a sequence is provided, the specified occurrence of the element is used.
|
getchildren(element$[,sequence]) returns the number of child elements that are found under the element. If a sequence is provided, the specified occurrence of the element is used. The sequence applies to the element, not the children. getchildren("/documents/document",5) returns the number of child elements found under the 5th document element under the documents root element.
|
getcount(element$) returns the number of times a given element occurs. This can be used to determine how many sequences of a particular element are available.
|
getelement$(element$[,sequence]) returns element and enclosed content specified by element$. If a sequence is provided, the specified occurrence of the element is used.
|
getns$(element$[,sequence],uri$) scans the attributes of an element for an XML namespace declaration that matches the uri$ provided. It returns the namespace name, which can then be used to access elements that require a namespace prefix that associates a name with a URI.
|
getvalue$(element$[,sequence[,toencoding$]]) returns the inner value of the specified element. If the element holds atomic data, the result is a string data value. Note that an element may contain sub-elements. If a sequence is provided, the specified occurrence of the element is used. If toencoding$ is provided, then the value is translated from the XML document's encoding to the specified encoding. A common toencoding$ value might be "iso8859-1" or "9j" to translate UnForm's default 8-bit text encoding.
|
loadfile(filename$) sets the XML content by reading filename$
|
parseattribute$(element$,name$) returns the entity-decoded value of the named attribute from the element string. If the attribute doesn't exist, null is returned.
|
parseelement(element$,tag$,value$,attributes$) parses the element string into components and fills the tag$, value$, and attributes$ values with the element's tag name, value, and attribute string, which is a linefeed-delimited list of tab-delimited name-value pairs as found in the element's main tag. The attribute values are entity-decoded.
The value string can by empty, a text value, or a child element. Returns 1 on success, 0 on failure. The value is not entity-decoded, to retain child element encoding.
|
setcontent(content$) sets the XML content to content$.
|
|