[wxWidgets.git] / utils / HelpGen / include / srcparser.h

/////////////////////////////////////////////////////////////////////////////
// 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$
// 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"

        // FOR NOW:: quick n' dirty:

        #define  string wxString

#endif

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

// 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_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;
        // string list
        typedef vector<string>     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(string)          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& fl ) {}

        virtual void VisitNameSpace( spNameSpace& ns ) {}   

        virtual void VisitClass( spClass& cl ) {}

        virtual void VisitEnumeration( spEnumeration& en ) {}

        virtual void VisitTypeDef( spTypeDef& td ) {}

        virtual void VisitPreprocessorLine( spPreprocessorLine& pd ) {}

        virtual void VisitAttribute( spAttribute& attr ) {}

        virtual void VisitOperation( spOperation& op ) {}

        virtual void VisitParameter( spParameter& param ) {}

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

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

class spComment
{
public:
        string mText;
        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;

        string& GetText();

        // contstant version of GetText()
        string  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*    mpParent; 

        // 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)
        string       mVirtualContextBody;
        string       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)
        string        mName;    

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 string& body, 
                                                            bool  hasChildren = FALSE,
                                                        const string& footer = "" );

        string GetVirtualContextBody();
        string 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 string GetBody( spContext* pCtx = NULL );

        virtual string GetHeader( spContext* pCtx = NULL );

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

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

        // returns identifier of this context
        inline string& GetName() { return mName; }

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

        // see comments on mpFirstOccurence member variable
        bool IsFirstOccurence();
        spContext* GetFirstOccurence();

        // returns not-NULL value if this context
        // is aggregated by another cotnext
        spContext* GetOutterContext();

        // perhaps more intuitive alias for `GetOutterContext()'
        inline spContext* GetParent() { return mpParent; }

        bool HasOutterContext();

        // add one aggregate (or child) into this context
        void AddMember ( spContext* pMember );
        MMemberListT& GetMembers();

        // append comment to the comment list decribing
        // this context
        void AddComment( spComment* pComment );

        // returns NULL, if the context with the given
        // name and type is not contained by this context
        // and it's children. Children's children are not
        // searched recursivelly if searchSubMembers is FALSE

        spContext* FindContext( const string& identifier,
                                    int   contextType      = SP_CTX_ANY,
                                                        bool  searchSubMembers = TRUE
                                  );

        // removes this context from it's parent
        // (NOTE:: context should have an outter cotnext
        //  to when this method is called, otherwise removal
        //  will result assertion failure)
        void RemoveThisContext();

        // returns TRUE, if this object is aggregated in the file
        bool IsInFile();

        // TRUE, if outter context is a namespace
        bool IsInNameSpace();

        // TRUE, if outter context is a class
        bool IsInClass();

        // TRUE, if outter cotext is an operation (TRUE for "spParameter"s)
        bool IsInOperation();

    // TRUE if the context is public
    bool IsPublic() const { return mVisibility == SP_VIS_PUBLIC; }

        // NOTE:: method returns not the type of this object
        //                but the file/namespace/class/operation or file in which this
        //                attribute is contained. First, check for the type of
        //        context using the above method. 
        
        //                Requiering container which does not exist, will result
        //        in assertion failure

        spClass&     GetClass(); 
        spFile&      GetFile();
        spNameSpace& GetNameSpace();
        spOperation& GetOperation();

        // each new context should override this method
        // to return it's specific type 
        virtual int GetContextType() { return SP_CTX_UNKNOWN; }

        // perhaps more intuitive short-cut
        inline int GetType() { return GetContextType(); }

        // derived classes override this to invoke VisitXXX method
        // which corresponds to the class of specific context,
        // - this is what the "Visitor" pattern told us ^)

        // if method is not overriden, then it's probably user-defined
        // custom context

        virtual void AcceptVisitor( spVisitor& visitor )
        
                { visitor.VisitCustomContext( *this );  };

        // called by visitors, to remove given subcontext 
        // of this context object
        void RemoveChild( spContext* pChild );

        void RemoveChildren();

        spContext* GetEnclosingContext( int mask = SP_CTX_ANY );
};

// stores information about single argument of operation

class spParameter : public spContext
{
public:
        // type of argument (parameter)
        string mType;

        // "stringified" initial value
        string mInitVal;

public:
        virtual int GetContextType() { return SP_CTX_PARAMETER; }

        virtual void AcceptVisitor( spVisitor& visitor ) 
                { visitor.VisitParameter( *this ); }
};


// stores information about member(or global) variable

class spAttribute : public spContext
{
public:
        // type of the attribute
        string mType;

        // it's initial value
        string mInitVal;

        // constantness
        bool   mIsConstant;
public:

        virtual int GetContextType() { return SP_CTX_ATTRIBUTE; }

        virtual void AcceptVisitor( spVisitor& visitor ) 
                { visitor.VisitAttribute( *this ); }
};

class spOperation : public spContext
{
public:
        // type of return value
        string      mRetType;

        // argument list
        //MParamListT mParams;

        // TRUE, if operation does not modify
        // the content of the object
        bool        mIsConstant;

        // flag, specific to C++
        bool        mIsVirtual;

        // TRUE, if definition follows the declaration immediatelly
        bool        mHasDefinition;

        // scope if any (e.g. MyClass::MyFunction(), scope stirng is "MyClass" )
        // usually found along with implementation of the method, which is now skipped

        string      mScope;

public:
        spOperation();

        // returns full declaration of the operations
        // (ret val., identifier, arg. list),

        // arguments are marked up with italic,
        // default values marked up with bold-italic,
        // all the rest is marked as bold

        // NOTE:: this method may be overriden by class
        //        specific to concrete parser, to provide
        //        language-dependent reperesnetation of
        //        operation and it's argumetn list
        //
        // the default implementation outputs name in
        // C++/Java syntax

        virtual string GetFullName(MarkupTagsT tags);

        virtual int GetContextType() { return SP_CTX_OPERATION; }

        virtual void AcceptVisitor( spVisitor& visitor ) 
                { visitor.VisitOperation( *this ); }

};

// stores infromation about preprocessor directive

class spPreprocessorLine : public spContext 
{

public:

        // prepocessor statement including '#' and
        // attached multiple lines with '\' character
        string mLine;               

        int    mDefType; // see SP_PREP_DEFINITION_TYPES enumeration 

public:

        virtual int GetContextType() { return SP_CTX_PREPROCESSOR; }

        virtual int GetStatementType() { return mDefType; }

        string CPP_GetIncludedFileNeme();

        virtual void AcceptVisitor( spVisitor& visitor ) 
                { visitor.VisitPreprocessorLine( *this ); }
};

// stores information about the class 

class spClass : public spContext
{
public:
        // list of superclasses/interfaces
        StrListT     mSuperClassNames;

        // see SP_CLASS_TYPES enumeration
        int          mClassSubType;    

        // see SP_INHERITANCE_TYPES enumeration
        int          mInheritanceType;

        // valid if mClassSubType is SP_CLTYPE_TEMPLATE_CLASS
        string       mTemplateTypes;

        // TRUE, if it's and interface of abstract base class
        bool         mIsAbstract;

public:

        // sorts class members in the following order:
        // 
        // (by "privacy level" - first private, than protected, public)
        //
        //     within above set
        //
        //       (by member type - attributes first, than methods, nested classes)
        //
        //          within above set
        //
        //             (by identifier of the member)
        
        virtual void SortMembers();

        virtual int GetContextType() { return SP_CTX_CLASS; }

        virtual void AcceptVisitor( spVisitor& visitor ) 
                { visitor.VisitClass( *this ); }
};

// stores information about enum statement

class spEnumeration  : public spContext
{
public:
        string mEnumContent; // full-text content of enumeration

public:
        virtual int GetContextType() { return SP_CTX_ENUMERATION; }

        virtual void AcceptVisitor( spVisitor& visitor ) 
                { visitor.VisitEnumeration( *this ); }
};

class spTypeDef  : public spContext
{
public:
        // the original type which is redefined
        // by this type definition
        string mOriginalType;

public:
        virtual int GetContextType() { return SP_CTX_TYPEDEF; }

        virtual void AcceptVisitor( spVisitor& visitor ) 
                { visitor.VisitTypeDef( *this ); }
};

// NOTE:: files context may be put to other
//        file context, resulting in a collection
//        of parsed file contexts, with a virtual "superfile"

class spFile : public spContext
{
public:
        // since file name cannot be determined from
        // source code, filling in this field is optional
        string mFileName; 

public:
        virtual int GetContextType() { return SP_CTX_FILE; }

        virtual void AcceptVisitor( spVisitor& visitor ) 
                { visitor.VisitFile( *this ); }
};

//TODO:: comments.

class SourceParserPlugin
{
public:
        virtual bool CanUnderstandContext( char* cur, char* end, spContext* pOuttterCtx ) = 0;
        virtual void ParseContext( char* start, char*& cur, char* end, spContext* pOuttterCtx ) = 0;
};

// abstract interface for source parsers
// which can output parsing results in the
// form of context-tree, where each node
// should be derivative of spContext, (see
// above classes)

class SourceParserBase 
{
private:
        // auto-resizing file buffer, created in ParseFile()
        // to reuse large heap block for multiple parsings
        
        char* mpFileBuf; 
        int   mFileBufSz;

protected:
        SourceParserPlugin* mpPlugin;
                 
protected:
        // value is set in the derived parser classes
        int mParserStatus;

public:
        SourceParserBase();
        virtual ~SourceParserBase();

        // loads entier source file(as text) into memory,
        // and passes it's contents to ParseAll() method,
        // memory occupied by source text is released after
        // parsing is done
        //
        // (NOTE:: this is the default implementation),

        virtual spFile* ParseFile( const char* fname );

        // should returns the root-node of the created context tree
        // (user is responsible for releasing it from the heep)
        // "end" should point to the (last character + 1) of the 
        // source text area

        virtual spFile* Parse( char* start, char* end ) = 0;

        // returns parser "status word" (specific to concrete parser)
        int GetParserStatus() { return mParserStatus; }

        void SetPlugin( SourceParserPlugin* pPlugin );
};

#endif