CodeSnip Old Code (SVN)

{
 * This Source Code Form is subject to the terms of the Mozilla Public License,
 * v. 2.0. If a copy of the MPL was not distributed with this file, You can
 * obtain one at http://mozilla.org/MPL/2.0/
 *
 * Copyright (C) 2008-2012, Peter Johnson (www.delphidabbler.com).
 *
 * $Rev$
 * $Date$
 *
 * Implements extensions to TXMLDocument and IXMLDocument that provide some
 * helper methods. Also provides a simple list object that can contain XML
 * nodes with enumerator.
}


unit UXMLDocumentEx;


interface


uses
  // Delphi
  SysUtils,
  // Project
  Generics.Collections, XMLIntf, XMLDoc, XMLDom;


type
  ///  <summary>
  ///  Interface to a simple list of XML nodes. This interface is designed to
  ///  enable creation and manipulation of a list of IXMLNode objects without
  ///  reference to XML document..
  ///  </summary>
  IXMLSimpleNodeList = interface(IInterface)
    ['{93ABE85F-FBAC-4FDA-B071-5DD1C8537844}']
    ///  <summary>Retrieves a node from the list by index.</summary>
    function GetItem(Idx: Integer): IXMLNode;
    ///  <summary>Adds a given node to the list and returns index of new node
    ///  in list.</summary>
    function Add(const Node: IXMLNode): Integer;
    ///  <summary>Returns number of items in list.</summary>
    function Count: Integer;
    ///  <summary>Creates list enumerator.</summary>
    ///  <remarks>This method is mainly for use by the compiler and permits the
    ///  list to be used in for..in loops.</remarks>
    function GetEnumerator: TEnumerator<IXMLNode>;
    ///  <summary>Indexed access to list items.</summary>
    property Items[Idx: Integer]: IXMLNode read GetItem; default;
  end;

type
  ///  <summary>
  ///  Extension of XMLIntf.IXMLDocument.
  ///  </summary>
  ///  <remarks>
  ///  Provides some methods that help with searching for nodes in the document,
  ///  creation of new nodes and loading and saving documents from and to byte
  ///  arrays.
  ///  </remarks>
  IXMLDocumentEx = interface(IXMLDocument)
    ['{2BE340ED-DD60-4DC4-B3F7-EF9C1C46DA6D}']

    ///  <summary>Finds a node specified by a path from, and including the
    ///  document's root node.</summary>
    ///  <param name="PathToNode">DOMString [in] Path to node from root node.
    ///  </param>
    ///  <returns>IXMLNode - Reference to required node or nil if node not
    ///  found.</returns>
    ///  <remarks>Node in path are separated by backslash, e.g.
    ///  root\node1\node2</remarks>
    function FindNode(PathToNode: DOMString): IXMLNode;

    ///  <summary>Finds all child nodes of a parent node that are elements and
    ///  have a specified name.</summary>
    ///  <param name="ParentNode">IXMLNode [in] Node containing child nodes to
    ///  be found.</param>
    ///  <param name="NodeName">DOMString [in] Name of required element nodes.
    ///  </param>
    ///  <returns>IXMLSimpleNodeList - List of matching nodes.</returns>
    function FindChildNodes(const ParentNode: IXMLNode;
      const NodeName: DOMString): IXMLSimpleNodeList;
      overload;

    ///  <summary>Finds all child nodes of a parent node that are elements, have
    ///  a specified name and have a specified attribute value.</summary>
    ///  <param name="ParentNode">IXMLNode [in] Node containing child nodes to
    ///  be found.</param>
    ///  <param name="NodeName">DOMString [in] Name of required element nodes.
    ///  </param>
    ///  <param name="AttribName">DOMString [in] Name of required attribute.
    ///  </param>
    ///  <param name="AttribValue">OleVariant [in] Required value of AttribName.
    ///  </param>
    ///  <returns>IXMLSimpleNodeList - List of matching nodes.</returns>
    function FindChildNodes(const ParentNode: IXMLNode;
      const NodeName, AttribName: DOMString;
      const AttribValue: OleVariant): IXMLSimpleNodeList;
      overload;

    ///  <summary>Finds first child node that has a given name.</summary>
    ///  <param name="ParentNode">IXMLNode [in] Node containing child nodes to
    ///  be searched.</param>
    ///  <param name="NodeName">DOMString [in] Name of required element node.
    ///  </param>
    ///  <returns>IXMLNode - Reference to found node or nil if no node found.
    ///  </returns>
    function FindFirstChildNode(const ParentNode: IXMLNode;
      const NodeName: DOMString): IXMLNode;
      overload;

    ///  <summary>Finds first child node that has a given name and attribute
    ///  value.</summary>
    ///  <param name="ParentNode">IXMLNode [in] Node containing child nodes to
    ///  be found.</param>
    ///  <param name="NodeName">DOMString [in] Name of required element node.
    ///  </param>
    ///  <param name="AttribName">DOMString [in] Name of required attribute.
    ///  </param>
    ///  <param name="AttribValue">OleVariant [in] Required value of AttribName.
    ///  </param>
    ///  <returns>IXMLNode - Reference to found node or nil if no node found.
    ///  </returns>
    function FindFirstChildNode(const ParentNode: IXMLNode;
      const NodeName, AttribName: DOMString;
      const AttribValue: OleVariant): IXMLNode;
      overload;

    ///  <summary>Creates a new parented XML node in document.</summary>
    ///  <param name="Parent">IXMLNode [in] Parent node of new node.</param>
    ///  <param name="NodeName">DOMString [in] Name of new node.</param>
    ///  <returns>IXMLNode - Requied new node.</returns>
    function CreateElement(const Parent: IXMLNode;
      const NodeName: DOMString): IXMLNode; overload;

    ///  <summary>Creates a new parented XML text node in document.</summary>
    ///  <param name="Parent">IXMLNode [in] Parent node of new node.</param>
    ///  <param name="NodeName">DOMString [in] Name of new node.</param>
    ///  <param name="Text">DOMString [in] Text stored in new node.</param>
    ///  <returns>IXMLNode - Requied new node.</returns>
    function CreateElement(const Parent: IXMLNode;
      const NodeName, Text: DOMString): IXMLNode; overload;

    ///  <summary>Loads XML document from data stored in byte array.</summary>
    ///  <param name="Bytes">TBytes [in] Array of bytes to load.</param>
    procedure LoadFromBytes(const Bytes: TBytes);

    ///  <summary>Stores content of XML document in byte array using encoding
    ///  specified in inherited Encoding property.</summary>
    ///  <returns>TBytes - Array of bytes storing XML document.</returns>
    function SaveToBytes: TBytes;
  end;

type
  ///  <summary>
  ///  Implementation of a simple list of XML nodes that can be created and
  ///  manipulated without reference to XML document.
  ///  </summary>
  TXMLSimpleNodeList = class(TInterfacedObject,
    IXMLSimpleNodeList
  )
  strict private
    var
      ///  <summary>List of nodes.</summary>
      fList: TList<IXMLNode>;
  public
    ///  <summary>Object constructor. Creates object with empty list.</summary>
    constructor Create;
    ///  <summary>Object destructor. Tears down object.</summary>
    destructor Destroy; override;

    { IXMLSimpleNodeList methods }
    ///  <summary>Retrieves a node from the list by index.</summary>
    function GetItem(Idx: Integer): IXMLNode;
    ///  <summary>Adds a given node to the list and returns index of new node
    ///  in list.</summary>
    function Add(const Node: IXMLNode): Integer;
    ///  <summary>Returns number of items in list.</summary>
    function Count: Integer;
    ///  <summary>Creates list enumerator.</summary>
    function GetEnumerator: TEnumerator<IXMLNode>;
  end;

type
  ///  <summary>
  ///  Extension of TXMLDocument from XMLDoc unit that implements the methods of
  ///  IXMLDocumentEx.
  ///  </summary>
  TXMLDocumentEx = class(TXMLDocument,
    IXMLDocument, IXMLDocumentEx
  )
  public
    { IXMLDocumentEx methods }

    ///  <summary>Finds a node specified by a path from, and including the
    ///  document's root node.</summary>
    ///  <param name="PathToNode">DOMString [in] Path to node from root node.
    ///  </param>
    ///  <returns>IXMLNode - Reference to required node or nil if node not
    ///  found.</returns>
    ///  <remarks>Node in path are separated by backslash, e.g.
    ///  root\node1\node2</remarks>
    function FindNode(PathToNode: DOMString): IXMLNode;

    ///  <summary>Finds all child nodes of a parent node that are elements and
    ///  have a specified name.</summary>
    ///  <param name="ParentNode">IXMLNode [in] Node containing child nodes to
    ///  be found.</param>
    ///  <param name="NodeName">DOMString [in] Name of required element nodes.
    ///  </param>
    ///  <returns>IXMLSimpleNodeList - List of matching nodes.</returns>
    function FindChildNodes(const ParentNode: IXMLNode;
      const NodeName: DOMString): IXMLSimpleNodeList;
      overload;

    ///  <summary>Finds all child nodes of a parent node that are elements, have
    ///  a specified name and have a specified attribute value.</summary>
    ///  <param name="ParentNode">IXMLNode [in] Node containing child nodes to
    ///  be found.</param>
    ///  <param name="NodeName">DOMString [in] Name of required element nodes.
    ///  </param>
    ///  <param name="AttribName">DOMString [in] Name of required attribute.
    ///  </param>
    ///  <param name="AttribValue">OleVariant [in] Required value of AttribName.
    ///  </param>
    ///  <returns>IXMLSimpleNodeList - List of matching nodes.</returns>
    function FindChildNodes(const ParentNode: IXMLNode;
      const NodeName, AttribName: DOMString;
      const AttribValue: OleVariant): IXMLSimpleNodeList;
      overload;

    ///  <summary>Finds first child node that has a given name.</summary>
    ///  <param name="ParentNode">IXMLNode [in] Node containing child nodes to
    ///  be searched.</param>
    ///  <param name="NodeName">DOMString [in] Name of required element node.
    ///  </param>
    ///  <returns>IXMLNode - Reference to found node or nil if no node found.
    ///  </returns>
    function FindFirstChildNode(const ParentNode: IXMLNode;
      const NodeName: DOMString): IXMLNode;
      overload;

    ///  <summary>Finds first child node that has a given name and attribute
    ///  value.</summary>
    ///  <param name="ParentNode">IXMLNode [in] Node containing child nodes to
    ///  be found.</param>
    ///  <param name="NodeName">DOMString [in] Name of required element node.
    ///  </param>
    ///  <param name="AttribName">DOMString [in] Name of required attribute.
    ///  </param>
    ///  <param name="AttribValue">OleVariant [in] Required value of AttribName.
    ///  </param>
    ///  <returns>IXMLNode - Reference to found node or nil if no node found.
    ///  </returns>
    function FindFirstChildNode(const ParentNode: IXMLNode;
      const NodeName, AttribName: DOMString;
      const AttribValue: OleVariant): IXMLNode;
      overload;

    ///  <summary>Creates a new parented XML node in document.</summary>
    ///  <param name="Parent">IXMLNode [in] Parent node of new node.</param>
    ///  <param name="NodeName">DOMString [in] Name of new node.</param>
    ///  <returns>IXMLNode - Requied new node.</returns>
    function CreateElement(const Parent: IXMLNode;
      const NodeName: DOMString): IXMLNode; overload;

    ///  <summary>Creates a new parented XML text node in document.</summary>
    ///  <param name="Parent">IXMLNode [in] Parent node of new node.</param>
    ///  <param name="NodeName">DOMString [in] Name of new node.</param>
    ///  <param name="Text">DOMString [in] Text stored in new node.</param>
    ///  <returns>IXMLNode - Requied new node.</returns>
    function CreateElement(const Parent: IXMLNode;
      const NodeName, Text: DOMString): IXMLNode; overload;

    ///  <summary>Loads XML document from data stored in byte array.</summary>
    ///  <param name="Bytes">TBytes [in] Array of bytes to load.</param>
    procedure LoadFromBytes(const Bytes: TBytes);

    ///  <summary>Stores content of XML document in byte array using encoding
    ///  specified in inherited Encoding property.</summary>
    ///  <returns>TBytes - Array of bytes storing XML document.</returns>
    function SaveToBytes: TBytes;
  end;


implementation


uses
  // Delphi
  Classes,
  // Project
  UIStringList;


{ TXMLDocumentEx }

function TXMLDocumentEx.FindChildNodes(const ParentNode: IXMLNode;
  const NodeName: DOMString): IXMLSimpleNodeList;
var
  NodeList: IXMLNodeList; // list of child nodes of parent
  Node: IXMLNode;         // a node from NodeList
  Idx: Integer;           // loops thru nodes of NodeList.
begin
  Assert(Assigned(ParentNode),
    ClassName + '.FindChildNodes: ParentNode is nil');
  Result := TXMLSimpleNodeList.Create;
  NodeList := ParentNode.ChildNodes;
  for Idx := 0 to Pred(NodeList.Count) do
  begin
    Node := NodeList[Idx];
    if (Node.NodeType = ntElement) and (Node.NodeName = NodeName) then
      Result.Add(Node);
  end;
end;

function TXMLDocumentEx.CreateElement(const Parent: IXMLNode;
  const NodeName: DOMString): IXMLNode;
begin
  Result := CreateNode(NodeName);
  Parent.ChildNodes.Add(Result);
end;

function TXMLDocumentEx.CreateElement(const Parent: IXMLNode; const NodeName,
  Text: DOMString): IXMLNode;
begin
  Result := CreateElement(Parent, NodeName);
  Result.Text := Text;
end;

function TXMLDocumentEx.FindChildNodes(const ParentNode: IXMLNode;
  const NodeName, AttribName: DOMString;
  const AttribValue: OleVariant): IXMLSimpleNodeList;
var
  NodeList: IXMLNodeList; // list of child nodes of parent
  Node: IXMLNode;         // a node from NodeList
  Idx: Integer;           // loops thru nodes of NodeList.
begin
  Assert(Assigned(ParentNode), ClassName + 'FindChildNodes: ParentNode is nil');
  Result := TXMLSimpleNodeList.Create;
  NodeList := ParentNode.ChildNodes;
  for Idx := 0 to Pred(NodeList.Count) do
  begin
    Node := NodeList[Idx];
    if (Node.NodeType = ntElement) and (Node.NodeName = NodeName)
      and (Node.Attributes[AttribName] = AttribValue) then
      Result.Add(Node);
  end;
end;

function TXMLDocumentEx.FindFirstChildNode(const ParentNode: IXMLNode;
  const NodeName: DOMString): IXMLNode;
begin
  Result := ParentNode.ChildNodes.FindNode(NodeName);
end;

function TXMLDocumentEx.FindFirstChildNode(const ParentNode: IXMLNode;
  const NodeName, AttribName: DOMString;
  const AttribValue: OleVariant): IXMLNode;
var
  Nodes: IXMLSimpleNodeList;  // list of all matching nodes
begin
  Nodes := FindChildNodes(ParentNode, NodeName, AttribName, AttribValue);
  if Nodes.Count > 0 then
    Result := Nodes[0]
  else
    Result := nil;
end;

function TXMLDocumentEx.FindNode(PathToNode: DOMString): IXMLNode;
var
  NodeNames: IStringList;   // list of names of nodes in path
  NodeName: string;         // name of a node in list
  NodeList: IXMLNodeList;   // list of child nodes of a node in path
  Node: IXMLNode;           // refers to each node in path
begin
  Node := nil;
  NodeList := Self.ChildNodes;
  NodeNames := TIStringList.Create(PathToNode, '\', False);
  for NodeName in NodeNames do
  begin
    Node := NodeList.FindNode(NodeName);
    if not Assigned(Node) then
      Break;
    NodeList := Node.ChildNodes;
  end;
  Result := Node;
end;

procedure TXMLDocumentEx.LoadFromBytes(const Bytes: TBytes);
var
  Stm: TBytesStream;  // stream used to perform actual loading
begin
  Stm := TBytesStream.Create(Bytes);
  try
    LoadFromStream(Stm);
  finally
    Stm.Free;
  end;
end;

function TXMLDocumentEx.SaveToBytes: TBytes;
var
  Stm: TBytesStream;  // stream to which XML doc writes data
begin
  Stm := TBytesStream.Create;
  try
    SaveToStream(Stm);
    Result := Stm.Bytes;
    // we need to set length because Stm.Bytes may have many trailing 0 bytes
    SetLength(Result, Stm.Size);
  finally
    Stm.Free;
  end;
end;

{ TXMLSimpleNodeList }

function TXMLSimpleNodeList.Add(const Node: IXMLNode): Integer;
begin
  Result := fList.Add(Node);
end;

function TXMLSimpleNodeList.Count: Integer;
begin
  Result := fList.Count;
end;

constructor TXMLSimpleNodeList.Create;
begin
  inherited;
  fList := TList<IXMLNode>.Create;
end;

destructor TXMLSimpleNodeList.Destroy;
begin
  fList.Free;
  inherited;
end;

function TXMLSimpleNodeList.GetEnumerator: TEnumerator<IXMLNode>;
begin
  Result := fList.GetEnumerator;
end;

function TXMLSimpleNodeList.GetItem(Idx: Integer): IXMLNode;
begin
  Result := fList[Idx];
end;

end.