udiagramcreator.pas

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

   Assert(Index >= GetOptionCount);
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;






{Checks whether the identifier should be included in the documentation. May be
 called multiple times per identifier and from different methods. That a file
 should not be documented, does not mean that no identifier of it should be
 documented. If a record-like type should not be documented, that means also no
 members of it will.~[br]
 So notice: always check if in a record-like type and it is not documented;
 and also notice, that it will also be called for the special exported
 identifiers.
~param Ident   the identifier to check whether it should not be documentated
               (or nil in case of the file)
~param TheFile the file the identifier is defined in
~result whether the identifier should be excluded from the documentation }
function TDiagramCreator.DoNotDocumentIdentifier(Ident: TIdentifier;
                                          TheFile: TPascalFile = nil): Boolean;
begin
 Assert(Assigned(Ident) or Assigned(TheFile));
 Assert(not Assigned(Ident) or not Assigned(TheFile) or
        (Ident.InFile = TheFile));

 //if used by another generator, use also its filter
 Result := (Assigned(FFilterGenerator) and
            FFilterGenerator.DoNotDocumentIdentifier(Ident, TheFile)) or
           inherited DoNotDocumentIdentifier(Ident, TheFile);
end;












{Handles one parameter (either an option or something to add/remove).
~param Parameter the parameter to handle }
procedure TDiagramCreator.DiagramParameter(Parameter: String);
var       FirstChar      :Char;          //the first character of the parameter
begin
 if Parameter <> '' then                 //parameter given?
  begin
   FirstChar := Parameter[1];              //get first character
   if FirstChar in ['/', '+', '-'] then    //special character?
    Delete(Parameter, 1, 1);                 //remove it

   if FirstChar = '/' then                 //is an option?
    DiagramOption(Parameter)                 //handle the option
   else
    DiagramAddSub(Parameter, FirstChar = '-');  //add or remove some boxes
  end;
end;

{Handles a list of parameters.
~param Parameters a string with several space-separated parameters to handle }
procedure TDiagramCreator.DiagramParameters(Parameters: String);
var       i              :Integer;    //counter through the string
          Parameter      :String;     //each parameter
begin
 Parameters := Trim(Parameters);
 while Parameters <> '' do            //while parameters left
  begin
   i := 0;                              //search end of the next parameter
   while (i < Length(Parameters)) and (Parameters[i + 1] > ' ') do
    inc(i);
   Parameter := copy(Parameters, 1, i); //extract the parameter
   Delete(Parameters, 1, i + 1);        //remove it from the string
   Parameters := TrimLeft(Parameters);  //and remove separators

   DiagramParameter(Parameter);         //handle the parameter
  end;
end;





{Aggregates all files in the diagram to ~[link FAllOptionsAggregator].
 Type: ~[link TForEachBoxRecallFunc]
~param TheClass always nil, only files are in the diagram
~param TheFile  each file in the diagram
~param Selected if the box of the file is selected
~result what actions to take on the box or the enumeration, alwayws [] }
function TDiagramCreator.AggregateFiles(TheClass: TRecordType;
                                        TheFile: TPascalFile;
                                    Selected: Boolean): TBoxEnumerationActions;
begin
// assert(not Selected);
 assert(not assigned(TheClass));
 //add the file to the list
 FAllOptionsAggregator := FAllOptionsAggregator + ' ' +
                          TheFile.InternalFileName;
 Result := [];                      //next file
end;

{Aggregates all classes in the diagram to ~[link FAllOptionsAggregator].
 Type: ~[link TForEachBoxRecallFunc]
~param TheClass each class in the diagram
~param TheFile  the file of the class
~param Selected if the box of the class is selected
~result what actions to take on the box or the enumeration, alwayws [] }
function TDiagramCreator.AggregateClasses(TheClass: TRecordType;
                                          TheFile: TPascalFile;
                                    Selected: Boolean): TBoxEnumerationActions;
begin
// assert(not Selected);
 assert(TheClass.InFile = TheFile);
 assert(assigned(TheFile));
 //add the class to the list
 FAllOptionsAggregator := FAllOptionsAggregator + ' ' +
                          TheClass.Name + '(' + TheFile.InternalFileName + ')';
 Result := [];                      //next class
end;


{Gets a long string with all options and the content of the diagram
 suitable for ~[link DiagramParameters].
~result all options and boxes in the diagram }
function TDiagramCreator.GetAllOptionsString: String;

 {Returns the kinds of member to be shown in record-like types.
 ~result the string defining the kinds of members }
 function MemberKinds: String;
 var      Desc           :TOptionDescription; //an option describing a set
          Value          :TOptionValue;       //value of the set
 begin
  //get the shown members
  Value.SetData := SetToOption(FDiagram.ShowMembers,
                               SizeOf(FDiagram.ShowMembers));

  ClearDescription(Desc);                      //clear structure
  Desc.DataType := otSet;                      //it is a set of
  Desc.SetNames := OptionItemsFilterMembersByKind; //kinds of members

  Result := ValueToString(Value, Desc);        //get its string-representation
 end;

 {Returns the scopes of members to be shown in record-like types.
 ~result the string defining the scopes }
 function Scopes: String;
 var      Desc      :TOptionDescription;   //an option describing a set
          Value     :TOptionValue;         //value of the set
 begin
  //get the shown members
  Value.SetData := SetToOption(FDiagram.ShowScopes,
                               SizeOf(FDiagram.ShowScopes),
                               Ord(Low(TMemberScope)));

  ClearDescription(Desc);                      //clear structure
  Desc.DataType := otSet;                      //it is a set of
  Desc.SetNames := OptionItemsFilterMembersByScope; //scopes of members

  Result := ValueToString(Value, Desc);        //get its string-representation
 end;

 {Returns the kinds of record-like types to be shown in files.
 ~result the string defining the kinds }
 function Types: String;
 var      Desc      :TOptionDescription;   //an option describing a set
          Value     :TOptionValue;         //value of the set
 begin
  //get the shown members

  Value.SetData := SetToOption(FDiagram.ShowClasses,
                               SizeOf(FDiagram.ShowClasses));

  ClearDescription(Desc);                      //clear structure
  Desc.DataType := otSet;                      //it is a set of
  Desc.SetNames := OptionItemsFilterClassesByKind; //record-like types

  Result := ValueToString(Value, Desc);        //get its string-representation
 end;


         //to translate boolean values to strings
const    BoolMask: array[Boolean] of Char = ('0', '1');
         //to translate the algorithm to lay-out the diagram to a string
         LayOutMask: array[TDiagramLayOut] of String =
                     ('sugiyama', 'simple', 'simplepostprocess');
{$IFOPT C+}
var      CheckAllOpts   :set of TDiagramOption;
{$ENDIF}

var      S              :String;     //a general string
         i              :Integer;    //general counter
begin
{$IFOPT C+}
 CheckAllOpts := [Low(TDiagramOption)..High(TDiagramOption)];
{$ENDIF}

 //kind of the doagram has to be first!
 //(will start a new diagram, i.e. delete all boxes)
 if FDiagram.IsFileDiagram then
  Result := DiagramOptionNames[doFile]
 else
  Result := DiagramOptionNames[doClass];
 Result := '/' + Result;
{$IFOPT C+}
 CheckAllOpts := CheckAllOpts - [doClass, doFile];
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doAssociations] + '=' +
           BoolMask[FDiagram.ShowAssociations];
{$IFOPT C+}
 Exclude(CheckAllOpts, doAssociations);
{$ENDIF}

 S := FDiagram.Font.Name;
 for i := 1 to Length(S) do          //replace all spaces ' ' with stars '*'
  if S[i] = ' ' then
   S[i] := '*';
 Result := Result + ' /' + DiagramOptionNames[doFont] + '=' + S;
{$IFOPT C+}
 Exclude(CheckAllOpts, doFont);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doImplementation] + '=' +
           BoolMask[FDiagram.ShowUsingImplementation];
{$IFOPT C+}
 Exclude(CheckAllOpts, doImplementation);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doLayout] + '=' +
           LayOutMask[FLayout];
{$IFOPT C+}
 Exclude(CheckAllOpts, doLayout);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doMargin] + '=' +
           IntToStr(FDiagram.Margin);
{$IFOPT C+}
 Exclude(CheckAllOpts, doMargin);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doMemberKinds] + '=' +
           MemberKinds;
{$IFOPT C+}
 Exclude(CheckAllOpts, doMemberKinds);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doParameter] + '=' +
           BoolMask[FDiagram.ShowMethodParameters];
{$IFOPT C+}
 Exclude(CheckAllOpts, doParameter);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doResult] + '=' +
           BoolMask[FDiagram.ShowReturnType];
{$IFOPT C+}
 Exclude(CheckAllOpts, doResult);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doScopes] + '=' + Scopes;
{$IFOPT C+}
 Exclude(CheckAllOpts, doScopes);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doShowFile] + '=' +
           BoolMask[FDiagram.ShowFileNameInClass];
{$IFOPT C+}
 Exclude(CheckAllOpts, doShowFile);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doShowPrivate] + '=' +
           BoolMask[FDiagram.ShowClassesNotInInterface];
{$IFOPT C+}
 Exclude(CheckAllOpts, doShowPrivate);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doSize] + '=' +
           IntToStr(FDiagram.Font.Size);
{$IFOPT C+}
 Exclude(CheckAllOpts, doSize);
{$ENDIF}

 Result := Result + ' /' + DiagramOptionNames[doTypes] + '=' + Types;
{$IFOPT C+}
 Exclude(CheckAllOpts, doTypes);
{$ENDIF}


{$IFOPT C+}
 Assert(CheckAllOpts = []);                //all possible parameters returned?
{$ENDIF}



 FAllOptionsAggregator := '';              //clear aggregator
 if FDiagram.IsFileDiagram then            //aggregate all files/classes
  FDiagram.ForEachBox(AggregateFiles)
 else
  FDiagram.ForEachBox(AggregateClasses);

 Result := Result + FAllOptionsAggregator; //add all files/classes
 FAllOptionsAggregator := '';              //clear aggregator
end;









{Handles an option for the diagram.
~param Option the option to handle }
procedure TDiagramCreator.DiagramOption(Option: String);
var       Valid          :Boolean;     //option is vaild

 {Sets the font to the value, its name.
 ~param Value the name of the font to set }
 procedure SetFont(Value: String);
 var       i         :Integer;             //counter through the string
 begin
  //allows to insert names with spaces in a space-separated list of parameters:
  for i := 0 to Length(Value) do  //replace all "*" with spaces
   if Value[i] = '*' then
    Value[i] := ' ';