src/classdef.h

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17
  18 #ifndef CLASSDEF_H
  19 #define CLASSDEF_H
  20
  21 #include <qlist.h>
  22 #include <qdict.h>
  23 #include <qptrdict.h>
  24
  25 #include "definition.h"
  26
  27 struct Argument;
  28 class MemberDef;
  29 class MemberList;
  30 class MemberDict;
  31 class ClassList;
  32 class ClassSDict;
  33 class OutputList;
  34 class FileDef;
  35 class FileList;
  36 class BaseClassList;
  37 class NamespaceDef;
  38 class MemberDef;
  39 class ExampleSDict;
  40 class MemberNameInfoSDict;
  41 class UsesClassDict;
  42 class ConstraintClassDict;
  43 class MemberGroupSDict;
  44 class QTextStream;
  45 class PackageDef;
  46 class GroupDef;
  47 class StringDict;
  48 struct IncludeInfo;
  49 class ClassDefImpl;
  50 class ArgumentList;
  51 class FTextStream;
  52
  53 /** A class representing of a compound symbol.
  54  *
  55  *  A compound can be a class, struct, union, interface, service, singleton,
  56  *  or exception.
  57  *  \note This class should be renamed to CompoundDef
  58  */
  59 class ClassDef : public Definition
  60 {
  61   public:
  62     /** The various compound types */
  63     enum CompoundType { Class,     //=Entry::CLASS_SEC,
  64                         Struct,    //=Entry::STRUCT_SEC,
  65                         Union,     //=Entry::UNION_SEC,
  66                         Interface, //=Entry::INTERFACE_SEC,
  67                         Protocol,  //=Entry::PROTOCOL_SEC,
  68                         Category,  //=Entry::CATEGORY_SEC,
  69                         Exception, //=Entry::EXCEPTION_SEC
  70                         Service,   //=Entry::CLASS_SEC
  71                         Singleton, //=Entry::CLASS_SEC
  72                       };
  73
  74     /** Creates a new compound definition.
  75      *  \param fileName  full path and file name in which this compound was
  76      *                   found.
  77      *  \param startLine line number where the definition of this compound
  78      *                   starts.
  79      *  \param startColumn column number where the definition of this compound
  80      *                   starts.
  81      *  \param name      the name of this compound (including scope)
  82      *  \param ct        the kind of Compound
  83      *  \param ref       the tag file from which this compound is extracted
  84      *                   or 0 if the compound doesn't come from a tag file
  85      *  \param fName     the file name as found in the tag file.
  86      *                   This overwrites the file that doxygen normally
  87      *                   generates based on the compound type & name.
  88      *  \param isSymbol  If TRUE this class name is added as a publicly
  89      *                   visible (and referencable) symbol.
  90      *  \param isJavaEnum If TRUE this class is actually a Java enum.
  91      *                    I didn't add this to CompoundType to avoid having
  92      *                    to adapt all translators.
  93      */
  94     ClassDef(const char *fileName,int startLine,int startColumn,
  95              const char *name,CompoundType ct,
  96              const char *ref=0,const char *fName=0,
  97              bool isSymbol=TRUE,bool isJavaEnum=FALSE);
  98     /** Destroys a compound definition. */
  99    ~ClassDef();
 100
 101     //-----------------------------------------------------------------------------------
 102     // --- getters
 103     //-----------------------------------------------------------------------------------
 104
 105     /** Used for RTTI, this is a class */
 106     DefType definitionType() const { return TypeClass; }
 107
 108     /** Returns the unique base name (without extension) of the class's file on disk */
 109     QCString getOutputFileBase() const;
 110     QCString getInstanceOutputFileBase() const;
 111
 112     /** Returns the base name for the source code file */
 113     QCString getSourceFileBase() const;
 114
 115     /** If this class originated from a tagfile, this will return the tag file reference */
 116     QCString getReference() const;
 117
 118     /** Returns TRUE if this class is imported via a tag file */
 119     bool isReference() const;
 120
 121     /** Returns TRUE if this is a local class definition, see EXTRACT_LOCAL_CLASSES */
 122     bool isLocal() const;
 123
 124     /** returns the classes nested into this class */
 125     ClassSDict *getClassSDict() const;
 126
 127     /** returns TRUE if this class has documentation */
 128     bool hasDocumentation() const;
 129
 130     /** returns TRUE if this class has a non-empty detailed description */
 131     bool hasDetailedDescription() const;
 132
 133     /** returns the file name to use for the collaboration graph */
 134     QCString collaborationGraphFileName() const;
 135
 136     /** returns the file name to use for the inheritance graph */
 137     QCString inheritanceGraphFileName() const;
 138
 139     /** Returns the name as it is appears in the documentation */
 140     QCString displayName(bool includeScope=TRUE) const;
 141
 142     /** Returns the type of compound this is, i.e. class/struct/union/.. */
 143     CompoundType compoundType() const;
 144
 145     /** Returns the type of compound as a string */
 146     QCString compoundTypeString() const;
 147
 148     /** Returns the list of base classes from which this class directly
 149      *  inherits.
 150      */
 151     BaseClassList *baseClasses() const;
 152
 153     /** Returns the list of sub classes that directly derive from this class
 154      */
 155     BaseClassList *subClasses() const;
 156
 157     /** Returns a dictionary of all members. This includes any inherited
 158      *  members. Members are sorted alphabetically.
 159      */
 160     MemberNameInfoSDict *memberNameInfoSDict() const;
 161
 162     /** Return the protection level (Public,Protected,Private) in which
 163      *  this compound was found.
 164      */
 165     Protection protection() const;
 166
 167     /** returns TRUE iff a link is possible to this item within this project.
 168      */
 169     bool isLinkableInProject() const;
 170
 171     /** return TRUE iff a link to this class is possible (either within
 172      *  this project, or as a cross-reference to another project).
 173      */
 174     bool isLinkable() const;
 175
 176     /** the class is visible in a class diagram, or class hierarchy */
 177     bool isVisibleInHierarchy();
 178
 179     /** show this class in the declaration section of its parent? */
 180     bool visibleInParentsDeclList() const;
 181
 182     /** Returns the template arguments of this class
 183      *  Will return 0 if not applicable.
 184      */
 185     ArgumentList *templateArguments() const;
 186
 187     /** Returns the namespace this compound is in, or 0 if it has a global
 188      *  scope.
 189      */
 190     NamespaceDef *getNamespaceDef() const;
 191
 192     /** Returns the file in which this compound's definition can be found.
 193      *  Should not return 0 (but it might be a good idea to check anyway).
 194      */
 195     FileDef      *getFileDef() const;
 196
 197     /** Returns the Java package this class is in or 0 if not applicable.
 198      */
 199
 200     MemberDef    *getMemberByName(const QCString &) const;
 201
 202     /** Returns TRUE iff \a bcd is a direct or indirect base class of this
 203      *  class. This function will recursively traverse all branches of the
 204      *  inheritance tree.
 205      */
 206     bool isBaseClass(ClassDef *bcd,bool followInstances,int level=0);
 207
 208     /** Returns TRUE iff \a bcd is a direct or indirect sub class of this
 209      *  class.
 210      */
 211     bool isSubClass(ClassDef *bcd,int level=0);
 212
 213     /** returns TRUE iff \a md is a member of this class or of the
 214      *  the public/protected members of a base class
 215      */
 216     bool isAccessibleMember(MemberDef *md);
 217
 218     /** Returns a sorted dictionary with all template instances found for
 219      *  this template class. Returns 0 if not a template or no instances.
 220      */
 221     QDict<ClassDef> *getTemplateInstances() const;
 222
 223     /** Returns the template master of which this class is an instance.
 224      *  Returns 0 if not applicable.
 225      */
 226     ClassDef *templateMaster() const;
 227
 228     /** Returns TRUE if this class is a template */
 229     bool isTemplate() const;
 230
 231     IncludeInfo *includeInfo() const;
 232
 233     UsesClassDict *usedImplementationClasses() const;
 234
 235     UsesClassDict *usedByImplementationClasses() const;
 236
 237     UsesClassDict *usedInterfaceClasses() const;
 238
 239     ConstraintClassDict *templateTypeConstraints() const;
 240
 241     bool isTemplateArgument() const;
 242
 243     /** Returns the definition of a nested compound if
 244      *  available, or 0 otherwise.
 245      *  @param name The name of the nested compound
 246      */
 247     virtual Definition *findInnerCompound(const char *name) const;
 248
 249     /** Returns the template parameter lists that form the template
 250      *  declaration of this class.
 251      *
 252      *  Example: <code>template<class T> class TC {};</code>
 253      *  will return a list with one ArgumentList containing one argument
 254      *  with type="class" and name="T".
 255      */
 256     void getTemplateParameterLists(QList<ArgumentList> &lists) const;
 257
 258     QCString qualifiedNameWithTemplateParameters(
 259         QList<ArgumentList> *actualParams=0,int *actualParamIndex=0) const;
 260
 261     /** Returns TRUE if there is at least one pure virtual member in this
 262      *  class.
 263      */
 264     bool isAbstract() const;
 265
 266     /** Returns TRUE if this class is implemented in Objective-C */
 267     bool isObjectiveC() const;
 268
 269     /** Returns TRUE if this class is implemented in Fortran */
 270     bool isFortran() const;
 271
 272     /** Returns TRUE if this class is implemented in C# */
 273     bool isCSharp() const;
 274
 275     /** Returns TRUE if this class is marked as final */
 276     bool isFinal() const;
 277
 278     /** Returns TRUE if this class is marked as sealed */
 279     bool isSealed() const;
 280
 281     /** Returns TRUE if this class is marked as published */
 282     bool isPublished() const;
 283
 284     /** Returns TRUE if this class represents an Objective-C 2.0 extension (nameless category) */
 285     bool isExtension() const;
 286
 287     /** Returns TRUE if this class represents a forward declaration of a template class */
 288     bool isForwardDeclared() const;
 289
 290     /** Returns the class of which this is a category (Objective-C only) */
 291     ClassDef *categoryOf() const;
 292
 293     /** Returns the name of the class including outer classes, but not
 294      *  including namespaces.
 295      */
 296     QCString className() const;
 297
 298     /** Returns the members in the list identified by \a lt */
 299     MemberList *getMemberList(MemberListType lt);
 300
 301     /** Returns the list containing the list of members sorted per type */
 302     const QList<MemberList> &getMemberLists() const;
 303
 304     /** Returns the member groups defined for this class */
 305     MemberGroupSDict *getMemberGroupSDict() const;
 306
 307     QDict<int> *getTemplateBaseClassNames() const;
 308
 309     ClassDef *getVariableInstance(const char *templSpec);
 310
 311     bool isUsedOnly() const;
 312
 313     QCString anchor() const;
 314     bool isEmbeddedInOuterScope() const;
 315
 316     bool isSimple() const;
 317
 318     const ClassList *taggedInnerClasses() const;
 319     ClassDef *tagLessReference() const;
 320
 321     MemberDef *isSmartPointer() const;
 322
 323     bool isJavaEnum() const;
 324
 325     bool isGeneric() const;
 326     bool isAnonymous() const;
 327     const ClassSDict *innerClasses() const;
 328     QCString title() const;
 329
 330     QCString generatedFromFiles() const;
 331     const FileList &usedFiles() const;
 332
 333     const ArgumentList *typeConstraints() const;
 334     const ExampleSDict *exampleList() const;
 335     bool hasExamples() const;
 336     QCString getMemberListFileName() const;
 337     bool subGrouping() const;
 338
 339     bool isSliceLocal() const;
 340
 341     //-----------------------------------------------------------------------------------
 342     // --- setters ----
 343     //-----------------------------------------------------------------------------------
 344
 345     void insertBaseClass(ClassDef *,const char *name,Protection p,Specifier s,const char *t=0);
 346     void insertSubClass(ClassDef *,Protection p,Specifier s,const char *t=0);
 347     void setIncludeFile(FileDef *fd,const char *incName,bool local,bool force);
 348     void insertMember(MemberDef *);
 349     void insertUsedFile(FileDef *);
 350     bool addExample(const char *anchor,const char *name, const char *file);
 351     void mergeCategory(ClassDef *category);
 352     void setNamespace(NamespaceDef *nd);
 353     void setFileDef(FileDef *fd);
 354     void setSubGrouping(bool enabled);
 355     void setProtection(Protection p);
 356     void setGroupDefForAllMembers(GroupDef *g,Grouping::GroupPri_t pri,const QCString &fileName,int startLine,bool hasDocs);
 357     void addInnerCompound(Definition *d);
 358     ClassDef *insertTemplateInstance(const QCString &fileName,int startLine,int startColumn,
 359                                 const QCString &templSpec,bool &freshInstance);
 360     void addUsedClass(ClassDef *cd,const char *accessName,Protection prot);
 361     void addUsedByClass(ClassDef *cd,const char *accessName,Protection prot);
 362     void setIsStatic(bool b);
 363     void setCompoundType(CompoundType t);
 364     void setClassName(const char *name);
 365     void setClassSpecifier(uint64 spec);
 366
 367     void setTemplateArguments(ArgumentList *al);
 368     void setTemplateBaseClassNames(QDict<int> *templateNames);
 369     void setTemplateMaster(ClassDef *tm);
 370     void setTypeConstraints(ArgumentList *al);
 371     void addMembersToTemplateInstance(ClassDef *cd,const char *templSpec);
 372     void makeTemplateArgument(bool b=TRUE);
 373     void setCategoryOf(ClassDef *cd);
 374     void setUsedOnly(bool b);
 375
 376     void addTaggedInnerClass(ClassDef *cd);
 377     void setTagLessReference(ClassDef *cd);
 378     void setName(const char *name);
 379
 380     void setMetaData(const char *md);
 381
 382     //-----------------------------------------------------------------------------------
 383     // --- actions ----
 384     //-----------------------------------------------------------------------------------
 385
 386     void findSectionsInDocumentation();
 387     void addMembersToMemberGroup();
 388     void addListReferences();
 389     void addTypeConstraints();
 390     void computeAnchors();
 391     void mergeMembers();
 392     void sortMemberLists();
 393     void distributeMemberGroupDocumentation();
 394     void writeDocumentation(OutputList &ol);
 395     void writeDocumentationForInnerClasses(OutputList &ol);
 396     void writeMemberPages(OutputList &ol);
 397     void writeMemberList(OutputList &ol);
 398     void writeDeclaration(OutputList &ol,MemberDef *md,bool inGroup,
 399                           ClassDef *inheritedFrom,const char *inheritId);
 400     void writeQuickMemberLinks(OutputList &ol,MemberDef *md) const;
 401     void writeSummaryLinks(OutputList &ol);
 402     void reclassifyMember(MemberDef *md,MemberType t);
 403     void writeInlineDocumentation(OutputList &ol);
 404     void writeDeclarationLink(OutputList &ol,bool &found,
 405                               const char *header,bool localNames);
 406     void removeMemberFromLists(MemberDef *md);
 407     void addGroupedInheritedMembers(OutputList &ol,MemberListType lt,
 408                               ClassDef *inheritedFrom,const QCString &inheritId);
 409     int countMembersIncludingGrouped(MemberListType lt,ClassDef *inheritedFrom,bool additional);
 410     int countInheritanceNodes();
 411     void writeTagFile(FTextStream &);
 412
 413     bool visited;
 414
 415   protected:
 416     void addUsedInterfaceClasses(MemberDef *md,const char *typeStr);
 417     bool hasNonReferenceSuperClass();
 418     void showUsedFiles(OutputList &ol);
 419
 420   private:
 421     void writeDocumentationContents(OutputList &ol,const QCString &pageTitle);
 422     void internalInsertMember(MemberDef *md,Protection prot,bool addToAllList);
 423     void addMemberToList(MemberListType lt,MemberDef *md,bool isBrief);
 424     MemberList *createMemberList(MemberListType lt);
 425     void writeInheritedMemberDeclarations(OutputList &ol,MemberListType lt,int lt2,const QCString &title,ClassDef *inheritedFrom,bool invert,bool showAlways,QPtrDict<void> *visitedClasses);
 426     void writeMemberDeclarations(OutputList &ol,MemberListType lt,const QCString &title,
 427                                  const char *subTitle=0,bool showInline=FALSE,ClassDef *inheritedFrom=0,int lt2=-1,bool invert=FALSE,bool showAlways=FALSE,QPtrDict<void> *visitedClasses=0);
 428     void writeMemberDocumentation(OutputList &ol,MemberListType lt,const QCString &title,bool showInline=FALSE);
 429     void writeSimpleMemberDocumentation(OutputList &ol,MemberListType lt);
 430     void writePlainMemberDeclaration(OutputList &ol,MemberListType lt,bool inGroup,ClassDef *inheritedFrom,const char *inheritId);
 431     void writeBriefDescription(OutputList &ol,bool exampleFlag);
 432     void writeDetailedDescription(OutputList &ol,const QCString &pageType,bool exampleFlag,
 433                                   const QCString &title,const QCString &anchor=QCString());
 434     void writeIncludeFiles(OutputList &ol);
 435     void writeIncludeFilesForSlice(OutputList &ol);
 436     //void writeAllMembersLink(OutputList &ol);
 437     void writeInheritanceGraph(OutputList &ol);
 438     void writeCollaborationGraph(OutputList &ol);
 439     void writeMemberGroups(OutputList &ol,bool showInline=FALSE);
 440     void writeNestedClasses(OutputList &ol,const QCString &title);
 441     void writeInlineClasses(OutputList &ol);
 442     void startMemberDeclarations(OutputList &ol);
 443     void endMemberDeclarations(OutputList &ol);
 444     void startMemberDocumentation(OutputList &ol);
 445     void endMemberDocumentation(OutputList &ol);
 446     void writeAuthorSection(OutputList &ol);
 447     void writeMoreLink(OutputList &ol,const QCString &anchor);
 448     void writeDetailedDocumentationBody(OutputList &ol);
 449
 450     int countAdditionalInheritedMembers();
 451     void writeAdditionalInheritedMembers(OutputList &ol);
 452     void addClassAttributes(OutputList &ol);
 453     int countMemberDeclarations(MemberListType lt,ClassDef *inheritedFrom,
 454                                 int lt2,bool invert,bool showAlways,QPtrDict<void> *visitedClasses);
 455     int countInheritedDecMembers(MemberListType lt,
 456                                  ClassDef *inheritedFrom,bool invert,bool showAlways,
 457                                  QPtrDict<void> *visitedClasses);
 458     void getTitleForMemberListType(MemberListType type,
 459                QCString &title,QCString &subtitle);
 460     QCString includeStatement() const;
 461     void addTypeConstraint(const QCString &typeConstraint,const QCString &type);
 462
 463     ClassDefImpl *m_impl;
 464 };
 465
 466 //------------------------------------------------------------------------
 467
 468 /** Class that contains information about a usage relation.
 469  */
 470 struct UsesClassDef
 471 {
 472   UsesClassDef(ClassDef *cd) : classDef(cd)
 473   {
 474     accessors = new QDict<void>(17);
 475     containment = TRUE;
 476   }
 477  ~UsesClassDef()
 478   {
 479     delete accessors;
 480   }
 481   void addAccessor(const char *s)
 482   {
 483     if (accessors->find(s)==0)
 484     {
 485       accessors->insert(s,(void *)666);
 486     }
 487   }
 488   /** Class definition that this relation uses. */
 489   ClassDef *classDef;
 490
 491   /** Dictionary of member variable names that form the edge labels of the
 492    *  usage relation.
 493    */
 494   QDict<void> *accessors;
 495
 496   /** Template arguments used for the base class */
 497   QCString templSpecifiers;
 498
 499   bool containment;
 500 };
 501
 502 /** Dictionary of usage relations.
 503  */
 504 class UsesClassDict : public QDict<UsesClassDef>
 505 {
 506   public:
 507     UsesClassDict(int size) : QDict<UsesClassDef>(size) {}
 508    ~UsesClassDict() {}
 509 };
 510
 511 /** Iterator class to iterate over a dictionary of usage relations.
 512  */
 513 class UsesClassDictIterator : public QDictIterator<UsesClassDef>
 514 {
 515   public:
 516     UsesClassDictIterator(const QDict<UsesClassDef> &d)
 517       : QDictIterator<UsesClassDef>(d) {}
 518    ~UsesClassDictIterator() {}
 519 };
 520
 521 //------------------------------------------------------------------------
 522
 523 /** Class that contains information about an inheritance relation.
 524  */
 525 struct BaseClassDef
 526 {
 527   BaseClassDef(ClassDef *cd,const char *n,Protection p,
 528                Specifier v,const char *t) :
 529         classDef(cd), usedName(n), prot(p), virt(v), templSpecifiers(t) {}
 530
 531   /** Class definition that this relation inherits from. */
 532   ClassDef *classDef;
 533
 534   /** name used in the inheritance list
 535    * (may be a typedef name instead of the class name)
 536    */
 537   QCString   usedName;
 538
 539   /** Protection level of the inheritance relation:
 540    *  Public, Protected, or Private
 541    */
 542   Protection prot;
 543
 544   /** Virtualness of the inheritance relation:
 545    *  Normal, or Virtual
 546    */
 547   Specifier  virt;
 548
 549   /** Template arguments used for the base class */
 550   QCString templSpecifiers;
 551 };
 552
 553 /** List of base classes.
 554  *
 555  *  The classes are alphabetically sorted on name if inSort() is used.
 556  */
 557 class BaseClassList : public QList<BaseClassDef>
 558 {
 559   public:
 560    ~BaseClassList() {}
 561     int compareValues(const BaseClassDef *item1,const BaseClassDef *item2) const
 562     {
 563       const ClassDef *c1=item1->classDef;
 564       const ClassDef *c2=item2->classDef;
 565       if (c1==0 || c2==0)
 566         return FALSE;
 567       else
 568         return qstricmp(c1->name(),c2->name());
 569     }
 570 };
 571
 572 /** Iterator for a list of base classes.
 573  */
 574 class BaseClassListIterator : public QListIterator<BaseClassDef>
 575 {
 576   public:
 577     BaseClassListIterator(const BaseClassList &bcl) :
 578       QListIterator<BaseClassDef>(bcl) {}
 579 };
 580
 581 //------------------------------------------------------------------------
 582
 583
 584 /** Class that contains information about a type constraint relations.
 585  */
 586 struct ConstraintClassDef
 587 {
 588   ConstraintClassDef(ClassDef *cd) : classDef(cd)
 589   {
 590     accessors = new QDict<void>(17);
 591   }
 592  ~ConstraintClassDef()
 593   {
 594     delete accessors;
 595   }
 596   void addAccessor(const char *s)
 597   {
 598     if (accessors->find(s)==0)
 599     {
 600       accessors->insert(s,(void *)666);
 601     }
 602   }
 603   /** Class definition that this relation uses. */
 604   ClassDef *classDef;
 605
 606   /** Dictionary of member types names that form the edge labels of the
 607    *  constraint relation.
 608    */
 609   QDict<void> *accessors;
 610 };
 611
 612 /** Dictionary of constraint relations.
 613  */
 614 class ConstraintClassDict : public QDict<ConstraintClassDef>
 615 {
 616   public:
 617     ConstraintClassDict(int size) : QDict<ConstraintClassDef>(size) {}
 618    ~ConstraintClassDict() {}
 619 };
 620
 621 /** Iterator class to iterate over a dictionary of constraint relations.
 622  */
 623 class ConstraintClassDictIterator : public QDictIterator<ConstraintClassDef>
 624 {
 625   public:
 626     ConstraintClassDictIterator(const QDict<ConstraintClassDef> &d)
 627       : QDictIterator<ConstraintClassDef>(d) {}
 628    ~ConstraintClassDictIterator() {}
 629 };
 630
 631 //------------------------------------------------------------------------
 632
 633 #endif