utils/HelpGen/src/HelpGen.cpp

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        HelpGen.cpp
   3 // Purpose:     Main program file for HelpGen
   4 // Author:      Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   5 // Modified by:
   6 // Created:     06/01/99
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1999 VZ
   9 // Licence:     GPL
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 /*
  13    TODO (+ means fixed)
  14
  15    (i) small fixes in the current version
  16
  17    +1. Quote special TeX characters like '&' and '_' (=> derive from wxFile)
  18     2. Document typedefs
  19     3. Document global variables
  20     4. Document #defines
  21
  22    (ii) plans for version 2
  23     1. Use wxTextFile for direct file access to avoid one scan method problems
  24
  25 */
  26
  27 // =============================================================================
  28 // declarations
  29 // =============================================================================
  30
  31 // -----------------------------------------------------------------------------
  32 // headers
  33 // -----------------------------------------------------------------------------
  34
  35 // wxWindows
  36 #include "wx/wxprec.h"
  37
  38 #ifndef WX_PRECOMP
  39     #include <wx/string.h>
  40     #include <wx/log.h>
  41     #include <wx/file.h>
  42 #endif // WX_PRECOMP
  43
  44 // C++ parsing classes
  45 #include "cjparser.h"
  46
  47 // standard headers
  48 #include <stdio.h>
  49 #include <time.h>
  50
  51 // -----------------------------------------------------------------------------
  52 // private functions
  53 // -----------------------------------------------------------------------------
  54
  55 // return the label for the given function name
  56 static wxString MakeLabel(const char *classname, const char *funcname);
  57
  58 // quotes special TeX characters in place
  59 static void TeXFilter(wxString* str);
  60
  61 // -----------------------------------------------------------------------------
  62 // private classes
  63 // -----------------------------------------------------------------------------
  64
  65 // add a function which sanitazes the string before writing it to the file
  66 class wxTeXFile : public wxFile
  67 {
  68 public:
  69     wxTeXFile() : wxFile() { }
  70
  71     bool WriteTeX(const wxString& s)
  72     {
  73         wxString t(s);
  74         TeXFilter(&t);
  75
  76         return wxFile::Write(t);
  77     }
  78 };
  79
  80 class HelpGenVisitor : public spVisitor
  81 {
  82 public:
  83     // ctor
  84     HelpGenVisitor();
  85
  86     virtual void VisitFile( spFile& fl );
  87     virtual void VisitClass( spClass& cl );
  88     virtual void VisitEnumeration( spEnumeration& en );
  89     virtual void VisitTypeDef( spTypeDef& td );
  90     virtual void VisitAttribute( spAttribute& attr );
  91     virtual void VisitOperation( spOperation& op );
  92     virtual void VisitParameter( spParameter& param );
  93
  94     void EndVisit();
  95
  96     // shut up g++ warning (ain't it stupid?)
  97     virtual ~HelpGenVisitor() { }
  98
  99 protected:
 100     // (re)initialize the state
 101     void Reset();
 102
 103     // insert documentation for enums/typedefs coming immediately before the
 104     // class declaration into the class documentation
 105     void InsertTypedefDocs();
 106     void InsertEnumDocs();
 107
 108     // write the headers for corresponding sections (only once)
 109     void InsertDataStructuresHeader();
 110     void InsertMethodsHeader();
 111
 112     // terminate the function documentation if it was started
 113     void CloseFunction();
 114
 115     wxTeXFile m_file;  // file we're writing to now
 116
 117     // state variables
 118     bool m_inClass,         // TRUE after file successfully opened
 119          m_inTypesSection,  // enums & typedefs go there
 120          m_inMethodSection, // functions go here
 121          m_isFirstParam,    // first parameter of current function?
 122          m_inFunction;      // we're parsing a function declaration
 123
 124     // holders for "saved" documentation
 125     wxString m_textStoredEnums,
 126              m_textStoredTypedefs,
 127              m_textStoredFunctionComment;
 128 };
 129
 130 // -----------------------------------------------------------------------------
 131 // private functions
 132 // -----------------------------------------------------------------------------
 133
 134 // =============================================================================
 135 // implementation
 136 // =============================================================================
 137
 138 int main(int argc, char **argv)
 139 {
 140     if ( argc < 2 ) {
 141         wxLogError("usage: %s <header files...>\n", argv[0]);
 142
 143         return 1;
 144     }
 145
 146     // be verbose
 147     wxLog::GetActiveTarget()->SetVerbose();
 148
 149     // create a parser object and a visitor derivation
 150     CJSourceParser parser;
 151     HelpGenVisitor visitor;
 152
 153     // parse all files
 154     for ( int i = 1; i < argc; i++ ) {
 155         spContext *ctxTop = parser.ParseFile(argv[i]);
 156         if ( !ctxTop ) {
 157             wxLogWarning("File '%s' couldn't be processed.", argv[i]);
 158         }
 159         else {
 160             ((spFile *)ctxTop)->mFileName = argv[i];
 161             visitor.VisitAll(*ctxTop);
 162             visitor.EndVisit();
 163         }
 164     }
 165
 166     return 0;
 167 }
 168
 169 // -----------------------------------------------------------------------------
 170 // HelpGenVisitor implementation
 171 // -----------------------------------------------------------------------------
 172
 173 HelpGenVisitor::HelpGenVisitor()
 174 {
 175     Reset();
 176 }
 177
 178 void HelpGenVisitor::Reset()
 179 {
 180     m_inClass =
 181     m_inFunction =
 182     m_inTypesSection =
 183     m_inMethodSection = false;
 184 }
 185
 186 void HelpGenVisitor::InsertTypedefDocs()
 187 {
 188     m_file.WriteTeX(m_textStoredTypedefs);
 189     m_textStoredTypedefs.Empty();
 190 }
 191
 192 void HelpGenVisitor::InsertEnumDocs()
 193 {
 194     m_file.WriteTeX(m_textStoredEnums);
 195     m_textStoredEnums.Empty();
 196 }
 197
 198 void HelpGenVisitor::InsertDataStructuresHeader()
 199 {
 200     if ( !m_inTypesSection ) {
 201         m_inTypesSection = true;
 202
 203         m_file.WriteTeX("\\wxheading{Data structures}\n\n");
 204     }
 205 }
 206
 207 void HelpGenVisitor::InsertMethodsHeader()
 208 {
 209     if ( !m_inMethodSection ) {
 210         m_inMethodSection = true;
 211
 212         m_file.WriteTeX( "\\latexignore{\\rtfignore{\\wxheading{Members}}}\n\n");
 213     }
 214 }
 215
 216 void HelpGenVisitor::CloseFunction()
 217 {
 218     if ( m_inFunction ) {
 219         m_inFunction = false;
 220
 221         wxString totalText;
 222         if ( m_isFirstParam ) {
 223             // no params found
 224             totalText << "\\void";
 225         }
 226
 227         totalText << "}\n\n";
 228
 229         if ( !m_textStoredFunctionComment.IsEmpty() )
 230             totalText << m_textStoredFunctionComment << '\n';
 231
 232         m_file.WriteTeX(totalText);
 233     }
 234 }
 235
 236 void HelpGenVisitor::EndVisit()
 237 {
 238     CloseFunction();
 239 }
 240
 241 void HelpGenVisitor::VisitFile( spFile& file )
 242 {
 243     wxLogInfo("Parsing classes from file '%s'...", file.mFileName.c_str());
 244 }
 245
 246 void HelpGenVisitor::VisitClass( spClass& cl )
 247 {
 248     wxString name = cl.GetName();
 249
 250     // the file name is built from the class name by removing the leading "wx"
 251     // if any and converting it to the lower case
 252     wxString filename = name;
 253     if ( filename(0, 2) == "wx" ) {
 254         filename.erase(0, 2);
 255     }
 256
 257     filename.MakeLower();
 258     filename += ".tex";
 259
 260     m_inClass = m_file.Open(filename, wxFile::write);
 261     if ( !m_inClass ) {
 262         wxLogError("Can't generate documentation for the class '%s'.",
 263                    name.c_str());
 264
 265         return;
 266     }
 267
 268     m_inMethodSection =
 269     m_inTypesSection = false;
 270
 271     wxLogInfo("Created new file '%s' for class '%s'.",
 272               filename.c_str(), name.c_str());
 273
 274     // the entire text we're writing to file
 275     wxString totalText;
 276
 277     // write out the header
 278     {
 279         time_t timeNow = time(NULL);
 280         wxString header;
 281         header.Printf("% automatically generated by HelpGen from %s at "
 282                       "%s" // no '\n' here because ctime() inserts one
 283                       "\\section{\\class{%s}}\\label{%s}\n",
 284                       filename.c_str(), ctime(&timeNow),
 285                       name.c_str(), wxString(name).MakeLower().c_str());
 286
 287         totalText << header << '\n';
 288     }
 289
 290     // the comment before the class generally explains what is it for so put it
 291     // in place of the class description
 292     if ( cl.HasComments() ) {
 293         wxString comment;
 294         const MCommentListT& comments = cl.GetCommentList();
 295         for ( MCommentListT::const_iterator i = comments.begin();
 296               i != comments.end();
 297               i++ ) {
 298             comment << (*i)->GetText();
 299         }
 300
 301         totalText << '\n' << comment << '\n';
 302     }
 303
 304     // derived from section
 305     wxString derived = "\\wxheading{Derived from}\n\n";
 306
 307     const StrListT& baseClasses = cl.mSuperClassNames;
 308     if ( baseClasses.size() == 0 ) {
 309         derived << "No base class";
 310     }
 311     else {
 312         bool first = true;
 313         for ( StrListT::const_iterator i = baseClasses.begin();
 314               i != baseClasses.end();
 315               i++ ) {
 316             if ( !first ) {
 317                 // separate from the previous one
 318                 derived << "\\\\\n";
 319             }
 320             else {
 321                 first = false;
 322             }
 323
 324             wxString baseclass = *i;
 325             derived << "\\helpref{" << baseclass << "}"
 326                        "{ " << baseclass.MakeLower()  << "}";
 327         }
 328     }
 329     totalText << derived << "\n\n";
 330
 331     // write all this to file
 332     m_file.WriteTeX(totalText);
 333
 334     // if there were any enums/typedefs before, insert their documentation now
 335     InsertDataStructuresHeader();
 336     InsertTypedefDocs();
 337     InsertEnumDocs();
 338 }
 339
 340 void HelpGenVisitor::VisitEnumeration( spEnumeration& en )
 341 {
 342     CloseFunction();
 343
 344     if ( m_inMethodSection ) {
 345         // FIXME that's a bug, but tell the user aboit it nevertheless... we
 346         // should be smart enough to process even the enums which come after the
 347         // functions
 348         wxLogWarning("enum '%s' ignored, please put it before the class "
 349                      "methods.", en.GetName().c_str());
 350         return;
 351     }
 352
 353     // simply copy the enum text in the docs
 354     wxString enumeration;
 355     enumeration << "{\\small \\begin{verbatim}\n"
 356                 << en.mEnumContent
 357                 << "\n\\end{verbatim}}\n";
 358
 359     // remember for later use if we're not inside a class yet
 360     if ( !m_inClass ) {
 361         if ( !m_textStoredEnums.IsEmpty() ) {
 362             m_textStoredEnums << '\n';
 363         }
 364
 365         m_textStoredEnums << enumeration;
 366     }
 367     else {
 368         // write the header for this section if not done yet
 369         InsertDataStructuresHeader();
 370
 371         enumeration << '\n';
 372         m_file.WriteTeX(enumeration);
 373     }
 374 }
 375
 376 void HelpGenVisitor::VisitTypeDef( spTypeDef& td )
 377 {
 378     CloseFunction();
 379
 380     wxFAIL_MSG("don't know how to document typedefs yet");
 381 }
 382
 383 void HelpGenVisitor::VisitAttribute( spAttribute& attr )
 384 {
 385     CloseFunction();
 386
 387     // only document the public member variables
 388     if ( !m_inClass || !attr.IsPublic() )
 389         return;
 390
 391     wxFAIL_MSG("don't know how to document member vars yet");
 392 }
 393
 394 void HelpGenVisitor::VisitOperation( spOperation& op )
 395 {
 396     CloseFunction();
 397
 398     if ( !m_inClass || !op.IsInClass() ) {
 399         // FIXME that's a bug too
 400         wxLogWarning("skipped global function '%s'.", op.GetName().c_str());
 401
 402         return;
 403     }
 404
 405     if ( op.mVisibility == SP_VIS_PRIVATE ) {
 406         // FIXME should we document protected functions?
 407         return;
 408     }
 409
 410     InsertMethodsHeader();
 411
 412     // save state info
 413     m_inFunction =
 414     m_isFirstParam = true;
 415
 416     m_textStoredFunctionComment.Empty();
 417     const MCommentListT& comments = op.GetCommentList();
 418     for ( MCommentListT::const_iterator i = comments.begin();
 419           i != comments.end();
 420           i++ ) {
 421         m_textStoredFunctionComment << (*i)->GetText();
 422     }
 423
 424     // start function documentation
 425     wxString totalText;
 426     const char *funcname = op.GetName().c_str();
 427     const char *classname = op.GetClass().GetName().c_str();
 428
 429     // check for the special case of dtor
 430     wxString dtor;
 431     if ( (funcname[0] == '~') && (strcmp(funcname + 1, classname) == 0) ) {
 432         dtor.Printf("\\destruct{%s}", classname);
 433         funcname = dtor;
 434     }
 435
 436     totalText.Printf("\\membersection{%s::%s}\\label{%s}\n"
 437                      "\\%sfunc{%s}{%s}{",
 438                      classname, funcname,
 439                      MakeLabel(classname, funcname).c_str(),
 440                      op.mIsConstant ? "const" : "",
 441                      op.mRetType.c_str(),
 442                      funcname);
 443
 444     m_file.WriteTeX(totalText);
 445 }
 446
 447 void HelpGenVisitor::VisitParameter( spParameter& param )
 448 {
 449     if ( !m_inFunction )
 450         return;
 451
 452     wxString totalText;
 453     if ( m_isFirstParam ) {
 454         m_isFirstParam = false;
 455     }
 456     else {
 457         totalText << ", ";
 458     }
 459
 460     totalText << "\\param{" << param.mType << " }{" << param.GetName();
 461     wxString defvalue = param.mInitVal;
 462     if ( !defvalue.IsEmpty() ) {
 463         totalText << " = " << defvalue;
 464     }
 465
 466     totalText << '}';
 467
 468     m_file.WriteTeX(totalText);
 469 }
 470
 471 // -----------------------------------------------------------------------------
 472 // global function implementation
 473 // -----------------------------------------------------------------------------
 474
 475 static wxString MakeLabel(const char *classname, const char *funcname)
 476 {
 477     wxString label(classname);
 478     if ( funcname[0] == '\\' ) {
 479         // we may have some special TeX macro - so far only \destruct exists,
 480         // but may be later others will be added
 481         static const char *macros[] = { "destruct" };
 482         static const char *replacement[] = { "dtor" };
 483
 484         size_t n;
 485         for ( n = 0; n < WXSIZEOF(macros); n++ ) {
 486             if ( strncmp(funcname + 1, macros[n], strlen(macros[n])) == 0 ) {
 487                 // found
 488                 break;
 489             }
 490         }
 491
 492         if ( n == WXSIZEOF(macros) ) {
 493             wxLogWarning("unknown function name '%s' - leaving as is.",
 494                          funcname);
 495         }
 496         else {
 497             funcname = replacement[n];
 498         }
 499     }
 500
 501     label << funcname;
 502
 503     label.MakeLower();
 504
 505     return label;
 506 }
 507
 508 static void TeXFilter(wxString* str)
 509 {
 510     // FIXME may be done much more quickly
 511     str->Replace("&", "\\&");
 512     str->Replace("_", "\\_");
 513 }
 514
 515 /* vi: set tw=80 et ts=4 sw=4: */