Unit CastleXMLUtils

DescriptionUsesClasses, Interfaces, Objects and RecordsFunctions and ProceduresTypesConstantsVariables

Description

Various XML and DOM utilities.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class EDOMChildElementError  
Class TXMLElementIterator Iterate over all children elements of given XML element.
Class TXMLElementFilteringIterator Iterate over children elements of given XML element, that have matching TagName.
Class TXMLCDataIterator Iterate over all CDATA nodes of given XML element.

Functions and Procedures

function DOMGetAttribute(const Element: TDOMElement; const AttrName: string; var Value: string): boolean;
function DOMGetCardinalAttribute(const Element: TDOMElement; const AttrName: string; var Value: Cardinal): boolean;
function DOMGetIntegerAttribute(const Element: TDOMElement; const AttrName: string; var Value: Integer): boolean;
function DOMGetSingleAttribute(const Element: TDOMElement; const AttrName: string; var Value: Single): boolean;
function DOMGetFloatAttribute(const Element: TDOMElement; const AttrName: string; var Value: Float): boolean;
function DOMGetBooleanAttribute(const Element: TDOMElement; const AttrName: string; var Value: boolean): boolean;
function DOMGetOneChildElement(const Element: TDOMElement): TDOMElement;
function DOMGetChildElement(const Element: TDOMElement; const ChildName: string; RaiseOnError: boolean): TDOMElement;
function DOMGetTextData(const Element: TDOMElement): string;
function DOMGetTextChild(const Element: TDOMElement; const ChildName: string): string;
procedure FreeChildNodes(const ChildNodes: TDOMNodeList);

Description

Functions and Procedures

function DOMGetAttribute(const Element: TDOMElement; const AttrName: string; var Value: string): boolean;

Retrieves from Element attribute Value and returns True, or (of there is no such attribute) returns False and does not modify Value. Value is a "var", not "out" param, because in the latter case it's guaranteed that the old Value will not be cleared.

function DOMGetCardinalAttribute(const Element: TDOMElement; const AttrName: string; var Value: Cardinal): boolean;

Like DOMGetAttribute, but reads Cardinal value.

function DOMGetIntegerAttribute(const Element: TDOMElement; const AttrName: string; var Value: Integer): boolean;

Like DOMGetAttribute, but reads Integer value.

function DOMGetSingleAttribute(const Element: TDOMElement; const AttrName: string; var Value: Single): boolean;

Like DOMGetAttribute, but reads Single value.

function DOMGetFloatAttribute(const Element: TDOMElement; const AttrName: string; var Value: Float): boolean;

Like DOMGetAttribute, but reads Float value.

function DOMGetBooleanAttribute(const Element: TDOMElement; const AttrName: string; var Value: boolean): boolean;

Like DOMGetAttribute, but reads Boolean value. A boolean value is interpreted just like FPC's TXMLConfig objects: true is designated by word true, false by word false, case is ignored.

If attribute exists but it's value is not true or false, then returns False and doesn't modify Value paramater. So behaves just like the attribute didn't exist.

function DOMGetOneChildElement(const Element: TDOMElement): TDOMElement;

This returns the one and only child element of this Element. If given Element has none or more than one child elements, returns Nil. This is handy for parsing XML in cases when you know that given element must contain exactly one other element in correct XML file.

function DOMGetChildElement(const Element: TDOMElement; const ChildName: string; RaiseOnError: boolean): TDOMElement;

Searches children elements inside Element for element with given ChildName.

For example

  <level>
    <creatures>
      ...
    </creatures>
    <items>
      ...
    </items>
  </level>

If you pass as Element the <level> node, and 'items' as ChildNode, then the TDOMElement representing <items> will be returned. If given ChildName will not exist or it will exist more than once (yes, that's checked), then will return Nil or raise EDOMChildElementError (depending on RaiseOnError).

Exceptions raised
EDOMChildElementError
If child not found or found more than once and RaiseOnError
function DOMGetTextData(const Element: TDOMElement): string;

This returns the text data contained in this element.

This is suitable if an element is supposed to contain only some text. It raises an error if an element contains any other element as child.

It concatenates all text data nodes that are direct children of this element. So if there are no text data nodes, it returns empty string without raising any error.

AFAIK it's uncommon but possible to have here more than one text node. Normally, more than one text nodes occur because they are separated by other child elements, but we already eliminated this possibility (i.e. we raise error in this case). Still, if you operated on DOM tree, e.g. deleted some elements, or inserted some text nodes, then I think it's possible that you will have more than one text node within this element. So this procedure should still work OK in this case.

function DOMGetTextChild(const Element: TDOMElement; const ChildName: string): string;

Gets a child of Element named ChildName, and gets text data within this child.

This is just a shortcut for DOMGetTextData(DOMGetChildElement(Element, ChildName, true)).

Exceptions raised
EDOMChildElementError
If child not found or found more than once and RaiseOnError
procedure FreeChildNodes(const ChildNodes: TDOMNodeList);

If needed, free result of TDOMElement.ChildNodes.

This abstracts FPC DOM unit differences:

  • For FPC <= 2.2.x, it was needed to call ChildNodes.Release when you're done with them.

  • For FPC trunk, you do not have to free them at all (since rev 13143), and their Release method doesn't exist (since rev 13113).


Generated by PasDoc 0.12.1 on 2013-02-04 20:26:53