1 /******************************************************************************

     2  *

     3  * 

     4  *

     5  * Copyright (C) 1997-2008 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 

    24 #include <qgstring.h>

    25 

    26 struct SectionInfo;

    27 class QFile;

    28 class EntryNav;

    29 class FileDef;

    30 class FileStorage;

    31 class StorageIntf;

    32 

    33 enum Protection { Public, Protected, Private, Package } ;

    34 enum Specifier { Normal, Virtual, Pure } ;

    35 enum MethodTypes { Method, Signal, Slot, DCOP, Property, Event };

    36 enum RelatesType { Simple, Duplicate, MemberOf };

    37 enum Relationship { Member, Related, Foreign };

    38 

    39 struct ListItemInfo

    40 {

    41   QCString type;

    42   int itemId;

    43 };

    44 

    45 /*! \brief This class stores information about an inheritance relation

    46  */ 

    47 struct BaseInfo 

    48 {

    49   /*! Creates an object representing an inheritance relation */

    50   BaseInfo(const char *n,Protection p,Specifier v) : 

    51     name(n),prot(p),virt(v) {}

    52   QCString   name; //!< the name of the base class

    53   Protection prot; //!< inheritance type

    54   Specifier  virt; //!< virtualness

    55 };

    56 

    57 /*! \brief This class contains the information about the argument of a

    58  *         function or template

    59  *

    60  */

    61 struct Argument

    62 {

    63   /*! Construct a new argument. */

    64   Argument() {}

    65   /*! Copy an argument (does a deep copy of all strings). */

    66   Argument(const Argument &a) 

    67   { 

    68     attrib=a.attrib.copy();

    69     type=a.type.copy(); 

    70     name=a.name.copy(); 

    71     defval=a.defval.copy(); 

    72     docs=a.docs.copy();

    73     array=a.array.copy();

    74   }

    75   /*! Assignment of an argument (does a deep copy of all strings). */

    76   Argument &operator=(const Argument &a)

    77   {

    78     if (this!=&a)

    79     {

    80       attrib=a.attrib.copy();

    81       type=a.type.copy(); 

    82       name=a.name.copy(); 

    83       defval=a.defval.copy(); 

    84       docs=a.docs.copy();

    85       array=a.array.copy();

    86     }

    87     return *this;

    88   }

    89   /*! return TRUE if this argument is documentation and the argument has a

    90    *  non empty name.

    91    */

    92   bool hasDocumentation() const 

    93   { 

    94     return !name.isEmpty() && !docs.isEmpty(); 

    95   }

    96   

    97   QCString attrib;   /*!< Argument's attribute (IDL only) */

    98   QCString type;     /*!< Argument's type */

    99   QCString canType;  /*!< Cached value of canonical type (after type resolution). Empty initially. */

   100   QCString name;     /*!< Argument's name (may be empty) */

   101   QCString array;    /*!< Argument's array specifier (may be empty) */

   102   QCString defval;   /*!< Argument's default value (may be empty) */

   103   QCString docs;     /*!< Argument's documentation (may be empty) */

   104 };

   105 

   106 /*! \brief This class represents an function or template argument list. 

   107  *

   108  *  This class also stores some information about member that is typically

   109  *  put after the argument list, such as wether the member is const, 

   110  *  volatile or pure virtual.

   111  */

   112 class ArgumentList : public QList<Argument> 

   113 {

   114   public:

   115     /*! Creates an empty argument list */

   116     ArgumentList() : QList<Argument>(), 

   117                      constSpecifier(FALSE),

   118                      volatileSpecifier(FALSE),

   119                      pureSpecifier(FALSE)

   120                      { setAutoDelete(TRUE); }

   121     /*! Destroys the argument list */

   122    ~ArgumentList() {}

   123     bool hasDocumentation() const;

   124     /*! Does the member modify the state of the class? default: FALSE. */

   125     bool constSpecifier;

   126     /*! Is the member volatile? default: FALSE. */

   127     bool volatileSpecifier;

   128     /*! Is this a pure virtual member? default: FALSE */

   129     bool pureSpecifier;

   130 };

   131 

   132 typedef QListIterator<Argument> ArgumentListIterator;

   133 

   134 /*! \brief This struct is used to capture the tag file information 

   135  *         for an Entry. 

   136  */

   137 struct TagInfo 

   138 {

   139   QCString tagName;

   140   QCString fileName;

   141   QCString anchor;

   142 };

   143 

   144 struct Grouping 

   145 {

   146   enum GroupPri_t 

   147   {

   148     GROUPING_LOWEST,

   149     GROUPING_AUTO_WEAK = 

   150       GROUPING_LOWEST,     //!< membership in group was defined via \@weakgroup 

   151     GROUPING_AUTO_ADD,     //!< membership in group was defined via \@add[to]group 

   152     GROUPING_AUTO_DEF,     //!< membership in group was defined via \@defgroup

   153     GROUPING_AUTO_HIGHEST = GROUPING_AUTO_DEF,

   154     GROUPING_INGROUP,      //!< membership in group was defined by \@ingroup

   155     GROUPING_HIGHEST = GROUPING_INGROUP

   156   };

   157 

   158   static const char *getGroupPriName( GroupPri_t priority )

   159   {

   160     switch( priority )

   161     {

   162       case GROUPING_AUTO_WEAK:

   163         return "@weakgroup";

   164       case GROUPING_AUTO_ADD:

   165         return "@addtogroup";

   166       case GROUPING_AUTO_DEF:

   167         return "@defgroup";

   168       case GROUPING_INGROUP:

   169         return "@ingroup";

   170     }	    

   171     return "???";

   172   }

   173 

   174   Grouping( const char *gn, GroupPri_t p ) : groupname(gn), pri(p) {}

   175   Grouping( const Grouping &g ) : groupname(g.groupname), pri(g.pri) {}

   176   QCString groupname;   //!< name of the group

   177   GroupPri_t pri;       //!< priority of this definition

   178 

   179 };

   180 

   181 /*! \brief Represents an unstructured piece of information, about an

   182  *         entity found in the sources. 

   183  *

   184  *  parseMain() in scanner.l will generate a tree of these

   185  *  entries.

   186  */

   187 class Entry

   188 {

   189   public:

   190 

   191     /*! Kind of entries that are supported */

   192     enum Sections { 

   193       CLASS_SEC        = 0x00000001, 

   194       NAMESPACE_SEC    = 0x00000010,

   195       COMPOUND_MASK    = CLASS_SEC,

   196       SCOPE_MASK       = COMPOUND_MASK | NAMESPACE_SEC,

   197       

   198       CLASSDOC_SEC     = 0x00000800, 

   199       STRUCTDOC_SEC    = 0x00001000,

   200       UNIONDOC_SEC     = 0x00002000,

   201       EXCEPTIONDOC_SEC = 0x00004000,

   202       NAMESPACEDOC_SEC = 0x00008000,

   203       INTERFACEDOC_SEC = 0x00010000,

   204       PROTOCOLDOC_SEC  = 0x00020000,

   205       CATEGORYDOC_SEC  = 0x00040000,

   206       COMPOUNDDOC_MASK = CLASSDOC_SEC | STRUCTDOC_SEC | UNIONDOC_SEC | 

   207                          INTERFACEDOC_SEC | EXCEPTIONDOC_SEC | PROTOCOLDOC_SEC |

   208                          CATEGORYDOC_SEC,

   209 

   210       SOURCE_SEC       = 0x00400000,

   211       HEADER_SEC       = 0x00800000,

   212       FILE_MASK        = SOURCE_SEC | HEADER_SEC,

   213 

   214       ENUMDOC_SEC      = 0x01000000,

   215       ENUM_SEC         = 0x02000000,

   216       EMPTY_SEC        = 0x03000000, 

   217       PAGEDOC_SEC      = 0x04000000, 

   218       VARIABLE_SEC     = 0x05000000,

   219       FUNCTION_SEC     = 0x06000000,

   220       TYPEDEF_SEC      = 0x07000000,

   221       MEMBERDOC_SEC    = 0x08000000, 

   222       OVERLOADDOC_SEC  = 0x09000000,

   223       EXAMPLE_SEC      = 0x0a000000, 

   224       VARIABLEDOC_SEC  = 0x0b000000,

   225       FILEDOC_SEC      = 0x0c000000,

   226       DEFINEDOC_SEC    = 0x0d000000,

   227       INCLUDE_SEC      = 0x0e000000,

   228       DEFINE_SEC       = 0x0f000000,

   229       GROUPDOC_SEC     = 0x10000000,

   230       USINGDIR_SEC     = 0x11000000,

   231       MAINPAGEDOC_SEC  = 0x12000000,

   232       MEMBERGRP_SEC    = 0x13000000,

   233       USINGDECL_SEC    = 0x14000000,

   234       PACKAGE_SEC      = 0x15000000,

   235       PACKAGEDOC_SEC   = 0x16000000,

   236       OBJCIMPL_SEC     = 0x17000000,

   237       DIRDOC_SEC       = 0x18000000

   238     };

   239     enum MemberSpecifier

   240     {

   241       Inline    = 0x000001,

   242       Explicit  = 0x000002,

   243       Mutable   = 0x000004,

   244       Settable  = 0x000008,

   245       Gettable  = 0x000010,

   246       Readable  = 0x000020,

   247       Writable  = 0x000040,

   248       Final     = 0x000080,

   249       Abstract  = 0x000100,

   250       Addable   = 0x000200,

   251       Removable = 0x000400,

   252       Raisable  = 0x000800,

   253       Override  = 0x001000,

   254       New       = 0x002000,

   255       Sealed    = 0x004000,

   256       Initonly  = 0x008000,

   257       Optional  = 0x010000,

   258       Required  = 0x020000,

   259       NonAtomic = 0x040000,

   260       Copy      = 0x080000,

   261       Retain    = 0x100000,

   262       Assign    = 0x200000

   263     };

   264     enum ClassSpecifier

   265     {

   266       Template       = 0x0001,

   267       Generic        = 0x0002,

   268       Ref            = 0x0004,

   269       Value          = 0x0008,

   270       Interface      = 0x0010,

   271       Struct         = 0x0020,

   272       Union          = 0x0040,

   273       Exception      = 0x0080,

   274       Protocol       = 0x0100,

   275       Category       = 0x0200,

   276       SealedClass    = 0x0400,

   277       AbstractClass  = 0x0800

   278     };

   279     enum GroupDocType

   280     {

   281       GROUPDOC_NORMAL,        //!< defgroup

   282       GROUPDOC_ADD,           //!< addgroup

   283       GROUPDOC_WEAK           //!< weakgroup

   284     };                        //!< kind of group

   285 

   286 

   287     Entry();

   288     Entry(const Entry &);

   289     ~Entry();

   290     int getSize();

   291     void addSpecialListItem(const char *listName,int index);

   292     void createNavigationIndex(EntryNav *rootNav,FileStorage *storage,FileDef *fd);

   293 

   294     // while parsing a file these function can be used to navigate/build the tree

   295     void setParent(Entry *parent) { m_parent = parent; }

   296     Entry *parent() const { return m_parent; }

   297     const QList<Entry> *children() const { return m_sublist; }

   298 

   299     /*! Adds entry \e as a child to this entry */

   300     void	addSubEntry (Entry* e) ;

   301     /*! Restore the state of this Entry to the default value it has

   302      *  at construction time. 

   303      */

   304     void reset();

   305     void marshall(StorageIntf *);

   306     void unmarshall(StorageIntf *);

   307 

   308   public:

   309 

   310     // identification

   311     int          section;     //!< entry type (see Sections);

   312     QCString	 type;        //!< member type 

   313     QCString	 name;        //!< member name

   314     TagInfo     *tagInfo;     //!< tag file info

   315 

   316     // content

   317     Protection protection;    //!< class protection

   318     MethodTypes mtype;        //!< signal, slot, (dcop) method, or property?

   319     int  spec;                //!< class/member specifiers

   320     int  initLines;           //!< define/variable initializer lines to show 

   321     bool stat;                //!< static ?

   322     bool explicitExternal;    //!< explicitly defined as external?

   323     bool proto;               //!< prototype ?

   324     bool subGrouping;         //!< automatically group class members?

   325     bool callGraph;           //!< do we need to draw the call graph?

   326     bool callerGraph;         //!< do we need to draw the caller graph?

   327     Specifier    virt;        //!< virtualness of the entry 

   328     QCString     args;        //!< member argument string

   329     QCString     bitfields;   //!< member's bit fields

   330     ArgumentList *argList;    //!< member arguments as a list

   331     QList<ArgumentList> *tArgLists; //!< template argument declarations

   332     QGString	 program;     //!< the program text

   333     QGString     initializer; //!< initial value (for variables)

   334     QCString     includeFile; //!< include file (2 arg of \\class, must be unique)

   335     QCString     includeName; //!< include name (3 arg of \\class)

   336     QCString     doc;         //!< documentation block (partly parsed)

   337     int          docLine;     //!< line number at which the documentation was found

   338     QCString     docFile;     //!< file in which the documentation was found

   339     QCString     brief;       //!< brief description (doc block)

   340     int          briefLine;   //!< line number at which the brief desc. was found

   341     QCString     briefFile;   //!< file in which the brief desc. was found

   342     QCString     inbodyDocs;  //!< documentation inside the body of a function

   343     int          inbodyLine;  //!< line number at which the body doc was found

   344     QCString     inbodyFile;  //!< file in which the body doc was found

   345     QCString     relates;     //!< related class (doc block)

   346     RelatesType  relatesType; //!< how relates is handled

   347     QCString     read;        //!< property read accessor

   348     QCString     write;       //!< property write accessor

   349     QCString     inside;      //!< name of the class in which documents are found

   350     QCString     exception;   //!< throw specification

   351     ArgumentList *typeConstr; //!< where clause (C#) for type constraints

   352     int          bodyLine;    //!< line number of the definition in the source

   353     int          endBodyLine; //!< line number where the definition ends

   354     int          mGrpId;      //!< member group id

   355     QList<BaseInfo> *extends; //!< list of base classes    

   356     QList<Grouping> *groups;  //!< list of groups this entry belongs to

   357     QList<SectionInfo> *anchors; //!< list of anchors defined in this entry

   358     QCString	fileName;     //!< file this entry was extracted from

   359     int		startLine;    //!< start line of entry in the source

   360     QList<ListItemInfo> *sli; //!< special lists (test/todo/bug/deprecated/..) this entry is in

   361     bool        objc;         //!< Objective-C construct

   362     bool        hidden;       //!< does this represent an entity that is hidden from the output

   363     bool        artificial;   //!< Artificially introduced item

   364     GroupDocType groupDocType;

   365 

   366     static int  num;          //!< counts the total number of entries

   367 

   368     /// return the command name used to define GROUPDOC_SEC

   369     const char *groupDocCmd() const

   370     {

   371       switch( groupDocType ) 

   372       {

   373         case GROUPDOC_NORMAL: return "\\defgroup";

   374         case GROUPDOC_ADD: return "\\addgroup";

   375         case GROUPDOC_WEAK: return "\\weakgroup";

   376         default: return "unknown group command";

   377       }

   378     }

   379     Grouping::GroupPri_t groupingPri() const

   380     {

   381       if( section != GROUPDOC_SEC ) 

   382       {

   383         return Grouping::GROUPING_LOWEST;

   384       }

   385       switch( groupDocType ) 

   386       {

   387         case GROUPDOC_NORMAL: return Grouping::GROUPING_AUTO_DEF;

   388         case GROUPDOC_ADD:    return Grouping::GROUPING_AUTO_ADD;

   389         case GROUPDOC_WEAK:   return Grouping::GROUPING_AUTO_WEAK;

   390         default: return Grouping::GROUPING_LOWEST;

   391       }

   392     }

   393 

   394   private:  

   395     void createSubtreeIndex(EntryNav *nav,FileStorage *storage,FileDef *fd);

   396     Entry         *m_parent;    //!< parent node in the tree

   397     QList<Entry>  *m_sublist;   //!< entries that are children of this one

   398     Entry &operator=(const Entry &); 

   399 };

   400 

   401 class EntryNav

   402 {

   403   public:

   404     EntryNav(EntryNav *parent,Entry *e);

   405    ~EntryNav();

   406     void addChild(EntryNav *);

   407     bool loadEntry(FileStorage *storage);

   408     bool saveEntry(Entry *e,FileStorage *storage);

   409     void setEntry(Entry *e);

   410     void releaseEntry();

   411     void changeSection(int section) { m_section = section; }

   412     void setFileDef(FileDef *fd) { m_fileDef = fd; }

   413 

   414     Entry *entry() const { return m_info; }

   415     int section() const { return m_section; }

   416     const QCString &type() const { return m_type; }

   417     const QCString &name() const { return m_name; }

   418     TagInfo *tagInfo() const { return m_tagInfo; }

   419     const QList<EntryNav> *children() const { return m_subList; }

   420     EntryNav *parent() const { return m_parent; }

   421     FileDef *fileDef() const { return m_fileDef; }

   422 

   423   private:

   424 

   425     // navigation 

   426     EntryNav        *m_parent;    //!< parent node in the tree

   427     QList<EntryNav> *m_subList;   //!< entries that are children of this one

   428 

   429     // identification

   430     int          m_section;     //!< entry type (see Sections);

   431     QCString	 m_type;        //!< member type 

   432     QCString	 m_name;        //!< member name

   433     TagInfo     *m_tagInfo;      //!< tag file info

   434     FileDef     *m_fileDef;

   435 

   436     Entry       *m_info;

   437     int64        m_offset;

   438     bool         m_noLoad;

   439 };

   440 

   441 

   442 typedef QList<Entry> EntryList;

   443 typedef QListIterator<Entry> EntryListIterator;

   444 

   445 typedef QList<EntryNav> EntryNavList;

   446 typedef QListIterator<EntryNav> EntryNavListIterator;

   447 

   448 #endif