omnixmlutils.pas

OmniXML源码

{ $OmniXML: OmniXML/OmniXMLUtils.pas,v 1.1.1.1 2004/04/17 11:16:33 mr Exp $ }

(*:XML helper unit. Contains routines to convert data, retrieve/set data of
   different types, manipulate nodes, load/save XML documents.
   @author Primoz Gabrijelcic
   @desc <pre>
   (c) 2002 Primoz Gabrijelcic
   Free for personal and commercial use. No rights reserved.

   Author            : Primoz Gabrijelcic
   Creation date     : 2001-10-25
   Last modification : 2004-04-07
   Version           : 1.23
</pre>*)(*
   History:
     1.23: 2004-04-07
       - Added functions GetNodeTextFont and SetNodeTextFont.
     1.22a: 2004-04-07
       - Modified XMLBinaryToStr to always process entire stream.
       - Modified XMLStrToBinary to clear output stream at beginning.
     1.22: 2004-04-05
       - Added overloaded versions of GetNodeText and GetNodeCData.
     1.21: 2004-03-27
       - Added function AppendNode.
     1.20a: 2004-03-25
       - Fixed broken format strings (used for error reporting) in various XMLStrTo*
         functions.
     1.20: 2004-03-23
       - Added two more variants of Base64Encode and Base64Decode.
     1.19: 2004-03-01
       - GetNodeText*, GetNodeAttr*, and XMLStrTo* families extended with overloaded
         versions without a default value, raising exception on invalid/missing XML node.
     1.18: 2004-01-16
       - Functions OwnerDocument and DocumentElement made public.
     1.17: 2004-01-05
       - Remove some unnecessary 'overload' directives.
       - Added functions XMLStrToCurrency, XMLStrToCurrencyDef, XMLVariantToStr,
         and XMLCurrencyToStr.
       - Added function FindProcessingInstruction.
       - Added functions XMLSaveToAnsiString, XMLLoadFromAnsiString.
       - Fixed XMLSaveToString which incorrectly returned UTF8 string instead of
         UTF16.
     1.16: 2003-12-12
       - GetTextChild and SetTextChild made public.
       - New functions GetCDataChild and SetCDataChild.
       - New functions GetNodeCData and SetNodeCData.
       - New functions MoveNode and RenameNode.
       - Added functions XMLStrToExtended, XMLStrToExtendedDef, and
         XMLExtendedToStr.
     1.15b: 2003-10-01
       - Fixed another bug in SelectNode and EnsureNode (broken since 1.15).
     1.15a: 2003-09-22
       - Fixed bug in SelectNode and EnsureNode (broken since 1.15).
     1.15: 2003-09-21
       - Added function SelectNode.
     1.14: 2003-05-08
       - Overloaded Base64Encode, Base64Decode to work with strings too.
     1.13: 2003-04-01
       - Filter* and Find* routines modified to skip all non-ELEMENT_NODE nodes.
     1.12b: 2003-01-15
       - Safer implementation of some internal functions.
     1.12a: 2003-01-13
       - Adapted for latest fixes in OmniXML 2002-01-13.
     1.12: 2003-01-13
       - CopyNode, and CloneDocument made MS XML compatible.
       - Automatic DocumentElement dereferencing now works with MS XML.
     1.11: 2003-01-13
       - Fixed buggy GetNode(s)Text*/SetNode(s)Text* functions.
       - Fixed buggy CopyNode and CloneDocument.
     1.10a: 2003-01-09
       - Fixed filterProc support in the CopyNode.
     1.10: 2003-01-07
       - Added functions XMLLoadFromRegistry and XMLSaveToRegistry.
       - Added function CloneDocument.
       - Added parameter filterProc to the CopyNode procedure.
       - Smarter GetNodeAttr (automatically dereferences DocumentElement if
         root xml node is passed to it).
     1.09: 2002-12-26
       - Added procedure CopyNode that copies contents of one node into another.
       - Modified DeleteAllChildren to preserve Text property.
     1.08: 2002-12-21
       - Smarter GetNodeText (automatically dereferences DocumentElement if
         root xml node is passed to it).
     1.07a: 2002-12-10
       - Bug fixed in XMLSaveToString (broken since 1.06).
     1.07: 2002-12-09
       - Added XMLLoadFromFile and XMLSaveToFile.
       - Small code cleanup.
     1.06: 2002-12-09
       - MSXML compatible (define USE_MSXML).
     1.05a: 2002-11-23
       - Fixed bug in Base64Decode.
     1.05: 2002-11-05
       - Added function ConstructXMLDocument.
     1.04: 2002-10-03
       - Added function EnsureNode.
     1.03: 2002-09-24
       - Added procedure SetNodesText.
     1.02: 2002-09-23
       - SetNode* familiy of procedures changed into functions returning the
         modified node.
     1.01: 2001-11-07
       - (mr) Added function XMLDateTimeToStrEx.
       - (mr) ISODateTime2DateTime enhanced.
       - (mr) Bug fixed in Str2Time.
     1.0: 2001-10-25
       - Created by extracting common utilities from unit GpXML.
*)

unit OmniXMLUtils;

interface

{$I OmniXML.inc}

uses
{$IFDEF MSWINDOWS}
  Windows,
{$ENDIF}
  SysUtils,
  Classes,
  Graphics,
  OmniXML
{$IFDEF USE_MSXML}
  ,OmniXML_MSXML
{$ENDIF USE_MSXML}
{$IFDEF DELPHI6_UP}
  ,Variants
{$ENDIF DELPHI6_UP}
  ;

type
  {:Base class for OmniXMLUtils exceptions.
    @since   2004-03-01
  }
  EOmniXMLUtils = class(Exception);

  {:Delete the specified node.
  }
  procedure DeleteNode(parentNode: IXMLNode; nodeTag: string);

  {:Delete all/some children of the specified node.
  }
  procedure DeleteAllChildren(parentNode: IXMLNode; pattern: string = '');

  {:Retrive text child of the specified node.
  }
  function GetTextChild(node: IXMLNode): IXMLNode;

  {:Retrive CDATA child of the specified node.
  }
  function GetCDataChild(node: IXMLNode): IXMLNode;

  {:Returns CDATA value of the specified node.
  }
  function GetNodeCData(parentNode: IXMLNode; nodeTag: string;
    defaultValue: WideString): WideString; overload;

  {:Returns CDATA value of the specified node.
  }
  function GetNodeCData(node: IXMLNode): WideString; overload;

  {:Returns text of the specified node. Result is True if node exists, False
    otherwise.
  }
  function GetNodeText(parentNode: IXMLNode; nodeTag: string;
    var nodeText: WideString): boolean; overload;

  {:Returns text of the specified node. Result is True if node exists, False
    otherwise.
  }
  function GetNodeText(node: IXMLNode): WideString; overload;

  {:Returns texts of all child nodes into the string list. Text for each child
    is trimmed before it is stored in the list. Caller must create result list
    in advance.
  }
  procedure GetNodesText(parentNode: IXMLNode; nodeTag: string;
    {var} nodesText: TStrings); overload;

  {:Returns texts of all child nodes as a CRLF-delimited string.
  }
  procedure GetNodesText(parentNode: IXMLNode; nodeTag: string;
    var nodesText: string); overload;

  {:A family of functions that will return node text reformatted into another
    type or default value if node doesn't exist or if node text is not in a
    proper format. Basically they all call GetNodeText and convert the result.
  }
  function GetNodeTextStr(parentNode: IXMLNode; nodeTag: string; defaultValue: WideString): WideString; overload;
  function GetNodeTextReal(parentNode: IXMLNode; nodeTag: string; defaultValue: real): real; overload;
  function GetNodeTextInt(parentNode: IXMLNode; nodeTag: string; defaultValue: integer): integer; overload;
  function GetNodeTextInt64(parentNode: IXMLNode; nodeTag: string; defaultValue: int64): int64; overload;
  function GetNodeTextBool(parentNode: IXMLNode; nodeTag: string; defaultValue: boolean): boolean; overload;
  function GetNodeTextDateTime(parentNode: IXMLNode; nodeTag: string; defaultValue: TDateTime): TDateTime; overload;
  function GetNodeTextDate(parentNode: IXMLNode; nodeTag: string; defaultValue: TDateTime): TDateTime; overload;
  function GetNodeTextTime(parentNode: IXMLNode; nodeTag: string; defaultValue: TDateTime): TDateTime; overload;
  function GetNodeTextBinary(parentNode: IXMLNode; nodeTag: string; value: TStream): boolean;
  function GetNodeTextFont(parentNode: IXMLNode; nodeTag: string; value: TFont): boolean;

  {:A family of functions that will return node text reformatted into another
    type or raise exception if node doesn't exist or if node text is not in a
    proper format. Basically they all call GetNodeText and convert the result.
  }
  function GetNodeTextStr(parentNode: IXMLNode; nodeTag: string): WideString; overload;
  function GetNodeTextReal(parentNode: IXMLNode; nodeTag: string): real; overload;
  function GetNodeTextInt(parentNode: IXMLNode; nodeTag: string): integer; overload;
  function GetNodeTextInt64(parentNode: IXMLNode; nodeTag: string): int64; overload;
  function GetNodeTextBool(parentNode: IXMLNode; nodeTag: string): boolean; overload;
  function GetNodeTextDateTime(parentNode: IXMLNode; nodeTag: string): TDateTime; overload;
  function GetNodeTextDate(parentNode: IXMLNode; nodeTag: string): TDateTime; overload;
  function GetNodeTextTime(parentNode: IXMLNode; nodeTag: string): TDateTime; overload;

  {:Returns value of the specified attribute. Result is True if attribute
    exists, False otherwise.
  }
  function GetNodeAttr(parentNode: IXMLNode; attrName: string;
    var value: WideString): boolean;
    
  {:A family of functions that will return attribute value reformatted into
    another type or default value if attribute doesn't exist or if attribute
    is not in a proper format. Basically they all call GetNodeAttr and
    convert the result.
  }
  function GetNodeAttrStr(parentNode: IXMLNode; attrName: string; defaultValue: WideString): WideString; overload;
  function GetNodeAttrReal(parentNode: IXMLNode; attrName: string; defaultValue: real): real; overload;
  function GetNodeAttrInt(parentNode: IXMLNode; attrName: string; defaultValue: integer): integer; overload;
  function GetNodeAttrInt64(parentNode: IXMLNode; attrName: string; defaultValue: int64): int64; overload;
  function GetNodeAttrBool(parentNode: IXMLNode; attrName: string; defaultValue: boolean): boolean; overload;
  function GetNodeAttrDateTime(parentNode: IXMLNode; attrName: string; defaultValue: TDateTime): TDateTime; overload;
  function GetNodeAttrDate(parentNode: IXMLNode; attrName: string; defaultValue: TDateTime): TDateTime; overload;
  function GetNodeAttrTime(parentNode: IXMLNode; attrName: string; defaultValue: TDateTime): TDateTime; overload;

  {:A family of functions that will return attribute value reformatted into
    another type or raise exception if attribute doesn't exist or if attribute
    is not in a proper format. Basically they all call GetNodeAttr and
    convert the result.
  }
  function GetNodeAttrStr(parentNode: IXMLNode; attrName: string): WideString; overload;
  function GetNodeAttrReal(parentNode: IXMLNode; attrName: string): real; overload;
  function GetNodeAttrInt(parentNode: IXMLNode; attrName: string): integer; overload;
  function GetNodeAttrInt64(parentNode: IXMLNode; attrName: string): int64; overload;
  function GetNodeAttrBool(parentNode: IXMLNode; attrName: string): boolean; overload;
  function GetNodeAttrDateTime(parentNode: IXMLNode; attrName: string): TDateTime; overload;
  function GetNodeAttrDate(parentNode: IXMLNode; attrName: string): TDateTime; overload;
  function GetNodeAttrTime(parentNode: IXMLNode; attrName: string): TDateTime; overload;

  {:A family of functions used to convert string to some other value according
    to the conversion rules used in this unit. Used in Get* functions above.
  }
  function XMLStrToReal(nodeValue: WideString; var value: real): boolean; overload;
  function XMLStrToReal(nodeValue: WideString): real; overload;
  function XMLStrToRealDef(nodeValue: WideString; defaultValue: real): real;
  function XMLStrToExtended(nodeValue: WideString; var value: extended): boolean; overload;
  function XMLStrToExtended(nodeValue: WideString): extended; overload;
  function XMLStrToExtendedDef(nodeValue: WideString; defaultValue: extended): extended;
  function XMLStrToCurrency(nodeValue: WideString; var value: Currency): boolean; overload;
  function XMLStrToCurrency(nodeValue: WideString): Currency; overload;
  function XMLStrToCurrencyDef(nodeValue: WideString; defaultValue: Currency): Currency;
  function XMLStrToInt(nodeValue: WideString; var value: integer): boolean; overload;
  function XMLStrToInt(nodeValue: WideString): integer; overload;
  function XMLStrToIntDef(nodeValue: WideString; defaultValue: integer): integer;
  function XMLStrToInt64(nodeValue: WideString; var value: int64): boolean; overload;
  function XMLStrToInt64(nodeValue: WideString): int64; overload;
  function XMLStrToInt64Def(nodeValue: WideString; defaultValue: int64): int64;
  function XMLStrToBool(nodeValue: WideString; var value: boolean): boolean; overload;
  function XMLStrToBool(nodeValue: WideString): boolean; overload;
  function XMLStrToBoolDef(nodeValue: WideString; defaultValue: boolean): boolean;
  function XMLStrToDateTime(nodeValue: WideString; var value: TDateTime): boolean; overload;
  function XMLStrToDateTime(nodeValue: WideString): TDateTime; overload;
  function XMLStrToDateTimeDef(nodeValue: WideString; defaultValue: TDateTime): TDateTime;
  function XMLStrToDate(nodeValue: WideString; var value: TDateTime): boolean; overload;
  function XMLStrToDate(nodeValue: WideString): TDateTime; overload;
  function XMLStrToDateDef(nodeValue: WideString; defaultValue: TDateTime): TDateTime;
  function XMLStrToTime(nodeValue: WideString; var value: TDateTime): boolean; overload;
  function XMLStrToTime(nodeValue: WideString): TDateTime; overload;
  function XMLStrToTimeDef(nodeValue: WideString; defaultValue: TDateTime): TDateTime;
  function XMLStrToBinary(nodeValue: WideString; const value: TStream): boolean;

  {:Creates the node if it doesn't exist, then sets node CDATA to the specified
    value.
  }
  function SetNodeCData(parentNode: IXMLNode; nodeTag: string;
    value: WideString): IXMLNode;

  {:Creates the node if it doesn't exist, then sets node text to the specified
    value.
  }
  function SetNodeText(parentNode: IXMLNode; nodeTag: string;
    value: WideString): IXMLNode;

  {:Sets texts for many child nodes. All nodes are created anew.
  }
  procedure SetNodesText(parentNode: IXMLNode; nodeTag: string;
    nodesText: TStrings); overload;

  {:Sets texts for many child nodes. All nodes are created anew.
    @param nodesText Contains CRLF-delimited text list.
  }
  procedure SetNodesText(parentNode: IXMLNode; nodeTag: string;
    nodesText: string); overload;

  {:A family of functions that will first check that the node exists (creating
    it if necessary) and then set node text to the properly formatted value.
    Basically they all reformat the value to the string and then call
    SetNodeText.
  }
  function SetNodeTextStr(parentNode: IXMLNode; nodeTag: string;
    value: WideString): IXMLNode;
  function SetNodeTextValueStr(parentNode: IXMLNode; nodeTag: string;
    value: WideString): IXMLNode;
  function SetNodeTextReal(parentNode: IXMLNode; nodeTag: string;
    value: real): IXMLNode;
  function SetNodeTextValueReal(parentNode: IXMLNode; nodeTag: string;
    value: real): IXMLNode;
  function SetNodeTextInt(parentNode: IXMLNode; nodeTag: string;
    value: integer): IXMLNode; 
  function SetNodeTextValueInt(parentNode: IXMLNode; nodeTag: string;
    value: integer): IXMLNode;
  function SetNodeTextInt64(parentNode: IXMLNode; nodeTag: string;
    value: int64): IXMLNode;
  function SetNodeTextBool(parentNode: IXMLNode; nodeTag: string;
    value: boolean): IXMLNode;
  function SetNodeTextDateTime(parentNode: IXMLNode; nodeTag: string;
    value: TDateTime): IXMLNode;
  function SetNodeTextDate(parentNode: IXMLNode; nodeTag: string;
    value: TDateTime): IXMLNode;
  function SetNodeTextTime(parentNode: IXMLNode; nodeTag: string;
    value: TDateTime): IXMLNode;
  function SetNodeTextBinary(parentNode: IXMLNode; nodeTag: string;
    const value: TStream): IXMLNode;
  function SetNodeTextFont(parentNode: IXMLNode; nodeTag: string;
    value: TFont): IXMLNode;

  {:Set the value of the text child and return its interface.
  }
  function SetTextChild(node: IXMLNode; value: WideString): IXMLNode;

  {:Set the value of the CDATA child and return its interface.
  }
  function SetCDataChild(node: IXMLNode; value: WideString): IXMLNode;

  {:Creates the attribute if it doesn't exist, then sets it to the specified
    value.
  }
  procedure SetNodeAttr(parentNode: IXMLNode; attrName: string;
    value: WideString);

  {:A family of functions that will first check that the attribute exists
    (creating it if necessary) and then set attribute's value to the properly
    formatted value. Basically they all reformat the value to the string and
    then call SetNodeAttr.
  }
  procedure SetNodeAttrStr(parentNode: IXMLNode; attrName: string;
    value: WideString);
  procedure SetNodeAttrReal(parentNode: IXMLNode; attrName: string;
    value: real);
  procedure SetNodeAttrInt(parentNode: IXMLNode; attrName: string;
    value: integer);
  procedure SetNodeAttrValueInt(parentNode: IXMLNode; attrName: string;
    value: integer);
  procedure SetNodeAttrInt64(parentNode: IXMLNode; attrName: string;
    value: int64);
  procedure SetNodeAttrBool(parentNode: IXMLNode; attrName: string;
    value: boolean);
  procedure SetNodeAttrDateTime(parentNode: IXMLNode; attrName: string;
    value: TDateTime);
  procedure SetNodeAttrDate(parentNode: IXMLNode; attrName: string;
    value: TDateTime);
  procedure SetNodeAttrTime(parentNode: IXMLNode; attrName: string;
    value: TDateTime);

  {:A family of functions used to convert value to string according to the
    conversion rules used in this unit. Used in Set* functions above.
  }
  function XMLRealToStr(value: real): WideString;
  function XMLExtendedToStr(value: extended): WideString;
  function XMLCurrencyToStr(value: Currency): WideString;
  function XMLIntToStr(value: integer): WideString;
  function XMLInt64ToStr(value: int64): WideString;
  function XMLBoolToStr(value: boolean): WideString;
  function XMLDateTimeToStr(value: TDateTime): WideString;
  function XMLDateTimeToStrEx(value: TDateTime): WideString;