generatormessagesutilities.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) 2000-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 GeneratorMessagesUtilities;

{Contains types and functions to retrieve special "fields" from a message of a
 generator ~[link TGeneratorMessage]. There are two functions,
 ~[link GeneratorMessageFieldToString] retrieves a text representation of a
 field of a message and ~[link CompareGeneratorMessageField] compares a field
 of two messages and returns their relation.
}

interface

uses UGenerationMessages;

type

  //the definition of the fields of a message
  TGeneratorMessageFieldView = (
    //the identification number of the group of messages
    gmfwMessageID,
    //the title of the group of messages
    gmfwMessageIDTitle,
    //the number of the message in its group
    gmfwMessageNumber,
    //the general text - summary - of the kind of messages
    gmfwMessageNumberText,
    //a more verbose description or general help text of the kind of messages
    gmfwMessageNumberHelpText,
    //the seriousness of the message
    gmfwMessageNumberSeriousness,
    //the specific text of the message
    gmfwMessageText,
    //a representation of the position
    gmfwPositionAll,
    //the kind of the position of the message
    gmfwPositionKind,
    //the pascal file for which the message has been generated, this will be
    //empty if the message has been generated for identifiers,
    //~[link gmfwPositionAnyFile] will in that case use the file the identifier
    //is defined in
    gmfwPositionFile,
    //the row and column the mesage has been generated at
    gmfwPositionRowColumn,
    //the row the mesage has been generated in
    gmfwPositionRow,
    //the column the mesage has been generated in
    gmfwPositionColumn,
    //the identifier for which the mesage has been generated
    gmfwPositionIdentifier,
    //the record-like type containing the identifier (member) for which the
    //mesage has been generated, beware that if the identifier itself is a
    //record-like type this field will nevertheless be empty
    gmfwPositionMemberOf,
    //the pascal file in which the message has been generated
    gmfwPositionAnyFile,
    //the position for messages generated in the user documentation
    gmfwPositionUserDoc,
    //the file of user documentation in which the message has been generated
    gmfwPositionUserDocFile,
    //the page of user documentation for which the message has been generated
    gmfwPositionUserDocPage,
    //the position for messages generated in the help on a GUI
    gmfwPositionGUI,
    //the file/GUI for messages generated in the help on a GUI
    gmfwPositionGUIFile,
    //the topic of a GUI for messages generated in the help on a GUI
    gmfwPositionGUITopic
  );


      //the captions/titles/names of the fields of the messages
const GeneratorMessageFieldCaptions: array[TGeneratorMessageFieldView] of
                                     String = (
                                               'Message ID',
                                               'Message ID Title',
                                               'Message Number',
                                               'Message Kind Text',
                                               'Message Help Text',
                                               'Message Seriousness',
                                               'Message Text',
                                               'Position',
                                               'Position Kind',
                                               'Position File',
                                               'Position Row And Column',
                                               'Position Row',
                                               'Position Column',
                                               'Position Identifier',
                                               'Position MemberOf',
                                               'Position Any File',
                                               'Position UserDoc',
                                               'Position UserDoc File',
                                               'Position UserDoc Page',
                                               'Position GUI',
                                               'Position GUI File',
                                               'Position GUI Topic'
                                             );


//Retrieves a text representation of a field of a message
function GeneratorMessageFieldToString(Field: TGeneratorMessageFieldView;
                         const Message: TGeneratorMessage;
                         const Descriptions: TMessageDescriptionsList): String;


//Compares a field of two messages and returns their relation.
function CompareGeneratorMessageField(Field: TGeneratorMessageFieldView;
                        const M1, M2: TGeneratorMessage;
                        const Descriptions: TMessageDescriptionsList): Integer;



implementation

uses SysUtils,
     UBaseIdents;



{Retrieves a text representation of a field of a message.
~param Field        the field of the message to be returned as text
~param Message      the message to return a field of
~param Descriptions further information of the message
~result a text representation of a field of a message }
function GeneratorMessageFieldToString(Field: TGeneratorMessageFieldView;
                         const Message: TGeneratorMessage;
                         const Descriptions: TMessageDescriptionsList): String;

 {Returns the position of a message as a string.
 ~param Message the message whose position should be returned as a string
 ~result the position of the message }
 function GetMessagePosition: String;
 begin
  if assigned(Message.Position.Identifier) then    //is at an identifier?
   begin
    //return the file the identifier is defined in and the identifier itself
    Result := Message.Position.Identifier.InFile.InternalFileName + '.';
    //and record-like type the identifier is a member of, if available
    if assigned(Message.Position.Identifier.MemberOf) then
     Result := Result + Message.Position.Identifier.MemberOf.Name + '.';
    Result := Result + Message.Position.Identifier.Name;
   end
  else
   if assigned(Message.Position.TheFile) then      //is in a file?
    begin
     Result := Message.Position.TheFile.InternalFileName; //return name of file
     if Message.Position.Position.Row > 0 then       //position specified?
      Result := Result + Format(':%d:%d',              //add it
                                [Message.Position.Position.Row,
                                 Message.Position.Position.Column]);
    end
   else
    if (Message.Position.UserDocPage <> '') or     //is in user documentation?
       (Message.Position.UserDocFile <> '') then
     Result := '~[userDoc ' + Message.Position.UserDocPage + '.' + //return it
               ExtractFileName(Message.Position.UserDocFile)
    else
     if (Message.Position.GUIPageFile <> '') or    //is in help on GUI?
        (Message.Position.GUIPageTopic <> '') then
      Result := '~gui ' + Message.Position.GUIPageFile + //return position
                '#' + Message.Position.GUIPageTopic
     else
      Result := '';                          //no position for message known
 end;


 {Returns the kind of position of a message.
 ~param Message the message whose kind of position should be returned
 ~result the kind of the position of the message }
 function GetMessagePositionKind: String;
 begin
  if assigned(Message.Position.Identifier) then     //is at an identifier?
   Result := 'Identifier'
  else
   if assigned(Message.Position.TheFile) then       //is in a file?
    Result := 'File'
   else
    if (Message.Position.UserDocPage <> '') or      //is in user documentation?
       (Message.Position.UserDocFile <> '') then
     Result := 'UserDoc'
    else
     if (Message.Position.GUIPageFile <> '') or     //is in help of GUI?
        (Message.Position.GUIPageTopic <> '') then
      Result := 'GUI'
     else
      Result := '';                             //no position for message known
 end;

begin
 Result := '';
 case Field of              //return a text representation of the field
   gmfwMessageID:
       Result := IntToStr(Message.MessageID);
   gmfwMessageIDTitle:
       Result := Descriptions[Message.MessageID].Title;
   gmfwMessageNumber:
       Result := IntToStr(Message.MessageNumber);
   gmfwMessageNumberText:
       Result := Descriptions[Message.MessageID][Message.MessageNumber].Text;
   gmfwMessageNumberHelpText:
       Result := Descriptions[Message.MessageID][Message.MessageNumber].
                                                                      HelpText;
   gmfwMessageNumberSeriousness:
       Result := MessageSeriousnesses[Descriptions[Message.MessageID]
                                          [Message.MessageNumber].Seriousness];
   gmfwMessageText:
       Result := Message.Message;
   gmfwPositionAll:
       Result := GetMessagePosition;
   gmfwPositionKind:
       Result := GetMessagePositionKind;
   gmfwPositionFile:
       if Assigned(Message.Position.TheFile) then
        Result := Message.Position.TheFile.InternalFileName;
   gmfwPositionRowColumn:
       if Assigned(Message.Position.TheFile) and
          (Message.Position.Position.Row > 0) then
        begin
         Result := IntToStr(Message.Position.Position.Row);
         if Message.Position.Position.Column > 0 then
          Result := Result + ':' + IntToStr(Message.Position.Position.Column);
        end;
   gmfwPositionRow:
       if Assigned(Message.Position.TheFile) and
          (Message.Position.Position.Row > 0) then
        Result := IntToStr(Message.Position.Position.Row);
   gmfwPositionColumn:
       if Assigned(Message.Position.TheFile) and
          (Message.Position.Position.Column > 0) then
        Result := Result + ':' + IntToStr(Message.Position.Position.Column);
   gmfwPositionIdentifier:
       if Assigned(Message.Position.Identifier) then
        Result := Message.Position.Identifier.Name;
   gmfwPositionMemberOf:
       if Assigned(Message.Position.Identifier) and
          Assigned(Message.Position.Identifier.MemberOf)then
        Result := Message.Position.Identifier.MemberOf.Name;
   gmfwPositionAnyFile:
       if Assigned(Message.Position.TheFile) then
        Result := Message.Position.TheFile.InternalFileName
       else
        if Assigned(Message.Position.Identifier) then
         Result := Message.Position.Identifier.InFile.InternalFileName;
   gmfwPositionUserDoc:
       if (Message.Position.UserDocPage <> '') or
          (Message.Position.UserDocFile <> '') then
        Result := Message.Position.UserDocPage + '.' +
                  ExtractFileName(Message.Position.UserDocFile);
   gmfwPositionUserDocFile:
       if (Message.Position.UserDocPage <> '') or
          (Message.Position.UserDocFile <> '') then
        Result := ExtractFileName(Message.Position.UserDocFile);
   gmfwPositionUserDocPage:
       if (Message.Position.UserDocPage <> '') or
          (Message.Position.UserDocFile <> '') then
        Result := Message.Position.UserDocPage;
   gmfwPositionGUI:
       if (Message.Position.GUIPageFile <> '') or
          (Message.Position.GUIPageTopic <> '') then
        Result := Message.Position.GUIPageFile + '#' +
                  Message.Position.GUIPageTopic;
   gmfwPositionGUIFile:
       if (Message.Position.GUIPageFile <> '') or
          (Message.Position.GUIPageTopic <> '') then
        Result := Message.Position.GUIPageFile;
   gmfwPositionGUITopic:
       if (Message.Position.GUIPageFile <> '') or
          (Message.Position.GUIPageTopic <> '') then
        Result := Message.Position.GUIPageTopic;
 else
  Assert(False);
 end;
end;






{Compares a field of two messages and returns their relation.
~param Field        the field of the messages to compare
~param M1, M2       the messages to be compared
~param Descriptions more information about the messages
~result the relation of the fields of the two messages, either < 0, = 0,
        or > 0 }
function CompareGeneratorMessageField(Field: TGeneratorMessageFieldView;
                        const M1, M2: TGeneratorMessage;
                        const Descriptions: TMessageDescriptionsList): Integer;

 {Compares the positions of the messages.
 ~result the relation of the positions }
 function CompareMessagePosition: Integer;

  {Compares the relation of the two positions.
  ~result the relation between the positions, either equal zero, or less or
          more }
  function ComparePos(const P1, P2: TDocumentationPosition): Integer;

   {Compares two identifiers, making sure they are on the same level.
   ~param Ident1, Ident2     the identifiers to compare
   ~param ToIdent1, ToIdent2 the most top-level identifiers already compared
   ~result the relation between the identifiers, either equal zero, or less or
           more }
   function CompareMembers(Ident1, Ident2: TIdentifier;
                           ToIdent1, ToIdent2: TIdentifier): Integer;
   var      I1, I2        :TIdentifier;      //the members to compare
   begin
    I1 := Ident1;
    while I1.MemberOf <> ToIdent1 do         //get the next-level member
     I1 := I1.MemberOf;
    I2 := Ident2;
    while I2.MemberOf <> ToIdent2 do         //get the next-level member
     I2 := I2.MemberOf;
    Result := CompareText(I1.Name, I2.Name); //compare them
    if Result = 0 then                       //same?
     begin
      Result := Ord(I1 = Ident1) - Ord(I2 = Ident2);     //are members?
      if (Result = 0) and (I1 <> Ident1) then            //both members?
       Result := CompareMembers(Ident1, Ident2, I1, I2);   //compare members
     end;
   end;

  var      F1, F2    :TPascalFile;    //the file the messages was generated in
  begin
   Result := Ord(assigned(P2.TheFile) or assigned(P2.Identifier)) -
             Ord(assigned(P1.TheFile) or assigned(P1.Identifier));
   //both messages are in source files?
   if (Result = 0) and (assigned(P1.TheFile) or assigned(P1.Identifier)) then
    begin
     if assigned(P1.Identifier) then      //get the first file
      F1 := P1.Identifier.InFile
     else
      F1 := P1.TheFile;
     if assigned(P2.Identifier) then      //and the second file