ugenerationmessages.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) 2002-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 UGenerationMessages;

{Contains types of the messages to be generated when generating documentation,
 ~[link TGeneratorMessage] defines this meta-information.~[br]
 This includes the descriptions of the possible messages, the description of
 one message is given by ~[link TMessageDescription], these are grouped in a
 set of messages in ~[link TMessageDescriptions], all possible messages are
 finally defined in a list of lists of type
 ~[link TMessageDescriptionsList].~[br]
 ~[link TMessageFilter] allows to specify filters for messages. }

interface

uses Classes, IniFiles, 
     UPascalConsts, UBaseIdents;

type

  //a position in the documentation or its source;
  //for instance for messages
  TDocumentationPosition = record
    TheFile: TPascalFile;      //file in which the message occured or nil
    Position: TPosition;       //position in the file or .Row < 0
    Identifier: TIdentifier;   //identifier in which the message occured or nil
    UserDocFile: String;       //file of user documentation of message or ''
    UserDocPage: String;       //page of user documentation of message or ''
    GUIPageFile: String;       //file of GUI documentation of the message or ''
    GUIPageTopic: String;      //topic of GUI documentation of message or ''
  end;


  //an ID of a set of messages
  TMessageID = type Integer;
  //the number of a message in a set of messages
  TMessageNumber = type Integer;

  //a message of a generator
  TGeneratorMessage = record
    MessageID: TMessageID;            //ID of the set of messages
    MessageNumber: TMessageNumber;    //number in the set of messages

    Message: String;                  //the message text

    Position: TDocumentationPosition; //position of the message
  end;



//Clears a structure of a position in the documentation.
procedure ClearDocumentationPosition(var Position: TDocumentationPosition);

//Clears a structure of a message.
procedure ClearMessage(var Message: TGeneratorMessage);

//Initializes a structure of a message.
procedure InitMessage(var Message: TGeneratorMessage; MsgID: TMessageID;
                      MsgNumber: TMessageNumber; const MsgText: String);







   { * * *  ***  * * *  ***   TMessageDescriptions   ***  * * *  ***  * * *  }


type
  //the seriousness of the messages
  TMessageSeriousness = (
                         //just some information
                         msInformational,
                         //a hint, something that could easily be fixed
                         msHint,
                         //a warning message, something that does not, or not
                         //always work
                         msWarning,
                         //an error message, something failed
                         msError,
                         //a fatal error message, the generation was aborted/is
                         //incomplete
                         msFatal
                        );

  //the seriousnesses of the messages
  TMessageSeriousnesses = set of TMessageSeriousness;

const
  //texts describing the seriousnesses of the messages
  MessageSeriousnesses: array[TMessageSeriousness] of String =
                        ('Informational', 'Hint', 'Warning', 'Error', 'FATAL');


type

    //additional pieces of information about messages
//  TMessageInformationPiece = (mip);

    //additional information about messages
//  TMessageInformation = set of TMessageInformationPiece;


  //a description of a message
  TMessageDescription = record
    //a short description of the messages of this type
    Text: String;
    //a longer help text about the messages of this type
    HelpText: String;
    //seriousness of the message
    Seriousness: TMessageSeriousness;

//    Information: TMessageInformation;
//    HelpContext: THelpContext;
  end;


  {Manages a list of message types by their descriptions. The instances of this
   class are meant to be static, i.e. created when the application is started
   and freed when the it is terminated. }
  TMessageDescriptions = class
  private
    //the list of descriptions of messages
    FDescriptions: array of TMessageDescription;
    //a short title/description of the messages in this list;
    //it is also an identification and must not contain white spaces
    FTitle: String;
  protected
    //Returns the number of messages with this ID.
    function GetCount: TMessageNumber;
    //Returns a description of a message.
    function GetDescription(Index: TMessageNumber): TMessageDescription;
  public
    //Creates the list of messages and saves their desriptions.
    constructor Create(const Descriptions: array of TMessageDescription;
                       const Title: String);


    property Count: TMessageNumber read GetCount;
    property Descriptions[Index: TMessageNumber]: TMessageDescription
                                                  read GetDescription; default;
    property Title: String read FTitle;
  end;


  //a list of message lists
  TMessageDescriptionsList = array of TMessageDescriptions;



  //maps message IDs of one generator to those of another;
  //i.e. index is also of type TMessageID
  TMessageDescriptionMap = array of TMessageID;





   { * * *  ***  * * *  ***   TGeneratorMessageList   ***  * * *  ***  * * *  }

{$UNDEF ListTemplateItemIsObject}
{$UNDEF ListTemplateItemMayBeFreed}
{$UNDEF ListTemplateItemFreedByDefault}

  //the items for the template list to use
  TListTemplateListItem = TGeneratorMessage;

  //forward declaration to be able to define an alias so the template can
  //reference itself
  TGeneratorMessageList = class;

  //alias for the list to be used by the implementations of the methods
  TListTemplate = TGeneratorMessageList;

{$INCLUDE ..\..\General\Templates\ListTemplate.inc}

  {A list of messages of the generators. }
  TGeneratorMessageList

{$INCLUDE ..\..\General\Templates\ListTemplate.inc}








   { * * *  ***  * * *  ***   TMessageFilter   ***  * * *  ***  * * *  }


  //A typical yes/no/some type to express whether all messages in a list are
  //filtered, not filtered or only some are filtered and the others are not.
  TMessageFilterStatus = (
                          mfsNotFiltered,  //no message is filtered
                          mfsSomeFiltered, //some of the messages are filtered
                          mfsFiltered);    //all messages are filtered


  {Defines a filter for messages, the messages are only filtered by the title
   of their groups and their index in this group, so the filter does not need
   to know each possible message. If a message is filtered it should not be
   shown/logged. }
  TMessageFilter = class
  private
    //mapping from the titles of the groups of messages to a TBits instance
    //specifying whether an actual message is filtered
    FFilter: TStringList;


    //Returns whether all or some of the messages in the list are filtered.
    function GetDescFiltered(const Desc: TMessageDescriptionsList):
                                                          TMessageFilterStatus;
    //Sets whether all or none of the messages in the list are filtered.
    procedure SetDescFiltered(const Desc: TMessageDescriptionsList;
                              Value: TMessageFilterStatus);
    //Returns whether all or some of the messages in the group/set are
    //filtered.
    function GetAllFiltered(const Name: String): TMessageFilterStatus;
    //Sets whether all or none of the messages in the group/set are filtered.
    procedure SetAllFiltered(const Name: String; Value: TMessageFilterStatus);
    //Returns whether the specified message is filtered.
    function GetIsFiltered(const Name: String; ID: Integer): Boolean;
    //Sets whether the specified message is filtered.
    procedure SetIsFiltered(const Name: String; ID: Integer; Value: Boolean);
  public
    //Creates the object and the list containing the filter.
    constructor Create;
    //Frees the object and the list containing the filter.
    destructor Destroy; override;


    //Loads the filter from the ini file.
    procedure LoadFromIni(Ini: TCustomIniFile);
    //Saves the filter to the ini file.
    procedure SaveToIni(Ini: TCustomIniFile);

    //Sets the filter for a group by a bitmask in a string ('0' or '1').
    procedure SetFilterForGroup(const Group, BitMask: String);

    //Clears the whole filter.
    procedure ClearFilter;

    //whether and how all currently possible messages are filtered
    property DescFiltered[const Desc: TMessageDescriptionsList]:
                                                           TMessageFilterStatus
                                    read GetDescFiltered write SetDescFiltered;
    //whether and how all messages of the group/set are filtered
    property AllFiltered[const Name: String]: TMessageFilterStatus
                                      read GetAllFiltered write SetAllFiltered;
    //whether the message is filtered
    property IsFiltered[const Name: String; ID: Integer]: Boolean
                                                           read GetIsFiltered
                                                           write SetIsFiltered;
  end;





implementation


{Clears a structure of a position in the documentation.
~param Position the position to clear }
procedure ClearDocumentationPosition(var Position: TDocumentationPosition);
begin
 Position.UserDocFile := '';                     //clear all strings
 Position.UserDocPage := '';
 Position.GUIPageFile := '';
 Position.GUIPageTopic := '';
 FillChar(Position, SizeOf(Position), 0);        //clear structure
end;

{Clears a structure of a message.
~param Message the message to clear }
procedure ClearMessage(var Message: TGeneratorMessage);
begin
 Message.Message := '';                        //clear all strings
 ClearDocumentationPosition(Message.Position); //clear position
 FillChar(Message, SizeOf(Message), 0);        //clear structure
end;

{Initializes a structure of a message.
~param Message   the structure of a message to initialize
~param MsgID     the ID of the messages it should be one of
~param MsgNumber the number of the message of that ID it is
~param MsgText   the text of the message }
procedure InitMessage(var Message: TGeneratorMessage; MsgID: TMessageID;
                      MsgNumber: TMessageNumber; const MsgText: String);
begin
 ClearMessage(Message);                 //clear the message
 Message.MessageID := MsgID;            //and initialize it
 Message.MessageNumber := MsgNumber;
 Message.Message := MsgText;
end;