ujaddstate.pas

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

~param Defines the compiler symbols to change
~param Symbol  the symbol to define or undefine
~param DoSet   if the compiler symbol should be defined or undefined }
procedure ChangeDefine(Defines: TStrings; Symbol: String; DoSet: Boolean);
var       Index       :Integer;       //index of the compiler symbol
begin
 Index := Defines.IndexOf(Symbol);    //get index of the compiler symbol
 if (Index <> -1) <> DoSet then       //must be changed?
  if Index = -1 then                    //must be defined?
   Defines.Append(Symbol)                 //define the compiler symbol
  else
   Defines.Delete(Index);                 //undefine the compiler symbol
end;

{Defines or undefines a list of compiler symbols.
~param Defines the compiler symbols to change
~param Symbols the symbols to define or undefine
~param DoSet   if the compiler symbols should be defined or undefined }
procedure ChangeDefines(Defines: TStrings;
                        Symbols: array of String; DoSet: Boolean);
var       i            :Integer;            //counter through all symbols
begin
 for i := Low(Symbols) to High(Symbols) do  //for all compiler symbols
  ChangeDefine(Defines, Symbols[i], DoSet);   //define or undefine the symbol
end;

{Defines and undefines compiler symbols depending on Delphi/Kylix version.
~param Defines     the compiler symbols to change
~param CompilerVer the internal compiler version
~param IsAKylix    if it is Kylix }
procedure AdjustDefines(Defines: TStrings;
                        CompilerVer: Integer; IsAKylix: Boolean);
begin
 ChangeDefine(Defines, 'WINDOWS', CompilerVer = 80);     //only in Delphi 1
 //Delphi 2 and higher, but not in kylix
 ChangeDefine(Defines, 'WIN32', not IsAKylix and (CompilerVer <> 80));
 //Delphi 6 and higher, but not in kylix
 ChangeDefine(Defines, 'MSWINDOWS', not IsAKylix and (CompilerVer >= 140));
 //Delphi 6 and higher and Kylix
 ChangeDefine(Defines, 'CONDITIONALEXPRESSIONS', CompilerVer >= 140);
 ChangeDefines(Defines, ['LINUX', 'LINUX32', 'POSIX', 'POSIX32',   //in Kylix
                         'ELF', 'PC_MAPPED_EXCEPTIONS'], IsAKylix);

 //Delphi 2007 is only of a half new version
 if CompilerVer = 185 then
  ChangeDefine(Defines, 'VER180', True);     //is it compatible to Delphi 2006

 //some (unknown?) .NET compiler symbols
 if not (CompilerVer in DelphiDotNETVersionsPossible) then
  begin
   ChangeDefines(Defines, ['CLR', 'CIL', 'MANAGEDCODE'],
                 CompilerVer in DelphiDotNETVersions);
   if CompilerVer in DelphiDotNETVersions then             //it's .NET and
    ChangeDefines(Defines, ['WIN32', 'MSWINDOWS'], False);   //not Windows!
  end
 else
  if Defines.IndexOf('CLR') <> -1 then                   //it's .NET and
   ChangeDefines(Defines, ['WIN32', 'MSWINDOWS'], False);  //not Windows!
end;



{Returns the Delphi version by the define of the internal compiler version.
~param Defines the defined compiler symbols
~result the Delphi version obtained by the internal compiler version }
function GetDelphiVersion(Defines: TStrings): Integer;
begin
 if Defines.IndexOf('LINUX') = -1 then             //is not a kylix?
  begin
   Result := High(DelphiVersionNumbers);
   while (Result >= Low(DelphiVersionNumbers)) and   //compare compiler version
         (Defines.IndexOf(Format('VER%u',              //not found?
                                 [DelphiVersionNumbers[Result]])) = -1) do
    Dec(Result);                                         //try next version
  end
 else
  Result := -1;
end;

{Defines the internal compiler version by the Delphi version.
~param Version the version of Delphi to set
~param Defines the defined compiler symbols to change for the Delphi version }
procedure SetDelphiVersion(Version: Integer; Defines: TStrings);
var       Versions        :Integer;   //all internal compiler versions
          Index           :Integer;   //index of the compiler symbol
begin
 assert((Version >= Low(DelphiVersionNumbers)) and
        (Version <= High(DelphiVersionNumbers)));
 if DelphiVersionNumbers[Version] <> 0 then  //valid version?
  begin
   for Versions := 0 to 999 do          //for all possible versions
    begin
     Index := Defines.IndexOf(Format('VER%u', [Versions]));
     if Index <> -1 then                  //symbol of version defined?
      Defines.Delete(Index);                //remove compiler symbol
    end;
   //define the compiler symbol of the internal compiler version
   Defines.Append(Format('VER%u', [DelphiVersionNumbers[Version]]));
   //adjust other compiler symbols for the Delphi version
   AdjustDefines(Defines, DelphiVersionNumbers[Version], False);
  end;
end;
















{Writes a list of files and directories into an ini file.
~param Ini             the ini file to write the list to
~param Section         the section in the ini file to write the list to
~param List            the list to write
~param WriteBoolObject whether the "object" of each item should be written as
                       a boolean value }
procedure WriteFileListToIni(Ini: TCustomIniFile; const Section: String;
                             List: TStrings; WriteBoolObject: Boolean);
var       i                 :Integer; //counter through the list
begin
 Ini.EraseSection(Section);           //clear the section and write
 Ini.WriteInteger(Section, 'Count', List.Count); //the number of entries
 for i := 0 to List.Count - 1 do                 //for each entry
  begin      //write the file/directory and if it should be parsed recursively
   Ini.WriteString(Section, 'Item' + IntToStr(i), List[i]);
   if WriteBoolObject then
    Ini.WriteBool(Section, 'Recurse' + IntToStr(i),
                  assigned(List.Objects[i]));
  end;
end;

{Reads a list of files and directories from an ini file.
~param Ini                 the ini file to read the list from
~param Section             the section in the ini file containing the list
~param List                the list to read from the ini
~param ReadBooleanAsObject whether a boolean value should be read and assigned
                           as object or each entry }
procedure ReadFileListFromIni(Ini: TCustomIniFile; const Section: String;
                              List: TStrings; ReadBooleanAsObject: Boolean);
var       i                  :Integer;  //counter through the list
          S                  :String;   //the files in the list
begin
 List.Clear;                            //clear the list
 for i := 0 to Ini.ReadInteger(Section, 'Count', 0) - 1 do //for all entries
  begin
   S := Ini.ReadString(Section, 'Item' + IntToStr(i), '');  //read it
   if S <> '' then                 //the entry is valid?
    if ReadBooleanAsObject then      //boolean value should be read?
     //add the entry to the list and also mark it, if this is set in the ini
     List.AddObject(S, Pointer(Ord(Ini.ReadBool(Section,
                                                'Recurse' + IntToStr(i),
                                                False))))
    else
     List.Add(S);                      //add the entry to the list
  end;
end;









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



//read implementation of TJADDStateEventList

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









{Creates the object and everything so save the state.
~param MainIniFileName the name of the ini file use to initialize the objects
                       used to generate documentation whenever needed }
constructor TJADDState.Create(MainIniFileName: String);
begin
 inherited Create;                      //create the state object

 FFileList := TFileList.Create;         //create an empty list of parsed data

 FGenerate := TGeneratorManager.Create; //create manager to generate
 FGenerate.MainIniFileName := MainIniFileName;    //assign the ini file
 FGenerate.OnGeneratorChanged := HandlerGeneratorChanged; //and register event
 FGenerate.OnExtractorChanged := HandlerExtractorChanged;  //handlers
 FGenerate.OnEvaluatorChanged := HandlerEvaluatorChanged;


 FKeptParsedData := TList.Create;       //create list for kept data

 FDefines := TDefineOptions.Create;     //create & initialize compiler options

 FFilesToParse := TStringList.Create;   //create lists for files to parse
 FFilesToExclude := TStringList.Create; //or not
 FFilesOfLibrary := TStringList.Create; //or maybe

 //create list for messages while the parsing
 FParserMessages := TParseMessageList.Create;



 FFilesOfUserDoc := TStringList.Create; //create list for user documentation

 FGUIHelpLogFiles := TStringList.Create; //create list for log files of GUIs


 //create list for messages while the generating documentation
 FGenerationMessages := TGeneratorMessageList.Create;


 //create lists for events handlers
 FOnFileListChanged := TJADDStateEventList.Create;
 FOnGeneratorChanged := TJADDStateEventList.Create;
 FOnExtractorChanged := TJADDStateEventList.Create;
 FOnEvaluatorChanged := TJADDStateEventList.Create;
end;


{Frees the object and the state. }
destructor TJADDState.Destroy;
var        i         :Integer;     //counter through kept data
begin
 FOnFileListChanged.Free;          //free lists of event handlers
 FOnGeneratorChanged.Free;
 FOnExtractorChanged.Free;
 FOnEvaluatorChanged.Free;

 FGenerationMessages.Free;         //free list of messages while generating

 FGUIHelpLogFiles.Free;            //free list of log files of GUIs
 FFilesOfUserDoc.Free;             //free list of files with user documentation

 FParserMessages.Free;             //free list for messages while parsing

 FFilesOfLibrary.Free;             //free lists of files to parse or not
 FFilesToExclude.Free;
 FFilesToParse.Free;

 FDefines.Free;                    //free compiler options


 if assigned(FKeptParsedData) then //kept data available?
  begin
   if FKeptParsedData.IndexOf(FFileList) <> -1 then //current data kept?
    FFileList := nil;                                 //don't free it again

   for i := 0 to FKeptParsedData.Count - 1 do       //free all kept data
    TFileList(FKeptParsedData[i]).Free;

   FKeptParsedData.Free;                            //free list for kept data
  end;


 FGenerate.Free;                   //free manager to generate
 FFileList.Free;                   //free current parsed data

 inherited Destroy;                //free the state object
end;





{Access method to get the number of kept data sets.
~result the number of kept data sets }
function TJADDState.GetKeptDataCount: Integer;
begin
 Result := FKeptParsedData.Count;
end;

{Access method to get one of the kept data sets.
~param Index the index of the kept data to get
~result the kept data of the index }
function TJADDState.GetKeptDatas(Index: Integer): TFileList;
begin
 assert((Index >= 0) and (Index < FKeptParsedData.Count));
 Result := FKeptParsedData[Index];
end;






{Called when the generator of the documentation is replaced by another one.
~param Sender the sender of the event, ~[link FGenerate] }
procedure TJADDState.HandlerGeneratorChanged(Sender: TGeneratorManager);
begin
 if FGenerate.GeneratorAvailable then     //a generator avilable now?
  FGenerate.ParsedData := FFileList;        //set the current parsed data

 GeneratorChanged;                        //notify that generator has changed
end;

{Called when the extractor of comments for the documentation is replaced by
 another one.
~param Sender the sender of the event, ~[link FGenerate] }
procedure TJADDState.HandlerExtractorChanged(Sender: TGeneratorManager);
begin
 ExtractorChanged;                        //notify that extractor has changed
end;

{Called when the evaluator of texts for the documentation is replaced by
 another one.
~param Sender the sender of the event, ~[link FGenerate] }
procedure TJADDState.HandlerEvaluatorChanged(Sender: TGeneratorManager);
begin
 EvaluatorChanged;                        //notify that evaluator has changed
end;





{Calls each event handler in the list.
~param Handlers the list of handlers to call }
procedure TJADDState.CallEventHandlers(Handlers: TJADDStateEventList);
var       i         :Integer;            //counter through the event handlers
begin
 for i := Handlers.Count - 1 downto 0 do //call each handler
  Handlers.Items[i](Self);
end;


{Called when the current parsed data is changed.
~param NewFileList whether new parsed data has been assigned, instead of the
                   current one changed }
procedure TJADDState.FileListChanged(NewFileList: Boolean = True);
begin
 //clear messages from generating, their references to the identifiers
 FGenerationMessages.Clear;                                  //are invalid now
 FGenerationMessageDescriptions := nil;

 if NewFileList then                        //new list of files?
  begin
   ClearParserMessages;                       //clear parser messages
   if FGenerate.GeneratorAvailable then       //generator available?
    FGenerate.ParsedData := FFileList;          //assign it the new data
  end;

 CallEventHandlers(FOnFileListChanged);     //notify event handlers
end;

{Called when the generator of documentation is changed. }
procedure TJADDState.GeneratorChanged;
begin
 CallEventHandlers(FOnGeneratorChanged);    //notify event handlers
end;

{Called when the extractor of comments for the documentation is changed. }
procedure TJADDState.ExtractorChanged;
begin
 CallEventHandlers(FOnExtractorChanged);    //notify event handlers
end;

{Called when the evaluator of texts for the documentation is changed. }
procedure TJADDState.EvaluatorChanged;
begin
 CallEventHandlers(FOnEvaluatorChanged);    //notify event handlers
end;



{Clears the current parsed data. }
procedure TJADDState.ClearFileList;
var       OldList   :TFileList;                  //parsed data
begin
 if assigned(FFileList) then                     //not already empty?
  begin
   OldList := FFileList;                           //save old list
   FFileList := nil;                               //nothing parsed so far
   try
     FCompletelyParsed := False;
     FileListChanged;                              //notify
   finally
    if FKeptParsedData.IndexOf(OldList) = -1 then  //parsed data not kept?
     OldList.Free;                                   //free the parsed data
   end;
  end;
end;




{Clears the list of messages generated while parsing. }
procedure TJADDState.ClearParserMessages;
begin
 FParserMessages.Clear;
end;

{Called when a message is generated while parsing the pascal code.
~param Information all information about the message
~param Sender      the sender of the message, ~[link FFileList.ParserManager] }
procedure TJADDState.ParserMessage(const Information: TParseMessageInformation;
                                   Sender: TParserManager);
var       AddToList :Boolean; //whether the message should be added to the list
begin
 AddToList := True;           //assume it should be added
 if assigned(FOnParserMessage) then          //event handler assigned?
  FOnParserMessage(Information, Sender, Self, AddToList);
 if AddToList then            //message should be added to the list
  FParserMessages.Add(Information);          //save the message
end;