utils/HelpGen/src/scriptbinder.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        No names yet.
   3 // Purpose:     Contrib. demo
   4 // Author:      Aleksandras Gluchovas
   5 // Modified by:
   6 // Created:     22/09/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Aleskandars Gluchovas
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef __SCRIPTBINDER_G__
  13 #define __SCRIPTBINDER_G__
  14
  15 #if defined( wxUSE_TEMPLATE_STL )
  16
  17     #include <vector>
  18
  19     #ifdef WIN32
  20         #include <bstring.h>
  21     #else
  22         #include <strclass.h>
  23         #include <string.h>
  24     #endif
  25
  26 #else
  27
  28     #include "wxstlvec.h"
  29     #include "wx/string.h"
  30
  31     #if wxUSE_STD_STRING
  32         using std::string;
  33     #else
  34         // FIXME:: dirty!
  35         typedef wxString string;
  36     #endif
  37
  38 #endif
  39
  40 #ifndef ASSERT
  41 // assert yourself
  42 #define ASSERT(x) if (!(x) ) throw;
  43 #endif
  44
  45 #include "markup.h"
  46
  47 // just another portable stream class...
  48
  49 class ScriptStream
  50 {
  51 protected:
  52     char*  mpBuf;
  53     size_t mSize;
  54     size_t mCapacity;
  55 public:
  56     ScriptStream();
  57     ~ScriptStream();
  58
  59     void WriteBytes( const void* srcBuf, size_t count );
  60
  61     ScriptStream& operator<<( const char* str );
  62     ScriptStream& operator<<( const string& str );
  63     ScriptStream& operator<<( char ch );
  64
  65     void endl();
  66
  67     inline char*  GetBuf() { return mpBuf; }
  68     inline size_t GetBufSize() { return mSize; }
  69
  70     // clears current contents of the stream
  71     void Reset() { mSize = 0; }
  72 };
  73
  74
  75 class ScriptTemplate;
  76
  77 // used internally by ScriptTemplate
  78
  79 enum TEMPLATE_VARIABLE_TYPES
  80 {
  81     TVAR_INTEGER,
  82     TVAR_STRING,
  83     TVAR_DOUBLE,
  84     TVAR_REF_ARRAY
  85 };
  86
  87 // helper structures used only by ScriptTemplate
  88
  89 struct TVarInfo
  90 {
  91 public:
  92     const char*     m_Name;
  93     int             m_Type;
  94     int             mOfs;
  95
  96     TVarInfo( const char* name, int ofs, int varType )
  97         : m_Name(name),
  98           m_Type( varType ),
  99           mOfs( ofs )
 100     {}
 101 };
 102
 103 struct TArrayInfo : public TVarInfo
 104 {
 105 public:
 106     int mRefOfs;
 107     int mSizeIntOfs;
 108     int mObjRefTemplOfs;
 109
 110     TArrayInfo( const char* name )
 111         : TVarInfo( name, 0, TVAR_REF_ARRAY )
 112     {}
 113 };
 114
 115 // stores offset of the given member (of the given class)
 116 // to (*pOfs), though the use of template classes would have
 117 // solved this problem in much clearer fashion
 118
 119 // FOR NOW:: obtaining physical offset of class member
 120 //           does not appeare to be protable across compilers?
 121 // FIXME::   +/- 1 problem
 122
 123 #ifdef __UNIX__
 124     #define WEIRD_OFFSET 1
 125 #else
 126     #define WEIRD_OFFSET 0
 127
 128 #endif
 129
 130 #define GET_VAR_OFS( className, varName, pOfs )          \
 131     {                                                    \
 132         int* className::* varPtr;                        \
 133         varPtr = (int* className::*)&className::varName; \
 134                                                          \
 135         (*pOfs) = int(*(int*)&varPtr)-WEIRD_OFFSET;      \
 136     }
 137
 138 class ScriptSection;
 139
 140 #if defined( wxUSE_TEMPLATE_STL )
 141
 142     typedef vector<TVarInfo*> TVarListT;
 143
 144     // container class for sections
 145     typedef vector<ScriptSection*> SectListT;
 146
 147 #else
 148
 149     typedef TVarInfo*      TVarInfoPtrT;
 150     typedef ScriptSection* ScriptSectionPtrT;
 151
 152     typedef WXSTL_VECTOR_SHALLOW_COPY(TVarInfoPtrT) TVarListT;
 153
 154     // container class for sections
 155     typedef WXSTL_VECTOR_SHALLOW_COPY(ScriptSectionPtrT) SectListT;
 156
 157 #endif
 158
 159 // class performs preprocessing of arbitrary scripts,
 160 // replaces identifiers enclosed in $(..) tag, whith
 161 // values of the corresponding class member variables
 162
 163 class ScriptTemplate
 164 {
 165 protected:
 166     // do not use string object here - parsing of
 167     // C string can be much faster (in debug v.)
 168     char*     mTText;
 169
 170     TVarListT mVars;
 171
 172     inline void PrintVar( TVarInfo*     pInfo,
 173                           void*         dataObj,
 174                           ScriptStream& stm );
 175
 176 public:
 177     ScriptTemplate( const string& templateText );
 178     virtual ~ScriptTemplate();
 179
 180     bool HasVar( const char* name );
 181
 182     // Member variables registration methods.
 183
 184     // NOTE:: GET_VAR_OFS() macro should be used
 185     // to get offset of the class member (see #define above)
 186     void AddStringVar ( const char* name, int ofs );
 187     void AddIntegerVar( const char* name, int ofs );
 188     void AddDoubleVar ( const char* name, int ofs );
 189
 190     void AddObjectRefArray( const char*     name,
 191                             int             ofsRefToFirstObj,
 192                             int             ofsObjSizeInt,
 193                             int             ofsObjRefTempl
 194                           );
 195
 196     // reads the script, replaces $(..) tags with values
 197     // of registered members of dataObj object, and outputs
 198     // the result to given text stream
 199
 200     void PrintScript( void* dataObj, ScriptStream& stm );
 201 };
 202
 203 class ScriptSection;
 204
 205 // class manages section and aggregated sections of
 206 // inter-linked documents
 207
 208 class ScriptSection
 209 {
 210 protected:
 211
 212     // NOTE:: "$(NAME)", $(ID), "$(BODY)" and "$(REFLIST)" are
 213     //        reseved template variables of ScriptSection
 214
 215     // the below there members are registered to ScriptTemplate,
 216     // GUID within the section tree (numeric)
 217
 218     ScriptSection*  mpParent;
 219     string          mId;   // $(ID)
 220     string          m_Name;// $(NAME)
 221     string          mBody; // $(BODY)
 222
 223     // NULL, if this section is not aggregated anywhere
 224
 225     SectListT       mSubsections; // aggregated sectons
 226     SectListT       mReferences;  // registered as $(REFLIST)
 227
 228     bool            mAutoHide;  // see autoHide arg, in constructor
 229     bool            mSortOn;    // true, if sort subsectons by naem
 230
 231     // tempalte for this section
 232     ScriptTemplate* mpSectTempl;
 233
 234     // template used for links (or references) to this section
 235     ScriptTemplate* mpRefTempl;
 236
 237     // do not call destructor of this object,
 238     // call RemoveRef() instead
 239     int             mRefCount;
 240
 241     static int      mIdCounter;  // generator of GUIDs
 242
 243     // fields registered and used by ScriptTemplate object
 244     void*           mRefFirst;
 245     int             mArrSize;
 246
 247 protected:
 248     virtual void AddRef();
 249     virtual void RemoveRef();
 250     void DoRemoveEmptySections(int& nRemoved, SectListT& removedLst);
 251     void DoRemoveDeadLinks( SectListT& removedLst);
 252
 253 public:
 254
 255     // NOTE:: pass NULL to certain template, if your sure
 256     //        this kind of template will never be used,
 257     //        e.g. if section is contained but never referrenced,
 258     //        then pReferenceTemplate can be NULL
 259
 260     // if autoHide option is true, the section will be automatically
 261     // collapsed (not shown) if it doesn't contain any references
 262     // to other sections (e.g. could be usefull for autoamically
 263     // hiding empty index-sections).
 264
 265     ScriptSection( const wxString& name = wxEmptyString,
 266                    const wxString& body = wxEmptyString,
 267                    ScriptTemplate* pSectionTemplate   = NULL,
 268                    ScriptTemplate* pReferenceTemplate = NULL,
 269                    bool            autoHide           = false,
 270                    bool            sorted             = false
 271                  );
 272
 273     // calls RemoveRef() to all aggreagated sections first,
 274     // then to all referenced section - this way all
 275     // sections (even not aggregated ones) become "garbage-collected"
 276
 277     // NOTE:: do not call destructor directlly, call RemoveRef()
 278     //        instead
 279     virtual ~ScriptSection();
 280
 281
 282     // if addToReferencesToo is true, section is aggregated and
 283     // also added to reference list of this section
 284
 285     void AddSection( ScriptSection* pSection, bool addToReferencesToo = false );
 286
 287     // add cross-reference to this given section
 288     void AddReference( ScriptSection* pReferredSection );
 289
 290     // subsection may be given of variable depth level,
 291     // e.g. "publications/reviews/software"
 292
 293     ScriptSection* GetSubsection( const char* name );
 294
 295     // returns list aggregated sections
 296     SectListT& GetSubsections();
 297
 298     // binds reserved template names ( $(..) ) to member
 299     // vairalbes in the ScriptSection class, should be called
 300     // to initialize each user-code provided script template
 301
 302     static void RegisterTemplate( ScriptTemplate& sectionTempalte );
 303
 304     // prints out section tree to the stream, starting from
 305     // this section as a root node
 306     virtual void Print( ScriptStream& stm );
 307
 308     // searches empty sections which has autoHide == true,
 309     // and colapses them (this method should be called )
 310     // on the root-section of the sections tree
 311
 312     // NOTE:: does not work properly, yet!
 313     void RemoveEmptySections();
 314 };
 315
 316 // base class for documnetation generators
 317 // (allows user code set up target script type,
 318 //  independently of documentation type)
 319
 320 class DocGeneratorBase
 321 {
 322 protected:
 323     MarkupTagsT    mTags;
 324
 325     // override this method to do some post processing
 326     // after generation of document, or even write some
 327     // data into output stream, before the section tree
 328     // is flushed into it.
 329
 330     // return false, if something has gone wrong and
 331     // document cannot be saved now
 332
 333     virtual bool OnSaveDocument( ScriptStream& WXUNUSED(stm) )
 334         { return 1; }
 335
 336     // override this method to provide reference to
 337     // the top section of the document (used as default
 338     // starting section when saving a document)
 339
 340     virtual ScriptSection* GetTopSection()
 341         { return 0; }
 342
 343 public:
 344
 345     DocGeneratorBase()
 346         : mTags(0) // no defaul script
 347     {}
 348
 349     // dectrouctors of polymorphic classes SHOULD be virtual
 350     virtual ~DocGeneratorBase() {}
 351
 352     // returns tags, being used for specific target script
 353     MarkupTagsT GetScriptMarkupTags() { return mTags; }
 354
 355     // sets tag array for specific script
 356
 357     // NOTE:: Why virtual? since approach with MarkupTagsT is
 358     //        "flowless" only in theory. Overriding this method
 359     //        allows document generators to check the type of the
 360     //        target script, and perhaps make some modifications
 361     //        to generator's tamplates, to match the specific script
 362
 363     virtual void SetScriptMarkupTags( MarkupTagsT tags )
 364         { mTags = tags; }
 365
 366     // seves document to file starting from the root-node of
 367     // the document (provided by GetTopSection() method),
 368     // or from "pFromSection" if it's not NULL.
 369
 370     // fopenOptions arg. is string passed to fopen() method,
 371     // returns true, if saving was successful
 372
 373     virtual bool SaveDocument( const char*    fname,
 374                                const char*    fopenOptions = "w",
 375                                ScriptSection* pFromSection = NULL
 376                              );
 377
 378 };
 379
 380 #endif