The Scriptol Programming Language
Integrated Xml in Scriptol to C++
(c) 2001-2005 by D.G. Sureau
www.scriptol.com


This document describes the dom class used by Scriptol C++
To use it, just include the "libdom.sol" file into the source.
To load Xml documents from file, use additional libraries, as in SaxDemo.sol and LXDemo.sol examples.


Integrated XML
 Light Xml
 Include
 Header
 Doctype
 Element
 Dom
 Path
 Reading and writing
 Iterator
 Inserting and removing elements
 Html
 Limitations

Integrated XML


 Scriptol is the first language to use Xml as data structure.
 Xml is written into scriptol source in a light syntax, without angle-brackets.
 This manual is for Scriptol C++ only.

Light Xml


 The syntax of a xml structure is:
 xml [name]       ... optionally a name for the document.
  [xul]           ... optionally the xul modifier.
  [headers]       ... optional header elements.
  [doctype]       ... optional doctype element.
  [include]       ... optionally one or several include statement.
  tag             ... one or several tags.
 /xml


Include


 The include directive currently allow to include another xul document.
 Syntax:
 include href = "other-xul-document-location"


Header


 Syntax:
 <? identifier and attributes ?>


Doctype


 Syntax:
 <! identifiers and attributes >
 Note that the ending is > and not !>


Element


 A tag has the form:
 tagname [attribute [[,] attribute]* ]     ... optional a list of attributes.
   [tagname2]*               ... none, one or several sub-elements.
   text                      ... or a text
   ...
 /tagname                    ... the tag name is optional

If the list of attributes is continued on the next line, a comma must end the
current line at least.


Dom


 To use the xml document, an instance of dom must be created. The dom tree
is then filled by the build() method:
dom mydom
mydom.build()
 The complete list of dom's methods is given in the tutorial on CD, the main
ones are described in this chapter.
 To display the document, use the display() method.
 To save it, use the save() methods, with the filename as argument.
 In both cases, the dom.LIGHT argument allows to output it light.


Path


 Once the dom tree created, you can access the data and the attributes of tags
with dom's methods.
 But scriptol has a special syntax to point out an element inside the document.
 Tags and embedded tags are processed as objects and sub-objects:
 The syntax is:
 instance [.tagname]* [ attribute-name : value]? [.method-name(arguments)]?

- the name of the instance of dom,
- a dot followed by the name of the tag,
- this for each sub-tag,
- a couple attribute : value between square brackets if we want to select
  a tag among several ones with same name,
- a dot followed by a method and its arguments.

 If we want just point out an element, the at() method is used.
 But we can add any dom's method to the path of an element.
 See at demoxml.sol for an example.


Reading and writing


  You can read and change values of the attributes and the data.
- getValue(attribute-name)  returns the value of the attribute as argument.
- setValue(attribute-name, value) assigns a value to an attribute.
- getData() returns the data.
- setData(text) change or assign the text given as parameter.
  The data can be also assigned directly:
  Ex:   mydom.sometag.subtag.setData("some text")
  or:   mydom.sometag.subtag = "some text"


Iterator


 The dom class can also use the document as a xmlpull processor.
 Several methods allows to browse a dom tree.
- begin() points out the first element of the document.
- next() moves to the next element at same level (inside the same element).
- up() moves to the successor of the containing element.
- down() points out the child of the current element, if one.
- found() return true if a next or child element exists, false otherwise.
 Once an element pointed out, the previous methods are used to access the
data.


Inserting and removing elements


 You can insert elements either as child or as successor to a pointed out
element, or remove a pointed out element.
 Syntax:
 instancename.path.addNext(xnode)
 instancename.path.addChild(xnode)
 instancename.path.remove()

 To insert an element, you have to declare it into another xml document,
and get it with the getNode() method.
 You can move an element by inserting at a new location and removing it
then.



Html


 A html page has this format:
 xml
   html
     ...content...
   /html
 /xml


Limitations


 The integration of Xml into Scriptol (the first programming language to do
that) is in early stage of development and has limitations...
 Lot of improvements will come in the next version (4.2) of solc.
- loading a xml document at runtime. For now, you can only use lighter to
  remove brackets and include the file into the Scriptol source.
- multiple script files.
- events management, as in Sax.