Dom: instances of XML document
Once an XML document is described as a set of data, or an object, or
an analyzed text or elsething, a dom instance must be created to access
the document.
Dom means for "Document Object Model", and is a standard defined
by the world wide consortium web, (W3C).
However the dom class implemented into goes beyond the API defined by
the W3C, while it is a lot simpler to use.
Why to use dom?
Scriptol allows to use paths toward elements, as described further.
These path are linked to the name of the dom instance rather than the
document itself.
But why accessing element from within dom and not directly?
Example, with this document:
XML name = x
car
passengers
/passengers
/car
/XML
dom d = dom("x")
Whay to use: d.car.passengers
rather than : x.car.passengers
By using the dom class, we can:
- create multiple instances of an XML document, and modify the content
and structure of the document.
- use various dom function against the document.
Creating an instance
Syntax:
dom instancename
instancename.build()
or
dom instancename = dom("XMLname")
- instancename is the name of the object you create.
- XMLname is the name of the XML document defined into the source.
To use the dom class, the libdom.sol file must be included.
The include instruction is used:
include "libXML.sol"
At start, the instance provides an empty tree. This must be following
by a call to build() to assign an XML document either from the source
or a file. You can also create a tree from scratch thank to the addChild()
and addNext() methods.
About path
Here is a small XML document:
include
"libdom.sol" XML car driver name = "Hill" / passenger name = "wife" / passenger name = "children" age="13" / /car XML dom thedom = dom() print thedom.car.driver |
To access the driver element, the path is:
thedom.car.driver
That's actually a simplified form. The complete dom method to access
an element is:
at("element-name").
at("element-name") car be replaced by element-name, thus:
thedom.at("car").at("driver") is equivalent to:
thedom.car.driver
Persistency
When a path is accessed, the element pointer is remaining on the position
of this element.
If we want only point out an element whitout to perform any operation,
the at() method, without argument is used.
thedom.car.driver.at()
...is equivalent to:
thedom.car.at("driver")
Selecting an element
An XML element may be selected without by name and value of its attributes.
If the path of the element is not specified, the search start at the
current location.
The syntax is:
instancename [path] [ attribute-name : attribut-value ]
- name of the l'instance,
- an optional path (or the current location),
- a pair attribute and value between square braces and separated by
a colon.
Example:
XML car driver name = "Hill" / passenger name = "wife" "Lucida" /passenger passenger name = "children" / /car XML dom thedom = dom() print thedom.car.passenger["name" : "wife" ].getData() |
Reading the content of an element
The getData() method returns the content of an element, pointed out
or at the specified path.
In the example above, the statement, holding the path of the element,
returns "Lucida".
If the element is already pointed out, the getData() method may be associated
to the instance ddirectly, without path.
Exemple:
thedom.car.passenger["name" : "wife" ].at() print thedom.getData() |
The first statement points ou an element, the second one read its content.
Assigning a content to an element
The setData(text) assigns or changes the content of a pointed out
element .
If we want to assign "Christine" to the element, we write:
thedom.car.passenger["name : "wife" ].setData("Christine") |
We can write directly:
thedom.car.passenger["name" : "wife" ] = "Christine" |
reading the value of an attribute
An attribute is accessed with the path of the element, and the getValue
method return the value.
print thedom.car.passenger["name":"children"].getValue("age") |
> 13 |
The pair [attribute : value] designates precisely the element, et the
value of the "age" attribute is returned.
Changing the value of an attribute
The setValue() method, with the name and the new value of the attribute
is used.
If the attribute doesn't exist, it is created with the given name and
value.
Iterator: walking through a document
The iterator is a set of methods to scan an XML document.
- An element may be pointed out with the at() method.
- The reset() method set the pointer at start of the document;
- The begin() method set the pointer at start of the level.
- The next() method points out the next element, at the same level (inside
the current element).
- up() moves to the follower of the current container element.
- down() points out the first sub-element inside the current element.
- found() returns false when no more element is found.
Conclusion
All that is necessary to use an XML document as a class is defined
above. It may be use as a simplifed database. Just a small part of what
integrating XML into code may offers!
Exercises |
1) Here is a tiny french-english dictionary. |