Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

HelpGen is a prototype of the tool for automatic generation of the .tex files

Browse Source 
for wxWindows documentation from C++ headers


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1347 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
1999-01-08 17:46:08 +00:00
parent cde9f08e1f
commit cecfc5e7e5
21 changed files with 10005 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

736
utils/HelpGen/include/srcparser.h Normal file
View File

@@ -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 <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