ujaddnodes.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

    //~[linkUnit UICNodes COM].
    procedure TransformToICWithoutParam(ToNode: TICNCompound;
                                        const ParamStr: String;
                                        FirstNodeIndex: Integer;
                                        DestComment: TICDocComment);


    //Copies the remnant of the content of the node to the specified node.
    procedure CopyContentPartTo(Compound: TJaddNodeCompound;
                                const StartText: String;
                                FirstNodeIndex: Integer;
                                SelfClone: TJaddNodeCompound);
  public
    //Creates the object and registers itself to its owner.
    constructor Create(Owner: TJaddNodeOwner);
    //Frees the list of child nodes and the node itself.
    destructor Destroy; override;

    //Appends the specified node as a child node.
    procedure AppendNode(Node: TJaddNode);

    //Returns the content of the node as a parameter (ignores formattings
    //etc.).
    function AsParameter(var Parameter: String): Boolean; virtual;

    //Returns the number of child nodes of the node.
    function ChildCount: Integer;

    property Children[Index: Integer]: TJaddNode read GetChild;
  end;



   { * * *  ***  * * *  ***   TJaddNodeSection   ***  * * *  ***  * * *  }

  {The class for nodes of special (top-level) "sections" in this simple
   ~[linkUnit UJADDNodes DOM]. }
  TJaddNodeSection = class(TJaddNodeCompound)
  private
    //whether the kind of the seciton is unknown
    //(may be used to comment a parameter of a function)
    FUnknownSection: Boolean;
    //the used name of the section
    //(in case the kind is ~[link FUnknownSection unknown])
    FSectionName: String;
    //the kind of the section
    //(in case the kind is not ~[link FUnknownSection unknown])
    FSection: TJaddSection;

    //Transforms the section as comment of a parameter (or several parameters).
    procedure TransformParameter(ParamNames: String;
                                 const ParamStr: String;
                                 NextNodeIndex: Integer;
                                 DestComment: TICIdentifierComment);
  public
    //Would copy the node to the specified node, but this is not valid for
    //section nodes.
    procedure CopyTo(Compound: TJaddNodeCompound); override;

    //Transforms the section to the more general ~[linkUnit UICNodes COM].
    procedure TransformSection(DestComment: TICIdentifierComment);
    //Transforms the section as comment on a parameter to the more general
    //~[linkUnit UICNodes COM].
    procedure TransformAsParameterSection(DestComment: TICIdentifierComment);
    //Transforms the page to the more general ~[linkUnit UICNodes COM].
    procedure TransformPage(DestComment: TICSimpleComment);
    //Transforms the comment of a GUI to the more general
    //~[linkUnit UICNodes COM].
    procedure TransformGUI(DestComment: TICSimpleComment);


    property UnknownSection: Boolean read FUnknownSection
                                     write FUnknownSection;
    property Section: TJaddSection read FSection write FSection;
    property SectionName: String read FSectionName write FSectionName;
  end;



   { * * *  ***  * * *  ***  TJaddNodeInlineCommand  ***  * * *  ***  * * *  }

  {The class for nodes to represent special commands in this simple
   ~[linkUnit UJADDNodes DOM]. When they are transformed to the more general
   ~[linkUnit UICNodes COM] they are replaced with their evaluated content. }
  TJaddNodeInlineCommand = class(TJaddNodeCompound)
  private
    //the kind of the inline command represented by this node
    FInlineCommand: TJaddInlineCommand;
    //the used name of the inline command
    FCommandName: String;

    //Adds an error message if the node has some content (child nodes).
    procedure CheckTotallyEmpty;
    //Adds an error message if the node has some content left.
    procedure CheckEmpty(const ParamStr: String; FirstNodeIndex: Integer);

    //Returns whether the node is not inside an image (or diagram).
    function CheckNotInImage: Boolean;
    //Returns whether the node is not inside an inline command.
    function CheckNotInInlineCommand: Boolean;


    //Handles all inline commands that do not result in any nodes in the more
    //general ~[linkUnit UICNodes COM].
    procedure HandleEmptyCommand;

    //Handles the link inside an image by parsing it and adding it to the list.
    procedure HandleImageLink(ImageLinks: TImageLinkList);

    //Transforms the link to the more general ~[linkUnit UICNodes COM].
    procedure TransformLink(ToNode: TICNCompound; DestComment: TICDocComment);
    //Transforms the diagram description to the more general
    //~[linkUnit UICNodes COM].
    procedure TransformDiagram(ToNode: TICNCompound;
                               DestComment: TICDocComment);
    //Transforms the command to embed an image to the more general
    //~[linkUnit UICNodes COM].
    procedure TransformImage(ToNode: TICNCompound; DestComment: TICDocComment);

    //Calculates the result value for the inline command ~~[add ].
    function HandleAdd: String;
  public
    //Create an object for the node representing the inline command.
    constructor CreateInlineCommand(Owner: TJaddNodeOwner;
                                    InlineCommand: TJaddInlineCommand;
                                    const CommandName: String);

    //Copies the node and all its children to the specified node.
    procedure CopyTo(Compound: TJaddNodeCompound); override;

    //Returns the content of the node as a parameter (ignores formattings
    //etc.).
    function AsParameter(var Parameter: String): Boolean; override;

    //Transforms the inline command to the more general
    //~[linkUnit UICNodes COM].
    function HandleCommand(ToNode: TICNCompound;
                           DestComment: TICDocComment): Boolean;

    property InlineCommand: TJaddInlineCommand read FInlineCommand;
    property CommandName: String read FCommandName;
  end;












      //the default special character starting inline commands
const DefaultInlineCommandStart = '[';
      //the default character ending inline commands
      DefaultInlineCommandEnd = ']';



      //the alphabetically sorted list of available inline commands
const DefaultInlineCommandNames: array[TJaddInlineCommand] of String =
('',            'add',             'br',             'code',
 'definetext',  'definetextif',    'diagram',        'em',
 'helpcontext', 'image',           'imagelink',      'includefile',
 'inheritdoc',  'inserttext',      'insertvariable', 'link',
 'linkclass',   'linkextern',      'linkgui',        'linkpage',
 'linkunit',    'p',               'preformatted',   'sample',
 'userdoc',     'optionSupported', 'optionValue',
 '');



      //sorted list of texts whose values depend on the position
const VariableNames: array[TVariables] of String =
                     ('DefinitionColumn', 'DefinitionLine',
                      'FileName', 'FileSize', 'FileType',
                      'ForwardDefinitionColumn', 'ForwardDefinitionLine',
                      'NumberOfLines',
                      'ThisIdentifier', 'ThisClass',
                      'ThisPage', 'ThisPageName');







//Extracts the next parameter from the content of the node.
function ExtractParam(var ParamStr: String; ParentNode: TJaddNodeCompound;
                      var NextNodeIndex: Integer;
                      var Parameter: String): Boolean;

implementation

uses SysUtils,
     General,
     UFilePaths,
     UPascalConsts,
     UGUIHelpData;


{Extracts the next parameter from the content of the node.
~param ParamStr      the next text inside the node, on first call just '';
                     in: to start extracting parameters from;
                     out: after the extracted parameter
~param ParentNode    node containing more parameters
~param NextNodeIndex index of next node to read as parameter if not in
                     ParamStr, on first call simply 0 for the first node
~param Parameter     the resulting parameter, "" if none found
~result whether a parameter has been found (it may be "") }
function ExtractParam(var ParamStr: String; ParentNode: TJaddNodeCompound;
                      var NextNodeIndex: Integer;
                      var Parameter: String): Boolean;

 {Returns the index of the first white space in the string.
 ~param S the string to search the white space in
 ~result the index of the first white space in S, or -1 }
 function FirstWhiteSpace(const S: String): Integer;
 var      P              :PChar;      //runner through the string
 begin
  if S = '' then                      //string is empty
   Result := -1                         //no white space found
  else
   begin
    P := @S[1];                         //start with the first character
    while (P^ > ' ') do                 //search first white space
     inc(P);
    Result := Cardinal(P) - Cardinal(@S[1]) + 1;  //return the index
    if Result > Length(S) then                    //none found? (found the #0)
     Result := -1;                                  //no white space found
   end;
 end;

 {Returns the index of the first non white space in the string.
 ~param S the string to search the non-white space in
 ~result the index of the first non-white space in S, or -1 }
 function FirstNonWhiteSpace(const S: String): Integer;
 var      P                 :PChar;      //runner through the string
 begin
  if S = '' then                         //string is empty
   Result := -1                            //no white space found
  else
   begin
    P := @S[1];                            //start with the first character
    while P^ in [#1..' '] do               //skip all white spaces
     inc(P);
    Result := Cardinal(P) - Cardinal(@S[1]) + 1; //return the index
    if Result > Length(S) then                   //found the terminatin #0?
     Result := -1;                                 //only white spaces found
   end;
 end;

         //index of next node to read as parameter if not in Text (ParamStr)
var      NodeIndex   :Integer;
         //the text inside the node to extract the parameter from (or '')
         Text        :String;
         Finished    :Boolean;           //parameter extracted or end reached?
         //the next node to extract the parameter from
         NextNode    :TJaddNode;
         CmdValue    :String;            //evaluated value of an inline command
         Index       :Integer;           //index in the string Text
begin
 Result := False;                        //no parameter found yet
 Parameter := '';                        //parameter is empty so far
 NodeIndex := NextNodeIndex;             //get index of next node
 Text := ParamStr;                       //get text to extract parameter from
 Finished := False;                      //no parameter found yet
 while not Finished do                   //while not found and nodes available
  begin                                    //no text to extract parameter from?
   while (Text = '') and (NodeIndex < ParentNode.ChildCount) do
    begin
     NextNode := ParentNode.Children[NodeIndex];  //get the next node
     inc(NodeIndex);                              //move index to the next node
     if NextNode is TJaddNodeText then            //is a simple text
      //use its text to extract parameter
      Text := TJaddNodeText(NextNode).Text
     else                                         //has to be an inline command
      begin
       assert((NextNode.ClassType = TJaddNodeInlineCommand) or
              (NextNode.ClassType = TJaddNodeCompound));
       CmdValue := '';
       //evaluate the inline command as parameter
       if TJaddNodeCompound(NextNode).AsParameter(CmdValue) then
        begin
         Parameter := Parameter + CmdValue;         //add the value
         //at least some parameter has been found (this does not end
         Result := True                             //the function)
        end;
      end; //else NextNode is TJaddNodeText
    end; //while Text = '' and NodeIndex < ChildCount

    //some text found to extract parameter from?
   if Text <> '' then
    begin
     if (NodeIndex = 1) and (NextNodeIndex = 0) then //first parameter?
      begin
       Index := FirstNonWhiteSpace(Text);              //skip all white spaces