www.destructor.de

XML Scanner Reference Documentation

TXmlScanner is a VCL/CLX component wrapper for TXmlParser. You can simply click a TXmlScanner non-visual component on your form or data module and just use it.

How to use it

• Put a TXmlScanner component on your form
• Assign the name of the XML file to scan to the Filename property -- or -- call LoadFromFile (or LoadFromBuffer or SetBuffer) to load your XML into the component.
• Call the Execute method
• For every part the scanner finds in the XML file, one of the Events is triggered and you can do whatever you like with that part

TEasyXmlScanner

The TEasyXmlScanner component is easier to use than TXmlScanner: it lacks events which you won't need for standard applications. So there are only those events left in the object inspector that you're most likely to use. Everything else is the same.

LoadFromFile

PROCEDURE LoadFromFile (Filename : STRING); 

Loads the given file into the internal buffer of TXmlScanner. If you specify an unknown filename, the internal buffers will be cleared and a subsequent call to Execute will do nothing.

Parameters

See also

LoadFromBuffer, SetBuffer, Filename property

LoadFromBuffer

PROCEDURE LoadFromBuffer (Buffer : PChar); 

Loads the given buffer into the internal buffer of TXmlScanner. Buffer must be a null terminated string containing the XML document.

Parameters

See also

LoadFromFile, SetBuffer

SetBuffer

PROCEDURE SetBuffer (Buffer : PChar);

Makes the given buffer the data buffer where the parser gets the data from. This buffer must not be deallocated as long as Execute is working on it.

The Buffer must be null terminated.

The parser will not modify the contents of the buffer.

Parameters

See also

LoadFromFile, LoadFromBuffer

Execute

PROCEDURE Execute;

This is where the scanning takes place. Execute runs through the XML document and triggers one of the Events for every XML part it finds in the document.

When Execute returns, the whole document has been scanned.

Calling of the event methods is done synchronously (no threading, one after the other) so when Execute returns you can be sure that all of your Event handler methods have finished running.

Parameters

None

See also

LoadFromFile, LoadFromBuffer, SetBuffer, Normalize Property

Filename

PROPERTY Filename : STRING READ GetFilename WRITE LoadFromFile;

Gets/Sets the filename of the scanner. If you set the filename, the file is read into TXmlScanner's internal buffer.

See also

LoadFromFile

Normalize

PROPERTY Normalize : BOOLEAN READ GetNormalize WRITE SetNormalize;

If you set Normalize to TRUE, the following normalization on element text content will take place:

• Content which is only whitespace is not returned to your application
• Leading and trailing whitespace is trimmed off
• Contiguous whitespace characters are packed to one space character

Whitespace, as according to the XML 1.0 specification, is one of the following characters:

• The SPACE character (#32, #x0020)
• The TAB character (#9, #x0009)
• The CARRIAGE RETURN character (#13, #x000D)
• The LINE FEED character (#10, #x000A)

See also

Execute

OnAttList

PROPERTY OnAttList : TElementEvent  READ FOnAttList WRITE FOnAttList;

TElementEvent = PROCEDURE (Sender : TObject; ElemDef : TElemDef) OF OBJECT;

OnAttList is fired when the parser has found an <!ATTLIST> definition in the DTD. It gets passed the complete element definition as the ElemDef parameter which is a name/value pair list (TNvpList) containing the Attribute definitions (TAttrDef).

Parameters

Example

FOR I := 0 TO ElemDef.Count-1 DO BEGIN
    AD := TAttrDef (ElemDef [I]);
    IF AD.AttrType IN [atNotation, atEnumeration] 
      THEN S  := AD.Name + ': ' + AD.TypeDef + ' Default=' + AnsiQuotedStr (AD.Value, '''')
      ELSE S  := AD.Name+': '+CAttrType_Name [AD.AttrType] + ' Default=' + AnsiQuotedStr (AD.Value, '''');
    Memo1.Lines.Add (S);
    END;

OnCData

TContentEvent = PROCEDURE (Sender : TObject; Content : STRING) OF OBJECT;

PROPERTY OnCData : TContentEvent READ FOnCData WRITE FOnCData;

Is called whenever the Execute method has parsed a CDATA section.

Parameters

See also

Execute, OnStartTag, OnContent

OnComment

TCommentEvent = PROCEDURE (Sender : TObject; Comment : STRING) OF OBJECT;

PROPERTY OnComment : TCommentEvent READ FOnComment WRITE FOnComment;

Is called whenever the Execute method has parsed a comment.

Parameters

See also

Execute

OnContent

TContentEvent = PROCEDURE (Sender : TObject; Content : STRING) OF OBJECT;

PROPERTY OnContent : TContentEvent READ FOnContent WRITE FOnContent;

Is called whenever the Execute method has parsed element text content.

Parameters

See also

Execute, OnStartTag, OnCData

OnDtdError

TErrorEvent = PROCEDURE (Sender : TObject; ErrorPos : PChar) OF OBJECT;

PROPERTY OnDtdError : TErrorEvent READ FOnDtdError WRITE FOnDtdError;

Gets called whenever there is an error found in the DTD.

Parameters

OnDtdRead

TDtdEvent = PROCEDURE (Sender : TObject; RootElementName : STRING) OF OBJECT;

PROPERTY OnDtdRead : TDtdEvent READ FOnDtdRead WRITE FOnDtdRead;

Is called whenever the Execute method has finished parsing the document type declaration.

Parameters

See also

Execute

OnElement

PROPERTY OnElement : TElementEvent READ FOnElement WRITE FOnElement;

TElementEvent = PROCEDURE (Sender : TObject; ElemDef : TElemDef) OF OBJECT;

OnElement is fired when the parser has found an <!ELEMENT> definition in the DTD. It gets passed the complete element definition as the ElemDef parameter. The Attribute list is empty when OnElement gets fired.

Parameters

Example

Memo1.Lines.Add ('OnElement: '+ElemDef.Name+': '+ElemDef.Definition);

OnEmptyTag

TStartTagEvent = PROCEDURE (Sender : TObject; TagName : STRING; Attributes : TAttrList) OF OBJECT;

PROPERTY OnEmptyTag : TStartTagEvent READ FOnEmptyTag WRITE FOnEmptyTag;

Is called whenever the Execute method has read in an Empty-Element Tag of the form <name/>

When you have an Empty-Element Tag of the form <name></name>, the events OnStartTag and OnEndTag are triggered.

You can access the attributes by name or by scanning through the list of attributes (Value and Name are STRING variables, i is of type INTEGER):

Value := Attributes.Value ('name');         // Access by name

for i := 0 to Attributes.Count-1 do begin   // Scan through attributes
  Name  := Attributes.Name (i);
  Value := Attributes.Value (i);
  end;

Note that all names in XML are case-sensitive. This includes attribute names. The list of attributes is always sorted by name by the parser.

Parameters

See also

Execute, OnStartTag, OnEndTag

OnEndTag

TEndTagEvent = PROCEDURE (Sender : TObject; TagName : STRING) OF OBJECT;

PROPERTY OnEndTag : TEndTagEvent READ FOnEndTag WRITE FOnEndTag;

Is called whenever the Execute method has parsed an End Tag.

Parameters

See also

Execute, OnStartTag

OnEntity

TEntityEvent = PROCEDURE (Sender : TObject; EntityDef : TEntityDef) OF OBJECT;

PROPERTY OnEntity : TEntityEvent READ FOnEntity WRITE FOnEntity;

This event is fired when the parser has found an <!ENTITY> definition in the DTD.

Parameters

OnLoadExternal

TExternalEvent = PROCEDURE (Sender : TObject; 
                            SystemId, PublicId, NotationId : STRING;
                            VAR Result : TXmlParser) OF OBJECT;

PROPERTY OnLoadExternal : TExternalEvent READ FOnLoadExternal WRITE FOnLoadExternal;

When your XML document contains references to External Entities or External DTDs, the external entity must be loaded into memory. When the parser finds an External Entity reference or an external DTD reference, it fires to OnLoadExternal event.

The event handler must

• create a new TXmlParser instance and assign it to Result
• Load the external entity file into the newly created TXmlParser instance

Parameters

Example

There is a call to an external entity in the DTD:

<!ENTITY blah SYSTEM "myentity.xml">

In this case, "myentity.xml" is passed as the SYSTEM identifier. This is how the event handler looks like:

Result := TXmlParser.Create;
Result.LoadFromFile (SystemId);

Please note that TXmlParser is not able to do HTTP or FTP transfers. In case you need this, you must implement it yourself (e.g. by using Indy or other components that come with Delphi). When you have downloaded from HTTP or FTP, you can use TXmlParser.LoadFromBuffer or TXmlParser.SetBuffer to load the XML into the parser instance.

OnNotation

TNotationEvent = PROCEDURE (Sender : TObject; NotationDef : TNotationDef) OF OBJECT;

PROPERTY OnNotation : TNotationEvent READ FOnNotation WRITE FOnNotation;

OnNotation gets called when the parser has found a <!NOTATION> definition in the DTD.

Parameters

OnPI

TPIEvent = PROCEDURE (Sender : TObject; Target, Content: STRING; Attributes : TAttrList) OF OBJECT;

PROPERTY OnPI : TPIEvent READ FOnPI WRITE FOnPI;

Is called whenever the Execute method has parsed a Processing Instruction (PI).

A PI can have any format after the target. It is a common practice to specifiy "pseudo" attributes like the ones in start tags. For this, you get passed a list of attributes here, which is of course only valid and useable if the PI contains pseudo attributes.

Parameters

See also

Execute

OnStartTag

TStartTagEvent = PROCEDURE (Sender : TObject; TagName : STRING; Attributes : TAttrList) OF OBJECT;

PROPERTY OnStartTag : TStartTagEvent READ FOnStartTag WRITE FOnStartTag;

Is called whenever the Execute method has read in a Start Tag.

You can access the attributes by name or by scanning through the list of attributes (Value and Name are STRING variables, i is of type INTEGER):

Value := Attributes.Value ('name');         // Access by name

for i := 0 to Attributes.Count-1 do begin   // Scan through attributes
  Name  := Attributes.Name (i);
  Value := Attributes.Value (i);
  end;

Note that all names in XML are case-sensitive. This includes attribute names. The list of attributes is always sorted by name by the parser.

Parameters

See also

Execute, OnEndTag

OnTranslateEncoding

TEncodingEvent = FUNCTION  (Sender : TObject; CurrentEncoding, Source : STRING) : STRING OF OBJECT;

PROPERTY OnTranslateEncoding : TEncodingEvent READ FOnTranslateEncoding WRITE FOnTranslateEncoding;

The XML Specification states that every XML parser must be able to handle UTF-8 and UTF-16 documents. Beside these, parsers should be able to handle other Encodings. The encoding for a document is defined in the XML Prolog (for entire XML Documents) or in a Text Declaration at the beginning of Parsed External Entities or External DTD subsets.

So there is a source Encoding (the Encoding of the Document and its external parts) and a destination encoding (the encoding your application wishes to process). For every content string which is passed to your application (Text Content between Tags, CDATA sections, Attribute values) the OnTranslateEncoding event is fired. It retrieves the current source encoding by looking at the CurrentEncoding argument and translates the passed Source string into the desired destination encoding.

The TranslateEncoding method that is built into TXmlParser assumes that the destination encoding is the Windows ANSI encoding used in Windows apps. It can handle UTF-8 and ISO-8859-1 as source encodings. Note: It is assumed here that ISO-8859-1 and "Windows ANSI" are the same, which is not exactly true for some characters. 

UTF-8 correctly translated into the single-byte ANSI Windows-1252 format.

At the time of this writing, TXmlParser and TXmlScanner are not able to handle multi-byte character strings. This is likely to change in the future.

Parameters

Example

Let's assume that the CurrentEncoding is UTF-8 and you want to translate it to the Windows ANSI 1252 character set:

IF CurrentEncoding = 'UTF-8' THEN
  Result := Utf8ToAnsi (Source);     // Utf8ToAnsi provided by LibXmlParser

OnXmlProlog

TXmlPrologEvent = PROCEDURE (Sender : TObject; XmlVersion, Encoding: STRING; Standalone : BOOLEAN) OF OBJECT;

PROPERTY OnXmlProlog : TXmlPrologEvent READ FOnXmlProlog WRITE FOnXmlProlog;

Is called when the Execute method has parsed an XML Declaration or a Text Declaration.

Parameters

See also

Execute