src/classdef.h

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