ujaddstate.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) 2005-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 UJADDState;

{Contains the class ~[link TJADDState] that holds the state of the whole
 program. It should also act as a facade for most things directly related to
 parsing source code files and generating documentation. This should ease the
 pain of creating programs to do that, i.e. the command line version should get
 simpler.
}

interface

uses Classes, IniFiles,
     UBaseIdents,
     USaveParsed,
     UProgress,
     UTokenParser, UParse,
     UGenerationMessages, UGenerate;



type


   { * * *  ***  * * *  ***   TJADDState   ***  * * *  ***  * * *  }



  //representing the state of the program
  TJADDState = class;


  {Event handler called when something within the state changes.
  ~param State the state that has been changed }
  TJADDStateEvent = procedure (State: TJADDState) of object;



{$DEFINE ListTemplateUseIndexOf}
{$DEFINE ListTemplateItemIsMethod}
{$UNDEF ListTemplateItemIsObject}
{$UNDEF ListTemplateItemMayBeFreed}
{$UNDEF ListTemplateItemFreedByDefault}

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

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

  {A list of event handlers for ~[link TJADDState]. }
  TJADDStateEventList

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

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





  {Called when a message is generated while parsing the pascal code.
  ~param Information all information about the message
  ~param Parser      the parser manager used to parse the code
  ~param Sender      the sender of the message
  ~param AddToList   whether the message should be added to the list, default
                     is True }
  TParserMessageEvent = procedure(const Information: TParseMessageInformation;
                                  Parser: TParserManager;
                                  Sender: TJADDState;
                                  var AddToList: Boolean) of object;



  {Holds the state of the whole program. It should also act as a facade for
   most things directly related to parsing source code files and generating
   documentation. This should ease the pain of creating programs to do that,
   i.e. the command line version should get simpler. }
  TJADDState = class
  private
    //the list of the parsed files
    FFileList: TFileList;
    //if ~[link FFileList] contains complete data (no errors, not aborted)
    FCompletelyParsed: Boolean;

    //to generate the documentation
    FGenerate: TGeneratorManager;


    //the list of kept data
    FKeptParsedData: TList;



    //shows the progress of the parsing of source code or of the generating of
    //documentation
    FProgress: IProgressInterface;


    //the compiler options to use when parsing the files
    FDefines: TDefineOptions;

    //Contains the list of files to parse. Directories in the list mean the
    //files in them should be parsed. If the object is not nil of a project
    //file, all used files are also parsed. If it is not nil for a directory,
    //all files in its subdirectories are also parsed.
    FFilesToParse: TStrings;
    //Contains the list of files to exclude from parsing. Directories in the
    //list mean the files in them should not be parsed. If the object of a
    //directory is not nil, all files in its subdirectories are also not
    //parsed.
    FFilesToExclude: TStrings;
    //Contains the list of files to parse only, if they are used by parsed
    //files. This means also, all files they use are parsed. Directories in the
    //list mean the files in them should be parsed. If the object of a
    //directory is not nil, all files in its subdirectories may also be parsed.
    FFilesOfLibrary: TStrings;

    //the messages while parsing the pascal code
    FParserMessages: TParseMessageList;



    //the list of files with user documentation to be included in the
    //documentation
    FFilesOfUserDoc: TStrings;

    //Contains the list of log files of a GUI to read and to generate a help
    //about. Directories in the list mean the files in them should be parsed.
    //If the object is not nil for a directory, all files in its subdirectories
    //are also read.
    FGUIHelpLogFiles: TStrings;




    //the messages while generating the documentation
    FGenerationMessages: TGeneratorMessageList;
    //the descriptions of the messages while generating the documentation
    FGenerationMessageDescriptions: TMessageDescriptionsList;


    //the event handler to be called when a message is generated while parsing
    FOnParserMessage: TParserMessageEvent;

    //contains the event handlers to be called when the parsed data is changed
    FOnFileListChanged: TJADDStateEventList;
    //contains the event handlers to be called when the generator of the
    //documentation is replaced by another one
    FOnGeneratorChanged: TJADDStateEventList;
    //contains the event handlers to be called when the extractor of comments
    //for the documentation is replaced by another one
    FOnExtractorChanged: TJADDStateEventList;
    //contains the event handlers to be called when the evaluator of texts for
    //the documentation is replaced by another one
    FOnEvaluatorChanged: TJADDStateEventList;








    //Access method to get the number of kept data sets.
    function GetKeptDataCount: Integer;
    //Access method to get one of the kept data sets.
    function GetKeptDatas(Index: Integer): TFileList;



    //Called when the generator of the documentation is replaced by another
    //one.
    procedure HandlerGeneratorChanged(Sender: TGeneratorManager);
    //Called when the extractor of comments for the documentation is replaced
    //by another one.
    procedure HandlerExtractorChanged(Sender: TGeneratorManager);
    //Called when the evaluator of texts for the documentation is replaced by
    //another one.
    procedure HandlerEvaluatorChanged(Sender: TGeneratorManager);



    //Calls each event handler in the list.
    procedure CallEventHandlers(Handlers: TJADDStateEventList);

    //Called when the current parsed data is changed.
    procedure FileListChanged(NewFileList: Boolean = True);
    //Called when the generator of documentation is changed.
    procedure GeneratorChanged;
    //Called when the extractor of comments for the documentation is changed.
    procedure ExtractorChanged;
    //Called when the evaluator of texts for the documentation is changed.
    procedure EvaluatorChanged;


    //Clears the current parsed data.
    procedure ClearFileList;

    //Clears the list of messages generated while parsing.
    procedure ClearParserMessages;
    //Called when a message is generated while parsing the source code.
    procedure ParserMessage(const Information: TParseMessageInformation;
                            Sender: TParserManager);




  protected

  public
    //Creates the object and everything so save the state.
    constructor Create(MainIniFileName: String);
    //Frees the object and the state.
    destructor Destroy; override;




    //Gets the list of all log files of GUIs to generate a help about.
    procedure GetListOfGUIHelpLogFiles(List: TStrings);




    //Prepares for the parsing of source code.
    function StartParsing(Interactively: Boolean): TParserManager;
    //Parses the source code files.
    function DoParsing: Boolean;
    //Finishes the parsing and free the resources.
    procedure FinishParsing;



    //Generates the documentation.
    function GenerateDocumentation(OnlyUserDocumentation: Boolean): Boolean;
    //Generates the documentation as a help about a GUI.
    function GenerateGUIHelp: Boolean;




    //Initializes the state from the ini file.
    procedure ReadIni(Ini: TCustomIniFile);
    //Writes the state to an ini file.
    procedure WriteIni(Ini: TCustomIniFile);

    //Loads a DelphiDoc project ini file.
    procedure LoadProject(Ini: TCustomIniFile);
    //Saves the DelphiDoc project to an ini file.
    procedure SaveProject(Ini: TCustomIniFile);

    //Loads a project to generate help about a GUI from the ini file.
    procedure LoadGUIProject(Ini: TCustomIniFile);
    //Saves the project to generate help about a GUI to an ini file.
    procedure SaveGUIProject(Ini: TCustomIniFile);



    //Loads already parsed data from the file.
    function ReadDataFromFile(FileName: String): TParsedDataReadErrors;
    //Writes the parsed data to a file.
    procedure WriteDataToFile(FileName: String);



    //Marks the current data to be kept, so it is not freed when parsing again.
    procedure KeepCurrentData;
    //Gets the index of the current data in the list of kept data.
    function CurrentDataKeptIndex: Integer;
    //Selects parsed data from the list of kept parsed data.
    procedure SelectParsedData(Index: Integer);
    //Marks the parsed data in the list to not longer keep it.
    procedure DoNotKeepParsedData(Index: Integer);
    //Returns parsed data from the list of kept parsed data.
    function GetKeptData(Index: Integer): TFileList;




    property Progress: IProgressInterface read FProgress write FProgress;
    property Defines: TDefineOptions read FDefines;

    property FilesToParse: TStrings read FFilesToParse;
    property FilesToExclude: TStrings read FFilesToExclude;
    property FilesOfLibrary: TStrings read FFilesOfLibrary;

    property ParserMessages: TParseMessageList read FParserMessages;
    property FileList: TFileList read FFileList;

    property CompletelyParsed: Boolean read FCompletelyParsed;


    property FilesOfUserDocumentation: TStrings read FFilesOfUserDoc;
    property GUIHelpLogFiles: TStrings read FGUIHelpLogFiles;

    property Generate: TGeneratorManager read FGenerate;
    property GenerationMessages: TGeneratorMessageList
                                                      read FGenerationMessages;
    property GenerationMessageDescriptions: TMessageDescriptionsList
                                           read FGenerationMessageDescriptions;


    property KeptDatas[Index: Integer]: TFileList read GetKeptDatas;
    property KeptDataCount: Integer read GetKeptDataCount;


    property OnParserMessage: TParserMessageEvent read FOnParserMessage
                                                  write FOnParserMessage;

    property OnFileListChanged: TJADDStateEventList read FOnFileListChanged;
    property OnGeneratorChanged: TJADDStateEventList read FOnGeneratorChanged;
    property OnExtractorChanged: TJADDStateEventList read FOnExtractorChanged;
    property OnEvaluatorChanged: TJADDStateEventList read FOnEvaluatorChanged;
  end;









      //the section (in an ini file) to save the state to
const JADDStateIniSection = 'JADDState';
      //the section (in an ini file) to save the alternative content of the
      //main index to
      MainIndexIniSection = 'MainIndex';







//Defines or undefines a compiler symbol.
procedure ChangeDefine(Defines: TStrings;
                       Symbol: String; DoSet: Boolean); forward;
//Defines or undefines a list of compiler symbols.
procedure ChangeDefines(Defines: TStrings;
                        Symbols: array of String; DoSet: Boolean); forward;
//Defines and undefines compiler symbols depending on Delphi/Kylix version.
procedure AdjustDefines(Defines: TStrings;
                        CompilerVer: Integer; IsAKylix: Boolean); forward;

//Returns the Delphi version by the define of the internal compiler version.
function GetDelphiVersion(Defines: TStrings): Integer; forward;
//Defines the internal compiler version by the Delphi version.
procedure SetDelphiVersion(Version: Integer; Defines: TStrings); forward;




implementation

uses SysUtils,
{$IFDEF VER120}
     FileCtrl,
{$ENDIF}
     General, UFilePaths,
     UPascalConsts,
     UExtIdents,
     UFileParser,  //to load predefined identifiers of unit System
     UCodeParser,  //to load predefined constants (compiler defines)
     UGUIHelpIndexContent;






const
  //internal version numbers of all Delphi versions
  //(1 - 7, 8/.NET, 2005, 2006, 2007, ?)
  //~see UEditDefines.VersionNumbers
  DelphiVersionNumbers: array[0..11] of Byte =
                      (80, 90, 100, 120, 130, 140, 150, 160, 170, 180, 185, 0);

  //the versions of Delphi in which .NET is always activated
  DelphiDotNETVersions = [160];
  //the versions of Delphi in which .NET can be used (but does not have to)
  DelphiDotNETVersionsPossible = [170, 180, 185];



  //the names of the kinds of links to be saved to an ini file and load from it
  GUIHelpIniLinkKinds: array[TGUIMainIndexLinkKind] of String =
                       ('', 'linkGUI', 'linkPage', 'linkExtern');















{Defines or undefines a compiler symbol.