Module Interface XML:Basic:Parser

SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST

# XML:Basic:Parser

This parser builds on the non-validating parser XML:Parser. It uses the element description facilities from XML:Basic:Element to perform syntactical and semantical checks, as well as to construct a data structure from an XML document. It is intended for small XML documents, like configuration files or messages.

This version of the "basic" parser does not support namespaces.

### Import List

        IO
        URI
        XML:Basic:Element
        XML:Builder
        XML:DTD
        XML:Error
        XML:Error
        XML:Locator
        XML:UnicodeCodec

Class List
Build |

Class Summary: Build [Detail]
      +---XML:Builder.Builder
           |
           +--XML:Basic:Parser.Build
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.
EndElement(NamespaceDeclaration, String) Called when an end tag is parsed.
[Error](Code)
[ErrorName](Code, String)
[ErrorString](Code, String)
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.
StartElement(NamespaceDeclaration, String) Called whenever a start tag is being parsed.
Inherited Methods
From XML:Builder.Builder: Attribute, AttributesDone, Characters, Comment, EndCDATA, EndDTD, EndDocument, EndElement, EndEntity, EntityDecl, NamespaceDeclaration, Notation, ProcessingInstruction, SetErrorListener, SetLocator, SkippedEntity, StartCDATA, StartDTD, StartDocument, StartElement, StartEntity

Type Summary
[ElementStack] = POINTER TO ARRAY OF Element

Procedure Summary
Parse(ByteChannel, URI, Factory, RootFactory, LONGINT, SET, VAR List): Element Parses an XML document from reader ``byteReader`' request.

Constant Summary
validate

Class Detail: Build

Method Detail

### Attribute

    PROCEDURE (b: Build) 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.

> [Description inherited from Attribute]

> Redefines: Attribute

### AttributesDone

    PROCEDURE (b: Build) 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.

> [Description inherited from AttributesDone]

> Redefines: AttributesDone

### Characters

    PROCEDURE (b: Build) 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).

> [Description inherited from Characters]

> Redefines: Characters

### EndElement

    PROCEDURE (b: Build) 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.

> [Description inherited from EndElement]

> Redefines: EndElement

### Error

    PROCEDURE (b: Build) [Error](code: Code)

### ErrorName

    PROCEDURE (b: Build) [ErrorName](code: Code;
                        name: String)

### ErrorString

    PROCEDURE (b: Build) [ErrorString](code: Code;
                          string: String)

### SetErrorListener

    PROCEDURE (b: Build) 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.

> [Description inherited from SetErrorListener]

> Redefines: SetErrorListener

### SetLocator

    PROCEDURE (b: Build) 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.

> [Description inherited from SetLocator]

> Redefines: SetLocator

### StartElement

    PROCEDURE (b: Build) 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.

> [Description inherited from StartElement]

> Redefines: StartElement

Type Detail

### ElementStack

    TYPE [ElementStack] = POINTER TO ARRAY OF Element

Procedure Detail

### Parse

    PROCEDURE Parse(byteReader: ByteChannel;
                    baseURI: URI;
                    unicodeFactory: Factory;
                    rootFactory: RootFactory;
                    maxNestingDepth: LONGINT;
                    flags: SET;
                    VAR errList: List): Element
      RAISES Error;

> Parses an XML document from reader ``byteReader`' request. If baseURI is not NIL, or if validate is in flags, external references in the XML document are followed. In this case, relative URIs are interpreted using the base URI baseURI. If unicodeFactory is given, then the document is assumed to use its character encoding.

> The root element of the document is created by selecting the matching factory function from rootFactory. An error is signalled if the nesting level of an element exceeds maxNestingDepth.

> The parser acts as a validating parser if validate is in flags.

> In case of an error, errList refers to the error list and result is NIL. Otherwise, errList is NIL and an instance of the root element is returned.

Constant Detail

### validate

    CONST validate