src/entry.h

   1 /******************************************************************************
   2  *
   3  * $Id: entry.h,v 1.36 2001/03/19 19:27:40 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 ENTRY_H
  19 #define ENTRY_H
  20
  21 #include "qtbc.h"
  22 #include <qlist.h>
  23 #include "types.h"
  24
  25 #include <qgstring.h>
  26
  27 struct SectionInfo;
  28 class QFile;
  29 class EntryNav;
  30 class FileDef;
  31 class FileStorage;
  32 class StorageIntf;
  33 class ArgumentList;
  34 struct ListItemInfo;
  35
  36 /** This class stores information about an inheritance relation
  37  */
  38 struct BaseInfo
  39 {
  40   /*! Creates an object representing an inheritance relation */
  41   BaseInfo(const char *n,Protection p,Specifier v) :
  42     name(n),prot(p),virt(v) {}
  43   QCString   name; //!< the name of the base class
  44   Protection prot; //!< inheritance type
  45   Specifier  virt; //!< virtualness
  46 };
  47
  48 /** This struct is used to capture the tag file information
  49  *  for an Entry.
  50  */
  51 struct TagInfo
  52 {
  53   QCString tagName;
  54   QCString fileName;
  55   QCString anchor;
  56 };
  57
  58 /** Represents an unstructured piece of information, about an
  59  *  entity found in the sources.
  60  *
  61  *  parseMain() in scanner.l will generate a tree of these
  62  *  entries.
  63  */
  64 class Entry
  65 {
  66   public:
  67
  68     /*! Kind of entries that are supported */
  69     enum Sections {
  70       CLASS_SEC        = 0x00000001,
  71       NAMESPACE_SEC    = 0x00000010,
  72       COMPOUND_MASK    = CLASS_SEC,
  73       SCOPE_MASK       = COMPOUND_MASK | NAMESPACE_SEC,
  74
  75       CLASSDOC_SEC     = 0x00000800,
  76       STRUCTDOC_SEC    = 0x00001000,
  77       UNIONDOC_SEC     = 0x00002000,
  78       EXCEPTIONDOC_SEC = 0x00004000,
  79       NAMESPACEDOC_SEC = 0x00008000,
  80       INTERFACEDOC_SEC = 0x00010000,
  81       PROTOCOLDOC_SEC  = 0x00020000,
  82       CATEGORYDOC_SEC  = 0x00040000,
  83       COMPOUNDDOC_MASK = CLASSDOC_SEC | STRUCTDOC_SEC | UNIONDOC_SEC |
  84                          INTERFACEDOC_SEC | EXCEPTIONDOC_SEC | PROTOCOLDOC_SEC |
  85                          CATEGORYDOC_SEC,
  86
  87       SOURCE_SEC       = 0x00400000,
  88       HEADER_SEC       = 0x00800000,
  89       FILE_MASK        = SOURCE_SEC | HEADER_SEC,
  90
  91       ENUMDOC_SEC      = 0x01000000,
  92       ENUM_SEC         = 0x02000000,
  93       EMPTY_SEC        = 0x03000000,
  94       PAGEDOC_SEC      = 0x04000000,
  95       VARIABLE_SEC     = 0x05000000,
  96       FUNCTION_SEC     = 0x06000000,
  97       TYPEDEF_SEC      = 0x07000000,
  98       MEMBERDOC_SEC    = 0x08000000,
  99       OVERLOADDOC_SEC  = 0x09000000,
 100       EXAMPLE_SEC      = 0x0a000000,
 101       VARIABLEDOC_SEC  = 0x0b000000,
 102       FILEDOC_SEC      = 0x0c000000,
 103       DEFINEDOC_SEC    = 0x0d000000,
 104       INCLUDE_SEC      = 0x0e000000,
 105       DEFINE_SEC       = 0x0f000000,
 106       GROUPDOC_SEC     = 0x10000000,
 107       USINGDIR_SEC     = 0x11000000,
 108       MAINPAGEDOC_SEC  = 0x12000000,
 109       MEMBERGRP_SEC    = 0x13000000,
 110       USINGDECL_SEC    = 0x14000000,
 111       PACKAGE_SEC      = 0x15000000,
 112       PACKAGEDOC_SEC   = 0x16000000,
 113       OBJCIMPL_SEC     = 0x17000000,
 114       DIRDOC_SEC       = 0x18000000
 115     };
 116     enum MemberSpecifier
 117     {
 118       Inline      = 0x00000001,
 119       Explicit    = 0x00000002,
 120       Mutable     = 0x00000004,
 121       Settable    = 0x00000008,
 122       Gettable    = 0x00000010,
 123       Readable    = 0x00000020,
 124       Writable    = 0x00000040,
 125       Final       = 0x00000080,
 126       Abstract    = 0x00000100,
 127       Addable     = 0x00000200,
 128       Removable   = 0x00000400,
 129       Raisable    = 0x00000800,
 130       Override    = 0x00001000,
 131       New         = 0x00002000,
 132       Sealed      = 0x00004000,
 133       Initonly    = 0x00008000,
 134       Optional    = 0x00010000,
 135       Required    = 0x00020000,
 136       NonAtomic   = 0x00040000,
 137       Copy        = 0x00080000,
 138       Retain      = 0x00100000,
 139       Assign      = 0x00200000,
 140       Strong      = 0x00400000,
 141       Weak        = 0x00800000,
 142       Unretained  = 0x01000000,
 143       Alias       = 0x02000000,
 144       ConstExp    = 0x04000000,
 145       Default     = 0x08000000,
 146       Delete      = 0x10000000,
 147       NoExcept    = 0x20000000
 148     };
 149     enum ClassSpecifier
 150     {
 151       Template       = 0x0001,
 152       Generic        = 0x0002,
 153       Ref            = 0x0004,
 154       Value          = 0x0008,
 155       Interface      = 0x0010,
 156       Struct         = 0x0020,
 157       Union          = 0x0040,
 158       Exception      = 0x0080,
 159       Protocol       = 0x0100,
 160       Category       = 0x0200,
 161       SealedClass    = 0x0400,
 162       AbstractClass  = 0x0800,
 163       Enum           = 0x1000  // for Java-style enums
 164     };
 165     enum GroupDocType
 166     {
 167       GROUPDOC_NORMAL,        //!< defgroup
 168       GROUPDOC_ADD,           //!< addgroup
 169       GROUPDOC_WEAK           //!< weakgroup
 170     };                        //!< kind of group
 171
 172     Entry();
 173     Entry(const Entry &);
 174    ~Entry();
 175
 176     /*! Returns the static size of the Entry (so excluding any dynamic memory) */
 177     int getSize();
 178
 179     void addSpecialListItem(const char *listName,int index);
 180     void createNavigationIndex(EntryNav *rootNav,FileStorage *storage,FileDef *fd);
 181
 182     // while parsing a file these function can be used to navigate/build the tree
 183     void setParent(Entry *parent) { m_parent = parent; }
 184
 185     /*! Returns the parent for this Entry or 0 if this entry has no parent. */
 186     Entry *parent() const { return m_parent; }
 187
 188     /*! Returns the list of children for this Entry
 189      *  @see addSubEntry() and removeSubEntry()
 190      */
 191     const QList<Entry> *children() const { return m_sublist; }
 192
 193     /*! Adds entry \a e as a child to this entry */
 194     void addSubEntry (Entry* e) ;
 195
 196     /*! Removes entry \a e from the list of children.
 197      *  Returns a pointer to the entry or 0 if the entry was not a child.
 198      *  Note the entry will not be deleted.
 199      */
 200     Entry *removeSubEntry(Entry *e);
 201
 202     /*! Restore the state of this Entry to the default value it has
 203      *  at construction time.
 204      */
 205     void reset();
 206
 207     /*! Serialize this entry to a persistent storage stream. */
 208     void marshall(StorageIntf *);
 209
 210     /*! Reinitialize this entry from a persistent storage stream. */
 211     void unmarshall(StorageIntf *);
 212
 213   public:
 214
 215     // identification
 216     int          section;     //!< entry type (see Sections);
 217     QCString     type;        //!< member type
 218     QCString     name;        //!< member name
 219     TagInfo     *tagInfo;     //!< tag file info
 220
 221     // content
 222     Protection protection;    //!< class protection
 223     MethodTypes mtype;        //!< signal, slot, (dcop) method, or property?
 224     int  spec;                //!< class/member specifiers
 225     int  initLines;           //!< define/variable initializer lines to show
 226     bool stat;                //!< static ?
 227     bool explicitExternal;    //!< explicitly defined as external?
 228     bool proto;               //!< prototype ?
 229     bool subGrouping;         //!< automatically group class members?
 230     bool callGraph;           //!< do we need to draw the call graph?
 231     bool callerGraph;         //!< do we need to draw the caller graph?
 232     Specifier    virt;        //!< virtualness of the entry
 233     QCString     args;        //!< member argument string
 234     QCString     bitfields;   //!< member's bit fields
 235     ArgumentList *argList;    //!< member arguments as a list
 236     QList<ArgumentList> *tArgLists; //!< template argument declarations
 237     QGString     program;     //!< the program text
 238     QGString     initializer; //!< initial value (for variables)
 239     QCString     includeFile; //!< include file (2 arg of \\class, must be unique)
 240     QCString     includeName; //!< include name (3 arg of \\class)
 241     QCString     doc;         //!< documentation block (partly parsed)
 242     int          docLine;     //!< line number at which the documentation was found
 243     QCString     docFile;     //!< file in which the documentation was found
 244     QCString     brief;       //!< brief description (doc block)
 245     int          briefLine;   //!< line number at which the brief desc. was found
 246     QCString     briefFile;   //!< file in which the brief desc. was found
 247     QCString     inbodyDocs;  //!< documentation inside the body of a function
 248     int          inbodyLine;  //!< line number at which the body doc was found
 249     QCString     inbodyFile;  //!< file in which the body doc was found
 250     QCString     relates;     //!< related class (doc block)
 251     RelatesType  relatesType; //!< how relates is handled
 252     QCString     read;        //!< property read accessor
 253     QCString     write;       //!< property write accessor
 254     QCString     inside;      //!< name of the class in which documents are found
 255     QCString     exception;   //!< throw specification
 256     ArgumentList *typeConstr; //!< where clause (C#) for type constraints
 257     int          bodyLine;    //!< line number of the definition in the source
 258     int          endBodyLine; //!< line number where the definition ends
 259     int          mGrpId;      //!< member group id
 260     QList<BaseInfo> *extends; //!< list of base classes
 261     QList<Grouping> *groups;  //!< list of groups this entry belongs to
 262     QList<SectionInfo> *anchors; //!< list of anchors defined in this entry
 263     QCString    fileName;     //!< file this entry was extracted from
 264     int         startLine;    //!< start line of entry in the source
 265     QList<ListItemInfo> *sli; //!< special lists (test/todo/bug/deprecated/..) this entry is in
 266     SrcLangExt  lang;         //!< programming language in which this entry was found
 267     bool        hidden;       //!< does this represent an entity that is hidden from the output
 268     bool        artificial;   //!< Artificially introduced item
 269     GroupDocType groupDocType;
 270
 271
 272     static int  num;          //!< counts the total number of entries
 273
 274     /// return the command name used to define GROUPDOC_SEC
 275     const char *groupDocCmd() const
 276     {
 277       switch( groupDocType )
 278       {
 279         case GROUPDOC_NORMAL: return "\\defgroup";
 280         case GROUPDOC_ADD: return "\\addgroup";
 281         case GROUPDOC_WEAK: return "\\weakgroup";
 282         default: return "unknown group command";
 283       }
 284     }
 285     Grouping::GroupPri_t groupingPri() const
 286     {
 287       if( section != GROUPDOC_SEC )
 288       {
 289         return Grouping::GROUPING_LOWEST;
 290       }
 291       switch( groupDocType )
 292       {
 293         case GROUPDOC_NORMAL: return Grouping::GROUPING_AUTO_DEF;
 294         case GROUPDOC_ADD:    return Grouping::GROUPING_AUTO_ADD;
 295         case GROUPDOC_WEAK:   return Grouping::GROUPING_AUTO_WEAK;
 296         default: return Grouping::GROUPING_LOWEST;
 297       }
 298     }
 299
 300   private:
 301     void createSubtreeIndex(EntryNav *nav,FileStorage *storage,FileDef *fd);
 302     Entry         *m_parent;    //!< parent node in the tree
 303     QList<Entry>  *m_sublist;   //!< entries that are children of this one
 304     Entry &operator=(const Entry &);
 305 };
 306
 307 /** Wrapper for a node in the Entry tree.
 308  *
 309  *  Allows navigating through the Entry tree and load and storing Entry
 310  *  objects persistently to disk.
 311  */
 312 class EntryNav
 313 {
 314   public:
 315     EntryNav(EntryNav *parent,Entry *e);
 316    ~EntryNav();
 317     void addChild(EntryNav *);
 318     bool loadEntry(FileStorage *storage);
 319     bool saveEntry(Entry *e,FileStorage *storage);
 320     void setEntry(Entry *e);
 321     void releaseEntry();
 322     void changeSection(int section) { m_section = section; }
 323     void setFileDef(FileDef *fd) { m_fileDef = fd; }
 324
 325     Entry *entry() const { return m_info; }
 326     int section() const { return m_section; }
 327     SrcLangExt lang() const { return m_lang; }
 328     const QCString &type() const { return m_type; }
 329     const QCString &name() const { return m_name; }
 330     TagInfo *tagInfo() const { return m_tagInfo; }
 331     const QList<EntryNav> *children() const { return m_subList; }
 332     EntryNav *parent() const { return m_parent; }
 333     FileDef *fileDef() const { return m_fileDef; }
 334
 335   private:
 336
 337     // navigation
 338     EntryNav        *m_parent;    //!< parent node in the tree
 339     QList<EntryNav> *m_subList;   //!< entries that are children of this one
 340
 341     // identification
 342     int          m_section;     //!< entry type (see Sections);
 343     QCString     m_type;        //!< member type
 344     QCString     m_name;        //!< member name
 345     TagInfo     *m_tagInfo;      //!< tag file info
 346     FileDef     *m_fileDef;
 347     SrcLangExt   m_lang;         //!< programming language in which this entry was found
 348
 349     Entry       *m_info;
 350     int64        m_offset;
 351     bool         m_noLoad;
 352 };
 353
 354
 355 typedef QList<Entry> EntryList;
 356 typedef QListIterator<Entry> EntryListIterator;
 357
 358 typedef QList<EntryNav> EntryNavList;
 359 typedef QListIterator<EntryNav> EntryNavListIterator;
 360
 361 #endif