uinlinecommand.pas

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

       end;
     icInsertText:                     //inserting a saved text
//~[insertText Doc_Text_Name [ElseText]]
       begin
        Result := GetInlineCommandArg(Text); //get name of the text
        if Result = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else
         begin
          Result := ICGetDefinedText(Result);   //get the text
          if Result = '' then                   //it is empty?
           Result := GetRemainingICText(Text)     //use else text
          else
           GetRemainingICText(Text);              //skip else text
         end;
       end;
     icInsertVariable:                 //inserting a variable text
//~[insertVariable Doc_Variable_Name [ElseText]]
       begin
        Result := GetInlineCommandArg(Text);  //get name of variable text
        if Result = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else
         begin
          Result := ICGetVariableText(Result);       //get its value
          if Result = '' then                        //is empty?
           Result := GetRemainingICText(Text)          //use else text
          else
           GetRemainingICText(Text);                   //skip else text
         end;
       end;
     icHelpContext:                    //define help context for current topic
//~[HelpContext Help_Context]
       begin
        Result := Trim(GetInlineCommandArg(Text));  //get text of help context
        GetRemainingICText(Text);                   //skip remaining text
        if Result = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else
         begin
          val(Result, Context, Code);               //parse help context
          if Code <> 0 then                         //is not a valid number?
           Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                        Ord(jcmkInvalidHelpContext),
                      Format('Invalid help context "%s" in inline-command %s!',
                             [Result, Command]))
          else
           Generator.CurrentHelpContext := Context;   //assign new help context
          Result := '';                             //no text to insert
         end;
       end;
     icCode: //special format of text
//~[code Text]
       Result := Generator.FormatText(dtfCode, GetRemainingICText(Text),
                                      SkipWhitespaces);
     icEmphasize: //special format of text
//~[em Text]
       Result := Generator.FormatText(dtfEmphasize, GetRemainingICText(Text),
                                      SkipWhitespaces);
     icPreFormatted: //special format of text
//~[preFormatted Text]
       Result := Generator.FormatText(dtfPreFormatted,
                                      GetRemainingICText(Text),
                                      SkipWhitespaces);
     icSample: //special format of text
//~[sample Text]                             //just format the text that way
       Result := Generator.FormatText(dtfSample, GetRemainingICText(Text),
                                      SkipWhitespaces);
     icInheritDoc:           //inherits documentation from other identifiers
//~[inheritDoc]       -> documentation at the parent
       begin
        //get comment from counterpart identifier in parent class
        Result := Generator.GetInheritedIdentifierDocumentation;
        if Result = '' then                       //is empty?
         Result := GetRemainingICText(Text)         //use else text
        else
         GetRemainingICText(Text);                  //skip else text
       end;
     icAdd:
//~[add Num1 Num2]    -> sum of both operands (integers)
       begin
        Result := Trim(GetInlineCommandArg(Text)); //get first number
        S := Trim(GetInlineCommandArg(Text));      //get second number
        if (Result = '') or (S = '') then          //not both given?
         Result := Result + S           //return the other or nothing
        else
         try                            //try adding them
           Result := IntToStr(StrToInt(Result) + StrToInt(S))
         except
           on EConvertError do
            begin
             Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                          Ord(jcmkNonNumericArgument),
                        Format(DocumentationTexts[dtInvalidNumericArguments].T,
                               [Command, Result, S]));
             Result := '';                //in case of an error, return nothing
            end
           else
            raise;
         end;
        GetRemainingICText(Text);       //skip remnant text
       end;
     icLinkGUI:   //write a link to the documentation of a component in the GUI
//~[linkGUI [GUIFile][#Component] [Text]]          -> link to the documentation
       begin
        Result := Trim(GetInlineCommandArg(Text));     //get link target
        if Result = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else
         S := Generator.GetGUIHelpURI(Result);         //get URI of link target
         if S = '' then                                //invalid link target?
          begin
           Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                        Ord(jcmkGUIHelpDocumentationNotFound),
                   Format(DocumentationTexts[dtGUIHelpDocumentationNotFound].T,
                          [Command, Result]));
           //just return the text
           Result := GetRemainingICText(Text);
          end
         else
          Result := Generator.InternalLink(S, GetRemainingICText(Text));
       end;
     icLinkPage:             //write a link to a page of user documentation
//~[linkPage Number|Name [Text]]      -> link to page of user documentation
       begin
        Result := Trim(GetInlineCommandArg(Text)); //get name or number of page
        if Result = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else
         if LowerCase(Result) = 'index' then       //is index?
          //write a link on the index of the user documentation
          Result := Generator.InternalLink(Generator.GetPageURI(-1),
                                           GetRemainingICText(Text))
         else
          begin
           val(Result, Index, Code);               //try to use it as a number
           if Code <> 0 then                       //not a number?
            Index := Generator.GetPageIndex(Result); //search it by name

           //not a valid number of a page given?
           if not Generator.PageIndexValid(Index) then
            begin
             Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                          Ord(jcmkUserDocPageNotFound),
                                Format(DocumentationTexts[dtUnknownPageName].T,
                                       [Command, Result]));
             //write at least the label of the link
             Result := GetRemainingICText(Text);
            end
           else                              //write link to the page
            Result := Generator.InternalLink(Generator.GetPageURI(Index),
                                             GetRemainingICText(Text));
          end;
       end;
     icUserDoc:              //read a file of user documentation
//~[userDoc Path\to\FileName NotExistsText ]
       begin
        S := GetInlineCommandArg(Text);            //get name and path of file
        Result := GetRemainingICText(Text);        //get else text
        if Generator.ReadUserDocumentation(S) then //try to read file, success?
         Result := ''                                //don't use else text
        else
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkUserDocFileNotFound),
                          Format(DocumentationTexts[dtUserDocFileNotFound].T,
                                 [Command, S]));
       end;
//~[image [Alignment=char] [ConvFormat/Ext=JPEG|JPG] [Resolution=WxH|0x0]
//        Drive\Path\ImageFile[.ext] [Alternative Text]
//        ~[imageinlinelink ...] ~[imageinlinelink ...] ]
//~[diagram ( /options[=value] ([+]|-)box[.mutators]* )+ ]
     icImage,               //include an image in the documentation
     icDiagram:             //create and include a diagram in the documentation
       if FInImageCommand then         //already inside an image declaration?
        begin                                  //generate warning message
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkImageInAnImage),
                                   Format(DocumentationTexts[dtImageInImage].T,
                                          [Command]));
         Index := Generator.ImageLinks.Count;    //save number of links
         GetRemainingICText(Text);             //skip remnant of inline command
         Generator.FreeImageLinks(Index);                //delete all new links
        end
       else
        begin
         if FICLevel <> 1 then            //inside an inline command?
          //generate warning
          Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                       Ord(jcmkImageInInlineCommand),
                       Format(DocumentationTexts[dtImageInsideInlineCommand].T,
                              [Command]));
         Generator.FreeImageLinks;        //clear list of links inside image

         FInImageCommand := True;
         try
           //read declaration and handle it
           if TInlineCommand(Index) = icImage then
            Result := InsertImage(Command, Text)
           else
            Result := InsertDiagram(Command, Text);
         finally
          FInImageCommand := False;
         end;
        end;
//        ~[imageinlinelink x,y,x,y link       ident        [Alternative Text]]
//        ~[imageinlinelink x,y,x,y linkUnit   file         [Alternative Text]]
//        ~[imageinlinelink x,y,x,y linkClass  ident        [Alternative Text]]
//        ~[imageinlinelink x,y,x,y linkExtern URI          [Alternative Text]]
//        ~[imageinlinelink x,y,x,y linkpage   introduction [Alternative Text]]
//        ~[imageinlinelink x,y,x,y linkgui    #ButtonOK    [Alternative Text]]
     icImageLink:            //link inside the current image?
       if FInImageCommand then              //inside an image declaration?
        ParseImageLink(Command, Text)         //parse the link data
       else
        begin
         GetRemainingICText(Text);            //skip the inline command
         //generate a warning message
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkImageLinkOutsideImage),
                          Format(DocumentationTexts[dtImageLinkOutsideImage].T,
                                 [Command, InlineCommands[icImage]]));
        end;
   else
    raise Exception.CreateFmt('Invalid Index for Inline-Command: %d', [Index]);
   end;
  end
 else
  begin
   if Command <> '' then
    Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                 Ord(jcmkUnknownInlineCommand),
                           Format(DocumentationTexts[dtUnknownInlineCommand].T,
                                  [Command]));
//~[ Text]       -> Text
   Result := GetRemainingICText(Text);  //just use all text
  end;
end;













{Returns the number of variable texts available in this class, i.e. registered
 and handled by this class (and its ancestors).
~result the number of variable texts available in this class }
class function TJADDCommentEvaluator.GetTopHandledVariableIndex: Cardinal;
begin
 assert(Ord(Low(TVariables)) = 0);
 Result := Ord(High(TVariables)) - Ord(Low(TVariables));
end;

{Registers a variable text to be queried by
 ~[code ~~~[[insertVariable <Name>~[]]. Previously defined handler can be
 overridden by specifying the same name.
~param Name       the name of the variable text to be registered with
~param IndexValue the value to request the variable text with }
procedure TJADDCommentEvaluator.RegisterVariableText(const Name: String;
                                                     IndexValue: Cardinal);
var       Index      :Integer;   //index of the variable text in the list
begin
 //index of the variable text in the list of registered variable texts
 if FVariableTexts.Find(Name, Index) then  //if found in the list
  FVariableTexts.Objects[Index] := TObject(IndexValue)   //just set the value
 else
  FVariableTexts.AddObject(Name, TObject(IndexValue));   //add to the list
end;

{Returns a variable text depending on the position where it is requested.
~param Index the value to call the variable text previously defined when
             registered then variable text with ~[link RegisterVariableText]
~result the value of the variabel text at the position of the request }
function TJADDCommentEvaluator.ICGetVariableTextByIndex(Index:
                                                             Cardinal): String;
         //index of the current page of user documentation
var      UserDocPageIndex     :Integer;
begin
 Result := '';              //return by default an empty text
 case TVariables(Index) of  //return the value depending on the request-value
   //the column in which the current identifier is defined in
   vDefinitionColumn: if assigned(Generator.CommentIdent) then
                       Result := IntToStr(Generator.CommentIdent.Position.
                                                                       Column);
   //the line in which the current identifier is defined in
   vDefinitionLine:   if assigned(Generator.CommentIdent) then
                       Result := IntToStr(Generator.CommentIdent.Position.Row);
   //the name of the current file
   vFileName:      if assigned(Generator.CommentFile) then
                    Result := Generator.CommentFile.InternalFileName;
   //the size of the current file (may vary, depending on the EOL characters)
   vFileSize:      if assigned(Generator.CommentFile) then
                    Result := IntToStr(length(Generator.CommentFile.Lines.
                                                                        Text));
   //the type of the current file (unit, program, library or package)
   vFileType:      if assigned(Generator.CommentFile) then
                    Result := LowerCase(FileTypeNames[Generator.CommentFile.
                                                                    FileType]);
   //the column in which the current identifier is first defined in
   vForwardDefinitionColumn:
                   if assigned(Generator.CommentIdent) then
                    Result := IntToStr(Generator.CommentIdent.ForwardDefPos.
                                                                       Column);
   //the line in which the current identifier is first defined in
   vForwardDefinitionLine:
                   if assigned(Generator.CommentIdent) then
                    Result := IntToStr(G