uparse.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 UParse;

{Encapsulates the parsing of a project/several pascal-files, so it provides a
 facade. It's a simple way to call the various methods in the right sequence.
 There are a lot of functions and methods of different classes to call.
 It's all done by creating an object of the class ~[link TParserManager] and
 then mainly by calling ~[link TParserManager.ParseFiles ParseFiles] after
 setting what files should be parsed. }

interface

uses Classes,
     UProgress,
     UPascalConsts,
     UBaseIdents,
     UTokenParser, UFileParser;


type



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

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

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

  {A list of messages generated while parsing the pascal code. Can f.i. be used
   in the handler procedure of type ~[link TMessageProc] to save the messages
   for further computing. }
  TParseMessageList

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

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




  

   { * * *  ***  * * *  ***   TParserManager   ***  * * *  ***  * * *  }


  //a reference on a class of a parser of pascal data
  TParserClass = class of TFileParser;



  //the class to parse a set of files of pascal data
  TParserManager = class;

  {Called when a message is generated while parsing the pascal code.
   Used in the property ~[link TParserManager].~[link TParserManager.OnMessage
   OnMessage]
  ~param Information all information about the message
  ~param Sender      the sender of the message }
  TMessageProc = procedure(const Information: TParseMessageInformation;
                           Sender: TParserManager) of object;




  {Can be used to parse sets of files of pascal data. After all necessary
   settings have been set, ~[link ParseFiles] can be called to parse the
   specified files. ~[link PreparseOneFile] can be used, if some files should
   be selected for parsing before the final parsing with ParseFiles. This is a
   facade for all the parsing related objects.. }
  TParserManager = class
  private
    //the class to create pascal parsers of
    FParserClass: TParserClass;

    //default compiler options when parsing files
    FDefineOptions: TDefineOptions;

    //names of files to parse only if used by other files
    FLibFileNames: TStringList;
    //absolute paths of the files in ~[link FLibFileNames]
    FLibFilePaths: TStringList;




    {the list for the parsed files; all parsers for the files will
     be added to it; property DefineOptions must be initialized so
     far (besides that it should be empty/clear(/uninitialized)) }
    FList: TFileList;

    {the list of files and directories to parse

     for files: the list of files to parse; if the objects-Property
     is not nil (that means Boolean(objects[i]) = True) and it is a
     project-file all used units will be parsed, too

     for directories: the list of directories whose files will be
     parsed; must be the absolute short names; that's means they're
     unique; if the objects-Property is not nil all subdirectories
     will also be parsed

     May be nil if no files should be parsed (have to be added to
     List already). }
    FParse: TStrings;

    {the list of files and directories not to parse

     for files: the list of files which will be not parsed if in
     a directory given by Parse or used by a project-file

     for directories: the list of directories whose files will not
     be parsed; must be the absolute short names; that's means
     they're unique; if the objects-Property is not nil all
     subdirectories will also not be parsed }
    FNotParse: TStrings;

    {the list of files and directories to parse if they are used by
     other files

     for files: the list of files to parse if used
     
     for directories: the list of directories whose files will be
     parsed; must be the absolute short names; that's means they're
     unique; if the objects-Property is not nil all subdirectories
     will also be parsed }
    FLibs: TStrings;


    {an object to show the FProgress and give the user the
     possibility to abort the parsing; must not be nil}
    FProgress: IProgressInterface;



    //if not nil called, when a message is generated
    FOnMessage: TMessageProc;







    //Sets the compiler options to use.
    procedure SetDefineOptions(Value: TDefineOptions);




    //Gets the list of files to parse only if they are used by other files.
    procedure GetLibList;

    //Sorts the list of files depending on their usage.
    procedure SortFileList(List: TFileList);



    //Generates a warning-message if the internal (pascal) name of the file
    //differs from the name of the file in the file-system.
    procedure TestFileName(TheFile: TPascalFile);

{$IFOPT C+}

    //Tests the inheritance-hierarchy-linking between record-like types
    //(debug).
    function TestRecordLikeLinks(Kind: TRecordKind; List: TFileList): Boolean;

{$ENDIF}




    //Parses the specified new files.
    procedure ParseNewFiles;
    //Parses all units the files use (in their interfaces).
    procedure ParseAllUsedUnits;
    //Parses all units the files use and interfaces of units.
    procedure ParseInterfacesAndUsedUnits;

    //Encapsulates the parsing of several pascal-files.
    procedure DoParseFiles;



    //Checks the file and parses it, if it is valid.
    procedure ParseFile(Name: String; Recursive: Boolean;
                        Dirs, NotFiles, NotDirs: TStrings;
                        UseDefines: TDefines = nil);

    //Parses the files and adds them to the list.
    procedure ParseList(Files, Dirs, NotFiles, NotDirs: TStrings);

  public
    //Creates the list for pascal files.
    constructor Create(List: TFileList);
    //Frees the list and all parsers.
    destructor Destroy; override;





    //Preparses a file or files in a directory.
    procedure PreparseOneFile(const FileName: String;
                              IsDir, Recursive: Boolean);

    //Encapsulates the parsing of several pascal-files.
    function ParseFiles: Boolean;






    //Handles a message from a parser.
    procedure HandleMessage(const Information: TParseMessageInformation;
                            Parser: TFileParser);
    //Handles a warning message from a parser.
    procedure AddWarning(const Message: String; Parser: TFileParser);
    //Handles a hint message.
    procedure AddHint(const Message: String);



    //Called, if an unknown unit is used by a file.
    function UnknownUnit(Sender: TFileParser;
                         const UnitName: String): TPascalFile;









    property ParserClass: TParserClass read FParserClass write FParserClass;
    property DefineOptions: TDefineOptions read FDefineOptions
                                           write SetDefineOptions;
    property LibFileNames: TStringList read FLibFileNames;
    property LibFilePaths: TStringList read FLibFilePaths;




    property List: TFileList read FList write FList;

    property Parse: TStrings read FParse;
    property NotParse: TStrings read FNotParse;
    property Libs: TStrings read FLibs;

    property Progress: IProgressInterface read FProgress write FProgress;
    property OnMessage: TMessageProc read FOnMessage write FOnMessage;
  end;






implementation

uses SysUtils,
     UFilePaths,
     UPascalFiles,
     UExtIdents,
     USingleFileParser, UConditionalParser,
     General;





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





   { * * *  ***  * * *  ***   TParserManager   ***  * * *  ***  * * *  }



{Creates the list for pascal files. The class of which objects should be
 created to parse files of pascal data is initialized to the class ~[linkClass
 TCodeParser].
~param List the list to parse the data to }
constructor TParserManager.Create(List: TFileList);
begin
 inherited Create;                        //create the object

 assert(assigned(List));
 FList := List;                           //save the list
 assert(not assigned(List.ParserManager));
 List.ParserManager := Self;              //assign back-reference to list

 //use the class TConditionalParser to parse files
 FParserClass := TConditionalParser;

 //create default defined compiler options
 FDefineOptions := TDefineOptions.Create;

 //lists of files to parse only if used by other files
 FLibFileNames := TStringList.Create;
 FLibFileNames.Sorted := True;
 FLibFileNames.Duplicates := dupError;
 FLibFilePaths := TStringList.Create;

 //list of files and directories to parse, or not, or only when used by
 FParse := TStringList.Create;                      //other files
 FNotParse := TStringList.Create;
 FLibs := TStringList.Create;
end;


{Frees the list and all parsers. }
destructor TParserManager.Destroy;
begin
 //remove reference on itself
 if assigned(List) and (List.ParserManager = Self) then
  List.ParserManager := nil;

 FParse.Free;             //free lists of files to parse
 FNotParse.Free;
 FLibs.Free;

 FLibFileNames.Free;      //free lists of files to parse if used by other files
 FLibFilePaths.Free;

 FDefineOptions.Free;     //free default defined compiler options

 inherited Destroy;       //free the object
end;














{Sets the compiler options to use.
~param Value the compiler options to use }
procedure TParserManager.SetDefineOptions(Value: TDefineOptions);
begin
 FDefineOptions.CopyOptions(Value);
end;