Castle Game Engine

Unit CastleXMLUtils

Description
Uses
Classes, Interfaces, Objects and Records
Functions and Procedures
Types
Constants
Variables

Description

XML utilities.

This unit provides a lot of comfortable routines and helpers to manipulate XML files. It builds on top of FPC DOM unit, and you can still use the full power of FPC DOM unit, however we provide helpers to do a lot of things easier.

The engine example application that manipulates XML files is inside examples/short_api_samples/xml_utils/ . This is the code that loads and saves XML: 

{ Manage list of bookmarks, in particular load and save them to a simple XML file. }
unit MyBookmarks;

interface

uses Classes, SysUtils, Generics.Collections;

type
  { Bookmark definition. Contains URL and additional data. }
  TBookmark = class
    Caption, Url: String;
    function CaptionFinal: String;
  end;

  { List of TBookmark. }
  TBookmarkList = class({$ifdef FPC}specialize{$endif} TObjectList<TBookmark>)
    procedure Load;
    procedure Save;
  end;

const
  BookmarksDatabase = 'my-bookmarks.xml';

implementation

uses DOM,
  CastleXMLUtils, CastleURIUtils;

{ TBookmark ------------------------------------------------------------------ }

function TBookmark.CaptionFinal: String;
begin
  if Caption <> '' then
    Result := Caption
  else
    Result := Url;
end;

{ TBookmarkList -------------------------------------------------------------- }

procedure TBookmarkList.Load;
var
  B: TBookmark;
  Document: TXMLDocument;
  I: TXMLElementIterator;
begin
  Clear;

  if URIFileExists(BookmarksDatabase) then
  begin
    Document := URLReadXML(BookmarksDatabase);
    try
      if Document.DocumentElement.TagName8 <> 'bookmark-list' then
        raise Exception.CreateFmt('Bookmarks XML file has invalid top-level element: %s', [
          Document.DocumentElement.TagName8
        ]);
      I := Document.DocumentElement.ChildrenIterator('bookmark');
      try
        while I.GetNext do
        begin
          B := TBookmark.Create;
          B.Url := I.Current.AttributeString('url');
          B.Caption := I.Current.AttributeString('caption');
          Add(B);
        end;
      finally
        FreeAndNil(I);
      end;
    finally
      FreeAndNil(Document);
    end;
  end;
end;

procedure TBookmarkList.Save;
var
  Document: TXMLDocument;
  RootElement, Child: TDOMElement;
  B: TBookmark;
begin
  Document := TXMLDocument.Create;
  try
    RootElement := Document.CreateElement('bookmark-list');
    Document.AppendChild(RootElement);

    for B in Self do
    begin
      Child := RootElement.CreateChild('bookmark');
      Child.AttributeSet('caption', B.Caption);
      Child.AttributeSet('url', B.Url);
    end;

    URLWriteXML(Document, BookmarksDatabase);
  finally
    FreeAndNil(Document);
  end;
end;

end.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class EDOMAttributeMissing  
Class EDOMChildElementError  
Class TDOMNodeHelper  
Class TDOMCharacterDataHelper  
Class TDOMElementHelper  
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; deprecated 'use helper method AttributeString on TDOMElement';
function DOMGetCardinalAttribute(const Element: TDOMElement; const AttrName: string; var Value: Cardinal): boolean; deprecated 'use helper method AttributeCardinal on TDOMElement';
function DOMGetIntegerAttribute(const Element: TDOMElement; const AttrName: string; var Value: Integer): boolean; deprecated 'use helper method AttributeInteger on TDOMElement';
function DOMGetSingleAttribute(const Element: TDOMElement; const AttrName: string; var Value: Single): boolean; deprecated 'use helper method AttributeSingle on TDOMElement';
function DOMGetFloatAttribute(const Element: TDOMElement; const AttrName: string; var Value: Float): boolean; deprecated 'use helper method AttributeFloat on TDOMElement';
function DOMGetBooleanAttribute(const Element: TDOMElement; const AttrName: string; var Value: boolean): boolean; deprecated 'use helper method AttributeBoolean on TDOMElement';
function DOMGetOneChildElement(const Element: TDOMElement): TDOMElement; deprecated 'This method did not prove to be of much use, and it only clutters the API. Don''t use, or show us a convincing usecase when this is sensible.';
function DOMGetChildElement(const Element: TDOMElement; const ChildName: string; RaiseOnError: boolean): TDOMElement; deprecated 'use TDOMElement helper called ChildElement';
function DOMGetTextData(const Element: TDOMElement): string; deprecated 'use TDOMElement helper called TextData';
function DOMGetTextChild(const Element: TDOMElement; const ChildName: string): string; deprecated 'This method did not prove to be of much use, and it only clutters the API. Don''t use, or show us a convincing usecase when this is sensible.';
procedure FreeChildNodes(const ChildNodes: TDOMNodeList); deprecated 'this is useless since a long time (FPC >= 2.4.x), you can remove this as the engine does not support older FPC versions anyway';
procedure URLReadXML(out Doc: TXMLDocument; const URL: String); overload;
function URLReadXML(const URL: String): TXMLDocument; overload;
procedure URLWriteXML(Doc: TXMLDocument; const URL: String); overload;
procedure URLReadXML(out Doc: TXMLDocument; const URL: String; const BlowFishKeyPhrase: string); overload;
function URLReadXML(const URL: String; const BlowFishKeyPhrase: string): TXMLDocument; overload;
procedure URLWriteXML(Doc: TXMLDocument; const URL: String; const BlowFishKeyPhrase: string); overload;

Description

Functions and Procedures

function DOMGetAttribute(const Element: TDOMElement; const AttrName: string; var Value: string): boolean; deprecated 'use helper method AttributeString on TDOMElement';

Warning: this symbol is deprecated: use helper method AttributeString on TDOMElement

Retrieves from Element attribute Value and returns True, or (if 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.

Deprecated, use Element.AttributeString instead.

function DOMGetCardinalAttribute(const Element: TDOMElement; const AttrName: string; var Value: Cardinal): boolean; deprecated 'use helper method AttributeCardinal on TDOMElement';

Warning: this symbol is deprecated: use helper method AttributeCardinal on TDOMElement

Like DOMGetAttribute, but reads Cardinal value.

Deprecated, use Element.AttributeCardinal instead.

function DOMGetIntegerAttribute(const Element: TDOMElement; const AttrName: string; var Value: Integer): boolean; deprecated 'use helper method AttributeInteger on TDOMElement';

Warning: this symbol is deprecated: use helper method AttributeInteger on TDOMElement

Like DOMGetAttribute, but reads Integer value.

Deprecated, use Element.AttributeInteger instead.

function DOMGetSingleAttribute(const Element: TDOMElement; const AttrName: string; var Value: Single): boolean; deprecated 'use helper method AttributeSingle on TDOMElement';

Warning: this symbol is deprecated: use helper method AttributeSingle on TDOMElement

Like DOMGetAttribute, but reads Single value.

Deprecated, use Element.AttributeSingle instead.

function DOMGetFloatAttribute(const Element: TDOMElement; const AttrName: string; var Value: Float): boolean; deprecated 'use helper method AttributeFloat on TDOMElement';

Warning: this symbol is deprecated: use helper method AttributeFloat on TDOMElement

Like DOMGetAttribute, but reads Float value.

Deprecated, use Element.AttributeFloat instead.

function DOMGetBooleanAttribute(const Element: TDOMElement; const AttrName: string; var Value: boolean): boolean; deprecated 'use helper method AttributeBoolean on TDOMElement';

Warning: this symbol is deprecated: use helper method AttributeBoolean on TDOMElement

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.

Deprecated, use Element.AttributeBoolean instead.

function DOMGetOneChildElement(const Element: TDOMElement): TDOMElement; deprecated 'This method did not prove to be of much use, and it only clutters the API. Don''t use, or show us a convincing usecase when this is sensible.';

Warning: this symbol is deprecated: This method did not prove to be of much use, and it only clutters the API. Don't use, or show us a convincing usecase when this is sensible.

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; deprecated 'use TDOMElement helper called ChildElement';

Warning: this symbol is deprecated: use TDOMElement helper called ChildElement

 
function DOMGetTextData(const Element: TDOMElement): string; deprecated 'use TDOMElement helper called TextData';

Warning: this symbol is deprecated: use TDOMElement helper called TextData

 
function DOMGetTextChild(const Element: TDOMElement; const ChildName: string): string; deprecated 'This method did not prove to be of much use, and it only clutters the API. Don''t use, or show us a convincing usecase when this is sensible.';

Warning: this symbol is deprecated: This method did not prove to be of much use, and it only clutters the API. Don't use, or show us a convincing usecase when this is sensible.

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); deprecated 'this is useless since a long time (FPC >= 2.4.x), you can remove this as the engine does not support older FPC versions anyway';

Warning: this symbol is deprecated: this is useless since a long time (FPC >= 2.4.x), you can remove this as the engine does not support older FPC versions anyway

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.

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

procedure URLReadXML(out Doc: TXMLDocument; const URL: String); overload;

Replacements for standard ReadXMLFile and WriteXMLFile that operate on URLs. Optionally they can encrypt / decrypt content using BlowFish.

function URLReadXML(const URL: String): TXMLDocument; overload;
 
procedure URLWriteXML(Doc: TXMLDocument; const URL: String); overload;
 
procedure URLReadXML(out Doc: TXMLDocument; const URL: String; const BlowFishKeyPhrase: string); overload;
 
function URLReadXML(const URL: String; const BlowFishKeyPhrase: string): TXMLDocument; overload;
 
procedure URLWriteXML(Doc: TXMLDocument; const URL: String; const BlowFishKeyPhrase: string); overload;
 
Generated by PasDoc 0.16.0.