uicdeclarationassembler.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) 2006-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 UICDeclarationAssembler;

{Contains only the class ~[linkClass TICDeclarationAssembler] to assemble the
 declaration of identifiers in the nodes of the
 ~[linkUnit UICNodes COM] - Comment Object Model.
}

interface

uses UBaseIdents,
     UMakeDoc,
     UICNodes;


type


   { * * *  ***  * * *  ***  TICDeclarationAssembler  ***  * * *  ***  * * *  }

  //used to assemble the declaration of an identifier
  TICDeclarationAssembler = class;


  {Called when a reference to an implemented interface is found in the
   declaration but the interface has not been implemented by the class. This
   is an inconsistency within the data that may indicate the the source can not
   be compiled or the parser is faulty.
  ~param Sender        the sender of the event, the assembler of delcarations
  ~param InterfaceName the name of the interface that has been referenced
                       inside but not implemented by a class
  ~param Position      the position where the unknown interface has been used,
                       either a method or a property
  ~param FromMethod    whether the interface has been referenced to rename one
                       of its methods, instead of aliases its implementation to
                       a property }
  TInterfaceUnknownEvent = procedure(Sender: TICDeclarationAssembler;
                                     const InterfaceName: String;
                                     Position: TIdentifier;
                                     FromMethod: Boolean) of object;


  {Used to assemble the declaration of an identifier in the nodes of the
   ~[linkUnit UICNodes COM] - Comment Object Model. This can be done by calling
   the method ~[link GetDeclaration] with the identifier in question, which
   will the identifier's ~[link TIdentifier.GetDeclaration GetDeclaration]
   method with itself. After that the declaration can be copied (clones) from
   the property ~[link Declaration]. }
  TICDeclarationAssembler = class(TDeclarationAssembler)
  private
    //the generator for which the declaration is assembled,
    //used to find other identifiers
    FGenerator: TMakeDoc;

    //called when a reference to an implemented interface is found in the
    //declaration but the interface has not been implemented by the class
    FOnUnknownInterface: TInterfaceUnknownEvent;


    //the assembled declaration
    FDeclaration: TICNCompound;

    //used to optimize simple texts
    FCacheText: String;


    //Prepares the assembling of a declaration.
    procedure PrepareAssembling;


    //Flushes the cache of simple text if necessary.
    procedure CheckText;
    //Adds a simple pascal token to the declaration being assembled.
    procedure AddPascalToken(const Text: String; Kind: TICPascalCode);
    //Adds a link on the identifier.
    procedure CreateLink(Ident: TIdentifier; AddFileLink: Boolean = False);
    //Adds a link to the file.
    procedure CreateFileLink(TheFile: TPascalFile);

  protected
  public
    //Creates the assembler object and saves the reference on the generator.
    constructor Create(Generator: TMakeDoc);
    //Frees the object and declaration.
    destructor Destroy; override;

    //Assembles the declaration of the identifier.
    procedure GetDeclaration(Identifier: TIdentifier); override;
    //Assembles the declaration of a part of an identifier.
    procedure GetDeclarationPart(Identifier: TIdentifier; const Expr: String);


    //Will be called for all reserved words.
    procedure ReservedWord(const Word: String); override;
    //Will be called for all texts of identifiers.
    procedure IdentifierText(const Text: String); override;
    //Will be called for all names of identifier-type identifiers.
    procedure TypeIdentifierText(Ident: TIdentifier); override;

    //Will be called for a text of a type identifier.
//    procedure TypeText(const TypeStr: String); override;

    //Will be called for all expressions.
    procedure ExprText(const ExprStr: String); override;
    //Will be called for texts.
    procedure Text(const Text: String); override;
    //Will be called for read- and write-attributes of properties.
    procedure PropertyReadWrite(const ReadWrite: String; Prop: TProperty);
                                                                      override;
    //Will be called for implements-attribute of properties.
    procedure PropertyImplements(Prop: TProperty); override;
    //Will be called for a reference on a method of an implemented interface.
    procedure InterfaceMethod(const Name: String; Method: TIdentifier);
                                                                      override;
    //Will be called for a reference on a method.
    procedure MethodName(const Name: String; MethodOf: TRecordType); override;


    property OnUnknownInterface: TInterfaceUnknownEvent
                            read FOnUnknownInterface write FOnUnknownInterface;
    property Declaration: TICNCompound read FDeclaration;
  end;





implementation

uses SysUtils,
     General,
     UPascalConsts,
     UExtIdents,
     UTokenParser;




   { * * *  ***  * * *  ***  TICDeclarationAssembler  ***  * * *  ***  * * *  }


{Creates the assembler object and saves the reference on the generator.
~param Generator the generator for whichs pascal data declarations will be
                 assembled }
constructor TICDeclarationAssembler.Create(Generator: TMakeDoc);
begin
 inherited Create;                    //create assembler

 FGenerator := Generator;             //save reference on generator
end;

{Frees the object and declaration. }
destructor TICDeclarationAssembler.Destroy;
begin
 if Assigned(FDeclaration) then       //declaration assembled?
  FDeclaration.Owner.Free;              //free assembled declaration

 inherited Destroy;                   //free the assembler
end;



{Prepares the assembling of a declaration. }
procedure TICDeclarationAssembler.PrepareAssembling;
var       Owner        :TICNodeOwner; //the owner of the assembled desclaration
begin
 if Assigned(FDeclaration) then       //old declaration still saved?
  begin
   FDeclaration.Owner.Free;             //free it
   FDeclaration := nil;
  end;

 Owner := TICNodeOwner.Create;        //create new owner
 try                                  //and node for declaration
   FDeclaration := TICNCompound.CreateCompound(Owner);
 except
   Owner.Free;
   raise;
 end;
end;



{Flushes the cache of simple text if necessary. }
procedure TICDeclarationAssembler.CheckText;
begin
 if FCacheText <> '' then              //some text cached/buffered?
  begin                                  //add the text
   FDeclaration.AppendNode(TICNText.CreateText(FDeclaration.Owner,
                                               FCacheText));
   FCacheText := '';                     //the cache is now empty
  end;
end;

{Adds a simple pascal token to the declaration being assembled.
~param Text the token to be added
~param Kind the kind of the text }
procedure TICDeclarationAssembler.AddPascalToken(const Text: String;
                                                 Kind: TICPascalCode);
begin
 CheckText;                             //check for cached/buffered text
 //add the pascal token
 FDeclaration.AppendNode(TICNPascalCode.CreatePascalCode(FDeclaration.Owner,
                                                         Kind, Text));
end;

{Adds a link on the identifier.
~param Ident       a identifier to that a link should be generated
~param AddFileLink whether a link on its file should also be generated }
procedure TICDeclarationAssembler.CreateLink(Ident: TIdentifier;
                                             AddFileLink: Boolean = False);
begin
 CheckText;                          //check for cached/buffered text
 if AddFileLink then                 //link on file should also be generated?
  begin
   CreateFileLink(Ident.InFile);       //add link on the file
   Text('.');                          //and separating dot
   CheckText;                          //add the separating dot
  end;
(*
 FDeclaration.AppendNode(TICNLinkIdentifier.CreateIdentifierLink(
                                  FDeclaration.Owner, Ident.Name, Ident, nil));
*)
 //add the link to the identifier
 FDeclaration.AppendNode(TICNPascalLink.CreateLink(FDeclaration.Owner,
                                                   Ident, nil));
end;

{Adds a link to the file.
~param TheFile a file to that a link should be added }
procedure TICDeclarationAssembler.CreateFileLink(TheFile: TPascalFile);
begin
 CheckText;                             //check for cached/buffered text
(*
 FDeclaration.AppendNode(TICNLinkIdentifier.CreateIdentifierLink(
                                                      FDeclaration.Owner,
                                                      TheFile.InternalFileName,
                                                      nil, TheFile));
*)
 //add link to the file
 FDeclaration.AppendNode(TICNPascalLink.CreateLink(FDeclaration.Owner,
                                                   nil, TheFile));
end;