ubaseidents.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) 2003-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 UBaseIdents;

{Contains the most basic classes to represent the structures in pascal
 code.~[br]
 ~[linkClass TFileList] will contain all parsed files, including the included
 ones. These are represented by objects of the class
 ~[linkClass TPascalFile].~[br]
 Likewise ~[linkClass TIdentifierList] acts as a list of identifiers, for
 instance all identifiers within a file. ~[linkClass TIdentifierFileList] can
 contain both, identifiers and files.~[br]
 ~[linkClass TDefines] represents compiler options etc. that are used while
 parsing the pascal code. ~[linkClass TDefineOptions] is used to set these
 options and can also parse the .cfg/.conf files of Delphi project to set them
 automatically.

 It also contains the base classes for all identifiers. The other classes for
 the identifiers are defined in the unit ~[linkUnit UExtIdents].
 ~[linkClass TIdentifier] is the abstract base class of all identifiers.
 ~[linkClass TType] is the abstract base class of all types.
 ~[linkClass TIdentType] is the class for types defined by an identifier, it
 holds the name of the identifier and can hold the link to it.
 ~[linkClass TPackableType] is the base class for all types that can be packed,
 i.e. defined with the reserved word packed. ~[linkClass TRecordType] is the
 class for all record-like type, this means all records, classes by the object-
 and class-model, interfaces and dispatch interfaces. ~[linkClass TProperty] is
 the class for all properties.~[br]
 ~[linkClass TTextFormat] serves as a set of call-back functions to format
 text when getting the descriptions of identifiers, it is extended by the
 generators of documentation. ~[linkClass TIdentStream] is the abstract base
 class to save and load parsed pascal data to/from a stream. }


interface

uses SysUtils, Classes,
     UPascalConsts;





type
  //all data about a file of pascal code
  TPascalFile = class;


  //compiler options while parsing a file
  TDefines = class;
  //compiler options to parse the files/project, and also to read the .conf
  //file
  TDefineOptions = class;


  //base class of all identifiers
  TIdentifier = class;
  //class for all record-like types
  TRecordType = class;
  //a simple list of identifiers
  TIdentifierList = class;

  //base class for saving and loading parsed data
  TIdentStream = class;




  //version of saved data
  TFileListVersion = type Integer;

  //version of saved data of identifiers and files
  TIdentClassVersion = type Integer;









   { * * *  ***  * * *  ***   TFileList   ***  * * *  ***  * * *  }


  //a pointer on an entry in a list of files
  PFileEntry = ^TFileEntry;
  //an entry in a list of files
  TFileEntry = record
    Next: PFileEntry;            //the next entry in the list
    TheFile: TPascalFile;        //the file of this entry
  end;


  {Serves as a list of files of pascal data. It has methods to get,
   remove, test, count etc. the files and copy the list. It actually contains
   two lists, one for parsed pascal files and another one for all included
   files. Data to convert the absolute short unique file names to their longer
   "real" names is also saved. }
  TFileList = class
  private
    //the list of the files
    FList: PFileEntry;
    //the list of all $INCLUDEd files
    FIncludedFileList: PFileEntry;

    //the pascal dialect of the parsed files
    FPascalDialect: TPascalDialect;


    //used in conjunction ~[link FTranslateLongPaths] to translate the saved
    //short paths and names of parsed files to the long real ones
    FTranslateShortPaths: TStringList;
    //used in conjunction ~[link FTranslateShortPaths] to translate the saved
    //short paths and names of parsed files to the long real ones
    FTranslateLongPaths: TStringList;


    //an object for the parser(s) of the files to manage the parsing
    FParserManager: TObject;



    //Logs the long versions of the path and name of the file in order to
    //enable the re-translation to its longer form.
    procedure LogLongPath(Path: String);

    //Adds an included file to the list.
    procedure AddIncludedFile(TheFile: TPascalFile);

    //Removes all included files and frees them.
    procedure RemoveAllIncluded;

  protected

  public
    //Creates the list of pascal files.
    constructor Create;
    //Frees the list and all files.
    destructor Destroy; override;


    //Gets the version the list will save its data in by ~[link Save].
    class function GetVersion: TFileListVersion;
    //Checks if the list can read data of the version by ~[link Load].
    class function CheckVersion(Version: TFileListVersion): Boolean;



    //Adds the empty numbers of files.
    procedure AddEmptyFiles(Files, IncludedFiles: Integer);


    //Adds the file.
    function AddFile(const FileName: String): TPascalFile;

    //Adds all references of files.
    procedure AddList(List: TFileList);
    //Adds the file to the list.
    procedure AddFileToThisList(TheFile: TPascalFile);

    //Logs the inclusion and reads the $INCLUDEd file.
    function IncludeFile(const AbsoluteShortFilePath,
                         OriginalFileName: String): TPascalFile;

    //Gets the number of included files.
    function IncludedFileCount: Integer;
    //Gets an included file by its index.
    function GetIncludedFileByIndex(Index: Integer): TPascalFile;
    //Gets an included file by its unique name.
    function GetIncludedFileAbsolute(const PathName: String): TPascalFile;



    //Tests if a file is in the list.
    function IsIn(AFile: TPascalFile): Boolean;
    //Tests if a file is included and in the appropriate list.
    function IsIncluded(AFile: TPascalFile): Boolean;

    //Gets a file by its unique name.
    function GetFileAbsolute(const PathName: String): TPascalFile;
    //Gets a file by its internal name.
    function GetFileByName(Name: String): TPascalFile;
    //Gets a file by the index.
    function GetFile(Index: Integer): TPascalFile;

    //Returns the index of the file in the list or -1.
    function IndexOf(AFile: TPascalFile): Integer;

    //Removes the file from the list and frees it optionally.
    procedure Remove(AFile: TPascalFile; Free: Boolean = False);
    //Removes all files and frees them optionally.
    procedure RemoveAll(Free: Boolean = True);

    //Counts the files in the list.
    function Count: Integer;
    //Tests if the list is empty.
    function IsEmpty: Boolean;



    //Returns the longest common path of all files (short names).
    function GetCommonBasePath: String;
    //Returns the long version of a path and name of a file.
    function GetLongPathName(ShortPath: String): String;


    //Saves the data of the list to the stream.
    procedure Save(Stream: TIdentStream);
    //Loads the data of the list from the stream.
    procedure Load(Stream: TIdentStream; Version: TFileListVersion);


    //Checks for each class if it is abstract.
    procedure CheckAbstractClasses;



    property PascalDialect: TPascalDialect read FPascalDialect
                                           write FPascalDialect;
    property Files[Index: Integer]: TPascalFile read GetFile; default;
    property Included[Index: Integer]: TPascalFile read GetIncludedFileByIndex; 
    property ParserManager: TObject read FParserManager write FParserManager;
  end;










  { * * *  ***  * * *  ***   TStatisticOfPascalFile   ***  * * *  ***  * * *  }


  //the kind of values hold for the statistic about a pascal source file
  TPascalFileStatistic = (
                          //number of directly included files (of $I's)
                          pfsIncludedFiles,
                          //number of included files, even by other included
                          //files
                          pfsAllIncludedFiles,

                          //number of lines in the file and all included ones
                          psfLines,
                          //number of characters in the file and all included
                          //ones
                          psfCharacters,
                          //number of tokens in the file and all included ones
                          pfsTokens,
                          //number of compiler directives used in the file and
                          //all included ones
                          pfsCompilerDirectives,
                          //number of by conditional compiling skipped tokens
                          //in the file and all included ones
                          pfsSkippedTokens,
                          //number of empty lines in the file and all included
                          //ones
                          psfEmptyLines,
                          //number of lines with comments in the file and all
                          //included ones
                          psfLinesWithComments,
                          //number of lines with some pascal characters
                          //(not comments) in the file and all included ones
                          psfLinesWithTokens,

                          //number of lines in the file
                          psfLinesNotIncluded,
                          //number of characters in the file
                          psfCharactersNotIncluded,
                          //number of tokens in the file
                          pfsTokensNotIncluded,
                          //number of compiler directives used in the file
                          pfsCompilerDirectivesNotIncluded,
                          //number of by conditional compiling skipped tokens
                          //in the file
                          pfsSkippedTokensNotIncluded,

                          //number of empty lines in the file
                          psfEmptyLinesNotIncluded,
                          //number of lines with comments in the file
                          psfLinesWithCommentsNotIncluded,
                          //number of lines with some pascal characters
                          //(not comments) in the file
                          psfLinesWithTokensNotIncluded,

                          //number of type casts (of known types) in the file
                          //and all included ones
                          psfTypeCastsKnown,
                          //number of implemented functions in the file and
                          //all included ones
                          psfFunctionBodys,
                          //number of "with" statements in the file and all
                          //included ones
                          psfWithStatements,
                          //number of overloaded functions (and operators in
                          //future releases?) in the file and all included ones
                          psfOverload,
                          //number of "goto" statements in the file and all
                          //included ones
                          psfGoTo,
                          //number of "goto" statements in the file and all
                          //included ones
                          psfLabel,
                          //number of assembler blocks (including assembler
                          //functions) statements in the file and all included
                          //ones
                          psfAsmBlocks);

  //all holded values for the statistics on a pascal file
  TPascalFileStatisticNumbers = array[TPascalFileStatistic] of Integer;

  {Holds some statistics on a pascal source file. }
  TStatisticOfPascalFile = class
  private
    //the values of the statistics
    FNumbers: TPascalFileStatisticNumbers;
  public
    //Creates the object to hold the statistics.
    constructor Create;

    //Initializes the statistics by setting all values to 0.
    procedure Initialize;
    //Invalidates all values of the statistics by setting them to -1.
    procedure Invalidate;

    //Increments a number of the statistics.
    procedure Increment(Value: TPascalFileStatistic);
    //Increments a number of the statistics by a specified value.
    procedure IncrementBy(Value: TPascalFileStatistic; By: Integer);

    //Adds the statistics of another file to create a summed up statistic.
    procedure SumStatistics(Statistic: TStatisticOfPascalFile);

    //Calculates the average of the sums for statistics.
//    procedure AverageStatistic(ByCount: Integer);

{
    //Saves the statistics of the pascal file to the stream.
    procedure Save(Stream: TIdentStream);
    //Loads the statistics of a pascal file from the stream.
    procedure Load(Stream: TIdentStream; Version: TIdentClassVersion);
}

    property Numbers: TPascalFileStatisticNumbers read FNumbers;
  end;