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.