uinlinecommand.pas

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

                           var SkipWhitespaces: Boolean): String; virtual;




    //Returns the number of variable texts available in this class.
    class function GetTopHandledVariableIndex: Cardinal; virtual;
    //Registers a variable text to be queried by
    //~[code ~~~[[insertVariable <Name>~[]].
    procedure RegisterVariableText(const Name: String; IndexValue: Cardinal);
    //Returns a variable text depending on the position where it is requested.
    function ICGetVariableTextByIndex(Index: Cardinal): String; virtual;

    //Returns the content of the file and if it could be read.
    function ICGetFileContent(FileName: String;
                              var Content: String): Boolean; virtual;






    //Handles the including of an image in the documentation.
    function InsertImage(const Command: String; var Text: String): String;
    //Parses the declaration of a link inside an image.
    procedure ParseImageLink(const Command: String; var Text: String);


    //Adds all boxes of the diagram as links for the image of the diagram.
    procedure AddDiagramLinks(TheClass: TRecordType; TheFile: TPascalFile;
                              Position, Size: TPoint);
    //Handles the creation and including of a diagram in the documentation.
    function InsertDiagram(const Command: String; var Text: String): String;








    property JADDCommentEvaluatorMessagesID: TMessageID
                                          read FJADDCommentEvaluatorMessagesID;
  public
    //Creates the object and saves the reference on the generator.
    constructor Create(Generator: TCommentDoc); override;
    //Destroys the evaluator object and the different lists.
    destructor Destroy; override;



    //Returns a description of the evaluator of comments.
    class function GetDescription: TEvaluatorDescription; override;


    //Returns the number of available options in evaluators of this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                      override;
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;





    //Resets the attributes to ready the avaluator for a new generation.
    procedure ResetForNewGeneration; override;



    //Saves the current state of the evaluator and resets it.
    procedure PushAndResetEnvironment; override;
    //Restores a previously saved state of the evaluator.
    procedure PopEnvironment; override;




    //Parses the comment to a text in the format of the documentation.
    function ParseText(Text: String; Force: Boolean): String; override;
    //Returns the next argument of an inline command or a section.
    function GetInlineCommandArg(var Text: String): String; override;




    property CommandChar: Char read FCommandChar;
    property ICStartChar: Char read FICStartChar;
    property ICEndChar: Char read FICEndChar;
  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 InlineCommands: array[TInlineCommand] 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',
 '');


      //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');







//The list of evaluators of comments.
//Contains the names of the classes of the evaluators and references to the
//classed themselves in the corresponding objects.
var EvaluatorClasses: TStringList = nil;


//Adds a class of evaluators of comments to the list of evaluators.
procedure AddCommentEvaluatorClass(EvaluatorClass: TCommentEvaluatorClass);



implementation

uses SysUtils,
     UFilePaths,
     UPascalConsts,
     UDocumentationTexts,
     UDiagramCreator,
     UImages, UGUIHelpData,
     UCommentExtraction;









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


    //the descriptions of messages that can be added in the class
    //~[link TJADDCommentEvaluator]
var JADDCommentEvaluatorMessageDescriptions: TMessageDescriptions;





{Creates the object and saves the reference on the generator.
~param Generator the generator to evaluate the comments for }
constructor TJADDCommentEvaluator.Create(Generator: TCommentDoc);
var         varTexts   :TVariables;      //counter for each variable text
begin
 inherited Create(Generator);            //create the evaluator object

 //register messages of this class
 FJADDCommentEvaluatorMessagesID := Generator.RegisterMessages(
                                      JADDCommentEvaluatorMessageDescriptions);

 FCommandChar := DefaultSectionSeparatorChar; //set default special characters
 FICStartChar := DefaultInlineCommandStart;
 FICEndChar := DefaultInlineCommandEnd;


 FDefinedTexts := TStringList.Create;         //create list for defined texts
 AddDefinedTexts;                             //define names of classes

 FVariableTexts := TStringList.Create;        //create list for variable texts
 FVariableTexts.Sorted := True;
 FVariableTexts.Duplicates := dupError;
 //add handlers for the variable texts
 for varTexts := low(varTexts) to high(varTexts) do
  RegisterVariableText(VariableNames[varTexts], Ord(varTexts));

end;

{Destroys the evaluator object and the different lists. }
destructor TJADDCommentEvaluator.Destroy;
begin
 if assigned(Generator) then    //unregister messages of this class
  Generator.UnRegisterMessages(FJADDCommentEvaluatorMessagesID);

 FVariableTexts.Free;               //free the lists
 FDefinedTexts.Free;

 inherited Destroy;                 //free the evaluator object
end;












{Returns a description of the evaluator of comments.
~result a description of the evaluator of comments }
class function TJADDCommentEvaluator.GetDescription: TEvaluatorDescription;
begin
 Result.Name := 'JADD ~[commands ]';
 Result.Identification := 'JADDSource';
 Result.Description := 'Parses all inline commands of format: ~[command parameters* Text].';
end;


{Returns the number of available options in evaluators of this class.
~result the number of available options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TJADDCommentEvaluator.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 4;
end;

{Gets a description of an option.
~param Index index of the option to get data of
~param Desc  out: the description of the option (name, type, default value,
                  etc.)
~see GetOptionCount }
class procedure TJADDCommentEvaluator.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
var             PreOptionCount   :Cardinal; //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited GetOptionDescription(Index, Desc)  //forward to parent's method
 else
  begin
   ClearDescription(Desc);               //clear structure
   case Index - PreOptionCount of        //depending on index of option
     0:  begin                           //set the values describing the option
          Desc.Name := 'CommandChar';
          Desc.Category := 'Commands';
          Desc.Description := 'The character that starts inline commands.';
          Desc.DataType := otString;
          Desc.StrMaxLen := 1;
          Desc.DefaultValue.StrData := DefaultSectionSeparatorChar;
         end;
     1:  begin
          Desc.Name := 'InlineCommandStartChar';
          Desc.Category := 'Commands';
          Desc.Description := 'The character that starts an inline command after the "CommandChar".';
          Desc.DataType := otString;
          Desc.StrMaxLen := 1;
          Desc.DefaultValue.StrData := DefaultInlineCommandStart;
         end;
     2:  begin
          Desc.Name := 'InlineCommandEndChar';
          Desc.Category := 'Commands';
          Desc.Description := 'The character that ends an inline command.';
          Desc.DataType := otString;
          Desc.StrMaxLen := 1;
          Desc.DefaultValue.StrData := DefaultInlineCommandEnd;
         end;
     3:  begin
          Desc.Name := 'DontParseComments';
          Desc.Description := 'Don''t parse the comments, just treat them as general comment without special characters and sections.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := False;
         end;
   else
    assert(Index >= GetOptionCount);       //invalid index!
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
 end;
end;

{Gets the value of an option. Call ~[link GetOptionDescription] to get the type
 and the meaning of the option.
~param Index index of the option to get the value of
~result the value of the option
~see GetOptionCount
~see GetOptionDescription
~see SetOption }
function TJADDCommentEvaluator.GetOption(Index: Cardinal): TOptionValue;
var      PreOptionCount       :Cardinal; //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  Result := inherited GetOption(Index)         //forward to parent's method
 else
  begin
   case Index - PreOptionCount of              //depending on index of option
     0: Result.StrData := FCommandChar;          //get the value
     1: Result.StrData := FICStartChar;
     2: Result.StrData := FICEndChar;
     3: Result.BoolData := FDontParseComments;
   else
    assert(Index >= GetOptionCount);           //invalid index!
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
  end;
end;

{Sets the value of an option. Call ~[link GetOptionDescription] to get the type
 and the meaning of the option.
~param Index index of the option to set the value
~param Value the new value of the option
~see GetOptionCount