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 the class of which this is a category (Objective-C only) */
 275     ClassDef *categoryOf() const;
 276
 277     /** Returns the name of the class including outer classes, but not
 278      *  including namespaces.
 279      */
 280     QCString className() const;
 281
 282     /** Returns the members in the list identified by \a lt */
 283     MemberList *getMemberList(MemberListType lt);
 284
 285     /** Returns the list containing the list of members sorted per type */
 286     const QList<MemberList> &getMemberLists() const;
 287
 288     /** Returns the member groups defined for this class */
 289     MemberGroupSDict *getMemberGroupSDict() const;
 290
 291     QDict<int> *getTemplateBaseClassNames() const;
 292
 293     ClassDef *getVariableInstance(const char *templSpec);
 294
 295     bool isUsedOnly() const;
 296
 297     QCString anchor() const;
 298     bool isEmbeddedInOuterScope() const;
 299
 300     bool isSimple() const;
 301
 302     const ClassList *taggedInnerClasses() const;
 303     ClassDef *tagLessReference() const;
 304
 305     MemberDef *isSmartPointer() const;
 306
 307     bool isJavaEnum() const;
 308
 309     bool isGeneric() const;
 310     const ClassSDict *innerClasses() const;
 311     QCString title() const;
 312
 313     QCString generatedFromFiles() const;
 314     const FileList &usedFiles() const;
 315
 316     const ArgumentList *typeConstraints() const;
 317     const ExampleSDict *exampleList() const;
 318     bool hasExamples() const;
 319     QCString getMemberListFileName() const;
 320     bool subGrouping() const;
 321
 322
 323     //-----------------------------------------------------------------------------------
 324     // --- setters ----
 325     //-----------------------------------------------------------------------------------
 326
 327     void insertBaseClass(ClassDef *,const char *name,Protection p,Specifier s,const char *t=0);
 328     void insertSubClass(ClassDef *,Protection p,Specifier s,const char *t=0);
 329     void setIncludeFile(FileDef *fd,const char *incName,bool local,bool force);
 330     void insertMember(MemberDef *);
 331     void insertUsedFile(FileDef *);
 332     bool addExample(const char *anchor,const char *name, const char *file);
 333     void mergeCategory(ClassDef *category);
 334     void setNamespace(NamespaceDef *nd);
 335     void setFileDef(FileDef *fd);
 336     void setSubGrouping(bool enabled);
 337     void setProtection(Protection p);
 338     void setGroupDefForAllMembers(GroupDef *g,Grouping::GroupPri_t pri,const QCString &fileName,int startLine,bool hasDocs);
 339     void addInnerCompound(Definition *d);
 340     ClassDef *insertTemplateInstance(const QCString &fileName,int startLine,int startColumn,
 341                                 const QCString &templSpec,bool &freshInstance);
 342     void addUsedClass(ClassDef *cd,const char *accessName,Protection prot);
 343     void addUsedByClass(ClassDef *cd,const char *accessName,Protection prot);
 344     void setIsStatic(bool b);
 345     void setCompoundType(CompoundType t);
 346     void setClassName(const char *name);
 347     void setClassSpecifier(uint64 spec);
 348
 349     void setTemplateArguments(ArgumentList *al);
 350     void setTemplateBaseClassNames(QDict<int> *templateNames);
 351     void setTemplateMaster(ClassDef *tm);
 352     void setTypeConstraints(ArgumentList *al);
 353     void addMembersToTemplateInstance(ClassDef *cd,const char *templSpec);
 354     void makeTemplateArgument(bool b=TRUE);
 355     void setCategoryOf(ClassDef *cd);
 356     void setUsedOnly(bool b);
 357
 358     void addTaggedInnerClass(ClassDef *cd);
 359     void setTagLessReference(ClassDef *cd);
 360
 361     //-----------------------------------------------------------------------------------
 362     // --- actions ----
 363     //-----------------------------------------------------------------------------------
 364
 365     void findSectionsInDocumentation();
 366     void addMembersToMemberGroup();
 367     void addListReferences();
 368     void computeAnchors();
 369     void mergeMembers();
 370     void sortMemberLists();
 371     void distributeMemberGroupDocumentation();
 372     void writeDocumentation(OutputList &ol);
 373     void writeDocumentationForInnerClasses(OutputList &ol);
 374     void writeMemberPages(OutputList &ol);
 375     void writeMemberList(OutputList &ol);
 376     void writeDeclaration(OutputList &ol,MemberDef *md,bool inGroup,
 377                           ClassDef *inheritedFrom,const char *inheritId);
 378     void writeQuickMemberLinks(OutputList &ol,MemberDef *md) const;
 379     void writeSummaryLinks(OutputList &ol);
 380     void reclassifyMember(MemberDef *md,MemberType t);
 381     void writeInlineDocumentation(OutputList &ol);
 382     void writeDeclarationLink(OutputList &ol,bool &found,
 383                               const char *header,bool localNames);
 384     void removeMemberFromLists(MemberDef *md);
 385     void addGroupedInheritedMembers(OutputList &ol,MemberListType lt,
 386                               ClassDef *inheritedFrom,const QCString &inheritId);
 387     int countMembersIncludingGrouped(MemberListType lt,ClassDef *inheritedFrom,bool additional);
 388     int countInheritanceNodes();
 389
 390     bool visited;
 391
 392   protected:
 393     void addUsedInterfaceClasses(MemberDef *md,const char *typeStr);
 394     bool hasNonReferenceSuperClass();
 395     void showUsedFiles(OutputList &ol);
 396
 397   private:
 398     void writeTagFileMarker();
 399     void writeDocumentationContents(OutputList &ol,const QCString &pageTitle);
 400     void internalInsertMember(MemberDef *md,Protection prot,bool addToAllList);
 401     void addMemberToList(MemberListType lt,MemberDef *md,bool isBrief);
 402     MemberList *createMemberList(MemberListType lt);
 403     void writeInheritedMemberDeclarations(OutputList &ol,MemberListType lt,int lt2,const QCString &title,ClassDef *inheritedFrom,bool invert,bool showAlways,QPtrDict<void> *visitedClasses);
 404     void writeMemberDeclarations(OutputList &ol,MemberListType lt,const QCString &title,
 405                                  const char *subTitle=0,bool showInline=FALSE,ClassDef *inheritedFrom=0,int lt2=-1,bool invert=FALSE,bool showAlways=FALSE,QPtrDict<void> *visitedClasses=0);
 406     void writeMemberDocumentation(OutputList &ol,MemberListType lt,const QCString &title,bool showInline=FALSE);
 407     void writeSimpleMemberDocumentation(OutputList &ol,MemberListType lt);
 408     void writePlainMemberDeclaration(OutputList &ol,MemberListType lt,bool inGroup,ClassDef *inheritedFrom,const char *inheritId);
 409     void writeBriefDescription(OutputList &ol,bool exampleFlag);
 410     void writeDetailedDescription(OutputList &ol,const QCString &pageType,bool exampleFlag,
 411                                   const QCString &title,const QCString &anchor=QCString());
 412     void writeIncludeFiles(OutputList &ol);
 413     //void writeAllMembersLink(OutputList &ol);
 414     void writeInheritanceGraph(OutputList &ol);
 415     void writeCollaborationGraph(OutputList &ol);
 416     void writeMemberGroups(OutputList &ol,bool showInline=FALSE);
 417     void writeNestedClasses(OutputList &ol,const QCString &title);
 418     void writeInlineClasses(OutputList &ol);
 419     void startMemberDeclarations(OutputList &ol);
 420     void endMemberDeclarations(OutputList &ol);
 421     void startMemberDocumentation(OutputList &ol);
 422     void endMemberDocumentation(OutputList &ol);
 423     void writeAuthorSection(OutputList &ol);
 424     void writeMoreLink(OutputList &ol,const QCString &anchor);
 425     void writeDetailedDocumentationBody(OutputList &ol);
 426
 427     int countAdditionalInheritedMembers();
 428     void writeAdditionalInheritedMembers(OutputList &ol);
 429     void addClassAttributes(OutputList &ol);
 430     int countMemberDeclarations(MemberListType lt,ClassDef *inheritedFrom,
 431                                 int lt2,bool invert,bool showAlways,QPtrDict<void> *visitedClasses);
 432     int countInheritedDecMembers(MemberListType lt,
 433                                  ClassDef *inheritedFrom,bool invert,bool showAlways,
 434                                  QPtrDict<void> *visitedClasses);
 435     void getTitleForMemberListType(MemberListType type,
 436                QCString &title,QCString &subtitle);
 437     QCString includeStatement() const;
 438
 439
 440     ClassDefImpl *m_impl;
 441
 442 };
 443
 444 /** Class that contains information about a usage relation.
 445  */
 446 struct UsesClassDef
 447 {
 448   UsesClassDef(ClassDef *cd) : classDef(cd)
 449   {
 450     accessors = new QDict<void>(17);
 451     containment = TRUE;
 452   }
 453  ~UsesClassDef()
 454   {
 455     delete accessors;
 456   }
 457   void addAccessor(const char *s)
 458   {
 459     if (accessors->find(s)==0)
 460     {
 461       accessors->insert(s,(void *)666);
 462     }
 463   }
 464   /** Class definition that this relation uses. */
 465   ClassDef *classDef;
 466
 467   /** Dictionary of member variable names that form the edge labels of the
 468    *  usage relation.
 469    */
 470   QDict<void> *accessors;
 471
 472   /** Template arguments used for the base class */
 473   QCString templSpecifiers;
 474
 475   bool containment;
 476 };
 477
 478 /** Dictionary of usage relations.
 479  */
 480 class UsesClassDict : public QDict<UsesClassDef>
 481 {
 482   public:
 483     UsesClassDict(int size) : QDict<UsesClassDef>(size) {}
 484    ~UsesClassDict() {}
 485 };
 486
 487 /** Iterator class to iterate over a dictionary of usage relations.
 488  */
 489 class UsesClassDictIterator : public QDictIterator<UsesClassDef>
 490 {
 491   public:
 492     UsesClassDictIterator(const QDict<UsesClassDef> &d)
 493       : QDictIterator<UsesClassDef>(d) {}
 494    ~UsesClassDictIterator() {}
 495 };
 496
 497 /** Class that contains information about an inheritance relation.
 498  */
 499 struct BaseClassDef
 500 {
 501   BaseClassDef(ClassDef *cd,const char *n,Protection p,
 502                Specifier v,const char *t) :
 503         classDef(cd), usedName(n), prot(p), virt(v), templSpecifiers(t) {}
 504
 505   /** Class definition that this relation inherits from. */
 506   ClassDef *classDef;
 507
 508   /** name used in the inheritance list
 509    * (may be a typedef name instead of the class name)
 510    */
 511   QCString   usedName;
 512
 513   /** Protection level of the inheritance relation:
 514    *  Public, Protected, or Private
 515    */
 516   Protection prot;
 517
 518   /** Virtualness of the inheritance relation:
 519    *  Normal, or Virtual
 520    */
 521   Specifier  virt;
 522
 523   /** Template arguments used for the base class */
 524   QCString templSpecifiers;
 525 };
 526
 527 /** List of base classes.
 528  *
 529  *  The classes are alphabetically sorted on name if inSort() is used.
 530  */
 531 class BaseClassList : public QList<BaseClassDef>
 532 {
 533   public:
 534    ~BaseClassList() {}
 535     int compareValues(const BaseClassDef *item1,const BaseClassDef *item2) const
 536     {
 537       const ClassDef *c1=item1->classDef;
 538       const ClassDef *c2=item2->classDef;
 539       if (c1==0 || c2==0)
 540         return FALSE;
 541       else
 542         return qstricmp(c1->name(),c2->name());
 543     }
 544 };
 545
 546 /** Iterator for a list of base classes.
 547  */
 548 class BaseClassListIterator : public QListIterator<BaseClassDef>
 549 {
 550   public:
 551     BaseClassListIterator(const BaseClassList &bcl) :
 552       QListIterator<BaseClassDef>(bcl) {}
 553 };
 554
 555 #endif