srcparser.h

wxGTK 是 wxWidgets 的 linux GTK+ (>2.2.3)版本。wxWidgets 是一个跨平台的 GUI 框架

/////////////////////////////////////////////////////////////////////////////
// Name:        No names yet.
// Purpose:     To provide a simple _framework_
//              for series of source code parsers with
//              compatible interfaces
// Author:      Aleksandras Gluchovas
// Modified by: AG on 28/12/98
// Created:     22/09/98
// RCS-ID:      $Id: srcparser.h,v 1.15 2006/10/08 14:34:37 VZ Exp $
// Copyright:   (c) Aleskandars Gluchovas
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

#ifndef __SRCPARSER_G__
#define __SRCPARSER_G__

#if defined( wxUSE_TEMPLATE_STL )
    #include <vector>

    #ifdef WIN32
    #include <bstring.h>
    #else

    #include <strclass.h>
    #include <string.h>

    #endif

#else
    #include "wx/string.h"
    #include "wxstlvec.h"

#endif

#include "markup.h" // markup tags used in spOperator::GetFullName()

// these methods are used for debugging only and disappear in the release build
#ifdef __WXDEBUG__
    #define DECLARE_DUMP virtual void DumpThis(const wxString& indent) const;
#else
    #define DECLARE_DUMP
#endif

// context class list in "inside-out" order :

class spContext;

class spParameter;
class spAttribute;
class spOperation;
class spEnumeration;
class spTypeDef;
class spPreprocessorLine;
class spClass;
class spNameSpace;
class spFile;

// source context visibilities
enum SRC_VISIBLITY_TYPES
{
    SP_VIS_PUBLIC,
    SP_VIS_PROTECTED,
    SP_VIS_PRIVATE
};

// class types
enum SP_CLASS_TYPES
{
    SP_CLTYPE_INVALID,
    SP_CLTYPE_CLASS,
    SP_CLTYPE_TEMPLATE_CLASS,
    SP_CLTYPE_STRUCTURE,
    SP_CLTYPE_UNION,
    SP_CLTYPE_INTERFACE
};

// inheritance types
enum SP_INHERITANCE_TYPES
{
    SP_INHERIT_VIRTUAL,
    SP_INHERIT_PUBLIC,
    SP_INHERIT_PRIVATE
};

// proprocessor definitions types (specific to C++ code)

enum SP_PREP_DEFINITION_TYPES
{
    SP_PREP_DEF_DEFINE_SYMBOL,
    SP_PREP_DEF_REDEFINE_SYMBOL,
    SP_PREP_DEF_INCLUDE_FILE,
    SP_PREP_DEF_OTHER
};

// common context types

#define SP_CTX_UNKNOWN       0x000
#define    SP_CTX_FILE          0x001
#define    SP_CTX_NAMESPACE     0x002
#define    SP_CTX_CLASS         0x004
#define SP_CTX_TYPEDEF       0x008
#define SP_CTX_PREPROCESSOR  0x010
#define SP_CTX_ENUMERATION   0x020
#define    SP_CTX_ATTRIBUTE     0x040
#define    SP_CTX_OPERATION     0x080
#define    SP_CTX_PARAMETER     0x100

// other (custom) context codes may be defined elsewere, however they should
// not clash with above codes for common type and also should not
// exceed 16-bits of in value

// masks all context types (up to 16 custom context can be defined)

#define SP_CTX_ANY           0xFFFF

class spComment;



#if defined( wxUSE_TEMPLATE_STL )

    // context members
    typedef vector<spContext*> MMemberListT;
    // comments list
    typedef vector<spComment*> MCommentListT;
    // list of parameters
    typedef vector<spParameter*> MParamListT;
    // wxString list
    typedef vector<wxString>   StrListT;

#else

    typedef spContext*   spContextPtrT;
    typedef spComment*   spCommentPtrT;
    typedef spParameter* spParameterPtrT;
    typedef WXSTL_VECTOR_SHALLOW_COPY(spContextPtrT)   MMemberListT;
    typedef WXSTL_VECTOR_SHALLOW_COPY(spCommentPtrT)   MCommentListT;
    typedef WXSTL_VECTOR_SHALLOW_COPY(spParameterPtrT) MParamListT;
    typedef WXSTL_VECTOR_SHALLOW_COPY(wxString)        StrListT;

#endif
// base class for all visitors of source code contents

class spVisitor
{
protected:
    bool mSiblingSkipped;
    bool mChildSkipped;
    int  mContextMask;

    spContext* mpCurCxt;

public:
    // methods invoked by context

    // method invoked from user's controling code
    // to visit all nodes staring at the given context.
    // Content is sorted if requrired, see comments
    // spClass on sorting the class members

    void VisitAll( spContext& atContext,
                   bool sortContent = true
                 );

    // methods invoked by visitor

    // goes to the next context in the outter scope
    // NOTE:: should not be invoked more than once while
    //        visiting certain context

    void SkipSiblings();

    // prevents going down into the contexts contained by
    // the current context
    // NOTE:: the same as above

    void SkipChildren();

    // can be called only in from visiting procedure
    void RemoveCurrentContext();

    // method enables fast filtered traversal
    // of source content, e.g. collecting only classes,
    // or only global functions

    // arg. context - can contain combination of contexts concatinated
    //           with bitwise OR, e.g. SP_CTX_CLASS | SP_CTX_NAMESPACE
    //
    // method can be invoked from the user's controling as well as
    // from within the visting procedure

    void SetFilter( int contextMask );

    // methods should be implemneted by specific visitor:

    // NOTE:: Do not confuse visiting with parsing, first
    //        the source is parsed, and than can be visited
    //        multiple times by variouse visitors (there can
    //        be more the one visitor visiting content at a time)

    virtual void VisitFile( spFile& WXUNUSED(fl) ) {}

    virtual void VisitNameSpace( spNameSpace& WXUNUSED(ns) ) {}

    virtual void VisitClass( spClass& WXUNUSED(cl) ) {}

    virtual void VisitEnumeration( spEnumeration& WXUNUSED(en) ) {}

    virtual void VisitTypeDef( spTypeDef& WXUNUSED(td) ) {}

    virtual void VisitPreprocessorLine( spPreprocessorLine& WXUNUSED(pd) ) {}

    virtual void VisitAttribute( spAttribute& WXUNUSED(attr) ) {}

    virtual void VisitOperation( spOperation& WXUNUSED(op) ) {}

    virtual void VisitParameter( spParameter& WXUNUSED(param) ) {}

    virtual void VisitCustomContext( spContext& WXUNUSED(ctx) ) {}

    virtual ~spVisitor() { }
};

// stores one section of comments,
// multiple sections can be put to geather
// and attached to some context

class spComment
{
public:
    wxString  m_Text;
    bool      mIsMultiline; // multiline comments ar those with /**/'s

    // true, if these was an empty empty
    // line above single line comment

    bool      mStartsPar;

public:

    bool      IsMultiline() const;
    bool      StartsParagraph() const;

    wxString& GetText();

    // contstant version of GetText()
    wxString  GetText() const;
};

// abstract base class for common (to most languages) code
// contexts (constructs), e.g file, namespace, class, operation,
// etc

class spContext
{
protected:
    // "linked" list of comments belonging to this context
    MCommentListT mComments;

    // NULL, if this is file context
    MMemberListT   mMembers;

    // NULL, if this is top-most context
    spContext*    m_pParent;

    // points to context object, where the this context
    // was originally declared, meaning that this object
    // is redeclaration (or if in the case of operation
    // this context object most probably referres to the
    // implemnetation in .cpp file for example)

    // is NULL, if this object referres to the first occurence
    // of the context

    spContext*    mpFirstOccurence;

    // used, to avoid excessive sorting of context's agreggates
    bool          mAlreadySorted;

public:

    // source line number, (-1) if unknown
    int           mSrcLineNo;

    // offset of context in the source file, (-1) if unknown
    int           mSrcOffset;

    // lentgh of the context in characters, (-1) if unknown
    int           mContextLength;

    // source line number, in which this cotext ends, (-1) if unknown
    int           mLastScrLineNo;

    // fields are valid, if the may contain other contexts nested inside
    int           mHeaderLength;
    int           mFooterLength;

    // zero-based index of the first character of
    // this context in the source line, (-1) if unknown
    int           mFirstCharPos;

    // zero-based index of the first character of
    // this context in the last source line of this context, (-1) if unknown
    int           mLastCharPos;

    // see SRC_VISIBLITY_TYPES enumeration
    int           mVisibility;

    // true, if context does not really exist in the source
    //       but was created by external tools (e.g. forward engineering)

    bool         mIsVirtualContext;
    bool         mVirtualContextHasChildren;

    // body of the context in case (mIsVirtual == true)
    wxString     mVirtualContextBody;
    wxString     mVittualContextFooter;

    // e.g. can be used by documentation generator to store
    // reference to section object
    void*         mpUserData;

public:
    // universal identifier of the context (e.g. class name)
    wxString      m_Name;

public:
    // default constructor
    spContext();

    // automatically destorys all aggregated contexts
    // (thus, it's enought to call destructor of root-context)
    virtual ~spContext();

    // see mUererData member;
    void* GetUserData() { return mpUserData; }

    // sets untyped pointer to user data
    void SetUserData( void* pUserData )
        { mpUserData = pUserData; }

    // searches the whole context tree for the cotnexts
    // which match given masks, pust results into lst array
    void GetContextList( MMemberListT& lst, int contextMask );

    // used by default visitor's implementation
    bool IsSorted();

    /*** forward/reverse ingineering fecilities ***/

    bool PositionIsKnown();

    bool IsVirtualContext();

    bool VitualContextHasChildren();

    void SetVirtualContextBody( const wxString& body,
                                bool  hasChildren = false,
                                const wxString& footer = wxEmptyString );

    wxString GetVirtualContextBody();
    wxString GetFooterOfVirtualContextBody();

    // can be overriden by top-level context classes
    // to find-out ot the source-fragment of this
    // context using it's position information
    virtual wxString GetBody( spContext* pCtx = NULL );

    virtual wxString GetHeader( spContext* pCtx = NULL );

    // true, if there is at least one entry
    // in the comment list of this context
    bool HasComments();
    MCommentListT& GetCommentList() { return mComments; }
    const MCommentListT& GetCommentList() const { return mComments; }

    // should be overriden, if the context supports sorting
    // of it's members
    virtual void SortMembers() {}

    // returns identifier of this context
    inline wxString& GetName() { return m_Name; }

    // returns -1, if souce line # is unknow
    inline int GetSourceLineNo() { return mSrcLineNo; }