uinlinecommand.pas

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

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2003-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UInlineCommand;

{Contains the class to evaluate comments for the generators of documentation,
 ~[link TJADDCommentEvaluator]. It evaluates inline commands of the JADD-style.
}

interface

uses Windows, Classes,
{$IFNDEF LINUX}
     Graphics,
{$ELSE}
     QGraphics,
{$ENDIF}
     UBaseIdents,
     UOptions,
     UGenerationMessages, UMakeDoc, UCommentDoc;


type


   { * * *  ***  * * *  ***   TJADDCommentEvaluator   ***  * * *  ***  * * *  }


  //These are the inline commands available in the comments so far. This
  //enumeration is sorted like ~[link InlineCommands] for faster searching in
  //that array. This will have to change to allow the names of the inline
  //commands to be edited.
  TInlineCommand = (
                    //no command, just use the text
                    icNone,
                    //Adds both values and inserts the result instead.
                    icAdd,
                    //Forces a new line/a line break.
                    icLineBreak,
                    //Formats the text as code.
                    icCode,
                    //Defines a text to a symbolic name.
                    icDefineText,
                    //Defines a text to a symbolic name if two strings are in a
                    //required relationship.
                    icDefineTextIf,
                    //Creates a diagram and inserts it into the documentation.
                    icDiagram,
                    //Emphasizes the text.
                    icEmphasize,
                    //Defines the help context for the current topic.
                    icHelpContext,
                    //Adds an image to the documentation.
                    icImage,
                    //Creates a link in the current image.
                    icImageLink,
                    //Includes a file of low level codes of the current format.
                    icIncludeFile,
                    //Inherits the documentation of the current identifier and
                    //section from the parent class.
                    icInheritDoc,
                    //Inserts a defined text by a symbolic name.
                    icInsertText,
                    //Inserts a variable text, its value depending on the
                    //position where it is used.
                    icInsertVariable,
                    //Creates a link to an identifier.
                    icLink,
                    //Creates a link to an identifier of a class.
                    icLinkClass,
                    //Creates a link to an URI.
                    icLinkExtern,
                    //Creates a link inside the currently generating help
                    icLinkGUI,                          //on a GUI.
                    //Creates a link to a page in the user documentation.
                    icLinkPage,
                    //Creates a link to a file.
                    icLinkUnit,
                    //Forces a new paragraph to start.
                    icParagraph,
                    //Formats the text preformatted, i.e. as code, and
                    //preserves the indentation and multiple spaces.
                    icPreFormatted,
                    //Formats the code as a small sample of code.
                    icSample,
                    //Reads the file as part of the user documentation.
                    icUserDoc,

                    //This command may be inserted automatically when no
                    //comment has been given at all. It is similar to
                    //~[link icInheritDoc] but the comment may be inherited
                    //from different sources (i.e. for properties from their
                    //read-attribute)
                    icInheritDefaultComment
                    );

      //all inline commands creating a link (should not be nested!)
const InlineCommandLinks = [icLink, icLinkClass, icLinkExtern,
                            icLinkGUI, icLinkPage, icLinkUnit];

type

  //Variable texts, that can be queried by ~[code ~~~[[insertVariable~[]].
  //Their resulting texts depend on the position where they are queried.
  //If they are not applicable at the requested position, an empty text will be
  //used.
  TVariables = (
                //column in that the current identifier has been defined in
                vDefinitionColumn,
                //line in that the current identifier has been defined in
                vDefinitionLine,
                //(internal) name of current file
                vFileName,
                //size of file (may differ from actual size (#13#10 problem))
                vFileSize,
                //kind of current file (unit, program, library or package)
                vFileType,
                //column in that the current identifier has been first defined
                //in
                vForwardDefinitionColumn,
                //line in that the current identifier has been first defined in
                vForwardDefinitionLine,
                //number of lines in the file
                vNumberOfLines,
                //the current identifier, whose documentation is currently
                //evaluated, transformed or generated
                vThisIdentifier,
                //if the current identifier, whose documentation is currently
                //evaluated or generated, is a class this value will evaluate
                //to the same name, if it is a member, it will evaluate to the
                //class it is a member of
                vThisClass,
                //number of the current page in the user documentation
                vThisPage,
                //name of the current page in the user documentation
                vThisPageName);










  {The messages that can be generated by the evaluator of the class
   ~[link TJADDCommentEvaluator]. }
  TJADDCommentMessageKind = (
                             //found a single ~~ inside a comment
                             jcmkSingleCommandChar,
                             //an unknown inline command (~~[command ]) has
                             //been found
                             jcmkUnknownInlineCommand,
                             //an inline command wasn't closed, probably the ]
                             //has been forgotten after ~~[command
                             jcmkUnclosedInlineCommand,
                             //an inline command expected an argument, but none
                             //(valid) was found
                             jcmkMissingInlineCommandArgument,


                             //invalid name of a variable given;
                             //inline commands: ~~[defineText ...],
                             //~~[defineTextIf ...], ~~[insertText ...]
                             jcmkInvalidTextVariableName,
                             //a referenced file does not exist
                             //inline command: ~~[includeFile ... ]
                             jcmkFileDoesNotExist,
                             //an invalid help context was specified, i.e. not
                             //numeric; inline command: ~~[HelpContext ... ]
                             jcmkInvalidHelpContext,
                             //invalid argument given when a number is
                             //expected; inline command: ~~[add ... ...]
                             jcmkNonNumericArgument,


                             //the identifier to create a link to wasn't found
                             jcmkUnknownLinkTarget,
                             //a file of user documentation couldn't be found;
                             //inline commands: ~~[userDoc File]
                             jcmkUserDocFileNotFound,
                             //the page to link to couldn't be found (yet);
                             //inline commands: ~~[linkPage ...]
                             jcmkUserDocPageNotFound,
                             //topic of documentation for a GUI couldn't be
                             //found; inline commands: ~~[linkGUI File]
                             jcmkGUIHelpDocumentationNotFound,


                             //an image should be inserted inside an image
                             jcmkImageInAnImage,
                             //an image should be inserted inside an inline
                             //command; this is only a warning
                             jcmkImageInInlineCommand,
                             //image link found outside of an image
                             jcmkImageLinkOutsideImage,
                             //error while trying to insert an image in the
                             //documentation
                             jcmkImage,

                             //a diagram to be inserted in the documentation is
                             //empty, no valid classes or files have been added
                             jcmkDiagramIsEmpty
                            );










   {Evaluates comments for the generators of documentation. It evaluates inline
    commands of the original JADD-style. }
  TJADDCommentEvaluator = class(TCommentEvaluator)
  private
    //ID of the messages of this class
    FJADDCommentEvaluatorMessagesID: TMessageID;


    //the character starting inline commands in comments
    FCommandChar: Char;
    //the character starting an inline command after
    //~[link FCommandChar] in comments
    FICStartChar: Char;
    //the character ending an inline command
    FICEndChar: Char;

    //if comments shouldn't be parsed (i.e. ~[link FCommandChar] not handled)
    FDontParseComments: Boolean;




    //current level in inline commands; 0 for not being in an inline command
    FICLevel: Integer;

    //currently parsing inline command to include an image?
    //(to detect errors like images in images)
    FInImageCommand: Boolean;





    //A list of texts mapped to names; similar to variables in code. Can be
    //queried by ~[code ~~~[[insertText <Name>~[]] and set in comments by
    //~[code ~~~[[defineText <Name> <Text>~[]]. Foe example "DocClass" is
    //predefined as the name of the class of the generator generating the
    //documentation. The value in this documentation is
    //"~[code ~[insertText DocClass]]".
    FDefinedTexts: TStringList;
    //A list of variable texts mapped to names; similar like functions, result
    //depends on the position, where the text is requested. Can be queried by
    //~[code ~~~[[insertVariable <Name>~[]] in comments.
    FVariableTexts: TStringList;



    //Counter of diagrams (to generate name).
    FDiagramCounter: Integer;

    //map of the message IDs of the diagram creator to the generator
    FDiagramMessageMap: TMessageDescriptionMap;







    //stack of inline command level
    FICLevelStack: array of Integer;



    //Adds defined texts for the documentation.
    procedure AddDefinedTexts;


    //Called when a message is generated by the creator of diagrams.
    procedure DiagramCreatorMessage(Message: TGeneratorMessage;
                                    Sender: TMakeDoc; var AddtoList: Boolean);

    //Saves a text by a name.
    procedure ICSetDefinedText(const Name, Text: String);
    //Saves a text by a name if the two arguments are in the demanded relation.
    procedure ICSetDefinedTextIf(var Text: String);
    //Requests a saved text by its name.
    function ICGetDefinedText(const Name: String): String;


    //Requests a text, whose value depends on the position it is requested at.
    function ICGetVariableText(const Name: String): String;
  protected


    //Parses a comment text to a text in the format of the documentation with
    //evaluating inline commands.
    function GetText(var Text: String; InInlineCommand: Boolean): String;
    //Handles the occurrence of the special comment character as an inline
    //command.
    function ParseCommand(var Text: String): String;

    //Returns the remnant text of an inline command.
    function GetRemainingICText(var Text: String): String;
    //Evaluates inline commands and returns their replacement text.
    function InlineCommand(const Command: String; var Text: String;