src/entry.h

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 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     static const uint64 ForwardDecl     = (1ULL<<15); // forward declarad template classes
 137
 138     // member specifiers (add new items to the beginning)
 139     static const uint64 PrivateGettable     = (1ULL<<20); // C# private getter
 140     static const uint64 ProtectedGettable   = (1ULL<<21); // C# protected getter
 141     static const uint64 PrivateSettable     = (1ULL<<22); // C# private setter
 142     static const uint64 ProtectedSettable   = (1ULL<<23); // C# protected setter
 143     static const uint64 Inline          = (1ULL<<24);
 144     static const uint64 Explicit        = (1ULL<<25);
 145     static const uint64 Mutable         = (1ULL<<26);
 146     static const uint64 Settable        = (1ULL<<27);
 147     static const uint64 Gettable        = (1ULL<<28);
 148     static const uint64 Readable        = (1ULL<<29);
 149     static const uint64 Writable        = (1ULL<<30);
 150     static const uint64 Final           = (1ULL<<31);
 151     static const uint64 Abstract        = (1ULL<<32);
 152     static const uint64 Addable         = (1ULL<<33);
 153     static const uint64 Removable       = (1ULL<<34);
 154     static const uint64 Raisable        = (1ULL<<35);
 155     static const uint64 Override        = (1ULL<<36);
 156     static const uint64 New             = (1ULL<<37);
 157     static const uint64 Sealed          = (1ULL<<38);
 158     static const uint64 Initonly        = (1ULL<<39);
 159     static const uint64 Optional        = (1ULL<<40);
 160     static const uint64 Required        = (1ULL<<41);
 161     static const uint64 NonAtomic       = (1ULL<<42);
 162     static const uint64 Copy            = (1ULL<<43);
 163     static const uint64 Retain          = (1ULL<<44);
 164     static const uint64 Assign          = (1ULL<<45);
 165     static const uint64 Strong          = (1ULL<<46);
 166     static const uint64 Weak            = (1ULL<<47);
 167     static const uint64 Unretained      = (1ULL<<48);
 168     static const uint64 Alias           = (1ULL<<49);
 169     static const uint64 ConstExp        = (1ULL<<50);
 170     static const uint64 Default         = (1ULL<<51);
 171     static const uint64 Delete          = (1ULL<<52);
 172     static const uint64 NoExcept        = (1ULL<<53);
 173     static const uint64 Attribute       = (1ULL<<54); // UNO IDL attribute
 174     static const uint64 Property        = (1ULL<<55); // UNO IDL property
 175     static const uint64 Readonly        = (1ULL<<56); // on UNO IDL attribute or property
 176     static const uint64 Bound           = (1ULL<<57); // on UNO IDL attribute or property
 177     static const uint64 Constrained     = (1ULL<<58); // on UNO IDL property
 178     static const uint64 Transient       = (1ULL<<59); // on UNO IDL property
 179     static const uint64 MaybeVoid       = (1ULL<<60); // on UNO IDL property
 180     static const uint64 MaybeDefault    = (1ULL<<61); // on UNO IDL property
 181     static const uint64 MaybeAmbiguous  = (1ULL<<62); // on UNO IDL property
 182     static const uint64 Published       = (1ULL<<63); // UNO IDL keyword
 183
 184     enum GroupDocType
 185     {
 186       GROUPDOC_NORMAL,        //!< defgroup
 187       GROUPDOC_ADD,           //!< addgroup
 188       GROUPDOC_WEAK           //!< weakgroup
 189     };                        //!< kind of group
 190
 191     Entry();
 192     Entry(const Entry &);
 193    ~Entry();
 194
 195     /*! Returns the static size of the Entry (so excluding any dynamic memory) */
 196     int getSize();
 197
 198     void addSpecialListItem(const char *listName,int index);
 199     void createNavigationIndex(EntryNav *rootNav,FileStorage *storage,FileDef *fd);
 200
 201     // while parsing a file these function can be used to navigate/build the tree
 202     void setParent(Entry *parent) { m_parent = parent; }
 203
 204     /*! Returns the parent for this Entry or 0 if this entry has no parent. */
 205     Entry *parent() const { return m_parent; }
 206
 207     /*! Returns the list of children for this Entry
 208      *  @see addSubEntry() and removeSubEntry()
 209      */
 210     const QList<Entry> *children() const { return m_sublist; }
 211
 212     /*! Adds entry \a e as a child to this entry */
 213     void addSubEntry (Entry* e) ;
 214
 215     /*! Removes entry \a e from the list of children.
 216      *  Returns a pointer to the entry or 0 if the entry was not a child.
 217      *  Note the entry will not be deleted.
 218      */
 219     Entry *removeSubEntry(Entry *e);
 220
 221     /*! Restore the state of this Entry to the default value it has
 222      *  at construction time.
 223      */
 224     void reset();
 225
 226     /*! Serialize this entry to a persistent storage stream. */
 227     void marshall(StorageIntf *);
 228
 229     /*! Reinitialize this entry from a persistent storage stream. */
 230     void unmarshall(StorageIntf *);
 231
 232   public:
 233
 234     // identification
 235     int          section;     //!< entry type (see Sections);
 236     QCString     type;        //!< member type
 237     QCString     name;        //!< member name
 238     TagInfo     *tagInfo;     //!< tag file info
 239
 240     // content
 241     Protection protection;    //!< class protection
 242     MethodTypes mtype;        //!< signal, slot, (dcop) method, or property?
 243     uint64 spec;              //!< class/member specifiers
 244     int  initLines;           //!< define/variable initializer lines to show
 245     bool stat;                //!< static ?
 246     bool explicitExternal;    //!< explicitly defined as external?
 247     bool proto;               //!< prototype ?
 248     bool subGrouping;         //!< automatically group class members?
 249     bool callGraph;           //!< do we need to draw the call graph?
 250     bool callerGraph;         //!< do we need to draw the caller graph?
 251     Specifier    virt;        //!< virtualness of the entry
 252     QCString     args;        //!< member argument string
 253     QCString     bitfields;   //!< member's bit fields
 254     ArgumentList *argList;    //!< member arguments as a list
 255     QList<ArgumentList> *tArgLists; //!< template argument declarations
 256     QGString     program;     //!< the program text
 257     QGString     initializer; //!< initial value (for variables)
 258     QCString     includeFile; //!< include file (2 arg of \\class, must be unique)
 259     QCString     includeName; //!< include name (3 arg of \\class)
 260     QCString     doc;         //!< documentation block (partly parsed)
 261     int          docLine;     //!< line number at which the documentation was found
 262     QCString     docFile;     //!< file in which the documentation was found
 263     QCString     brief;       //!< brief description (doc block)
 264     int          briefLine;   //!< line number at which the brief desc. was found
 265     QCString     briefFile;   //!< file in which the brief desc. was found
 266     QCString     inbodyDocs;  //!< documentation inside the body of a function
 267     int          inbodyLine;  //!< line number at which the body doc was found
 268     QCString     inbodyFile;  //!< file in which the body doc was found
 269     QCString     relates;     //!< related class (doc block)
 270     RelatesType  relatesType; //!< how relates is handled
 271     QCString     read;        //!< property read accessor
 272     QCString     write;       //!< property write accessor
 273     QCString     inside;      //!< name of the class in which documents are found
 274     QCString     exception;   //!< throw specification
 275     ArgumentList *typeConstr; //!< where clause (C#) for type constraints
 276     int          bodyLine;    //!< line number of the definition in the source
 277     int          endBodyLine; //!< line number where the definition ends
 278     int          mGrpId;      //!< member group id
 279     QList<BaseInfo> *extends; //!< list of base classes
 280     QList<Grouping> *groups;  //!< list of groups this entry belongs to
 281     QList<SectionInfo> *anchors; //!< list of anchors defined in this entry
 282     QCString    fileName;     //!< file this entry was extracted from
 283     int         startLine;    //!< start line of entry in the source
 284     int         startColumn;  //!< start column of entry in the source
 285     QList<ListItemInfo> *sli; //!< special lists (test/todo/bug/deprecated/..) this entry is in
 286     SrcLangExt  lang;         //!< programming language in which this entry was found
 287     bool        hidden;       //!< does this represent an entity that is hidden from the output
 288     bool        artificial;   //!< Artificially introduced item
 289     GroupDocType groupDocType;
 290     QCString    id;           //!< libclang id
 291
 292
 293     static int  num;          //!< counts the total number of entries
 294
 295     /// return the command name used to define GROUPDOC_SEC
 296     const char *groupDocCmd() const
 297     {
 298       switch( groupDocType )
 299       {
 300         case GROUPDOC_NORMAL: return "\\defgroup";
 301         case GROUPDOC_ADD: return "\\addgroup";
 302         case GROUPDOC_WEAK: return "\\weakgroup";
 303         default: return "unknown group command";
 304       }
 305     }
 306     Grouping::GroupPri_t groupingPri() const
 307     {
 308       if( section != GROUPDOC_SEC )
 309       {
 310         return Grouping::GROUPING_LOWEST;
 311       }
 312       switch( groupDocType )
 313       {
 314         case GROUPDOC_NORMAL: return Grouping::GROUPING_AUTO_DEF;
 315         case GROUPDOC_ADD:    return Grouping::GROUPING_AUTO_ADD;
 316         case GROUPDOC_WEAK:   return Grouping::GROUPING_AUTO_WEAK;
 317         default: return Grouping::GROUPING_LOWEST;
 318       }
 319     }
 320
 321   private:
 322     void createSubtreeIndex(EntryNav *nav,FileStorage *storage,FileDef *fd);
 323     Entry         *m_parent;    //!< parent node in the tree
 324     QList<Entry>  *m_sublist;   //!< entries that are children of this one
 325     Entry &operator=(const Entry &);
 326 };
 327
 328 /** Wrapper for a node in the Entry tree.
 329  *
 330  *  Allows navigating through the Entry tree and load and storing Entry
 331  *  objects persistently to disk.
 332  */
 333 class EntryNav
 334 {
 335   public:
 336     EntryNav(EntryNav *parent,Entry *e);
 337    ~EntryNav();
 338     void addChild(EntryNav *);
 339     bool loadEntry(FileStorage *storage);
 340     bool saveEntry(Entry *e,FileStorage *storage);
 341     void setEntry(Entry *e);
 342     void releaseEntry();
 343     void changeSection(int section) { m_section = section; }
 344     void setFileDef(FileDef *fd) { m_fileDef = fd; }
 345
 346     Entry *entry() const { return m_info; }
 347     int section() const { return m_section; }
 348     SrcLangExt lang() const { return m_lang; }
 349     const QCString &type() const { return m_type; }
 350     const QCString &name() const { return m_name; }
 351     TagInfo *tagInfo() const { return m_tagInfo; }
 352     const QList<EntryNav> *children() const { return m_subList; }
 353     EntryNav *parent() const { return m_parent; }
 354     FileDef *fileDef() const { return m_fileDef; }
 355
 356   private:
 357
 358     // navigation
 359     EntryNav        *m_parent;    //!< parent node in the tree
 360     QList<EntryNav> *m_subList;   //!< entries that are children of this one
 361
 362     // identification
 363     int          m_section;     //!< entry type (see Sections);
 364     QCString     m_type;        //!< member type
 365     QCString     m_name;        //!< member name
 366     TagInfo     *m_tagInfo;      //!< tag file info
 367     FileDef     *m_fileDef;
 368     SrcLangExt   m_lang;         //!< programming language in which this entry was found
 369
 370     Entry       *m_info;
 371     int64        m_offset;
 372     bool         m_noLoad;
 373 };
 374
 375
 376 typedef QList<Entry> EntryList;
 377 typedef QListIterator<Entry> EntryListIterator;
 378
 379 typedef QList<EntryNav> EntryNavList;
 380 typedef QListIterator<EntryNav> EntryNavListIterator;
 381
 382 #endif