ujaddstate.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

{Gets the list of all log files of GUIs to generate a help about. This list
 will only contain files and no directories, instead it will contain the log
 files withing the directories.
~param List the list to receive all set log files of GUIs to generate a help
            about }
procedure TJADDState.GetListOfGUIHelpLogFiles(List: TStrings);
var       SortList  :TStringList;      //the list to contain the files
          i         :Integer;          //counter through the original list
          Entry     :String;           //each entry in the original list
{$IFNDEF LINUX}
          SearchRec :TSearchRec;       //used to obtain the long name
{$ENDIF}
begin
 SortList := TStringList.Create;       //create the list to get the files
 try
   SortList.Sorted := True;
   SortList.Duplicates := dupIgnore;   //duplicates have to be ignored!

   for i := 0 to FGUIHelpLogFiles.Count - 1 do //for each entry
    begin
     Entry := FGUIHelpLogFiles[i];               //get it
     if DirectoryExists(Entry) then              //is a directory?
      FindFilesByExtension('.log', Entry, SortList, //add all log files in it
                           assigned(FGUIHelpLogFiles.Objects[i]))
     else
      SortList.Append(ExtractShortPathName(ExpandFileName(Entry))); //add it
    end;

{$IFNDEF LINUX}
   SortList.Sorted := False;
   for i := 0 to SortList.Count - 1 do //for each entry
    begin
     //get long name of the file
     if FindFirst(SortList[i], faAnyFile, SearchRec) = 0 then //file found?
      try
        //set the original (long) name
        SortList[i] := ExtractFilePath(SortList[i]) + SearchRec.Name;
      finally
       FindClose(SearchRec);             //end the searching
      end;
    end;
{$ENDIF}

   List.Assign(SortList);              //set all found files
 finally
  SortList.Free;                       //free the list to search the files
 end;
end;















{Prepares for the parsing of source code. ~[link FinishParsing] has to be
 called after this, so the allocated resources may be freed.
~param Interactively whether the parsing should be interactively, the files to
                     parse and not to parse should be selected ony by one by
                     the user, so the already added files aren't parsed
~result the manager used to parse the source code, has to be freed by calling
        ~[link FinishParsing]
~see FinishParsing
~see DoParsing
~exception EParseException will not be thrown in here
~example An example how to parse with ~[link TJADDState]:
         ~[preformatted

         var      Parser       :TParserManager;
                  Success      :Boolean;
         ...
         begin
          ...
          Parser := State.StartParsing(...);
          try
            ...
            try
              Success := State.DoParsing;
            except
              on E: EParseException do
               begin
                ...
               end
              else
               raise;
            end;
          finally
           State.FinishParsing;
          end;
          ...
          ... Success ...
          ...
         ] }
function TJADDState.StartParsing(Interactively: Boolean): TParserManager;
begin
 ClearFileList;                            //free current list for the files

 FFileList := TFileList.Create;            //create a new list
 FCompletelyParsed := False;               //data must have been complete

 FileListChanged;                          //notify of new list

 //add list of predefined identifiers
 if FileExists('PreDefinedIdents.txt') then
  TFileParser.GetPreDefinedIdentList.LoadFromFile('PreDefinedIdents.txt');
 //add lists of types and identifiers in unit System (in case it is compiled)
 if FileExists('SystemTypes.txt') then
  TFileParser.GetSystemTypeList.LoadFromFile('SystemTypes.txt');
 if FileExists('SystemIdents.txt') then
  TFileParser.GetSystemIdentList.LoadFromFile('SystemIdents.txt');

 //create object to manage the parsing for the list
 Result := TParserManager.Create(FFileList);
 try
   if not Interactively then               //not adding files interactively?
    begin
     Result.Parse.Assign(FFilesToParse);     //set what to parse
     Result.NotParse.Assign(FFilesToExclude);
    end;
   Result.Libs.Assign(FFilesOfLibrary);    //set libraries

   Result.DefineOptions := FDefines;       //set compiler options

   ClearParserMessages;                    //clear old messages
   Result.OnMessage := ParserMessage;      //handle messages

 except
   Result.Free;
   raise;
 end;
end;

{Parses the source code files.
~result if the parsing was successful
~see StartParsing
~see FinishParsing }
function TJADDState.DoParsing: Boolean;
var      Info      :TParseMessageInformation;    //information about an error
begin
 assert(assigned(FFileList));
 assert(assigned(FFileList.ParserManager));
 assert(assigned(Progress));

 Result := False;                                //only for the compiler

 FProgress.Prepare;                              //show the progress
 //assign interface to show the progress
 TParserManager(FFileList.ParserManager).Progress := FProgress;
 try
   try
     //parse the pascal files
     Result := TParserManager(FFileList.ParserManager).ParseFiles;

     FCompletelyParsed := Result;                //completely parsed the data

   except
     on E: EParseException do                    //in case of a parse error
      begin

       //add the error message to the list of messages
       E.CopyInformationTo(Info);
       ParserMessage(Info, TParserManager(FFileList.ParserManager));

       FileListChanged(False);                   //notify that list changed

       raise;                                    //error not fully handled!
      end
     else
      raise;                                     //error not handled!
   end;
 finally
   try
     FProgress.Finished;                         //finish the progress
   finally
    TParserManager(FFileList.ParserManager).Progress := nil; //and remove it
   end;
 end;
end;

{Finishes the parsing and free the resources.
~see StartParsing
~see FinishParsing }
procedure TJADDState.FinishParsing;
var       i         :Integer;                        //counter through files
          AFile     :TPascalFile;                    //each file
begin
 assert(assigned(FFileList));
 assert(assigned(FFileList.ParserManager));

 try
   for i := 0 to FFileList.Count - 1 do              //free all parsers
    begin
     AFile := FFileList[i];
     AFile.Parser.Free;
     AFile.Parser := nil;
    end;

   for i := 0 to FFileList.IncludedFileCount - 1 do  //and of included files
    begin
     AFile := FFileList.Included[i];
     assert(not assigned(AFile.Parser));
     AFile.Parser.Free;
     AFile.Parser := nil;
    end;

 finally
  FFileList.ParserManager.Free;                      //free parser manager
  assert(not assigned(FFileList.ParserManager));
 end;

 FileListChanged(False);                             //notify of change
end;











{Generates the documentation.
~param OnlyUserDocumentation whether the parsed data should not be documented
                             and only the user documentation should be used
~result whether the generation of the documentation was successful }
function TJADDState.GenerateDocumentation(OnlyUserDocumentation:
                                                             Boolean): Boolean;
begin
 try
   FGenerate.ParsedData := FFileList;             //assign the parsed data

   FProgress.Prepare;                             //show the progress
   //assign interface to show the progress
   FGenerate.Progress := Progress;
   try
     if OnlyUserDocumentation then                //generate the documentation
      Result := FGenerate.GenerateOnlyUserDocumentation(FFilesOfUserDoc)
     else
      Result := FGenerate.Generate(FFilesOfUserDoc);
   finally
     try
       FProgress.Finished;                        //finish the progress
     finally
      FGenerate.Progress := nil;                  //and remove it
     end;
   end;
 finally
  FGenerationMessages.Clear;                      //clear old messages
  FGenerate.GetGeneratorMessages(FGenerationMessages,  //and get the new ones
                                 FGenerationMessageDescriptions);
 end;
end;

{Generates the documentation as a help about a GUI.
~result if the generation of the documentation was successful }
function TJADDState.GenerateGUIHelp: Boolean;
var      List      :TStringList;                //the list of log files
begin
 try                                            //generate the documentation
   FProgress.Prepare;                           //show the progress
   //assign interface to show the progress
   FGenerate.Progress := Progress;
   try
     List := TStringList.Create;                //create list for log files
     try
       GetListOfGUIHelpLogFiles(List);          //get all log files

       //try to generate documentation about/with them
       Result := FGenerate.GenerateGUIHelp(List, FFilesOfUserDoc);

     finally
      List.Free;                                //free the list of log files
     end;
   finally
     try
       FProgress.Finished;                      //finish the progress
     finally
      FGenerate.Progress := nil;                //and remove it
     end;
   end;
 finally
  FGenerationMessages.Clear;                    //clear old messages
  FGenerate.GetGeneratorMessages(FGenerationMessages,  //and get the new ones
                                 FGenerationMessageDescriptions);
 end;
end;








{Initializes the state from the ini file.
~param Ini the ini file to initialize from }
procedure TJADDState.ReadIni(Ini: TCustomIniFile);
var       Version           :Integer;        //the version of Delphi to emulate
          Identification    :String;         //identification of classes to use
begin
 //read the version of Delphi to emulate and set it if valid
 Version := Ini.ReadInteger(JADDStateIniSection, 'DelphiVersion', -1);
 if (Version >= 1) and (Version <= 9) then
  //set the compiler symbols of the version
  SetDelphiVersion(Version - 1, FDefines.PreDefines);


 Identification := Ini.ReadString(JADDStateIniSection, 'Generator', '');
 if Identification <> '' then     //a generator is specified in the ini file?
  //create the generator of documentation
  FGenerate.ChangeGeneratorByName(Identification);

 Identification := Ini.ReadString(JADDStateIniSection, 'Extractor', '');
 if Identification <> '' then     //an extractor is specified in the ini file?
  //create the extractor of documentation
  FGenerate.ChangeExtractorByName(Identification);

 Identification := Ini.ReadString(JADDStateIniSection, 'Evaluator', '');
 if Identification <> '' then     //an evaluator is specified in the ini file?
  //create the evaluator of texts
  FGenerate.ChangeEvaluatorByName(Identification);
end;

{Writes the state to an ini file.
~param Ini the ini file to write the state to }
procedure TJADDState.WriteIni(Ini: TCustomIniFile);
begin
 //write the version of Delphi to emulate
 Ini.WriteInteger(JADDStateIniSection, 'DelphiVersion',
                  GetDelphiVersion(FDefines.PreDefines) + 1);

 //write used classes to generate documentation
 if FGenerate.GeneratorAvailable then
  Ini.WriteString(JADDStateIniSection, 'Generator',
                  FGenerate.GeneratorDescription.Identification);
 Ini.WriteString(JADDStateIniSection, 'Extractor',
                 FGenerate.ExtractorDescription.Identification);
 Ini.WriteString(JADDStateIniSection, 'Evaluator',
                 FGenerate.EvaluatorDescription.Identification);
end;













{Loads a DelphiDoc project ini file.
~param Ini the ini of a DelphiDoc project to load }
procedure TJADDState.LoadProject(Ini: TCustomIniFile);

 {Parses the constants for the conditional compiling.
 ~param List the list to add the read constants to }
 procedure ReadConstants(List: TIdentifierList);
 var       Text         :String;             //the declaration of all constants
           Data         :TPascalFile;        //the file to parse the constants
           Parser       :TCodeParser;        //parser of the constants
           Token        :String;             //each token
           i            :Integer;            //counter through the constants
           Ident        :TIdentifier;        //each constant
 begin
  Text := '';
  //for all declared constants in the ini files
  for i := 0 to Ini.ReadInteger('CondCompilingConstants', 'Count', 0) - 1 do
   begin
    Token := Ini.ReadString('CondCompilingConstants', 'Constant' + IntToStr(i),
                            '');               //read declaration of constant
    if Token <> '' then                        //the entry is valid?
     Text := Text + Token + ';' + LineDelimiter; //add declaration
   end;

  if Text <> '' then                         //some constants found?
   begin
    Data := TPascalFile.Create;                //create file to parse them in
    try
      Data.SetContent('const ' + Text);        //parse the text as constants
      Parser := TCodeParser.Create(Data);      //create the parser
      Parser.SetContentToParse(Data.Lines);    //pre-parse the text

      Parser.ParseImplementations;             //parse all constants

      //clear constants
      FDefines.ConditionalCompilingConstants.RemoveAll;
      for i := 0 to Data.Idents.Count - 1 do   //for each parsed constant
       begin
        Ident := Data.Idents[i];                 //get and check it
        if Ident.ClassType <> TConstant then
         raise Exception.CreateFmtHelp('Identifier "%s" is not a constant (%s)!',
                                       [Ident.Name, Ident.ClassName], 0);

        if assigned(TConstant(Ident).ConstType) then