uinlinecommand.pas

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

   if Integer(p) - Integer(Pointer(Name)) <> length(Name) then
    Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                 Ord(jcmkInvalidTextVariableName),
                       Format(DocumentationTexts[dtInvalidNameForInsertText].T,
                              [Name]))
   else
    Result := FDefinedTexts.Values[Name]; //return the defined text
  end;
end;






{Requests a text, whose value depends on the position it is requested at.
~param Name the name fo the variable text to return
~result the value of the variable text at the position of the request }
function TJADDCommentEvaluator.ICGetVariableText(const Name: String): String;
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
  //return the text by its registered call-value
  Result := ICGetVariableTextByIndex(Cardinal(FVariableTexts.Objects[Index]))
 else
  Result := '';
end;













































{Parses a comment text to a text in the format of the documentation with
 evaluating inline commands.
~param Text            the text to parse; the parsed part will be deleted
~param InInlineCommand if the content of an inline command is being parsed; if
                       not the whole text should be parsed
~result the parsed text in the correct format }
function TJADDCommentEvaluator.GetText(var Text: String;
                                       InInlineCommand: Boolean): String;
var      p          :PChar;     //runner through the text
         len        :Integer;   //length of the immediate text the parse
begin
 assert(InInlineCommand = (FICLevel <> 0));

 Result := '';                  //nothing has been parsed, yet
 //while not end of the text reached or end of the inline command, in case only
 while (Text <> '') and         //it should be parsed
       ((Text[1] <> FICEndChar) or not InInlineCommand) do
  begin
   p := Pointer(Text);            //search next inline command or end of it
   while not (p^ in [#0, FCommandChar]) and
         ((p^ <> FICEndChar) or not InInlineCommand) do
    inc(p);

   len := Cardinal(p) - Cardinal(Pointer(Text));  //get length of skipped text
   //just add the text
   Result := Result + Generator.HandleRawCommentText(copy(Text, 1, len));
   Delete(Text, 1, len);          //and delete it

   if (Text <> '') and            //some text to parse follows?
      ((Text[1] <> FICEndChar) { or not InInlineCommand } ) then
    begin
     assert(Text[1] = FCommandChar);

     if length(Text) > 1 then       //not a single character?
      begin
       if Text[2] = FCommandChar then          //a quoted special character?
        begin
         //add just one of them
         Result := Result + Generator.HandleRawCommentText(FCommandChar);
         Delete(Text, 1, 2);                   //and delete them
        end
       else
        if Text[2] = FICStartChar then         //inline command?
         begin
          Delete(Text, 1, 2);                   //delete special characters and
          inc(FICLevel);
          Result := Result + ParseCommand(Text);  //parse the command
          dec(FICLevel);
         end
        else
         begin                                //just a single special character
          Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                       Ord(jcmkSingleCommandChar),
                              Format(DocumentationTexts[dtSingleCommandChar].T,
                                     [FCommandChar]));
          //treat as if it had been quoted
          Result := Result + Generator.HandleRawCommentText(FCommandChar);
          Delete(Text, 1, 1);                   //delete it
         end;
      end //if length(Text) > 1
     else
      begin
       Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                    Ord(jcmkSingleCommandChar),
                              Format(DocumentationTexts[dtSingleCommandChar].T,
                                     [FCommandChar]));
       //treat as if the single special character had been quoted
       Result := Result + Generator.HandleRawCommentText(FCommandChar);
       Text := '';                              //delete it
      end; //else length(Text) > 1
    end; //if not EndOfText/EndOfInlineCommand reached
  end; //while not EndOfText/EndOfInlineCommand reached

 assert(InInlineCommand or (Text = ''));
 assert((Text = '') or (Text[1] = FICEndChar));
end;






{Handles the occurrence of the special comment character as an inline command.
~param text the directly following text after the two special characters; the
            parsed part will be deleted
~result the parsed text/the value of the inline command }
function TJADDCommentEvaluator.ParseCommand(var Text: String): String;
var      Command              :String;    //the name of the inline command
         p                    :PChar;     //runner through the text
         //if whitespaces should be skipped after a format command
         SkipWhitespaces      :Boolean;
begin
 if Text = '' then                   //empty string?
  begin
   Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                Ord(jcmkUnclosedInlineCommand),
                          Format(DocumentationTexts[dtUnclosedInlineCommand].T,
                                 [FICEndChar]));
   Result := '';                       //nothing to parse
  end
 else                                //is a quoted special character?
  if Text[1] in [FICStartChar, FICEndChar] then
   begin
    Result := Generator.HandleRawCommentText(Text[1]);  //just add it
    Delete(Text, 1, 1);                //and remove it from the text
   end
  else
   begin
    p := Pointer(Text);                //read name of the inline command
    while p^ in ['A'..'Z', 'a'..'z', '0'..'9'] do
     inc(p);
    //and extract it
    Command := copy(Text, 1, Cardinal(p) - Cardinal(Pointer(Text)));
    while p^ in [#1..' '] do           //skip also following whitespaces
     inc(p);
    Delete(Text, 1, Cardinal(p) - Cardinal(Pointer(Text))); //and delete it

    SkipWhitespaces := False;        //assume not to skip following whitespaces
    //evaluate/execute the inline command
    Result := InlineCommand(Command, Text, SkipWhitespaces);

    //following whitespaces should be skipped?
    if SkipWhitespaces and (Text <> '') then
     begin
      p := Pointer(Text);
      while p^ in [#1..' '] do           //skip all white spaces and
       inc(p);
      Delete(Text, 1,  Cardinal(p) - Cardinal(Pointer(Text)));  //delete them
     end;
   end; //else Text = '' or  Text[1] in [FICStartChar, FICEndChar]
end;



{Returns the remnant text of an inline command.
~param Text the text to read and delete the remnant text from
~result the remnant text of an inline command }
function TJADDCommentEvaluator.GetRemainingICText(var Text: String): String;
begin
 Result := GetText(Text, True);          //parse the remnant text up to the end

 if Text <> '' then                      //end of inline command reached?
  begin
   assert(Text[1] = FICEndChar);
   Delete(Text, 1, 1);                     //remove the final character
//   Result := TrimRight(Result);
  end
 else
  Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                               Ord(jcmkUnclosedInlineCommand),
                          Format(DocumentationTexts[dtUnclosedInlineCommand].T,
                                 [FICEndChar]));
end;


{Evaluates inline commands and returns their replacement text.
~param Command         the inline command
~param Text            the remnant text with arguments to the comment etc.
~param SkipWhitespaces out: skip/ignore following white spaces
~result the formatted text resulting from the evaluation }
function TJADDCommentEvaluator.InlineCommand(const Command: String;
                                         var Text: String;
                                         var SkipWhitespaces: Boolean): String;
var      Index      :Integer;     //index of the inline command
         S          :String;      //a help string
         Code       :Integer;     //to test if a text is a number
         Context    :Cardinal;     //new help context
begin
 Result := '';
 //is a known inline command?
 if (Command <> '') and IsWordIn(Command, InlineCommands, Index) then
  begin
   case TInlineCommand(Index) of    //handle it depending on the command
     icLineBreak, icParagraph:        //formatings to insert
//~[p]
//~[br]
       begin                           //insert them
        Result := Generator.LineParagraphBreak(TInlineCommand(Index) =
                                               icParagraph,
                                               SkipWhitespaces);
        GetRemainingICText(Text);      //ignore remnant text
       end;
     icLink, icLinkClass, icLinkUnit:  //link to an identifier or file
//~[link Identifier [Text]]
//~[link #Member [Text]]
//~[link Identifier.Member [Text]]
//~[link Unit.Identifier [Text]]
//~[link Unit.Identifier.Member [Text]]
//~[linkClass ClassIdentifier [Text]]
//~[linkUnit UnitName [Text]]
       begin
        Result := GetInlineCommandArg(Text); //get identifier to link to
        if Result = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else                                 //create link to identifier
         Result := Generator.GetIdentifierFileLink(Result,
                                                   GetRemainingICText(Text),
                       TLinkFindType(ord(TInlineCommand(Index) <> icLink) +
                                     ord(TInlineCommand(Index) = icLinkUnit)));
       end;
     icLinkExtern:                     //link to an URI
//~[linkExtern URI [Text]]
       begin
        Result := GetInlineCommandArg(Text); //get URI
        if Result = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else                                 //create link to it
         Result := Generator.ExternalLink(Result, GetRemainingICText(Text));
       end;
     icDefineText:                     //defining a text
//~[defineText Doc_Text_Name DefineText]
       begin
        Result := GetInlineCommandArg(Text); //get name of text
        if Result = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else
         begin                               //save text with that name
          ICSetDefinedText(Result, GetRemainingICText(Text));
          Result := '';                      //return nothing
         end;
       end;
     icDefineTextIf:                   //defining a text under a condition
//~[defineTextIf Text1 [_]Operator Text2 Doc_Text_Name Text]
       //get all arguments and evaluate them, and assign if expression is true
       ICSetDefinedTextIf(Text);
     icIncludeFile:                    //includes directly code from a file
//~[includeFile FilePath [NotExistsText]]
       begin
        S := GetInlineCommandArg(Text);    //get name and path of file
        if S = '' then
         Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                      Ord(jcmkMissingInlineCommandArgument),
                   Format(DocumentationTexts[dtInlineCommandWithoutArgument].T,
                          [Command]))
        else                                 //read content of the file
         if not ICGetFileContent(S, Result) then //successfully?
          begin
           Result := GetRemainingICText(Text);     //use else text

           Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                        Ord(jcmkFileDoesNotExist),
               Format(DocumentationTexts[dtFileWithRawDataToIncludeNotFound].T,
                      [Command, S]));
          end
         else
          GetRemainingICText(Text);                //skip else text