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