src/classdef.h

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