DTD Support

DTD is a format to describe the structure of XML files. This module not only supports the description of XML but provides also a parser based on this description. More...

Classes
class	Exception
class	Parser
class	Factory
class	AbstractAttribute
class	Content
class	Optional
class	Alt
class	Seq
class	Repeat
class	PCDATA
class	IDAttribute
class	RefAttribute< T >
class	Attribute< T >

Functions
Content &	operator* (Content &c)
Content &	operator! (Content &c)
Content &	operator+ (Content &c1, Content &c2)
Content &	operator| (Content &c1, Content &c2)
Content &	operator, (Content &c1, Content &c2)
Content &	operator& (Content &c1, Content &c2)

Variables
Content &	EMPTY = _empty
Content &	ignored = _ignored
Content &	PCDATA = pcdata
Content &	ANY = any
const t::uint32	STRICT = AbstractAttribute::STRICT
const t::uint32	REQUIRED = AbstractAttribute::REQUIRED
const t::uint32	FORWARD = AbstractAttribute::FORWARD
const t::uint32	CROP = Parser::CROP

Detailed Description

DTD is a format to describe the structure of XML files. This module not only supports the description of XML but provides also a parser based on this description.

Basically, the DTD is made of two types of descriptions:

• The description of XML elements by their name, their attributes and their content.
• The description of the element attributes based on their name, their default value if any and some flags like REQUIRED (for required attributes).

The content of the elements may be made of simple text or other elements. This content can be described like regular expressions, that is as sequences, alternative, repetitions or optional elements.

Usage

Let the DTD below:

<!ELEMENT training (name,session*)>
<!ATTLIST training
        id    REQUIRED CDATA
        start CDATA
        end   CDATA>
<!ELEMENT name (#PCDATA)>
<!ELEMENT session (EMPTY)>
<!ATTLIST date REQUIRED CDATA>

The equivalent with the DTD module is:

#include <elm/xom/dtd.h>
using namespace dtd;
 
Element name("name", PCDATA);
Element session("session", EMPTY);
Att
        date<CDATA>(session, "start", "", REQUIRED);
Element training("name", (name, *session));
Att
        id<CDATA>(session, "start", "", REQUIRED),
        start<CDATA>(session, "start"),
        end<CDATA>(session, "end");

Then to parse XOM document, one has only to write:

xom::Document *doc = ...;
try {
    MyFactory factory;
training.parse(factory, doc);
use(factory.training);
}
catch(dtd::Exception& e) {
    cerr << "ERROR: " << e.message() << io::endl;
}

This last example shows the use of another structure named a Factory. A factory is an interface by the user of dtd module to react to the element found in the XML document and to let the application to build a data structure corresponding to the parsed document.

Continuing the example, the factory could be:

class TrainingFactory: public dtd::Factory {
public:
    void begin(dtd::Element& e) {
    if(e == training)
        training = new Training(*id, *start, *end);
        else if(e == name)
        training->setName(*PCDATA);
        else if(e == session) {
            cur = new Session(*date);
            training.add(cur);
        }
    }
 
    void getPCDATA(dtd::Element& e, xom::String s) {
        if(e == name)
            training->setName(s);
    }
 
    Training *training;
};

As shown in the example above, the function begin() called each time an element is found. Thanks to the element parameter, the corresponding action can be undertaken: build a Training object, recording the name or build a session object.

One can also observe that attributes and PCDATA records the actual value they get at the begin() function call time and this value can be accessed using the "*" operator.

Reference

Base classes encompass:

• otawa::dtd::Content - to describe a the content of an element.
• otawa::dtd::Element - to describe an element (that is also a dtd::Content).
• otawa::dtd::Att - to describe an attribute.

dtd module provides also support for identifiers and references with the classes:

• otawa::dtd::IDAtt - attribute representing an identifier.
• otawa::dtd::RefAtt<T> - attribute representing a reference.

To support identifiers, the factory must be able to return a pointer to an object that supports an identifier (function Factory::getRef()). In turn, a reference attribute will store this object pointer when the referenced identifier is resolved.

otawa::dtd::RefAtt<T> supports also forward references (when the flag FORWARD is set). In this case, if the reference cannot be resolved, it will store a memo with an application object to patch obtained by a call to Factory::getPatchRef(). Then when the identifier will be resolved, the parser will automatically call Factory::patch() for each forward reference with the patch object as parameter to let the application to perform the fix.

The content of an element may be made of:

• a otawa::dtd::Element itself (causing call to Factory::begin()),
• otawa::dtd::PCDATA to accept free text (causing call to Factory::getPCDATA()),
• otawa::dtd::ANY to accept anything (causing call to Factory::getAny()),
• otawa::dtd::Seq to accept a sequence of two contents,
• otawa::dtd::Alt to accept an alternative between two contents,
• otawa::dtd::Repeat to accept zero or more occurrences of a content,
• otawa::dtd::Opt to accept zero or one occurrence of a content.

A simpler way to use Seq, Alt and Repeat contents is to use the corresponding operators:

• ',' or '&' for a sequence
• '|' or '+' for an alternative,
• '*' (prefixed) for a repeat,
• '!' (prefixed) for an optional content.

Function Documentation

operator!()

Content & operator!

(

Content &

c

)

#include <include/elm/xom/dtd.h>

Build an optional content.

Parameters

c	Optional content.

References elm::dtd::_gc, and GC::add().

operator&()

Content & operator&	(	Content &	c1,
		Content &	c2
	)

#include <include/elm/xom/dtd.h>

Build a sequence content.

Parameters

c1	First content in the sequence.
c2	Second content in the sequence.

References elm::dtd::_gc, and GC::add().

operator*()

Content & operator*

(

Content &

c

)

#include <include/elm/xom/dtd.h>

Build a repeated content.

Parameters

c	Repeated content.

References elm::dtd::_gc, and GC::add().

operator+()

Content & operator+	(	Content &	c1,
		Content &	c2
	)

#include <include/elm/xom/dtd.h>

Build an alternate content.

Parameters

c1	First alternative.
c2	Second alternative.

References elm::dtd::_gc, and GC::add().

operator,()

Content & operator,	(	Content &	c1,
		Content &	c2
	)

#include <include/elm/xom/dtd.h>

Build a sequence content.

Warning

This operator has the smallest precedence level and it can be confused with the comma separating argument of a function call.

Parameters

c1	First content in the sequence.
c2	Second content in the sequence.

References elm::dtd::_gc, and GC::add().

operator|()

Content & operator|	(	Content &	c1,
		Content &	c2
	)

#include <include/elm/xom/dtd.h>

Build an alternate content.

Parameters

c1	First alternative.
c2	Second alternative.

References elm::dtd::_gc, and GC::add().

Variable Documentation

ANY

Content & ANY = any

#include <include/elm/xom/dtd.h>

Content supporting a sequence of both text and elements.

CROP

const t::uint32 CROP = Parser::CROP

#include <include/elm/xom/dtd.h>

Parser attribute indicating that the blank nodes (text made of spaces) can be ignored.

Referenced by Parser::doesCrop().

EMPTY

Content & EMPTY = _empty

#include <include/elm/xom/dtd.h>

Content ensuring that the content of an XML element is empty.

FORWARD

const t::uint32 FORWARD = AbstractAttribute::FORWARD

#include <include/elm/xom/dtd.h>

Attribute flag marking a reference attribute to enable support for forward references.

Referenced by AbstractAttribute::isForward().

ignored

Content & ignored = _ignored

#include <include/elm/xom/dtd.h>

Content ignoring what is exactly in the content: always answer the parsing succeeds.

PCDATA

Content & PCDATA = pcdata

#include <include/elm/xom/dtd.h>

Content representing a CDATA.

See also

PCDATAContent

REQUIRED

const t::uint32 REQUIRED = AbstractAttribute::REQUIRED

#include <include/elm/xom/dtd.h>

Attribute flag marking that the attribute as required its container element.

Referenced by AbstractAttribute::isRequired().

STRICT

const t::uint32 STRICT = AbstractAttribute::STRICT

#include <include/elm/xom/dtd.h>

Attribute flag causing parsing failure if there is an error during the attribute parsing.

Referenced by AbstractAttribute::isStrict().