uinlinecommand.pas

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

~see GetOptionDescription
~see GetOption }
procedure TJADDCommentEvaluator.SetOption(Index: Cardinal;
                                          const Value: 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?
  inherited SetOption(Index, Value)            //forward to parent's method
 else
  case Index - PreOptionCount of               //depending on index of option
    0:  if Value.StrData <> '' then              //set the value
         FCommandChar := Value.StrData[1]
        else
         FCommandChar := #0;
    1:  if Value.StrData <> '' then
         FICStartChar := Value.StrData[1]
        else
         FICStartChar := #0;
    2:  if Value.StrData <> '' then
         FICEndChar := Value.StrData[1]
        else
         FICEndChar := #0;
    3:  FDontParseComments := Value.BoolData;
  else
   assert(Index >= GetOptionCount);            //invalid index!
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;









{Resets the attributes to ready the evaluator for a new generation. }
procedure TJADDCommentEvaluator.ResetForNewGeneration;
begin
 inherited ResetForNewGeneration;           //reset inherited attributes

 FICLevel := 0;                             //reset attributes of the different
 FInImageCommand := False;                  //inline commands
 FDiagramCounter := 0;

 FDefinedTexts.Clear;                       //reset defined texts
 AddDefinedTexts;
end;




{Saves the current state of the evaluator and resets it. }
procedure TJADDCommentEvaluator.PushAndResetEnvironment;
begin
 SetLength(FICLevelStack, Length(FICLevelStack) + 1);  //add one entry to stack
 FICLevelStack[Length(FICLevelStack) - 1] := FICLevel; //save state to stack
 FICLevel := 0;                                        //reset the state
end;

{Restores a previously saved state of the evaluator. }
procedure TJADDCommentEvaluator.PopEnvironment;
begin
 assert(Length(FICLevelStack) > 0);

 FICLevel := FICLevelStack[Length(FICLevelStack) - 1]; //get state from stack
 SetLength(FICLevelStack, Length(FICLevelStack) - 1);  //remove it from stack
end;






















{Parses the comment to a text in the format of the documentation, if it is not
 disabled
~param Text  the text to parse
~param Force whether the parsing of the text should be forced
~result the parsed and formatted text }
function TJADDCommentEvaluator.ParseText(Text: String; Force: Boolean): String;
begin
 assert(FICLevel = 0);

 //comments shouldn't be parsed? (user documentation has to)
 if FDontParseComments and not Force then
  //just put it into the correct format
  Result := Generator.HandleRawCommentText(Text)
 else
  begin
   Result := GetText(Text, False);        //parse the comment into the format
   assert(Text = '');
   assert(FICLevel = 0);
  end;
end;



{Returns the next argument of an inline command.
~param Text the text to read and delete the argument from
~result the next argument in the text }
function TJADDCommentEvaluator.GetInlineCommandArg(var Text: String): String;
var      p          :PChar;   //runner through the text
begin
 Result := '';                //no argument found so far

 if Text <> '' then           //text available?
  begin
   p := Pointer(Text);
   while p^ in [#1..' '] do     //skip whitespaces and delete them
    inc(p);
   Delete(Text, 1, Cardinal(p) - Cardinal(Pointer(Text)));

   if Text <> '' then           //text still available?
    begin
     p := Pointer(Text);
     if p^ = FCommandChar then    //starts with the special character?
      begin
       inc(p);                      //skip it
       if p^ = FICStartChar then    //starts an inline command?
        begin
         Delete(Text, 1, 2);
         inc(FICLevel);
         Result := ParseCommand(Text); //evaluate it
         dec(FICLevel);
         p := Pointer(Text);
        end
       else
        if p^ = FCommandChar then   //just a quoted special character?
         begin
          Delete(Text, 1, 1);         //delete quoting character
          p := Pointer(Text);         //(use quoted one)
          inc(p);
         end
      end; //if p^ = FCommandChar

     if Text <> '' then           //text still available?
      begin
       while not (p^ in [#1..' ', FICEndChar]) do
        inc(p);                          //use all non-whitespaces
       Result := Result + copy(Text, 1,  //as argument
                               Cardinal(p) - Cardinal(Pointer(Text)));

       while p^ in [#1..' '] do          //skip all whitespaces and
        inc(p);
       //delete them with the argument
       Delete(Text, 1, Cardinal(p) - Cardinal(Pointer(Text)));
      end; //if Text <> ''
    end; //if Text <> ''
  end; //if Text <> ''
end;



























{Adds defined texts for the documentation. }
procedure TJADDCommentEvaluator.AddDefinedTexts;
begin                                       //define names of classes
 FDefinedTexts.Values['DocClass'] :=
                                  Generator.HandleRawText(Generator.ClassName);
 FDefinedTexts.Values['ExtractorClass'] :=
                        Generator.HandleRawText(Generator.Extractor.ClassName);
 FDefinedTexts.Values['EvaluatorClass'] := Generator.HandleRawText(ClassName);
end;


{Called when a message is generated by the creator of diagrams.
~param Message   the generated message
~param Sender    the generator generating the message while generating
~param AddToList whether the message should be added to the list, default is
                 True }
procedure TJADDCommentEvaluator.DiagramCreatorMessage(
                                                    Message: TGeneratorMessage;
                                                    Sender: TMakeDoc;
                                                    var AddtoList: Boolean);
begin
 AddToList := False;           //don't save the message in the diagram creator

 assert(Message.MessageID > 0);
 assert(Message.MessageID < Length(FDiagramMessageMap));
 assert(FDiagramMessageMap[Message.MessageID] > 0);
 //add the message with the mapped ID
 Generator.AddPositionMessage(FDiagramMessageMap[Message.MessageID],
                              Message.MessageNumber, Message.Message)
end;



{Saves a text by a name.
~param Name the name to save the text under
~param Text the text to save }
procedure TJADDCommentEvaluator.ICSetDefinedText(const Name, Text: String);
var       p          :PChar;     //runner through the name
begin
 if Name <> '' then              //name given?
  begin
   p := Pointer(Name);             //check name for (in)valid characters
   while p^ in ['A'..'Z', 'a'..'z', '0'..'9'] do
    inc(p);
   if Integer(p) - Integer(Pointer(Name)) <> length(Name) then
    Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                 Ord(jcmkInvalidTextVariableName),
              Format(DocumentationTexts[dtInvalidNameForDefineText].T, [Name]))
   else
    FDefinedTexts.Values[Name] := Text; //save the text by the name
  end;
end;

{Saves a text by a name if the two arguments are in the demanded relation.
~param Text the text of the command }
procedure TJADDCommentEvaluator.ICSetDefinedTextIf(var Text: String);
var       Arg1, Arg2 :String;    //the arguments to be in a demanded relation
          Op         :String; //operand defining demanded relation of arguments
          Name       :String;    //the name to save the text under
          DefText    :String;    //the text to define
          cmp        :Integer;   //the result of the comparison
          Define     :Boolean;   //if the text should be defined
begin
 Arg1 := GetInlineCommandArg(Text);
 Op := GetInlineCommandArg(Text);
 Arg2 := GetInlineCommandArg(Text);
 Name := GetInlineCommandArg(Text);
 DefText := GetRemainingICText(Text);
 if Op = '' then
  Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                               Ord(jcmkMissingInlineCommandArgument),
                      Format(DocumentationTexts[dtNoOperatorForDefineTextIf].T,
                             [InlineCommands[icDefineTextIf]]))
 else
  if Name = '' then
   Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                Ord(jcmkMissingInlineCommandArgument),
                     Format(DocumentationTexts[dtMissingNameForDefineTextIf].T,
                            [InlineCommands[icDefineTextIf]]))
  else
   begin
    if Op[1] = '_' then          //comparision should be in lower case?
     begin
      Arg1 := LowerCase(Arg1);     //convert both arguments to lower case
      Arg2 := LowerCase(Arg2);
      Delete(Op, 1, 1);            //remove this operator attachment
      if Op = '' then              //if no other operator defined
       Op := '=';                    //use equality a default operator
     end;
    if length(Op) > 2 then         //check operator
     Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                  Ord(jcmkMissingInlineCommandArgument),
                 Format(DocumentationTexts[dtInvalidOperatorForDefineTextIf].T,
                        [InlineCommands[icDefineTextIf], Op]))
    else
     begin
      cmp := CompareStr(Arg1, Arg2); //compare both arguments
      Define := False;               //assume relation is not satisfied
      //depending on both operator characters, treat the comparison result
      case ord(Op[1]) or (ord((Op + #0)[2]) shl 8) of
        ord('='), ord('=') or (ord('=') shl 8): Define := cmp = 0;
        ord('<') or (ord('>') shl 8),
        ord('!'), ord('!') or (ord('=') shl 8): Define := cmp <> 0;
        ord('<'):                               Define := cmp < 0;
        ord('<') or (ord('=') shl 8),
        ord('=') or (ord('<') shl 8):           Define := cmp <= 0;
        ord('>'):                               Define := cmp > 0;
        ord('>') or (ord('=') shl 8),
        ord('=') or (ord('>') shl 8):           Define := cmp >= 0;
      else
       Generator.AddPositionMessage(FJADDCommentEvaluatorMessagesID,
                                    Ord(jcmkMissingInlineCommandArgument),
                 Format(DocumentationTexts[dtInvalidOperatorForDefineTextIf].T,
                        [InlineCommands[icDefineTextIf], Op]));
      end;
      if Define then             //relation is satisfied? then define the text
       ICSetDefinedText(Name, DefText);
     end;
   end;
end;

{Requests a defined text by its name, if not defined just return an empty text.
~param Name the name of the defined text to return
~result the defined text }
function TJADDCommentEvaluator.ICGetDefinedText(const Name: String): String;
var      p          :PChar;     //to test the name of the defined test
begin
 Result := '';                  //assume text not defined/name not valid
 if Name <> '' then             //name given?
  begin
   p := Pointer(Name);            //check, if name if valid
   while p^ in ['A'..'Z', 'a'..'z', '0'..'9'] do
    inc(p);