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 a static class that helps with input and output to CodeSnip XML
 * documents.
}


unit UXMLDocHelper;


interface


uses
  // Delphi
  XMLIntf,
  // Project
  Compilers.UGlobals, DB.USnippetKind, UExceptions, UIStringList, UStructs,
  UXMLDocumentEx;


type

  {
  TXMLDocHelper:
    Static class that helps with input and output to CodeSnip XML documents.
    Provides functionality common to two or more XML read/write classes.
  }
  TXMLDocHelper = class(TObject)
  strict private
    class function FindRootNodeType(const XMLDoc: IXMLDocumentEx;
      const ANodeType: TNodeType): IXMLNode;
      {Finds a specified type of root node.
        @param XMLDoc [in] Document containing node.
        @param ANodeType [in] Type of node required.
        @return Reference to found node or nil if no node found.
      }
  public
    class function CreateXMLDoc: IXMLDocumentEx;
      {Creates a new XML document object with required properties.
        @return New XML document object.
      }
    class procedure CreateXMLProcInst(const XMLDoc: IXMLDocumentEx);
      {Creates xml processing instruction in document.
        @param XMLDoc [in] Document in which processing instruction is inserted.
      }
    class procedure CreateComment(const XMLDoc: IXMLDocumentEx;
      const Comment: string);
      {Creates a comment at the top level of an XML document.
        @param XMLDoc [in] Document in which comment is inserted.
        @param Comment [in] Comment to be inserted.
      }
    class function CreateRootNode(const XMLDoc: IXMLDocumentEx;
      const NodeName, Watermark: string; const Version: Integer): IXMLNode;
      {Creates a root in XML document.
        @param XMLDoc [in] Document in which to insert root node.
        @param NodeName [in] Name of root node.
        @param Watermark [in] Value of root node's "watermark" attribute.
        @param Version [in] Value of root node's "version" attribute.
        @return Reference to new root node.
      }
    class function GetSubTagText(const XMLDoc: IXMLDocumentEx;
      const ParentNode: IXMLNode; const SubTagName: string): string;
      {Gets text of subtag of a parent node in an XML document.
        @param XMLDoc [in] XML document containing sub tag.
        @param ParentNode [in] Parent node of sub tag.
        @param SubTagName [in] Name of desired subtag.
        @return Sub tag's text if sub tag exists and is a text node, ''
          otherwise.
      }
    class procedure GetPascalNameList(const XMLDoc: IXMLDocumentEx;
      const ListNode: IXMLNode; const NameList: IStringList);
      {Gets a list of names in <pascal-name> elements with a list.
        @param XMLDoc [in] XML document containing name list.
        @param ListNode [in] Node that contains list.
        @param NameList [in] Receives text of all <pascal-name> elements in
          list.
      }
    class function GetCompilerResults(const XMLDoc: IXMLDocumentEx;
      const SnippetNode: IXMLNode): TCompileResults;
      {Gets compiler results for a snippet in an XML document.
        @param XMLDoc [in] XML document containing snippet.
        @param SnippetNode [in] Document node that contains compiler results
          tag.
        @return Array of compiler results. Provides defaults for missing
          compilers.
      }
    class function GetStandardFormat(const XMLDoc: IXMLDocumentEx;
      const SnippetNode: IXMLNode; const Default: Boolean): Boolean;
      {Gets value of a <standard-format> node of a snippet in an XML document.
        @param XMLDoc [in] XML document containing snippet.
        @param SnippetNode [in] Snippet node that contains standard format tag.
        @param Default [in] Value to use if node doesn't exist or has
          non-standard value.
        @return Value of node, or default value.
      }
    class function GetSnippetKind(const XMLDoc: IXMLDocumentEx;
      const SnippetNode: IXMLNode; const Default: TSnippetKind): TSnippetKind;
      {Gets value of <kind> node of a snippet in an XML document.
        @param XMLDoc [in] XML document containing snippet.
        @param SnippetNode [in] Snippet node that contains kind tag.
        @param Default [in] Value to use if node doesn't exist or has
          non-standard value.
        @return Required snippet kind.
      }
    class function GetHiliteSource(const XMLDoc: IXMLDocumentEx;
      const SnippetNode: IXMLNode; const Default: Boolean): Boolean;
      {Gets value of a <highlight-source> node of a snippet in an XML document.
        @param XMLDoc [in] XML document containing snippet.
        @param SnippetNode [in] Snippet node that contains highlight source tag.
        @param Default [in] Value to use if node doesn't exist or has
          non-standard value.
        @return Value of node, or default value.
      }
    class procedure WriteCompilerResults(const XMLDoc: IXMLDocumentEx;
      const SnippetNode: IXMLNode; const CompRes: TCompileResults);
      {Writes compile results for a snippet to XML document.
        @param XMLDoc [in] XML document to receive compile results.
        @param SnippetNode [in] Node containing snippet that received compile
          results.
        @param CompRes [in] Array of compiler results.
      }
    class procedure WritePascalNameList(const XMLDoc: IXMLDocumentEx;
      const Parent: IXMLNode; const ListName: string; const Names: IStringList);
      {Writes a Pascal name list to an XML document.
        @param XMLDoc [in] XML document to which list is written.
        @param Parent [in] Parent node that is to contain name list.
        @param ListName [in] Name of new list node that is parent of list.
        @param Names [in] List of Pascal names.
      }
    class procedure WriteSnippetKind(const XMLDoc: IXMLDocumentEx;
      const SnippetNode: IXMLNode; const Value: TSnippetKind);
      {Writes a <kind> node to a an XML document.
        @param XMLDoc [in] XML document to receive the node.
        @param SnippetNode [in] Node containing snippet that receives kind node.
        @param Value [in] Value of <kind> node.
      }
    class function ValidateRootNode(const XMLDoc: IXMLDocumentEx;
      const ANodeName, AWatermark: string; const AVersions: TRange): Integer;
      {Validates the root node of an XML document.
        @param XMLDoc [in] XML document to be validated.
        @param ANodeName [in] Name of root mode.
        @param AWatermark [in] Required value of root node's "watermark"
          attribute.
        @param AVersions [in] Range of acceptable file version numbers.
        @return Document version.
        @except ECodeSnipXML raised on error.
      }
    class procedure ValidateProcessingInstr(const XMLDoc: IXMLDocumentEx);
      {Checks that an XML document has a valid xml processing instruction.
        @param XMLDoc [in] Document to be checked.
        @except ECodeSnipXML raised on error.
      }
  end;

  {
  ECodeSnipXML:
    Class of exception raised by TXMLDocHelper validation methods.
  }
  ECodeSnipXML = class(ECodeSnip);


implementation


uses
  // Delphi
  Windows {for inlining},
  // Project
  UStrUtils, UXMLDocConsts;


{ TXMLDocHelper }

class procedure TXMLDocHelper.CreateComment(const XMLDoc: IXMLDocumentEx;
  const Comment: string);
  {Creates a comment at the top level of an XML document.
    @param XMLDoc [in] Document in which comment is inserted.
    @param Comment [in] Comment to be inserted.
  }
begin
  XMLDoc.ChildNodes.Add(XMLDoc.CreateNode(' ' + Comment + ' ', ntComment));
end;

class function TXMLDocHelper.CreateRootNode(const XMLDoc: IXMLDocumentEx;
  const NodeName, Watermark: string; const Version: Integer): IXMLNode;
  {Creates a root in XML document.
    @param XMLDoc [in] Document in which to insert root node.
    @param NodeName [in] Name of root node.
    @param Watermark [in] Value of root node's "watermark" attribute.
    @param Version [in] Value of root node's "version" attribute.
    @return Reference to new root node.
  }
begin
  Result := XMLDoc.CreateNode(NodeName);
  Result.SetAttribute(cRootWatermarkAttr, Watermark);
  Result.SetAttribute(cRootVersionAttr, Version);
  XMLDoc.ChildNodes.Add(Result);
end;

class function TXMLDocHelper.CreateXMLDoc: IXMLDocumentEx;
  {Creates a new XML document object with required properties.
    @return New XML document object.
  }
begin
  Result := TXMLDocumentEx.Create(nil);
  Result.Options := [doNodeAutoIndent];
  Result.ParseOptions := [poPreserveWhiteSpace];
end;

class procedure TXMLDocHelper.CreateXMLProcInst(const XMLDoc: IXMLDocumentEx);
  {Creates xml processing instruction in document.
    @param XMLDoc [in] Document in which processing instruction is inserted.
  }
begin
  XMLDoc.ChildNodes.Add(
    XMLDoc.CreateNode(cXMLNode, ntProcessingInstr, cXMLNodeText)
  );
end;

class function TXMLDocHelper.FindRootNodeType(const XMLDoc: IXMLDocumentEx;
  const ANodeType: TNodeType): IXMLNode;
  {Finds a specified type of root node.
    @param XMLDoc [in] Document containing node.
    @param ANodeType [in] Type of node required.
    @return Reference to found node or nil if no node found.
  }
var
  Idx: Integer; // loops thru immediate child nodes of xml document
begin
  Result := nil;
  for Idx := 0 to Pred(XMLDoc.ChildNodes.Count) do
  begin
    if XMLDoc.ChildNodes.Nodes[Idx].NodeType = ANodeType then
    begin
      Result := XMLDoc.ChildNodes.Nodes[Idx];
      Break;
    end;
  end;
end;

class function TXMLDocHelper.GetCompilerResults(const XMLDoc: IXMLDocumentEx;
  const SnippetNode: IXMLNode): TCompileResults;
  {Gets compiler results for a snippet in an XML document.
    @param XMLDoc [in] XML document containing snippet.
    @param SnippetNode [in] Document node that contains compiler results tag.
    @return Array of compiler results. Provides defaults for missing compilers.
  }

  // -------------------------------------------------------------------------
  function IDStrToCompID(const IDStr: string;
    out Match: TCompilerID): Boolean;
    {Converts an identifier string to a compiler ID.
      @param IDStr [in] Identifier string.
      @param Match [out] Set to compiler ID that matches IDStr. Undefined if
        IDStr not recognised.
      @return True if IDStr is recognised, False if not.
    }
  var
    CompID: TCompilerID;  // loops thru all compiler IDs
  begin
    Result := False;
    for CompID := Low(TCompilerID) to High(TCompilerID) do
    begin
      if cCompilerIDs[CompID] = IDStr then
      begin
        Result := True;
        Match := CompID;
        Break;
      end;
    end;
  end;
  // -------------------------------------------------------------------------

var
  ListNode: IXMLNode;               // node that enclose compiler result nodes
  ResultsNodes: IXMLSimpleNodeList; // list of compiler-result nodes
  ResultNode: IXMLNode;             // a compiler-result node
  CompID: TCompilerID;              // loops thru compiler IDs
  CompResultStr: string;            // compiler id string from result node
begin
  // Initialise all results to unknown (query)
  for CompID := Low(TCompilerID) to High(TCompilerID) do
    Result[CompID] := crQuery;

  // Find enclosing node: valid if this is not present
  ListNode := XMLDoc.FindFirstChildNode(SnippetNode, cCompilerResultsNode);
  if not Assigned(ListNode) then
    Exit;

  // Get list of compiler-result nodes contained in list and process each one
  ResultsNodes := XMLDoc.FindChildNodes(ListNode, cCompilerResultNode);
  for ResultNode in ResultsNodes do
  begin
    if ResultNode.IsTextElement then
    begin
      // get compile result identifier
      CompResultStr := ResultNode.Text;
      if CompResultStr = '' then
        CompResultStr := '?';
      // add specified result function result
      if IDStrToCompID(
        ResultNode.Attributes[cCompilerResultIdAttr], CompID
      ) then
      begin
        case CompResultStr[1] of
          'Y': Result[CompID] := crSuccess;
          'N': Result[CompID] := crError;
          'W': Result[CompiD] := crWarning;
          else Result[CompID] := crQuery;
        end;
      end;
    end;
  end;
end;

class function TXMLDocHelper.GetHiliteSource(const XMLDoc: IXMLDocumentEx;
  const SnippetNode: IXMLNode; const Default: Boolean): Boolean;
  {Gets value of a <highlight-source> node of a snippet in an XML document.
    @param XMLDoc [in] XML document containing snippet.
    @param SnippetNode [in] Snippet node that contains highlight source tag.
    @param Default [in] Value to use if node doesn't exist or has non-standard
      value.
    @return Value of node, or default value.
  }
var
  Value: string;  // text value of HiliteSource node
begin
  Value := GetSubTagText(XMLDoc, SnippetNode, cHighlightSource);
  if Value <> '' then
    Result := Value <> '0'
  else
    Result := Default;
end;

class procedure TXMLDocHelper.GetPascalNameList(const XMLDoc: IXMLDocumentEx;
  const ListNode: IXMLNode; const NameList: IStringList);
  {Gets a list of names in <pascal-name> elements with a list.
    @param XMLDoc [in] XML document containing name list.
    @param ListNode [in] Node that contains list.
    @param NameList [in] Receives text of all <pascal-name> elements in list.
  }
var
  NameNode: IXMLNode;             // name of a node in the list
  NodeList: IXMLSimpleNodeList;   // list of matching child nodes if ListNode
begin
  NameList.Clear;
  if not Assigned(ListNode) then
    Exit;   // this is permitted since snippet lists can be empty or missing
  NodeList := XMLDoc.FindChildNodes(ListNode, cPascalNameNode);
  for NameNode in NodeList do
    if NameNode.IsTextElement then
      NameList.Add(NameNode.Text);
end;

class function TXMLDocHelper.GetSnippetKind(const XMLDoc: IXMLDocumentEx;
  const SnippetNode: IXMLNode; const Default: TSnippetKind): TSnippetKind;
  {Gets value of <kind> node of a snippet in an XML document.
    @param XMLDoc [in] XML document containing snippet.
    @param SnippetNode [in] Snippet node that contains kind tag.
    @param Default [in] Value to use if node doesn't exist or has non-standard
      value.
    @return Required snippet kind.
  }
var
  Value: string;  // text value of Kind node
begin
  Value := GetSubTagText(XMLDoc, SnippetNode, cKindNode);
  if StrSameText(Value, 'freeform') then
    Result := skFreeform
  else if StrSameText(Value, 'routine') then
    Result := skRoutine
  else if StrSameText(Value, 'const') then
    Result := skConstant
  else if StrSameText(Value, 'type') then
    Result := skTypeDef
  else if StrSameText(Value, 'unit') then
    Result := skUnit
  else if StrSameText(Value, 'class') then
    Result := skClass
  else
    Result := Default;
end;

class function TXMLDocHelper.GetStandardFormat(const XMLDoc: IXMLDocumentEx;
  const SnippetNode: IXMLNode; const Default: Boolean): Boolean;
  {Gets value of a <standard-format> node of a snippet in an XML document.
    @param XMLDoc [in] XML document containing snippet.
    @param SnippetNode [in] Snippet node that contains standard format tag.
    @param Default [in] Value to use if node doesn't exist or has non-standard
      value.
    @return Value of node, or default value.
  }
var
  Value: string;  // text value of Kind node
begin
  Value := GetSubTagText(XMLDoc, SnippetNode, cStandardFormatNode);
  if Value <> '' then
    Result := Value <> '0'
  else
    Result := Default;
end;

class function TXMLDocHelper.GetSubTagText(const XMLDoc: IXMLDocumentEx;
  const ParentNode: IXMLNode; const SubTagName: string): string;
  {Gets text of subtag of a parent node in an XML document.
    @param XMLDoc [in] XML document containing sub tag.
    @param ParentNode [in] Parent node of sub tag.
    @param SubTagName [in] Name of desired subtag.
    @return Sub tag's text if sub tag exists and is a text node, '' otherwise.
  }
var
  PropNode: IXMLNode; // sub tag's node
begin
  Result := '';
  PropNode := XMLDoc.FindFirstChildNode(ParentNode, SubTagName);
  if Assigned(PropNode) and (PropNode.IsTextElement) then
    Result := PropNode.Text;
end;

class procedure TXMLDocHelper.ValidateProcessingInstr(
  const XMLDoc: IXMLDocumentEx);
  {Checks that an XML document has a valid xml processing instruction.
    @param XMLDoc [in] Document to be checked.
    @except ECodeSnipXML raised on error.
  }
var
  XMLNode: IXMLNOde;  // xml processing node
resourcestring
  // Error messages
  sNoXMLProcInst = 'Invalid document: must begin with a valid XML processing '
    + 'instruction';
begin
  // Must have correct processing instruction (<?xml .... ?>)
  XMLNode := FindRootNodeType(XMLDoc, ntProcessingInstr);
  if not Assigned(XMLNode) or (XMLNode.NodeName <> cXMLNode)
    or (XMLNode.NodeType <> ntProcessingInstr) then
    raise ECodeSnipXML.Create(sNoXMLProcInst);
end;

class function TXMLDocHelper.ValidateRootNode(const XMLDoc: IXMLDocumentEx;
  const ANodeName, AWatermark: string; const AVersions: TRange): Integer;
  {Validates the root node of an XML document.
    @param XMLDoc [in] XML document to be validated.
    @param ANodeName [in] Name of root mode.
    @param AWatermark [in] Required value of root node's "watermark" attribute.
    @param AVersions [in] Range of acceptable file version numbers.
    @return Document version.
    @except ECodeSnipXML raised on error.
  }
var
  RootNode: IXMLNode; // document root node
resourcestring
  // Error messages
  sNoRootNode = 'Invalid document: no root element present';
  sBadRootName = 'Invalid document: root element must be named <%s>';
  sBadWatermark = 'Invalid document: watermark is incorrect';
  sBadVersion = 'Invalid document: unsupported document version %d';
begin
  RootNode := XMLDoc.DocumentElement;
  // There must be a root node
  if not Assigned(RootNode) then
    raise ECodeSnipXML.Create(sNoRootNode);
  // Correct root node must be present, with valid watermark and version
  if RootNode.NodeName <> ANodeName then
    raise ECodeSnipXML.CreateFmt(sBadRootName, [ANodeName]);
  if RootNode.Attributes[cRootWatermarkAttr] <> AWatermark then
    raise ECodeSnipXML.Create(sBadWatermark);
  Result := RootNode.Attributes[cRootVersionAttr];
  if not AVersions.Contains(Result) then
    raise ECodeSnipXML.CreateFmt(sBadVersion, [Result]);
end;

class procedure TXMLDocHelper.WriteCompilerResults(const XMLDoc: IXMLDocumentEx;
  const SnippetNode: IXMLNode; const CompRes: TCompileResults);
  {Writes compile results for a snippet to XML document.
    @param XMLDoc [in] XML document to receive compile results.
    @param SnippetNode [in] Node containing snippet that received compile
      results.
    @param CompRes [in] Array of compiler results.
  }
const
  // map of compiler results onto character representation store in XML file.
  cCompResMap: array[TCompileResult] of Char = ('Y', 'W', 'N', '?');
var
  CompResultsNode: IXMLNode;  // node that stores all compiler results
  CompResultNode: IXMLNode;   // each compiler result node
  CompID: TCompilerID;        // loops thru all supported compilers
begin
  // compiler results value: only write known results
  CompResultsNode := XMLDoc.CreateElement(SnippetNode, cCompilerResultsNode);
  for CompID := Low(TCompilerID) to High(TCompilerID) do
  begin
    if CompRes[CompID] <> crQuery then
    begin
      CompResultNode := XMLDoc.CreateElement(
        CompResultsNode, cCompilerResultNode,
        cCompResMap[CompRes[CompID]]
      );
      CompResultNode.Attributes[cCompilerResultIdAttr] := cCompilerIDs[CompID];
    end;
  end;
end;

class procedure TXMLDocHelper.WritePascalNameList(const XMLDoc: IXMLDocumentEx;
  const Parent: IXMLNode; const ListName: string; const Names: IStringList);
  {Writes a Pascal name list to an XML document.
    @param XMLDoc [in] XML document to which list is written.
    @param Parent [in] Parent node that is to contain name list.
    @param ListName [in] Name of new list node that is parent of list.
    @param Names [in] List of Pascal names.
  }
var
  ListNode: IXMLNode; // reference to enclosing list node
  Name: string;       // a name item in list
begin
  ListNode := XMLDoc.CreateElement(Parent, ListName);
  for Name in Names do
    XMLDoc.CreateElement(ListNode, cPascalNameNode, Name);
end;

class procedure TXMLDocHelper.WriteSnippetKind(const XMLDoc: IXMLDocumentEx;
  const SnippetNode: IXMLNode; const Value: TSnippetKind);
  {Writes a <kind> node to a an XML document.
    @param XMLDoc [in] XML document to receive the node.
    @param SnippetNode [in] Node containing snippet that receives kind node.
    @param Value [in] Value of <kind> node.
  }
const
  cValues: array[TSnippetKind] of string = (
    'freeform', 'routine', 'const', 'type', 'unit', 'class'
  );
begin
  XMLDoc.CreateElement(SnippetNode, cKindNode, cValues[Value]);
end;

end.