definition.h

/******************************************************************************
 *
 * 
 *
 * Copyright (C) 1997-2015 by Dimitri van Heesch.
 *
 * 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.
 *
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 */

#ifndef DEFINITION_H
#define DEFINITION_H

#include <qlist.h>
#include <qdict.h>

#include "types.h"

class FileDef;
class OutputList;
class SectionDict;
class MemberSDict;
class MemberDef;
class GroupDef;
class GroupList;
struct ListItemInfo;
struct SectionInfo;
class Definition;
class DefinitionImpl;
class FTextStream;
  
struct DocInfo
{
    QCString doc;  
    int      line;
    QCString file;
};

struct BriefInfo
{
    QCString doc;  
    QCString tooltip;  
    int      line;
    QCString file;
};

struct BodyInfo
{
    int      startLine;   
    int      endLine;     
    FileDef *fileDef;     
};
    
class DefinitionIntf
{
  public:
    DefinitionIntf() {}
    virtual ~DefinitionIntf() {}
    enum DefType 
    { 
      TypeClass      = 0, 
      TypeFile       = 1, 
      TypeNamespace  = 2, 
      TypeMember     = 3, 
      TypeGroup      = 4, 
      TypePackage    = 5, 
      TypePage       = 6, 
      TypeDir        = 7, 
      TypeSymbolList = 8
    };
    virtual DefType definitionType() const = 0;
};

class Definition : public DefinitionIntf
{
  public:
    struct Cookie
    {
      virtual ~Cookie() {}
    };

    Definition(
        const char *defFileName,int defLine,int defColumn,
        const char *name,const char *b=0,const char *d=0,
        bool isSymbol=TRUE);

    virtual ~Definition();

    //-----------------------------------------------------------------------------------
    // ----  getters -----
    //-----------------------------------------------------------------------------------

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

    virtual QCString displayName(bool includeScope=TRUE) const = 0;

    QCString localName() const;

    virtual QCString qualifiedName() const;

    QCString symbolName() const;

    virtual QCString getOutputFileBase() const = 0;

    virtual QCString anchor() const = 0;

    virtual QCString getSourceFileBase() const;

    virtual QCString getSourceAnchor() const;

    virtual QCString documentation() const;

    int docLine() const;

    QCString docFile() const;

    virtual QCString briefDescription(bool abbreviate=FALSE) const;

    QCString briefDescriptionAsTooltip() const;

    int briefLine() const;

    QCString inbodyDocumentation() const;

    QCString inbodyFile() const;

    int inbodyLine() const;

    QCString briefFile() const;

    QCString getDefFileName() const;

    QCString getDefFileExtension() const;

    int getDefLine() const { return m_defLine; }

    int getDefColumn() const { return m_defColumn; }

    virtual bool hasDocumentation() const;

    virtual bool hasUserDocumentation() const;

    virtual bool isLinkableInProject() const = 0;

    virtual bool isLinkable() const = 0;

    virtual bool isVisibleInProject() const;

    virtual bool isVisible() const;

    bool isHidden() const;

    bool isArtificial() const;

    virtual QCString getReference() const;

    virtual bool isReference() const;

    QCString externalReference(const QCString &relPath) const;

    int getStartBodyLine() const;

    int getEndBodyLine() const;

    FileDef *getBodyDef() const;

    SrcLangExt getLanguage() const;

    GroupList *partOfGroups() const;
    bool isLinkableViaGroup() const;

    QList<ListItemInfo> *xrefListItems() const;

    virtual Definition *findInnerCompound(const char *name);
    virtual Definition *getOuterScope() const;

    MemberSDict *getReferencesMembers() const;
    MemberSDict *getReferencedByMembers() const;

    bool hasSections() const;
    bool hasSources() const;

    bool hasBriefDescription() const;

    QCString id() const;

    //-----------------------------------------------------------------------------------
    // ----  setters -----
    //-----------------------------------------------------------------------------------

    virtual void setName(const char *name);

    void setId(const char *name);

    virtual void setDocumentation(const char *d,const char *docFile,int docLine,bool stripWhiteSpace=TRUE);

    virtual void setBriefDescription(const char *b,const char *briefFile,int briefLine);

    virtual void setInbodyDocumentation(const char *d,const char *docFile,int docLine);

    void setReference(const char *r);

    void addSectionsToDefinition(QList<SectionInfo> *anchorList);

    // source references
    void setBodySegment(int bls,int ble);
    void setBodyDef(FileDef *fd);
    void addSourceReferencedBy(MemberDef *d);
    void addSourceReferences(MemberDef *d);

    void setRefItems(const QList<ListItemInfo> *sli);
    void mergeRefItems(Definition *d);
    virtual void addInnerCompound(Definition *d);
    virtual void setOuterScope(Definition *d);

    virtual void setHidden(bool b);

    void setArtificial(bool b);
    void setLanguage(SrcLangExt lang);

    //-----------------------------------------------------------------------------------
    // --- actions ----
    //-----------------------------------------------------------------------------------

    void writeSourceDef(OutputList &ol,const char *scopeName);
    void writeInlineCode(OutputList &ol,const char *scopeName);
    void writeSourceRefs(OutputList &ol,const char *scopeName);
    void writeSourceReffedBy(OutputList &ol,const char *scopeName);
    void makePartOfGroup(GroupDef *gd);
    //void writePathFragment(OutputList &ol) const;
    void writeNavigationPath(OutputList &ol) const;
    QCString navigationPathAsString() const;
    virtual void writeQuickMemberLinks(OutputList &,MemberDef *) const {}
    virtual void writeSummaryLinks(OutputList &) {}
    QCString pathFragment() const;

    void writeDocAnchorsToTagFile(FTextStream &);
    void setLocalName(const QCString name);

    void addSectionsToIndex();
    void writeToc(OutputList &ol);

    void setCookie(Cookie *cookie) { delete m_cookie; m_cookie = cookie; }
    Cookie *cookie() const { return m_cookie; }

  protected:

    Definition(const Definition &d);

  private: 
    static void addToMap(const char *name,Definition *d);
    static void removeFromMap(Definition *d);

    void _setSymbolName(const QCString &name);

    int  _getXRefListId(const char *listName) const;
    void _writeSourceRefList(OutputList &ol,const char *scopeName,
                       const QCString &text,MemberSDict *members,bool);
    void _setBriefDescription(const char *b,const char *briefFile,int briefLine);
    void _setDocumentation(const char *d,const char *docFile,int docLine,bool stripWhiteSpace,bool atTop);
    void _setInbodyDocumentation(const char *d,const char *docFile,int docLine);
    bool _docsAlreadyAdded(const QCString &doc,QCString &sigList);
    DefinitionImpl *m_impl; // internal structure holding all private data
    QCString m_name;
    bool m_isSymbol;
    QCString m_symbolName;
    int m_defLine;
    int m_defColumn;
    Cookie *m_cookie;
};

class DefinitionList : public QList<Definition>, public DefinitionIntf
{
  public:
    ~DefinitionList() {}
    DefType definitionType() const { return TypeSymbolList; }
    int compareValues(const Definition *item1,const Definition *item2) const
    {
      return qstricmp(item1->name(),item2->name());
    }

};

class DefinitionListIterator : public QListIterator<Definition>
{
  public:
    DefinitionListIterator(const DefinitionList &l) :
      QListIterator<Definition>(l) {}
    ~DefinitionListIterator() {}
};

bool readCodeFragment(const char *fileName, 
                      int &startLine,int &endLine,
                      QCString &result);
#endif