wxPython/wxSWIG/SWIG/html.cxx

   1 /*******************************************************************************
   2  * Simplified Wrapper and Interface Generator  (SWIG)
   3  *
   4  * Author : David Beazley
   5  *
   6  * Department of Computer Science
   7  * University of Chicago
   8  * 1100 E 58th Street
   9  * Chicago, IL  60637
  10  * beazley@cs.uchicago.edu
  11  *
  12  * Please read the file LICENSE for the copyright and terms by which SWIG
  13  * can be used and distributed.
  14  *******************************************************************************/
  15
  16 #include "swig.h"
  17 #include "html.h"
  18
  19 /*******************************************************************************
  20  * $Header$
  21  *
  22  * File : html.cxx
  23  *
  24  * HTML specific functions for producing documentation.
  25  *******************************************************************************/
  26
  27 #define PRE      0
  28 #define FORMAT   1
  29
  30 // -----------------------------------------------------------------------------
  31 // HTML::HTML()
  32 //
  33 // Constructor.  Creates a new HTML documentation module object.
  34 //
  35 // Inputs : None
  36 //
  37 // Output : HTML Object
  38 //
  39 // Side Effects : None
  40 // -----------------------------------------------------------------------------
  41
  42 HTML::HTML() {
  43   sect_count = 0;
  44   last_section = 0;
  45
  46   // Initialize default tags for various parts of the documentation
  47
  48   tag_body = "<BODY BGCOLOR=\"#ffffff\">:</BODY>";
  49   tag_title = "<H1>:</H1>";
  50   tag_contents = "<HR><H1>:</H1>";
  51   tag_section = "<HR><H2>:</H2>";
  52   tag_subsection = "<H3>:</H3>";
  53   tag_subsubsection = "<H4>:</H4>";
  54   tag_usage = "<P><TT><B>:</B></TT>";
  55   tag_descrip = "<BLOCKQUOTE>:</BLOCKQUOTE>";
  56   tag_text = "<P>";
  57   tag_cinfo = "";
  58   tag_preformat = "<PRE>:</PRE>";
  59 }
  60
  61 // -----------------------------------------------------------------------------
  62 // char *HTML::start_tag(char *tag)
  63 //
  64 // Utility function for returning the first part of an HTML tag variable.
  65 // A tag must look like this :
  66 //
  67 //          "<b>:</b>"
  68 //
  69 // The start tag for this would be "<b>"
  70 //
  71 // Inputs : tag   = HTML tag string
  72 //
  73 // Output : Staring portion of the tag variable.
  74 //
  75 // Side Effects : None.
  76 // -----------------------------------------------------------------------------
  77
  78 char *HTML::start_tag(char *tag) {
  79   static String stag;
  80   char  *c;
  81
  82   stag = "";
  83   c = tag;
  84   while ((*c) && (*c != ':')) {
  85     stag << *c;
  86     c++;
  87   }
  88   return stag.get();
  89 }
  90
  91 // -----------------------------------------------------------------------------
  92 // char *HTML::end_tag(char *tag)
  93 //
  94 // Utility for returning an end-tag.  The counterpart to start_tag().
  95 //
  96 // Inputs : tag   = HTML tag string
  97 //
  98 // Output : Ending portion of tag variable.
  99 //
 100 // Side Effects : None
 101 // -----------------------------------------------------------------------------
 102
 103 char *HTML::end_tag(char *tag) {
 104   static String etag;
 105   char  *c;
 106
 107   etag = "";
 108   c = tag;
 109   while ((*c) && (*c != ':')) {
 110     c++;
 111   }
 112   if (*c) {
 113     c++;
 114     while (*c) {
 115       etag << *c;
 116       c++;
 117     }
 118   }
 119   return etag.get();
 120 }
 121
 122 // -----------------------------------------------------------------------------
 123 // void HTML::print_string(char *s, String &str, int mode)
 124 //
 125 // Outputs the contents of string s into String str.   If mode is 1, we
 126 // will reformat the text and apply a few common HTML character
 127 // substitutions.
 128 //
 129 // Inputs :  s    =  Documentation text string
 130 //           mode =  Formatting mode (0 = preformat, 1 = formatted)
 131 //
 132 // Output :  str  =  Output is append to str.
 133 //
 134 // Side Effects : None
 135 // -----------------------------------------------------------------------------
 136
 137 void HTML::print_string(char *s, String &str,int mode) {
 138   char *c;
 139   c = s;
 140   while (*c) {
 141     switch(*c) {
 142     case '\"':
 143       str << "&quot;";
 144       break;
 145     case '&':
 146       str << "&amp;";
 147       break;
 148     case '<':
 149       if (mode == PRE)
 150         str << "&lt;";
 151       else
 152         str << (char) *c;
 153       break;
 154     case '>':
 155       if (mode == PRE)
 156         str << "&gt;";
 157       else
 158         str << (char) *c;
 159       break;
 160     default :
 161       str << (char ) *c;
 162       break;
 163     }
 164     c++;
 165   }
 166 }
 167
 168 // -----------------------------------------------------------------------------
 169 // void HTML::print_decl(DocEntry *de)
 170 //
 171 // Generates documentation for a declaration.
 172 //
 173 // Inputs : de  = Documentation entry
 174 //
 175 // Output : None
 176 //
 177 // Side Effects : None
 178 // -----------------------------------------------------------------------------
 179
 180 void HTML::print_decl(DocEntry *de) {
 181
 182   char *c;
 183   c = de->usage.get();
 184   while ((*c) && ((*c == ' ') || (*c == '\t') || (*c == '\n'))) c++;
 185   if (c) {
 186     s_doc << start_tag(tag_usage);
 187     print_string(c,s_doc,PRE);
 188     s_doc << end_tag(tag_usage) << "\n";
 189   } else return;
 190
 191   // Only print this if there is information
 192
 193   if ((strlen(de->cinfo.get()) && de->print_info) || strlen(de->text.get())) {
 194     s_doc << start_tag(tag_descrip);
 195     if (!de->format)
 196       s_doc << start_tag(tag_preformat);
 197   }
 198
 199   // If there is any C annotation, print that
 200   if (de->print_info) {
 201     c = de->cinfo.get();
 202     if (strlen(c) > 0) {
 203       s_doc << start_tag(tag_cinfo);
 204       s_doc << "[ ";
 205       print_string(c,s_doc,PRE);
 206       s_doc << " ]" << end_tag(tag_cinfo) << "\n";
 207       if (de->format) s_doc << "<BR>";
 208     }
 209   }
 210
 211   c = de->text.get();
 212   if (strlen(c) > 0) {
 213     print_string(c,s_doc,de->format);
 214   }
 215
 216   if ((strlen(de->cinfo.get()) && de->print_info) || strlen(de->text.get())) {
 217     if (!de->format) s_doc << end_tag(tag_preformat);
 218     s_doc << end_tag(tag_descrip) << "\n";
 219   }
 220
 221   s_doc << "\n";
 222 }
 223
 224 // -----------------------------------------------------------------------------
 225 // void HTML::print_text(DocEntry *de)
 226 //
 227 // Generates documentation for a text-block. Strips any leading whitespace.
 228 //
 229 // Inputs : de = Documentation entry
 230 //
 231 // Output : None
 232 //
 233 // Side Effects : None
 234 // -----------------------------------------------------------------------------
 235
 236 void HTML::print_text(DocEntry *de) {
 237   char *c;
 238   c = de->text.get();
 239   if (strlen(c) > 0) {
 240     s_doc << start_tag(tag_text);
 241     if (!de->format)
 242       s_doc << start_tag(tag_preformat);
 243     print_string(c,s_doc,de->format);
 244     if (!de->format)
 245       s_doc << end_tag(tag_preformat) << "\n";
 246     s_doc << end_tag(tag_text) << "\n";
 247   }
 248 }
 249
 250 // -----------------------------------------------------------------------------
 251 // void HTML::title(DocEntry *de)
 252 //
 253 // Generates the title for an HTML document.
 254 //
 255 // Inputs : de = Title documentation entry
 256 //
 257 // Output : None
 258 //
 259 // Side Effects : None
 260 // -----------------------------------------------------------------------------
 261
 262 void HTML::title(DocEntry *de) {
 263   char *c;
 264   c = de->usage.get();
 265   if (strlen(c) > 0) {
 266     s_title << "<HEAD>\n"
 267           << "<TITLE>\n";
 268     print_string(c,s_title,PRE);
 269     s_title << "</TITLE>\n"
 270           << start_tag(tag_body) << "\n";
 271
 272     s_title << start_tag(tag_title);
 273     print_string(c,s_title,PRE);
 274     s_title << end_tag(tag_title) << "\n";
 275   }
 276
 277   if (!de->format)
 278     s_title << start_tag(tag_preformat);
 279
 280   // If there is any C annotation, print that
 281   if (de->print_info) {
 282     c = de->cinfo.get();
 283     if (strlen(c) > 0) {
 284       s_title << start_tag(tag_cinfo) << "[ ";
 285       print_string(c,s_title,de->format);
 286       s_title << " ]" << end_tag(tag_cinfo);
 287       if (de->format)
 288         s_title << "<BR>\n";
 289       else
 290         s_title << "\n";
 291     }
 292   }
 293
 294   c = de->text.get();
 295   if (strlen(c)) {
 296     print_string(c,s_title,de->format);
 297   }
 298   if (!de->format)
 299     s_title << end_tag(tag_preformat) << "\n";
 300 }
 301
 302 // -----------------------------------------------------------------------------
 303 // void HTML::newsection(DocEntry *de, int sectnum)
 304 //
 305 // Creates a new section.  sect_count is used to determine the formatting of
 306 // the header.  Also fills in a table of contents
 307 //
 308 // Inputs :
 309 //          de       = Documentation Entry
 310 //          sectnum  = Section number
 311 //
 312 // Output : None
 313 //
 314 // Side Effects :
 315 //          Creates a new subsection.  Updates HTML table of contents.
 316 // -----------------------------------------------------------------------------
 317
 318 void HTML::newsection(DocEntry *de,int sectnum) {
 319   int i,f;
 320   char *c;
 321
 322   char *tag;
 323
 324   sect_num[sect_count] = sectnum;
 325   sect_count++;
 326
 327   f = sect_count + 1;
 328   if (f > 5) f = 5;
 329
 330   // Form table of contents
 331   // if sect_count > last_section.  We need to indent
 332   // if sect_count < last_section.  We need to pop out
 333
 334   if (sect_count > last_section) {
 335     for (i = 0; i < sect_count - last_section; i++)
 336       contents << "<UL>";
 337   } else if (sect_count < last_section) {
 338     for (i = 0; i < last_section - sect_count; i++)
 339       contents << "</UL>";
 340   }
 341
 342   last_section = sect_count;
 343   contents << "<LI> <A HREF=\"#s";
 344
 345   s_doc << "<A name=\"s";
 346   for (i = 0; i < sect_count; i++) {
 347     s_doc << sect_num[i] << "_";
 348     contents << sect_num[i] << "_";
 349   }
 350
 351   contents << "\">";
 352
 353   // Figure out the tag fields
 354
 355   switch(f) {
 356   case 1:
 357     tag = tag_title;
 358     break;
 359   case 2:
 360     tag = tag_section;
 361     break;
 362   case 3:
 363     tag = tag_subsection;
 364     break;
 365   case 4:
 366     tag = tag_subsubsection;
 367     break;
 368   default:
 369     tag = tag_subsubsection;
 370   }
 371
 372   s_doc << "\">\n"
 373         << start_tag(tag);
 374
 375   for (i = 0; i < sect_count; i++) {
 376     s_doc << sect_num[i] << ".";
 377     contents << sect_num[i] << ".";
 378   }
 379   c = de->usage.get();
 380   s_doc << " ";
 381   contents << " ";
 382   print_string(c,s_doc,PRE);
 383   print_string(c,contents,PRE);
 384   s_doc << end_tag(tag) << "</A>\n";
 385   contents << "</A>\n";
 386
 387   if (!de->format)
 388     s_doc << start_tag(tag_preformat);
 389
 390   // If there is any C annotation, print that
 391   if (de->print_info) {
 392     c = de->cinfo.get();
 393     if (strlen(c) > 0) {
 394       s_doc << start_tag(tag_cinfo) << "[ ";
 395       print_string(c,s_doc,de->format);
 396       s_doc << " ]" << end_tag(tag_cinfo);
 397       if (de->format)
 398         s_doc << "<BR>\n";
 399       else
 400         s_doc << "\n";
 401     }
 402   }
 403
 404   // If there is a description text. Print it
 405
 406   c = de->text.get();
 407   if (strlen(c) > 0) {
 408     print_string(c,s_doc,de->format);
 409     s_doc << "\n";
 410   }
 411   if (!de->format)
 412     s_doc << end_tag(tag_preformat) << "\n";
 413
 414 }
 415
 416 // -----------------------------------------------------------------------------
 417 // void HTML::endsection()
 418 //
 419 // Ends a subsection.  It is an error to call this without first calling
 420 // newsection previously.
 421 //
 422 // Inputs : None
 423 //
 424 // Output : None
 425 //
 426 // Side Effects : Closes current section and goes back to parent.
 427 //
 428 // -----------------------------------------------------------------------------
 429
 430 void HTML::endsection() {
 431   if (sect_count > 0) sect_count--;
 432 }
 433
 434 // -----------------------------------------------------------------------------
 435 // void HTML::separator()
 436 //
 437 // Prints a separator after the declaration of a C++ class.  Currently
 438 // does nothing in HTML mode.
 439 //
 440 // Inputs : None
 441 //
 442 // Output : None
 443 //
 444 // Side Effects : None
 445 // -----------------------------------------------------------------------------
 446
 447 void HTML::separator() {
 448 }
 449
 450 // -----------------------------------------------------------------------------
 451 // void HTML::init(char *filename)
 452 //
 453 // Initializes the HTML module and opens up the documentation file.
 454 //
 455 // Inputs : filename  = Name of documentation file (without a suffix)
 456 //
 457 // Output : None
 458 //
 459 // Side Effects : Opens documentation file.
 460 // -----------------------------------------------------------------------------
 461
 462 void HTML::init(char *filename) {
 463   char f[256];
 464
 465   sprintf(f,"%s.html",filename);
 466   f_doc = fopen(f,"w");
 467   if (f_doc == NULL) {
 468     fprintf(stderr,"Unable to open %s\n",f);
 469     SWIG_exit(1);
 470   }
 471   /* Print a HTML banner */
 472   fprintf(f_doc,"<HTML>\n");
 473
 474 }
 475
 476 // -----------------------------------------------------------------------------
 477 // void HTML::close(void)
 478 //
 479 // Dumps the table of contents and forms the final documentation file. Closes
 480 // the documentation file upon completion.
 481 //
 482 // Inputs : None
 483 //
 484 // Output : None
 485 //
 486 // Side Effects : Closes documentation file.
 487 // -----------------------------------------------------------------------------
 488
 489 void HTML::close(void) {
 490
 491   int i;
 492   for (i = 0; i < last_section; i++)
 493     contents << "</UL>\n";
 494
 495   fprintf(f_doc,"%s\n",s_title.get());
 496   if (last_section) {
 497     fprintf(f_doc,"%s Contents %s\n",start_tag(tag_contents),end_tag(tag_contents));
 498     fprintf(f_doc,"%s\n",contents.get());
 499   }
 500   fprintf(f_doc,"%s\n",s_doc.get());
 501   fprintf(f_doc,"%s\n", end_tag(tag_body));
 502   fprintf(f_doc,"</HTML>\n");
 503   fclose(f_doc);
 504 }
 505
 506 // -----------------------------------------------------------------------------
 507 // void HTML::style(char *name, char *value)
 508 //
 509 // Process parameters given with the %style directive.  Does nothing if an
 510 // unrecognized parameter is given.
 511 //
 512 // Inputs :
 513 //          name   = name of style parameter
 514 //          value  = ASCII string with value of parameter.
 515 //
 516 // Output : None
 517 //
 518 // Side Effects : Updates internal style parameters.
 519 // -----------------------------------------------------------------------------
 520
 521 void HTML::style(char *name, char *value) {
 522   if (strcmp(name,"html_title") == 0) {
 523     if (value)
 524       tag_title = copy_string(value);
 525   } else if (strcmp(name,"html_contents") == 0) {
 526     if (value)
 527       tag_contents = copy_string(value);
 528   } else if (strcmp(name,"html_section") == 0) {
 529     if (value)
 530       tag_section = copy_string(value);
 531   } else if (strcmp(name,"html_subsection") == 0) {
 532     if (value)
 533       tag_subsection = copy_string(value);
 534   } else if (strcmp(name,"html_subsubsection") == 0) {
 535     if (value)
 536       tag_subsubsection = copy_string(value);
 537   } else if (strcmp(name,"html_usage") == 0) {
 538     if (value)
 539       tag_usage = copy_string(value);
 540   } else if (strcmp(name,"html_descrip") == 0) {
 541     if (value)
 542       tag_descrip = copy_string(value);
 543   } else if (strcmp(name,"html_text") == 0) {
 544     if (value)
 545       tag_text = copy_string(value);
 546   } else if (strcmp(name,"html_cinfo") == 0) {
 547     if (value)
 548       tag_cinfo = copy_string(value);
 549   } else if (strcmp(name,"html_preformat") == 0) {
 550     if (value)
 551       tag_preformat = copy_string(value);
 552   } else if (strcmp(name,"html_body") == 0) {
 553     if (value)
 554       tag_body = copy_string(value);
 555   }
 556 }
 557
 558 // -----------------------------------------------------------------------------
 559 // void HTML::parse_args(int argc, char **argv)
 560 //
 561 // Parse command line options given on the SWIG command line.
 562 //
 563 // Inputs :
 564 //          argc     = argument count
 565 //          argv     = argument array
 566 //
 567 // Output : None
 568 //
 569 // Side Effects : Marks arguments as being parsed.
 570 // -----------------------------------------------------------------------------
 571
 572 static char *html_usage = "\
 573 HTML Documentation Options (available with -dhtml)\n\
 574      None available.\n\n";
 575
 576 void HTML::parse_args(int argc, char **argv) {
 577   int i;
 578
 579   for (i = 0; i < argc; i++) {
 580     if (argv[i]) {
 581       if (strcmp(argv[i],"-help") == 0) {
 582         fputs(html_usage,stderr);
 583       }
 584     }
 585   }
 586 }
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598