# XML:Builder

### Import List

        URI
        XML:DTD
        XML:Locator

Class List
Attribute |
AttributeList |
Builder | This abstract class defines the interface of the XML parser to the application.

Class Summary: Attribute [Detail]

      +--XML:Builder.Attribute

Field Summary
attrDecl-: AttrDecl
localName: String
namespaceDecl: NamespaceDeclaration
pos-: Position
specified-: BOOLEAN
value-: AttValue
Constructor Summary
InitAttribute(Attribute, NamespaceDeclaration, String, AttrDecl, AttValue, BOOLEAN, Locator)
NewAttribute(NamespaceDeclaration, String, AttrDecl, AttValue, BOOLEAN, Locator): Attribute Creates a new attribute instance.

Class Summary: AttributeList [Detail]

      +--XML:Builder.AttributeList

Field Summary
attr-: AttributeArray The attribute values stored in the list.
len-: LONGINT The length of the attribute list.
Constructor Summary
InitAttributeList(AttributeList)
NewAttributeList(): AttributeList Creates a new, empty attribute list.
Method Summary
Append(Attribute) Appends the attribute attr to the list.
Clear() Returns attrList to an empty list.

Class Summary: Builder [Detail]

      +--XML:Builder.Builder

This abstract class defines the interface of the XML parser to the application. It is based on the W3C Working Draft ``XML Information Set`', dated March 2001. This specification can be obtained at http://www.w3.org/TR/2001/WD-xml-infoset-20010316/. All information items required by the XML Information Set are made available by the parser.

The low-level interface to the parser is governed by two requirements: It must make all core properties (and, as far as possible, all peripheral properties) of the XML Infoset available to the application, and the parser must be able to serve it without any overhead. For this reason, the interface is not an instance of any of the established parser interfaces, like SAX, SAX2, or DOM. Specializations of Builder provide these interfaces.

The parser itself is not namespace aware, even if this interface has the necessary hooks to provide namespace information. Namespaces are implemented by a special builder, XML:Builder:Namespaces.Builder, that translates between the parser and a namespace-aware application.

The parser calls the type-bound procedures of the builder while traversing the document. The string arguments passed to the procedures should not be modified by any concrete builder.

In case of a fatal error, the parser will stop invoking any builder procedures, with the exception of Builder.EndDocument.

Important: The locator positions always refer to the top level of the processed file. They do not follow internal entity references. For example, if a start tag of an element is defined within an internal entity, then the locator position of Builder.StartElement is the position of the entity reference, instead of the position of the markup text.

Constructor Summary
Init(Builder)
New(): Builder Creates a new builder that does not do anything with the callbacks initiated by the parser.
Method Summary
Attribute(NamespaceDeclaration, String, AttrDecl, AttValue, BOOLEAN) Called for every attribute (specified or defaulted) of the current element.
AttributesDone() Called when the all attributes of a start tag, specified or defaulted, have been reported to the application.
Characters(VAR StringVar, CharPos, CharPos, ElementWhitespaceType) Called for non-markup characters that appear within the document element.
Comment(VAR StringVar, CharPos, CharPos) Called for comments.
EndCDATA() Called at the end of a CDATA section.
EndDTD(ExternalEntity, BOOLEAN) This method is called by the paser when is done parsing the document type declaration.
EndDocument() Called by the parser after it has processed the whole document.
EndElement(NamespaceDeclaration, String) Called when an end tag is parsed.
EndEntity(Entity) Called when parsing of the replacement text of entity is done.
EntityDecl(Entity) Called for declarations of general entities.
NamespaceDeclaration(NamespaceDeclaration) Called for namespace declarations in an attribute list.
Notation(Notation) Called for notation declarations.
ProcessingInstruction(String, VAR StringVar, CharPos, CharPos, URI) Called for processing instructions.
SetErrorListener(ErrorListener) Indicates the object el that the builder should use for error signalling.
SetLocator(Locator) Indicates which locator object the parser uses to communicate positional information.
SkippedEntity(String, Entity) This method is called for every entity skipped by a non-validating parser, if it configured to ignore references to external parsed entities.
StartCDATA() Called at the beginning of a CDATA section.
StartDTD(Builder) Called by the parser just before it begins parsing the document type declaration.
StartDocument(ExternalEntity) Marks the start of the document.
StartElement(NamespaceDeclaration, String) Called whenever a start tag is being parsed.
StartEntity(Entity) This method is called before the replacement text of a general entity is inspected in an element's content.

Type Summary
[AttributeArray] = POINTER TO ARRAY OF Attribute

Class Detail: Attribute

Field Detail

### attrDecl

    FIELD attrDecl-: AttrDecl

### localName

    FIELD localName: String

### namespaceDecl

    FIELD namespaceDecl: NamespaceDeclaration

### pos

    FIELD pos-: Position

### specified

    FIELD specified-: BOOLEAN

### value

    FIELD value-: AttValue

Constructor Detail

### InitAttribute

    PROCEDURE InitAttribute(attr: Attribute;
                            namespaceDecl: NamespaceDeclaration;
                            localName: String;
                            attrDecl: AttrDecl;
                            value: AttValue;
                            specified: BOOLEAN;
                            locator: Locator)

### NewAttribute

    PROCEDURE NewAttribute(namespaceDecl: NamespaceDeclaration;
                           localName: String;
                           attrDecl: AttrDecl;
                           value: AttValue;
                           specified: BOOLEAN;
                           locator: Locator): Attribute

> Creates a new attribute instance. The instance's field are taken directly from the passed arguments. The locator is discarded if specified is FALSE.

Class Detail: AttributeList

Field Detail

### attr

    FIELD attr-: AttributeArray

> The attribute values stored in the list. The pointers in the range ``[0, len-1[`' refer to Attribute instances.

> The array pointer can change when the list is modified.

### len

    FIELD len-: LONGINT

> The length of the attribute list.

Constructor Detail

### InitAttributeList

    PROCEDURE InitAttributeList(attrList: AttributeList)

### NewAttributeList

    PROCEDURE NewAttributeList(): AttributeList

> Creates a new, empty attribute list.

Method Detail

### Append

    PROCEDURE (attrList: AttributeList) Append(attr: Attribute)

> Appends the attribute attr to the list.

### Clear

    PROCEDURE (attrList: AttributeList) Clear()

> Returns attrList to an empty list.

Class Detail: Builder

Constructor Detail

### Init

    PROCEDURE Init(b: Builder)

### New

    PROCEDURE New(): Builder

> Creates a new builder that does not do anything with the callbacks initiated by the parser.

Method Detail

### Attribute

    PROCEDURE (b: Builder) Attribute(namespaceDecl: NamespaceDeclaration;
                        localName: String;
                        attrDecl: AttrDecl;
                        value: AttValue;
                        specified: BOOLEAN)

> Called for every attribute (specified or defaulted) of the current element. For a namespace aware parser, namespaceDecl refers to the namespace URI of the element name. If the name has no namespace part, the argument is NIL. localName is the element minus the namespace prefix and the colon. The namespace prefix of the attribute name can be obtained from namespaceDecl.

> If an attribute declaration for this attribute is known to the parser, it is passed in attrDecl. Without a declaration, the application should treat the attribute as if it were of type DTD.attrCDATA.

> If the attribute is specified in the element's attribute list, instead of being defaulted from the attribute's declaration, specified is TRUE.

> The attribute's value is passed into the parameter value. Call DTD.AttValue.Flatten or DTD.AttValue.FlattenValue to retrieve the normalized value of the attribute. You can also access the data structure value. The string values in the data structure are normalized for CDATA values. When reading value for non-CDATA attributes, you must collapse sequences of whitespace into a single space, and remove any whitespace from the beginning and the end of the attribute value.

> The locator is at the beginning of the attribute's name, if specified is TRUE. For defaulted attributes, the locator is undefined.

### AttributesDone

    PROCEDURE (b: Builder) AttributesDone()

> Called when the all attributes of a start tag, specified or defaulted, have been reported to the application. The locator is positioned after the closing ``>`' of the start or empty element tag.

### Characters

    PROCEDURE (b: Builder) Characters(VAR chars: StringVar;
                         charsStart: CharPos;
                         charsEnd: CharPos;
                         elementWhitespace: ElementWhitespaceType)

> Called for non-markup characters that appear within the document element. The array slice ``chars[charsStart, charsEnd[`' holds the character data. elementWhitespace indicates whether the characters are whitespace appearing within element content.

> The locator refers to the first character.

> Note: It is up to the parser how it partitions character data before reporting it to the application. For example, the character data of an element may be reported in one call to Builder.Characters, or in multiple chunks, depending on embedded character references, general entity references, CDATA sections, and the size of the character content. It is only guaranteed that this procedure is called with an integral number of ISO 10646 characters (e.g., surrogate pairs are reported in one call).

### Comment

    PROCEDURE (b: Builder) Comment(VAR chars: StringVar;
                      charsStart: CharPos;
                      charsEnd: CharPos)

> Called for comments. The array slice ``chars[charsStart, charsEnd[`' holds the comment's content.

> The locator is positioned at the ``<!--`'.

### EndCDATA

    PROCEDURE (b: Builder) EndCDATA()

> Called at the end of a CDATA section. The locator refers to the position after the ``]]>`'.

### EndDTD

    PROCEDURE (b: Builder) EndDTD(externalDTD: ExternalEntity;
                     allDeclarationsProcessed: BOOLEAN)

> This method is called by the paser when is done parsing the document type declaration. If the DTD had an external subset, the reference to the entity is passed in externalDTD. The public and system identifier of the external subset are available through the entity item.

> If allDeclarationsProcessed is TRUE, then the parser has read the complete DTD.

> The locator is positioned after the closing ``>`' of the DTD, and the external DTD subset has been processed.

### EndDocument

    PROCEDURE (b: Builder) EndDocument()

> Called by the parser after it has processed the whole document. Afterwards, none of the other builder methods will be called. Note that unlike all the other event reporting methods, this method is even called if the document had a fatal error. The locator is positioned at the very end of the file.

### EndElement

    PROCEDURE (b: Builder) EndElement(namespaceDecl: NamespaceDeclaration;
                         localName: String)

> Called when an end tag is parsed. See Builder.StartElement for a description of the arguments. The locator is positioned at the beginning of the end tag's name, if an explicit end tag exists. Otherwise, it is placed after the closing ``/>`' of the empty element tag.

### EndEntity

    PROCEDURE (b: Builder) EndEntity(entity: Entity)

> Called when parsing of the replacement text of entity is done. The locator points to the first character after the entity reference.

### EntityDecl

    PROCEDURE (b: Builder) EntityDecl(entity: Entity)

> Called for declarations of general entities. The locator points to the first character of the declared name.

> Note: The document entity is passed to Builder.StartDocument, and the entity for the external DTD subset to Builder.EndDTD, of it exists.

### NamespaceDeclaration

    PROCEDURE (b: Builder) NamespaceDeclaration(namespaceDecl: NamespaceDeclaration)

> Called for namespace declarations in an attribute list. Note: The parser implementation XML:Parser.Parser does not know about namespaces and never calls this method. Use the adapter builder XML:Builder:Namespaces.Builder to introduce namespace information into the event stream. The locator position is undefined.

### Notation

    PROCEDURE (b: Builder) Notation(notation: Notation)

> Called for notation declarations. The locator points to the first character of the declared name.

### ProcessingInstruction

    PROCEDURE (b: Builder) ProcessingInstruction(target: String;
                                    VAR content: StringVar;
                                    contentStart: CharPos;
                                    contentEnd: CharPos;
                                    baseURI: URI)

> Called for processing instructions. target holds the PI's target part. The array slice ``content[contentStart, contentEnd[`' holds the content data. baseURI is the absolute URI of the entity in which the PI appears.

> The locator is positioned at the ``<?`'.

### SetErrorListener

    PROCEDURE (b: Builder) SetErrorListener(el: ErrorListener)

> Indicates the object el that the builder should use for error signalling. Any errors will subsequently be reported through el.Error. This method is called by the parser before it begins processing of the document.

### SetLocator

    PROCEDURE (b: Builder) SetLocator(locator: Locator)

> Indicates which locator object the parser uses to communicate positional information. If this method is not called before Builder.StartDocument, the builder should assume that no locator is available during processing. This method may be called several times during processing of a document.

> Pre-condition: ``locator`' is not NIL.

### SkippedEntity

    PROCEDURE (b: Builder) SkippedEntity(name: String;
                            entity: Entity)

> This method is called for every entity skipped by a non-validating parser, if it configured to ignore references to external parsed entities. name is the name of the skipped entity and entity its entity declaration, if this information is available. The locator refers to the beginning of the name of the entity reference.

### StartCDATA

    PROCEDURE (b: Builder) StartCDATA()

> Called at the beginning of a CDATA section. The next calls to Builder.Characters before Builder.EndCDATA represent the CDATA's character content.

> The locator is positioned at ``<![CDATA[`'.

### StartDTD

    PROCEDURE (b: Builder) StartDTD(dtdBuilder: Builder)

> Called by the parser just before it begins parsing the document type declaration. dtdBuilder is the object that is used by the parser to build the DTD data structure. All comments and processing instruction events that are reported between Builder.StartDTD and Builder.EndDTD are part of the DTD. Events from the internal DTD are reported before events of the external DTD. The locator is positioned at the beginning of ``<!DOCTYPE`'.

### StartDocument

    PROCEDURE (b: Builder) StartDocument(documentEntity: ExternalEntity)

> Marks the start of the document. This method is called just before parsing begins. The base URI of the document can be obtained from documentEntity, if it has been passed to XML:Parser.NewChannel. The locator is positioned at the very beginning of the file.

### StartElement

    PROCEDURE (b: Builder) StartElement(namespaceDecl: NamespaceDeclaration;
                           localName: String)

> Called whenever a start tag is being parsed. For a namespace aware parser, namespaceDecl refers to the namespace URI of the element name. If the name has no namespace part, the argument is NIL. localName is the element minus the namespace prefix and the colon. The namespace prefix of the attribute name can be obtained from namespaceDecl.

> b The locator is positioned at the beginning of the start tag's name.

> Note: Namespaces are only partially supported in the parser itself. For full namespace support, the special builder class XML:Builder:Namespaces.Builder must be put between the parser and the application.

### StartEntity

    PROCEDURE (b: Builder) StartEntity(entity: Entity)

> This method is called before the replacement text of a general entity is inspected in an element's content. entity refers to the entity that is being expanded. The locator points to the ``&`' in front of the name of the entity reference.

Type Detail

### AttributeArray

    TYPE [AttributeArray] = POINTER TO ARRAY OF Attribute