entry.h 14.7 KB
Newer Older
Dimitri van Heesch's avatar
Dimitri van Heesch committed
1 2
/******************************************************************************
 *
3
 * 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
4
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
5
 * Copyright (C) 1997-2013 by Dimitri van Heesch.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
6 7 8 9 10 11 12
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby 
 * granted. No representations are made about the suitability of this software 
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
13 14
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
15 16 17 18 19 20
 *
 */

#ifndef ENTRY_H
#define ENTRY_H

21
#include "types.h"
Dimitri van Heesch's avatar
Dimitri van Heesch committed
22

23
#include <qlist.h>
24 25
#include <qgstring.h>

26
struct SectionInfo;
27 28 29
class QFile;
class EntryNav;
class FileDef;
30
class FileStorage;
31
class StorageIntf;
32
class ArgumentList;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
33
struct ListItemInfo;
34

Dimitri van Heesch's avatar
Dimitri van Heesch committed
35
/** This class stores information about an inheritance relation
36
 */ 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
37 38
struct BaseInfo 
{
39
  /*! Creates an object representing an inheritance relation */
40 41
  BaseInfo(const char *n,Protection p,Specifier v) : 
    name(n),prot(p),virt(v) {}
42 43 44
  QCString   name; //!< the name of the base class
  Protection prot; //!< inheritance type
  Specifier  virt; //!< virtualness
Dimitri van Heesch's avatar
Dimitri van Heesch committed
45 46
};

Dimitri van Heesch's avatar
Dimitri van Heesch committed
47 48
/** This struct is used to capture the tag file information 
 *  for an Entry. 
49
 */
50 51 52 53 54 55 56
struct TagInfo 
{
  QCString tagName;
  QCString fileName;
  QCString anchor;
};

Dimitri van Heesch's avatar
Dimitri van Heesch committed
57 58
/** Represents an unstructured piece of information, about an
 *  entity found in the sources. 
59 60
 *
 *  parseMain() in scanner.l will generate a tree of these
Dimitri van Heesch's avatar
Dimitri van Heesch committed
61 62
 *  entries.
 */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
63 64 65 66
class Entry
{
  public:

67
    /*! Kind of entries that are supported */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
68 69
    enum Sections { 
      CLASS_SEC        = 0x00000001, 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
70
      NAMESPACE_SEC    = 0x00000010,
71
      COMPOUND_MASK    = CLASS_SEC,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
72
      SCOPE_MASK       = COMPOUND_MASK | NAMESPACE_SEC,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
73
      
74 75 76 77 78 79 80 81
      CLASSDOC_SEC     = 0x00000800, 
      STRUCTDOC_SEC    = 0x00001000,
      UNIONDOC_SEC     = 0x00002000,
      EXCEPTIONDOC_SEC = 0x00004000,
      NAMESPACEDOC_SEC = 0x00008000,
      INTERFACEDOC_SEC = 0x00010000,
      PROTOCOLDOC_SEC  = 0x00020000,
      CATEGORYDOC_SEC  = 0x00040000,
82 83
      SERVICEDOC_SEC   = 0x00080000,
      SINGLETONDOC_SEC = 0x00100000,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
84
      COMPOUNDDOC_MASK = CLASSDOC_SEC | STRUCTDOC_SEC | UNIONDOC_SEC | 
85
                         INTERFACEDOC_SEC | EXCEPTIONDOC_SEC | PROTOCOLDOC_SEC |
86
                         CATEGORYDOC_SEC | SERVICEDOC_SEC | SINGLETONDOC_SEC,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
87

88 89
      SOURCE_SEC       = 0x00400000,
      HEADER_SEC       = 0x00800000,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
90 91
      FILE_MASK        = SOURCE_SEC | HEADER_SEC,

92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
      ENUMDOC_SEC      = 0x01000000,
      ENUM_SEC         = 0x02000000,
      EMPTY_SEC        = 0x03000000, 
      PAGEDOC_SEC      = 0x04000000, 
      VARIABLE_SEC     = 0x05000000,
      FUNCTION_SEC     = 0x06000000,
      TYPEDEF_SEC      = 0x07000000,
      MEMBERDOC_SEC    = 0x08000000, 
      OVERLOADDOC_SEC  = 0x09000000,
      EXAMPLE_SEC      = 0x0a000000, 
      VARIABLEDOC_SEC  = 0x0b000000,
      FILEDOC_SEC      = 0x0c000000,
      DEFINEDOC_SEC    = 0x0d000000,
      INCLUDE_SEC      = 0x0e000000,
      DEFINE_SEC       = 0x0f000000,
      GROUPDOC_SEC     = 0x10000000,
      USINGDIR_SEC     = 0x11000000,
      MAINPAGEDOC_SEC  = 0x12000000,
      MEMBERGRP_SEC    = 0x13000000,
      USINGDECL_SEC    = 0x14000000,
      PACKAGE_SEC      = 0x15000000,
      PACKAGEDOC_SEC   = 0x16000000,
114
      OBJCIMPL_SEC     = 0x17000000,
115
      DIRDOC_SEC       = 0x18000000
116 117
      ,EXPORTED_INTERFACE_SEC = 0x19000000
      ,INCLUDED_SERVICE_SEC = 0x1A000000
Dimitri van Heesch's avatar
Dimitri van Heesch committed
118
    };
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178

    // class specifiers (add new items to the end)
    static const uint64 Template        = (1ULL<<0);
    static const uint64 Generic         = (1ULL<<1);
    static const uint64 Ref             = (1ULL<<2);
    static const uint64 Value           = (1ULL<<3);
    static const uint64 Interface       = (1ULL<<4);
    static const uint64 Struct          = (1ULL<<5);
    static const uint64 Union           = (1ULL<<6);
    static const uint64 Exception       = (1ULL<<7);
    static const uint64 Protocol        = (1ULL<<8);
    static const uint64 Category        = (1ULL<<9);
    static const uint64 SealedClass     = (1ULL<<10);
    static const uint64 AbstractClass   = (1ULL<<11);
    static const uint64 Enum            = (1ULL<<12); // for Java-style enums
    static const uint64 Service         = (1ULL<<13); // UNO IDL
    static const uint64 Singleton       = (1ULL<<14); // UNO IDL

    // member specifiers (add new items to the beginning)
    static const uint64 Inline          = (1ULL<<24);
    static const uint64 Explicit        = (1ULL<<25);
    static const uint64 Mutable         = (1ULL<<26);
    static const uint64 Settable        = (1ULL<<27);
    static const uint64 Gettable        = (1ULL<<28);
    static const uint64 Readable        = (1ULL<<29);
    static const uint64 Writable        = (1ULL<<30);
    static const uint64 Final           = (1ULL<<31);
    static const uint64 Abstract        = (1ULL<<32);
    static const uint64 Addable         = (1ULL<<33);
    static const uint64 Removable       = (1ULL<<34);
    static const uint64 Raisable        = (1ULL<<35);
    static const uint64 Override        = (1ULL<<36);
    static const uint64 New             = (1ULL<<37);
    static const uint64 Sealed          = (1ULL<<38);
    static const uint64 Initonly        = (1ULL<<39);
    static const uint64 Optional        = (1ULL<<40);
    static const uint64 Required        = (1ULL<<41);
    static const uint64 NonAtomic       = (1ULL<<42);
    static const uint64 Copy            = (1ULL<<43);
    static const uint64 Retain          = (1ULL<<44);
    static const uint64 Assign          = (1ULL<<45);
    static const uint64 Strong          = (1ULL<<46);
    static const uint64 Weak            = (1ULL<<47);
    static const uint64 Unretained      = (1ULL<<48);
    static const uint64 Alias           = (1ULL<<49);
    static const uint64 ConstExp        = (1ULL<<50);
    static const uint64 Default         = (1ULL<<51);
    static const uint64 Delete          = (1ULL<<52);
    static const uint64 NoExcept        = (1ULL<<53);
    static const uint64 Attribute       = (1ULL<<54); // UNO IDL attribute
    static const uint64 Property        = (1ULL<<55); // UNO IDL property
    static const uint64 Readonly        = (1ULL<<56); // on UNO IDL attribute or property
    static const uint64 Bound           = (1ULL<<57); // on UNO IDL attribute or property
    static const uint64 Constrained     = (1ULL<<58); // on UNO IDL property
    static const uint64 Transient       = (1ULL<<59); // on UNO IDL property
    static const uint64 MaybeVoid       = (1ULL<<60); // on UNO IDL property
    static const uint64 MaybeDefault    = (1ULL<<61); // on UNO IDL property
    static const uint64 MaybeAmbiguous  = (1ULL<<62); // on UNO IDL property
    static const uint64 Published       = (1ULL<<63); // UNO IDL keyword

179 180 181 182 183 184 185
    enum GroupDocType
    {
      GROUPDOC_NORMAL,        //!< defgroup
      GROUPDOC_ADD,           //!< addgroup
      GROUPDOC_WEAK           //!< weakgroup
    };                        //!< kind of group

Dimitri van Heesch's avatar
Dimitri van Heesch committed
186 187
    Entry();
    Entry(const Entry &);
188 189 190
   ~Entry();

    /*! Returns the static size of the Entry (so excluding any dynamic memory) */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
191
    int getSize();
192

193
    void addSpecialListItem(const char *listName,int index);
194
    void createNavigationIndex(EntryNav *rootNav,FileStorage *storage,FileDef *fd);
195 196 197

    // while parsing a file these function can be used to navigate/build the tree
    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 203 204

    /*! Returns the list of children for this Entry 
     *  @see addSubEntry() and removeSubEntry()
     */
205
    const QList<Entry> *children() const { return m_sublist; }
Dimitri van Heesch's avatar
Dimitri van Heesch committed
206

207 208 209 210 211 212 213 214 215
    /*! Adds entry \a e as a child to this entry */
    void addSubEntry (Entry* e) ;

    /*! Removes entry \a e from the list of children. 
     *  Returns a pointer to the entry or 0 if the entry was not a child. 
     *  Note the entry will not be deleted.
     */ 
    Entry *removeSubEntry(Entry *e);

216 217 218
    /*! Restore the state of this Entry to the default value it has
     *  at construction time. 
     */
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 228 229 230 231 232 233

  public:

    // identification
    int          section;     //!< entry type (see Sections);
    QCString	 type;        //!< member type 
    QCString	 name;        //!< member name
    TagInfo     *tagInfo;     //!< tag file info
Dimitri van Heesch's avatar
Dimitri van Heesch committed
234

235
    // content
236 237
    Protection protection;    //!< class protection
    MethodTypes mtype;        //!< signal, slot, (dcop) method, or property?
238
    uint64 spec;              //!< class/member specifiers
239
    int  initLines;           //!< define/variable initializer lines to show 
240 241 242 243
    bool stat;                //!< static ?
    bool explicitExternal;    //!< explicitly defined as external?
    bool proto;               //!< prototype ?
    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 247 248 249
    Specifier    virt;        //!< virtualness of the entry 
    QCString     args;        //!< member argument string
    QCString     bitfields;   //!< member's bit fields
    ArgumentList *argList;    //!< member arguments as a list
250
    QList<ArgumentList> *tArgLists; //!< template argument declarations
251 252
    QGString	 program;     //!< the program text
    QGString     initializer; //!< initial value (for variables)
253 254
    QCString     includeFile; //!< include file (2 arg of \\class, must be unique)
    QCString     includeName; //!< include name (3 arg of \\class)
255
    QCString     doc;         //!< documentation block (partly parsed)
256 257
    int          docLine;     //!< line number at which the documentation was found
    QCString     docFile;     //!< file in which the documentation was found
258
    QCString     brief;       //!< brief description (doc block)
259 260
    int          briefLine;   //!< line number at which the brief desc. was found
    QCString     briefFile;   //!< file in which the brief desc. was found
261 262 263
    QCString     inbodyDocs;  //!< documentation inside the body of a function
    int          inbodyLine;  //!< line number at which the body doc was found
    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 267
    QCString     read;        //!< property read accessor
    QCString     write;       //!< property write accessor
268 269
    QCString     inside;      //!< name of the class in which documents are found
    QCString     exception;   //!< throw specification
270
    ArgumentList *typeConstr; //!< where clause (C#) for type constraints
271 272 273
    int          bodyLine;    //!< line number of the definition in the source
    int          endBodyLine; //!< line number where the definition ends
    int          mGrpId;      //!< member group id
274 275
    QList<BaseInfo> *extends; //!< list of base classes    
    QList<Grouping> *groups;  //!< list of groups this entry belongs to
276
    QList<SectionInfo> *anchors; //!< list of anchors defined in this entry
277 278
    QCString	fileName;     //!< file this entry was extracted from
    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
Dimitri van Heesch's avatar
Dimitri van Heesch committed
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 289
    static int  num;          //!< counts the total number of entries

290
    /// return the command name used to define GROUPDOC_SEC
291
    const char *groupDocCmd() const
292
    {
293 294
      switch( groupDocType ) 
      {
295 296 297
        case GROUPDOC_NORMAL: return "\\defgroup";
        case GROUPDOC_ADD: return "\\addgroup";
        case GROUPDOC_WEAK: return "\\weakgroup";
298 299
        default: return "unknown group command";
      }
300
    }
301
    Grouping::GroupPri_t groupingPri() const
302
    {
303 304 305 306 307 308
      if( section != GROUPDOC_SEC ) 
      {
        return Grouping::GROUPING_LOWEST;
      }
      switch( groupDocType ) 
      {
309 310 311
        case GROUPDOC_NORMAL: return Grouping::GROUPING_AUTO_DEF;
        case GROUPDOC_ADD:    return Grouping::GROUPING_AUTO_ADD;
        case GROUPDOC_WEAK:   return Grouping::GROUPING_AUTO_WEAK;
312 313
        default: return Grouping::GROUPING_LOWEST;
      }
314
    }
315 316

  private:  
317
    void createSubtreeIndex(EntryNav *nav,FileStorage *storage,FileDef *fd);
318 319
    Entry         *m_parent;    //!< parent node in the tree
    QList<Entry>  *m_sublist;   //!< entries that are children of this one
Dimitri van Heesch's avatar
Dimitri van Heesch committed
320
    Entry &operator=(const Entry &); 
321 322
};

Dimitri van Heesch's avatar
Dimitri van Heesch committed
323 324 325 326 327
/** Wrapper for a node in the Entry tree.
 *
 *  Allows navigating through the Entry tree and load and storing Entry
 *  objects persistently to disk.
 */
328 329 330 331 332 333
class EntryNav
{
  public:
    EntryNav(EntryNav *parent,Entry *e);
   ~EntryNav();
    void addChild(EntryNav *);
334 335
    bool loadEntry(FileStorage *storage);
    bool saveEntry(Entry *e,FileStorage *storage);
336 337 338 339 340 341 342
    void setEntry(Entry *e);
    void releaseEntry();
    void changeSection(int section) { m_section = section; }
    void setFileDef(FileDef *fd) { m_fileDef = fd; }

    Entry *entry() const { return m_info; }
    int section() const { return m_section; }
343
    SrcLangExt lang() const { return m_lang; }
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362
    const QCString &type() const { return m_type; }
    const QCString &name() const { return m_name; }
    TagInfo *tagInfo() const { return m_tagInfo; }
    const QList<EntryNav> *children() const { return m_subList; }
    EntryNav *parent() const { return m_parent; }
    FileDef *fileDef() const { return m_fileDef; }

  private:

    // navigation 
    EntryNav        *m_parent;    //!< parent node in the tree
    QList<EntryNav> *m_subList;   //!< entries that are children of this one

    // identification
    int          m_section;     //!< entry type (see Sections);
    QCString	 m_type;        //!< member type 
    QCString	 m_name;        //!< member name
    TagInfo     *m_tagInfo;      //!< tag file info
    FileDef     *m_fileDef;
363
    SrcLangExt   m_lang;         //!< programming language in which this entry was found
364 365 366 367 368 369

    Entry       *m_info;
    int64        m_offset;
    bool         m_noLoad;
};

Dimitri van Heesch's avatar
Dimitri van Heesch committed
370 371 372 373

typedef QList<Entry> EntryList;
typedef QListIterator<Entry> EntryListIterator;

374 375 376
typedef QList<EntryNav> EntryNavList;
typedef QListIterator<EntryNav> EntryNavListIterator;

Dimitri van Heesch's avatar
Dimitri van Heesch committed
377
#endif