X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/cde9f08e1f2bba81294708c1d65bb869ed744e56..cecfc5e7e54067ea099334a1fbce852ca69a6b11:/utils/HelpGen/include/srcparser.h diff --git a/utils/HelpGen/include/srcparser.h b/utils/HelpGen/include/srcparser.h new file mode 100644 index 0000000000..39ad1c3c25 --- /dev/null +++ b/utils/HelpGen/include/srcparser.h @@ -0,0 +1,736 @@ +///////////////////////////////////////////////////////////////////////////// +// 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 + + #ifdef WIN32 + #include + #else + + #include + #include + + #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 MMemberListT; + // comments list + typedef vector MCommentListT; + // list of parameters + typedef vector MParamListT; + // string list + typedef vector 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