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         #ifdef 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*             mName;
  93         int                     mType;
  94         int                     mOfs;
  95
  96         TVarInfo( const char* name, int ofs, int varType )
  97                 : mName(name),
  98                   mType( 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
 171         TVarListT mVars;
 172
 173         inline void PrintVar( TVarInfo*  pInfo,
 174                                                   void*       dataObj,
 175                                                   ScriptStream& stm );
 176
 177 public:
 178         ScriptTemplate( const string& templateText );
 179         virtual ~ScriptTemplate();
 180
 181         bool HasVar( const char* name );
 182
 183         // Member variables registration methods.
 184
 185         // NOTE:: GET_VAR_OFS() macro should be used
 186         // to get offset of the class member (see #define above)
 187         void AddStringVar ( const char* name, int ofs );
 188         void AddIntegerVar( const char* name, int ofs );
 189         void AddDoubleVar ( const char* name, int ofs );
 190
 191         void AddObjectRefArray( const char*     name,
 192                                                         int                         ofsRefToFirstObj,
 193                                     int                     ofsObjSizeInt,
 194                                                         int                         ofsObjRefTempl
 195                                                   );
 196
 197         // reads the script, replaces $(..) tags with values
 198         // of registered members of dataObj object, and outputs
 199         // the result to given text stream
 200
 201         void PrintScript( void* dataObj, ScriptStream& stm );
 202 };
 203
 204 class ScriptSection;
 205
 206 // class manages section and aggregated sections of
 207 // inter-linked documents
 208
 209 class ScriptSection
 210 {
 211 protected:
 212
 213         // NOTE:: "$(NAME)", $(ID), "$(BODY)" and "$(REFLIST)" aree
 214         //        reseved template variables of ScriptSection
 215
 216         // the below there members are registered to ScriptTemplate,
 217         // GUID within the section tree (numeric)
 218
 219         ScriptSection*  mpParent;
 220         string          mId;   // $(ID)
 221         string          mName; // $(NAME)
 222         string          mBody; // $(BODY)
 223
 224         // NULL, if this section is not aggregated anywhere
 225
 226         SectListT       mSubsections; // aggregated sectons
 227         SectListT       mReferences;  // registered as $(REFLIST)
 228
 229         bool            mAutoHide;  // see autoHide arg, in constructor
 230         bool            mSortOn;    // TRUE, if sort subsectons by naem
 231
 232         // tempalte for this section
 233         ScriptTemplate* mpSectTempl;
 234
 235         // template used for links (or references) to this section
 236         ScriptTemplate* mpRefTempl;
 237
 238         // do not call destructor of this object,
 239         // call RemoveRef() instead
 240         int             mRefCount;
 241
 242         static int      mIdCounter;  // generator of GUIDs
 243
 244         // fields registered and used by ScriptTemplate object
 245         void*           mRefFirst;
 246         int             mArrSize;
 247
 248 protected:
 249         virtual void AddRef();
 250         virtual void RemoveRef();
 251         void DoRemoveEmptySections(int& nRemoved, SectListT& removedLst);
 252         void DoRemoveDeadLinks( SectListT& removedLst);
 253
 254 public:
 255
 256         // NOTE:: pass NULL to certain template, if your sure
 257         //        this kind of template will never be used,
 258         //        e.g. if section is contained but never referrenced,
 259         //        then pReferenceTemplate can be NULL
 260
 261         // if autoHide option is TRUE, the section will be automatically
 262         // collapsed (not shown) if it doesn't contain any references
 263         // to other sections (e.g. could be usefull for autoamically
 264         // hiding empty index-sections).
 265
 266         ScriptSection( const string&   name = "",
 267                                    const string&   body = "",
 268                                    ScriptTemplate* pSectionTemplate   = NULL,
 269                                    ScriptTemplate* pReferenceTemplate = NULL,
 270                                    bool            autoHide           = FALSE,
 271                                    bool            sorted             = FALSE
 272                                  );
 273
 274         // calls RemoveRef() to all aggreagated sections first,
 275         // then to all referenced section - this way all
 276         // sections (even not aggregated ones) become "garbage-collected"
 277
 278         // NOTE:: do not call destructor directlly, call RemoveRef()
 279         //        instead
 280         virtual ~ScriptSection();
 281
 282
 283         // if addToReferencesToo is TRUE, section is aggregated and
 284         // also added to reference list of this section
 285
 286         void AddSection( ScriptSection* pSection, bool addToReferencesToo = FALSE );
 287
 288         // add cross-reference to this given section
 289         void AddReference( ScriptSection* pReferredSection );
 290
 291         // subsection may be given of variable depth level,
 292         // e.g. "publications/reviews/software"
 293
 294         ScriptSection* GetSubsection( const char* name );
 295
 296         // returns list aggregated sections
 297         SectListT& GetSubsections();
 298
 299         // binds reserved template names ( $(..) ) to member
 300         // vairalbes in the ScriptSection class, should be called
 301         // to initialize each user-code provided script template
 302
 303         static void RegisterTemplate( ScriptTemplate& sectionTempalte );
 304
 305         // prints out section tree to the stream, starting from
 306         // this section as a root node
 307         virtual void Print( ScriptStream& stm );
 308
 309         // searches empty sections which has autoHide == TRUE,
 310         // and colapses them (this method should be called )
 311         // on the root-section of the sections tree
 312
 313         // NOTE:: does not work properly, yet!
 314         void RemoveEmptySections();
 315 };
 316
 317 // base class for documnetation generators
 318 // (allows user code set up target script type,
 319 //  independently of documentation type)
 320
 321 class DocGeneratorBase
 322 {
 323 protected:
 324         MarkupTagsT    mTags;
 325
 326         // override this method to do some post processing
 327         // after generation of document, or even write some
 328         // data into output stream, before the section tree
 329         // is flushed into it.
 330
 331         // return FALSE, if something has gone wrong and
 332         // document cannot be saved now
 333
 334         virtual bool OnSaveDocument( ScriptStream& WXUNUSED(stm) )
 335                 { return 1; }
 336
 337         // override this method to provide reference to
 338         // the top section of the document (used as default
 339         // starting section when saving a document)
 340
 341         virtual ScriptSection* GetTopSection()
 342                 { return 0; }
 343
 344 public:
 345
 346         DocGeneratorBase()
 347                 : mTags(0) // no defaul script
 348         {}
 349
 350         // dectrouctors of polymorphic classes SHOULD be virtual
 351         virtual ~DocGeneratorBase() {}
 352
 353         // returns tags, being used for specific target script
 354         MarkupTagsT GetScriptMarkupTags() { return mTags; }
 355
 356         // sets tag array for specific script
 357
 358         // NOTE:: Why virtual? since approach with MarkupTagsT is
 359         //        "flowless" only in theory. Overriding this method
 360         //        allows document generators to check the type of the
 361         //        target script, and perhaps make some modifications
 362         //        to generator's tamplates, to match the specific script
 363
 364         virtual void SetScriptMarkupTags( MarkupTagsT tags )
 365                 { mTags = tags; }
 366
 367         // seves document to file starting from the root-node of
 368         // the document (provided by GetTopSection() method),
 369         // or from "pFromSection" if it's not NULL.
 370
 371         // fopenOptions arg. is string passed to fopen() method,
 372         // returns TRUE, if saving was successfull
 373
 374         virtual bool SaveDocument( const char*    fname,
 375                                                            const char*    fopenOptions = "w",
 376                                                            ScriptSection* pFromSection = NULL
 377                                                            );
 378
 379 };
 380
 381 #endif