udiagramcreator.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) 2005-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 UDiagramCreator;

{Contains the generator ~[linkClass TDiagramCreator] to create diagrams about
 the parsed data. It is also used by other generators to create diagrams if the
 inline command ~~[diagram ] is used.
}

interface

uses Classes,
     UBaseIdents,
     UOptions, UGenerationMessages, UMakeDoc,
     UDiagram;







      //default name of the diagram file
const DefaultDiagramFileName = 'Diagram.bmp';
      //extension of map-file to generate links in the DelphiDoc-syntax
      DDMapFileExtension = '.txt';


type

   { * * *  ***  * * *  ***   TDiagramCreator   ***  * * *  ***  * * *  }


  {The messages that can be generated by the generators of the class
   ~[link TDiagramCreator]. }
  TDiagramCreatorMessageKind = (
                                //the diagram is empty, so it wasn't saved
                                dcmkDiagramIsEmpty,

                                //an unknown option was specified
                                dcmkUnknownOption,
                                //the value for an option was invalid
                                dcmkInvalidValueForOption,
                                //the specified font is not available on the
                                //current system
                                dcmkFontNotFoundOnSystem,
                                //the specified lay-out can't be used on the
                                //kind of diagrams
                                dcmkInvalidLayOut,
                                //autmatically lay-outing the diagram failed
                                dcmkLayOutFailed,

                                //the specified classes or files were not found
                                //so nothing has been added to the diagram
                                dcmkEmptyListToAddOrSub,

                                //the specified file to add to the diagram
                                //wasn't found
                                dcmkFileNotFound,
                                //no valid file has been specified
                                dcmkInvalidFileSpecified,

                                //no kinds of classes have been specified to
                                //add
                                dcmkNoClassesSpecified,
                                //the specified class to add to the diagram
                                //wasn't found
                                dcmkClassNotFound,
                                //no valid file has been specified in which the
                                //class should be defined in
                                dcmkNoFileSpecifiedForClass,
                                //the class was not found in the specified file
                                dcmkClassNotFoundInFile,

                                //an unknown modifier was specified
                                dcmkModifierUnknown,
                                //a modifier had invalid parameters
                                dcmkModifierParameter,
                                //a class/file had invalid parameters
                                dcmkParameters
                               );



  //the image format to export the diagram to
  TDiagramExportFileType = (
                            //detect the image format by the file extension,
                            //if no or an unknown extension has been specified
                            //export as a bitmap
                            deftDetectByExtension,
                            //export as a (huge) bitmap
                            deftBitmap,
                            //export as a PNG
                            deftPortableNetworkGraphics,
                            //export as a JPEG image
                            deftJPEG,
{$IFNDEF LINUX}
                            //export as a(n old) Windows Meta file
                            deftWindowsMetaFile,
                            //export as an Enhanced Windows Meta file
                            deftEnhancedWindowsMetaFile,
{$ENDIF}
                            //export as an SVG image
                            deftScalableVectorGraphics,
                            //export as a compressed SVG image
                            deftCompressedScalableVectorGraphics);



  {Creates diagrams of the parsed data. It can not only be used to create
   diagrams like a generator like the others, but is also used to create
   diagrams to include them in the documentation generated by other
   generators if the inline command ~~[diagram ] is used. An example:~[br]
   ~[diagram /scopes=11100 TType.Tree /showfile=0 /layout=post /members ]

  ~feature optimize filter (instead of "-type(...)" or "-unit", "-program"
           etc.) }
  TDiagramCreator = class(TMakeDoc)
  private
    //the diagram object to manage and create diagrams with
    FDiagram: TDiagram;
    //the algorithm to be used to layout the diagram
    FLayout: TDiagramLayOut;

    //ID of the messages of this class
    FDiagramCreatorMessagesID: TMessageID;

    //the generator that uses this generator to create a diagram;
    //used to decide whether identifiers are ignored
    FFilterGenerator: TMakeDoc;

    //the file to start searching for classes, if not nil
    FStartFile: TPascalFile;


    //the image format to be used when exporting the diagram
    FExportImageType: TDiagramExportFileType;
    //the character encoding of the image file if saved as an SVG image;
    //should be the same as the source code was in
    FCharacterEncoding: String;

    //the name of the image file the diagram should be saved in
    FImageFileName: String;
    //the name of the file to save the link map in
    //('' = none; *.txt = DelphiDoc; else HTML-map)
    FLinkMapFileName: String;





    //while getting all option with ~[link GetAllOptionsString] the list of
    //classes or files is aggregated in this field by ~[link AggregateClasses]
    //or ~[link AggregateFiles]
    FAllOptionsAggregator: String;




    //Handles one parameter (either an option or something to add/remove).
    procedure DiagramParameter(Parameter: String);
    //Handles a list of parameters.
    procedure DiagramParameters(Parameters: String);


    //Aggregates all files in the diagram to ~[link FAllOptionsAggregator].
    function AggregateFiles(TheClass: TRecordType; TheFile: TPascalFile;
                            Selected: Boolean): TBoxEnumerationActions;
    //Aggregates all classes in the diagram to ~[link FAllOptionsAggregator].
    function AggregateClasses(TheClass: TRecordType; TheFile: TPascalFile;
                              Selected: Boolean): TBoxEnumerationActions;
    //Gets a long string with all options and the content of the diagram
    //suitable for ~[link DiagramParameters].
    function GetAllOptionsString: String;





    //Handles an option for the diagram.
    procedure DiagramOption(Option: String);


    //Handles the first part of classes to add or remove from the diagram.
    function AddSubClassStart(const ClassName, Parameter: String;
                              List: TList): Boolean;
    //Handles modifiers of a list fo classes to add or remove from the diagram.
    function AddSubClassModifiers(List: TList; Modifiers: String): Boolean;

    //Handles the first part of files to add or remove from the diagram.
    function AddSubFileStart(const FileName, Parameter: String;
                             List: TList): Boolean;
    //Handles modifiers of a list fo files to add or remove from the diagram.
    function AddSubFileModifiers(List: TList; Modifiers: String): Boolean;


    //Handles a parameter to add or remove boxes from the diagram.
    procedure DiagramAddSub(What: String; DoSub: Boolean);
    //Starts a new diagram.
    procedure DiagramClear;

    //Lays-out the diagram automatically.
    procedure AutomaticallyLayoutDiagram;



    //Saves a link-map of the diagram to the file in DelphiDoc's format.
    procedure SaveDDLinkMap(const LinkFileName, DiagramFileName: String);
    //Saves a link-map of the diagram to the file as HTML image-map.
    procedure SaveHTMLLinkMap(const LinkFileName, DiagramFileName: String);

  protected
    //Called when the parsed data, the list of files is changed.
    procedure ParsedDataChanged; override;

    //Process parsed data; Create and save the diagram.
    function DoGenerateDocumentation: Boolean; override;

    property DiagramCreatorMessagesID: TMessageID
                                               read FDiagramCreatorMessagesID
                                               write FDiagramCreatorMessagesID;
  public
    //Creates the generator object.
    constructor Create; override;
    //Creates the generator object and initializes the options.
    destructor Destroy; override;


    //Returns a description of the documentation of the generator.
    class function GetDescription: TGeneratorDescription; override;

    //Returns the number of available options in this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                      override;
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;


    //Checks whether the identifier should be included in the documentation.
    function DoNotDocumentIdentifier(Ident: TIdentifier;
                                     TheFile: TPascalFile = nil): Boolean;
                                                                      override;




    //Creates a diagram from a list of parameters.
    procedure CreateDiagram(Params: TStrings);



    property Diagram: TDiagram read FDiagram;
    property FilterGenerator: TMakeDoc read FFilterGenerator
                                       write FFilterGenerator;
    property StartFile: TPascalFile read FStartFile write FStartFile;
    property CharacterEncoding: String read FCharacterEncoding
                                       write FCharacterEncoding;
  end;














implementation

uses SysUtils, Windows,
{$IFNDEF LINUX}
     Graphics, Forms, ShellAPI,
{$ELSE}
     QGraphics, QForms,
{$ENDIF}
     General,
     UPascalConsts{,
     UCommentDoc};



//Extracts the first part up to the first "." of a string.
function ExtractFirstPart(var What: String): String; forward;

//Extracts the name at the beginning of a string.
function ExtractName(var Part: String): String; forward;

//Adds an object to the list if it is not already in it.
procedure Add(List: TList; What: TObject); forward;

//Gets a set of kinds of record-like types from a string.
function GetRecordLikeTypeSet(const Filter: String;
                              var FilterSet: TRecordKinds): Boolean; forward;