src/outputgen.h

   1 /******************************************************************************
   2  *
   3  * $Id: outputgen.h,v 1.48 2001/03/19 19:27:41 root Exp $
   4  *
   5  * Copyright (C) 1997-2012 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17
  18 #ifndef OUTPUTGEN_H
  19 #define OUTPUTGEN_H
  20
  21 #include "qtbc.h"
  22 #include "ftextstream.h"
  23 #include <qbuffer.h>
  24 #include <qfile.h>
  25 #include <qstack.h>
  26 #include "index.h"
  27 #include "section.h"
  28
  29 class ClassDiagram;
  30 class DotClassGraph;
  31 class DotInclDepGraph;
  32 class DotCallGraph;
  33 class DotDirDeps;
  34 class DotGfxHierarchyTable;
  35 class DotGroupCollaboration;
  36 class DocNode;
  37 class MemberDef;
  38 class GroupDef;
  39 class Definition;
  40
  41 /** Output interface for code parser.
  42  */
  43 class CodeOutputInterface
  44 {
  45   public:
  46     virtual ~CodeOutputInterface() {}
  47     /*! Writes an ASCII string to the output. This function should keep
  48      *  spaces visible, should break lines at a newline and should convert
  49      *  tabs to the right number of spaces.
  50      */
  51     virtual void codify(const char *s) = 0;
  52
  53     /*! Writes a link to an object in a code fragment.
  54      *  \param ref      If this is non-zero, the object is to be found in
  55      *                  an external documentation file.
  56      *  \param file     The file in which the object is located.
  57      *  \param anchor   The anchor uniquely identifying the object within
  58      *                  the file.
  59      *  \param name     The text to display as a placeholder for the link.
  60      *  \param tooltip  The tooltip to display when the mouse is on the link.
  61      */
  62     virtual void writeCodeLink(const char *ref,const char *file,
  63                                const char *anchor,const char *name,
  64                                const char *tooltip) = 0;
  65
  66     virtual void writeLineNumber(const char *ref,const char *file,
  67                                  const char *anchor,int lineNumber) = 0;
  68     virtual void startCodeLine(bool hasLineNumbers) = 0;
  69     virtual void endCodeLine() = 0;
  70     virtual void startCodeAnchor(const char *label) = 0;
  71     virtual void endCodeAnchor() = 0;
  72     virtual void startFontClass(const char *) = 0;
  73     virtual void endFontClass() = 0;
  74     virtual void writeCodeAnchor(const char *name) = 0;
  75     virtual void linkableSymbol(int line,const char *symName,
  76                  Definition *symDef,Definition *context) = 0;
  77 };
  78
  79 /** Base Interface used for generating output outside of the
  80  *  comment blocks.
  81  *
  82  *  This abstract class is used by output generation functions
  83  *  to generate the output for a specific format,
  84  *  or a list of formats (see OutputList). This interface
  85  *  contains functions that generate fragments of the output.
  86  */
  87 class BaseOutputDocInterface : public CodeOutputInterface
  88 {
  89   public:
  90     virtual ~BaseOutputDocInterface() {}
  91     enum ParamListTypes { Param, RetVal, Exception };
  92     enum SectionTypes { /*See, Return, Author, Version,
  93                         Since, Date, Bug, Note,
  94                         Warning, Par, Deprecated, Pre,
  95                         Post, Invar, Remark, Attention,
  96                         Todo, Test, RCS, */ EnumValues,
  97                         Examples
  98                       };
  99
 100     virtual void parseText(const QCString &)  {}
 101
 102     /*! Start of a bullet list: e.g. \c \<ul\> in html. startItemListItem() is
 103      *  Used for the bullet items.
 104      */
 105     virtual void startItemList()  = 0;
 106
 107     /*! Writes a list item for a bullet or enumerated
 108      *  list: e.g. \c \<li\> in html
 109      */
 110     virtual void startItemListItem()  = 0;
 111
 112     /*! Writes a list item for a bullet or enumerated
 113      *  list: e.g. \c \</li\> in html
 114      */
 115     virtual void endItemListItem()  = 0;
 116
 117     /*! Ends a bullet list: e.g. \c \</ul\> in html */
 118     virtual void endItemList()    = 0;
 119
 120     /*! Writes an ASCII string to the output. Converts characters that have
 121      *  A special meaning, like \c & in html.
 122      */
 123     virtual void docify(const char *s) = 0;
 124
 125     /*! Writes a single ASCII character to the output. Converts characters
 126      *  that have a special meaning.
 127      */
 128     virtual void writeChar(char c) = 0;
 129
 130     /*! Writes an ASCII string to the output, \e without converting
 131      *  special characters.
 132      */
 133     virtual void writeString(const char *text) = 0;
 134
 135     /*! Starts a new paragraph */
 136     //virtual void newParagraph()   = 0;
 137
 138     /*! Starts a new paragraph */
 139     virtual void startParagraph() = 0;
 140     /*! Ends a paragraph */
 141     virtual void endParagraph() = 0;
 142
 143     /*! Writes a link to an object in the documentation.
 144      *  \param ref    If this is non-zero, the object is to be found in
 145      *                an external documentation file.
 146      *  \param file   The file in which the object is located.
 147      *  \param anchor The anchor uniquely identifying the object within
 148      *                the file.
 149      *  \param name   The text to display as a placeholder for the link.
 150      */
 151     virtual void writeObjectLink(const char *ref,const char *file,
 152                                  const char *anchor, const char *name) = 0;
 153
 154
 155     /*! Starts a (link to an) URL found in the documentation.
 156      *  \param url    The URL to link to.
 157      */
 158     virtual void startHtmlLink(const char *url) = 0;
 159
 160     /*! Ends a link started by startHtmlLink().
 161      */
 162     virtual void endHtmlLink() = 0;
 163
 164
 165     /*! Changes the text font to bold face. The bold section ends with
 166      *  endBold()
 167      */
 168     virtual void startBold()      = 0;
 169
 170     /*! End a section of text displayed in bold face. */
 171     virtual void endBold()        = 0;
 172
 173     /*! Changes the text font to fixed size. The section ends with
 174      *  endTypewriter()
 175      */
 176     virtual void startTypewriter() = 0;
 177
 178     /*! End a section of text displayed in typewriter style. */
 179     virtual void endTypewriter() = 0;
 180
 181     /*! Changes the text font to italic. The italic section ends with
 182      *  endEmphasis()
 183      */
 184     virtual void startEmphasis() = 0;
 185
 186     /*! Ends a section of text displayed in italic. */
 187     virtual void endEmphasis() = 0;
 188
 189     /*! Starts a source code fragment. The fragment will be
 190      *  fed to the code parser (see code.h) for syntax highlighting
 191      *  and cross-referencing. The fragment ends by a call to
 192      *  endCodeFragment()
 193      */
 194     virtual void startCodeFragment() = 0;
 195
 196     /*! Ends a source code fragment
 197      */
 198     virtual void endCodeFragment() = 0;
 199
 200
 201
 202
 203     /*! Writes a horizontal ruler to the output */
 204     virtual void writeRuler() = 0;
 205
 206     /*! Starts a description list: e.g. \c \<dl\> in HTML
 207      *  Items are surrounded by startDescItem() and endDescItem()
 208      */
 209     virtual void startDescription() = 0;
 210
 211     /*! Ends a description list: e.g. \c \</dl\> in HTML */
 212     virtual void endDescription() = 0;
 213
 214     /*! Starts an item of a description list: e.g. \c \<dt\> in HTML. */
 215     virtual void startDescItem() = 0;
 216
 217     virtual void startDescForItem() = 0;
 218     virtual void endDescForItem() = 0;
 219
 220     /*! Ends an item of a description list and starts the
 221      *  description itself: e.g. \c \</dt\> in HTML.
 222      */
 223     virtual void endDescItem() = 0;
 224
 225     virtual void startCenter() = 0;
 226     virtual void endCenter() = 0;
 227     virtual void startSmall() = 0;
 228     virtual void endSmall() = 0;
 229
 230     virtual void startSimpleSect(SectionTypes t,const char *file,
 231                                  const char *anchor,const char *title) = 0;
 232     virtual void endSimpleSect() = 0;
 233     virtual void startParamList(ParamListTypes t,const char *title) = 0;
 234     virtual void endParamList() = 0;
 235
 236     //virtual void writeDescItem() = 0;
 237     virtual void startTitle() = 0;
 238     virtual void endTitle()   = 0;
 239
 240     virtual void writeAnchor(const char *fileName,const char *name) = 0;
 241     virtual void startSection(const char *,const char *,SectionInfo::SectionType) = 0;
 242     virtual void endSection(const char *,SectionInfo::SectionType) = 0;
 243
 244     virtual void lineBreak(const char *style) = 0;
 245     virtual void addIndexItem(const char *s1,const char *s2) = 0;
 246
 247     virtual void writeNonBreakableSpace(int) = 0;
 248     virtual void startDescTable() = 0;
 249     virtual void endDescTable() = 0;
 250     virtual void startDescTableTitle() = 0;
 251     virtual void endDescTableTitle() = 0;
 252     virtual void startDescTableData() = 0;
 253     virtual void endDescTableData() = 0;
 254     virtual void startTextLink(const char *file,const char *anchor) = 0;
 255     virtual void endTextLink() = 0;
 256     virtual void startPageRef() = 0;
 257     virtual void endPageRef(const char *,const char *) = 0;
 258     virtual void startSubsection() = 0;
 259     virtual void endSubsection() = 0;
 260     virtual void startSubsubsection() = 0;
 261     virtual void endSubsubsection() = 0;
 262 };
 263
 264 /** Abstract output generator.
 265  *
 266  *  Subclass this class to add support for a new output format
 267  */
 268 class OutputGenerator : public BaseOutputDocInterface
 269 {
 270   public:
 271     enum OutputType { Html, Latex, Man, RTF, XML, DEF, Perl };
 272
 273     OutputGenerator();
 274     virtual ~OutputGenerator();
 275
 276     ///////////////////////////////////////////////////////////////
 277     // generic generator methods
 278     ///////////////////////////////////////////////////////////////
 279     virtual void enable() = 0;
 280     virtual void disable() = 0;
 281     virtual void enableIf(OutputType o) = 0;
 282     virtual void disableIf(OutputType o) = 0;
 283     virtual void disableIfNot(OutputType o) = 0;
 284     virtual bool isEnabled(OutputType o) = 0;
 285     virtual OutputGenerator *get(OutputType o) = 0;
 286     void startPlainFile(const char *name);
 287     void endPlainFile();
 288     //QCString getContents() const;
 289     bool isEnabled() const { return active; }
 290     void pushGeneratorState();
 291     void popGeneratorState();
 292     //void setEncoding(const QCString &enc) { encoding = enc; }
 293     //virtual void postProcess(QByteArray &) { }
 294
 295     virtual void writeDoc(DocNode *,Definition *ctx,MemberDef *md) = 0;
 296
 297     ///////////////////////////////////////////////////////////////
 298     // structural output interface
 299     ///////////////////////////////////////////////////////////////
 300     virtual void startFile(const char *name,const char *manName,
 301                            const char *title) = 0;
 302     virtual void writeSearchInfo() = 0;
 303     virtual void writeFooter(const char *navPath) = 0;
 304     virtual void endFile() = 0;
 305     virtual void startIndexSection(IndexSections) = 0;
 306     virtual void endIndexSection(IndexSections) = 0;
 307     virtual void writePageLink(const char *,bool) = 0;
 308     virtual void startProjectNumber() = 0;
 309     virtual void endProjectNumber() = 0;
 310     virtual void writeStyleInfo(int part) = 0;
 311     virtual void startTitleHead(const char *) = 0;
 312     virtual void endTitleHead(const char *fileName,const char *name) = 0;
 313     virtual void startIndexListItem() = 0;
 314     virtual void endIndexListItem()   = 0;
 315     virtual void startIndexList() = 0;
 316     virtual void endIndexList()   = 0;
 317     virtual void startIndexKey() = 0;
 318     virtual void endIndexKey()   = 0;
 319     virtual void startIndexValue(bool) = 0;
 320     virtual void endIndexValue(const char *,bool) = 0;
 321     virtual void startIndexItem(const char *ref,const char *file) = 0;
 322     virtual void endIndexItem(const char *ref,const char *file) = 0;
 323     virtual void startGroupHeader(int) = 0;
 324     virtual void endGroupHeader(int) = 0;
 325     virtual void startMemberSections() = 0;
 326     virtual void endMemberSections() = 0;
 327     virtual void startHeaderSection() = 0;
 328     virtual void endHeaderSection() = 0;
 329     virtual void startMemberHeader(const char *anchor) = 0;
 330     virtual void endMemberHeader() = 0;
 331     virtual void startMemberSubtitle() = 0;
 332     virtual void endMemberSubtitle() = 0;
 333     virtual void startMemberDocList() = 0;
 334     virtual void endMemberDocList() = 0;
 335     virtual void startMemberList() = 0;
 336     virtual void endMemberList() = 0;
 337     virtual void startInlineHeader() = 0;
 338     virtual void endInlineHeader() = 0;
 339     virtual void startAnonTypeScope(int) = 0;
 340     virtual void endAnonTypeScope(int) = 0;
 341     virtual void startMemberItem(const char *,int,const char *) = 0;
 342     virtual void endMemberItem() = 0;
 343     virtual void startMemberTemplateParams() = 0;
 344     virtual void endMemberTemplateParams(const char *,const char *) = 0;
 345     virtual void startMemberGroupHeader(bool) = 0;
 346     virtual void endMemberGroupHeader() = 0;
 347     virtual void startMemberGroupDocs() = 0;
 348     virtual void endMemberGroupDocs() = 0;
 349     virtual void startMemberGroup() = 0;
 350     virtual void endMemberGroup(bool) = 0;
 351     virtual void insertMemberAlign(bool) = 0;
 352     virtual void startMemberDoc(const char *,const char *,
 353                                 const char *,const char *,bool) = 0;
 354     virtual void endMemberDoc(bool) = 0;
 355     virtual void startDoxyAnchor(const char *fName,const char *manName,
 356                                  const char *anchor,const char *name,
 357                                  const char *args) = 0;
 358     virtual void endDoxyAnchor(const char *fileName,const char *anchor) = 0;
 359     virtual void writeLatexSpacing() = 0;
 360     virtual void writeStartAnnoItem(const char *type,const char *file,
 361                                     const char *path,const char *name) = 0;
 362     virtual void writeEndAnnoItem(const char *name) = 0;
 363     virtual void startMemberDescription(const char *anchor,const char *inheritId) = 0;
 364     virtual void endMemberDescription() = 0;
 365     virtual void startMemberDeclaration() = 0;
 366     virtual void endMemberDeclaration(const char *anchor,const char *inheritId) = 0;
 367     virtual void writeInheritedSectionTitle(const char *id,const char *ref,
 368                                             const char *file,const char *anchor,
 369                                             const char *title,const char *name) = 0;
 370     virtual void startIndent() = 0;
 371     virtual void endIndent() = 0;
 372     virtual void writeSynopsis() = 0;
 373     virtual void startClassDiagram() = 0;
 374     virtual void endClassDiagram(const ClassDiagram &,const char *,const char *) = 0;
 375     virtual void startDotGraph() = 0;
 376     virtual void endDotGraph(const DotClassGraph &g) = 0;
 377     virtual void startInclDepGraph() = 0;
 378     virtual void endInclDepGraph(const DotInclDepGraph &g) = 0;
 379     virtual void startGroupCollaboration() = 0;
 380     virtual void endGroupCollaboration(const DotGroupCollaboration &g) = 0;
 381     virtual void startCallGraph() = 0;
 382     virtual void endCallGraph(const DotCallGraph &g) = 0;
 383     virtual void startDirDepGraph() = 0;
 384     virtual void endDirDepGraph(const DotDirDeps &g) = 0;
 385     virtual void writeGraphicalHierarchy(const DotGfxHierarchyTable &g) = 0;
 386     virtual void startQuickIndices() = 0;
 387     virtual void endQuickIndices() = 0;
 388     virtual void writeSplitBar(const char *) = 0;
 389     virtual void writeNavigationPath(const char *) = 0;
 390     virtual void writeLogo() = 0;
 391     virtual void writeQuickLinks(bool compact,HighlightedItem hli,const char *file) = 0;
 392     virtual void writeSummaryLink(const char *file,const char *anchor,const char *title,bool first) = 0;
 393     virtual void startContents() = 0;
 394     virtual void endContents() = 0;
 395     virtual void startTextBlock(bool) = 0;
 396     virtual void endTextBlock(bool) = 0;
 397     virtual void lastIndexPage() = 0;
 398     virtual void startMemberDocPrefixItem() = 0;
 399     virtual void endMemberDocPrefixItem() = 0;
 400     virtual void startMemberDocName(bool) = 0;
 401     virtual void endMemberDocName() = 0;
 402     virtual void startParameterType(bool,const char *key) = 0;
 403     virtual void endParameterType() = 0;
 404     virtual void startParameterName(bool) = 0;
 405     virtual void endParameterName(bool,bool,bool) = 0;
 406     virtual void startParameterList(bool) = 0;
 407     virtual void endParameterList() = 0;
 408
 409     virtual void startConstraintList(const char *) = 0;
 410     virtual void startConstraintParam() = 0;
 411     virtual void endConstraintParam() = 0;
 412     virtual void startConstraintType() = 0;
 413     virtual void endConstraintType() = 0;
 414     virtual void startConstraintDocs() = 0;
 415     virtual void endConstraintDocs() = 0;
 416     virtual void endConstraintList() = 0;
 417
 418     virtual void startMemberDocSimple() = 0;
 419     virtual void endMemberDocSimple() = 0;
 420     virtual void startInlineMemberType() = 0;
 421     virtual void endInlineMemberType() = 0;
 422     virtual void startInlineMemberName() = 0;
 423     virtual void endInlineMemberName() = 0;
 424     virtual void startInlineMemberDoc() = 0;
 425     virtual void endInlineMemberDoc() = 0;
 426
 427
 428     virtual void startLabels() = 0;
 429     virtual void writeLabel(const char *,bool) = 0;
 430     virtual void endLabels() = 0;
 431
 432   protected:
 433     FTextStream t;
 434     QFile *file;
 435     QCString fileName;
 436     QCString dir;
 437     bool active;
 438     QStack<bool> *genStack;
 439
 440   private:
 441     OutputGenerator(const OutputGenerator &o);
 442     OutputGenerator &operator=(const OutputGenerator &o);
 443 };
 444
 445 /** Interface used for generating documentation.
 446  *
 447  *  This abstract class is used by several functions
 448  *  to generate the output for a specific format.
 449  *  This interface contains some state saving and changing
 450  *  functions for dealing with format specific output.
 451  */
 452 class OutputDocInterface : public BaseOutputDocInterface
 453 {
 454   public:
 455     virtual ~OutputDocInterface() {}
 456
 457     /*! Create a new output generator. This can later by appended
 458      *  to the current one using append().
 459      */
 460     //virtual OutputDocInterface *clone() = 0;
 461
 462     /*! Disables all output formats except format \a o
 463      *  (useful for OutputList only)
 464      */
 465     virtual void disableAllBut(OutputGenerator::OutputType o) = 0;
 466
 467     /*! Enables all output formats as far as they have been enabled in
 468      *  the config file. (useful for OutputList only)
 469      */
 470     virtual void enableAll() = 0;
 471
 472     /*! Disables all output formats (useful for OutputList only) */
 473     virtual void disableAll()= 0;
 474
 475     /*! Disables a specific output format (useful for OutputList only) */
 476     virtual void disable(OutputGenerator::OutputType o) = 0;
 477
 478     /*! Enables a specific output format (useful for OutputList only) */
 479     virtual void enable(OutputGenerator::OutputType o) = 0;
 480
 481     /*! Check whether a specific output format is currently enabled
 482      *  (useful for OutputList only)
 483      */
 484     virtual bool isEnabled(OutputGenerator::OutputType o) = 0;
 485
 486     /*! Appends the output generated by generator \a g to this
 487      *  generator.
 488      */
 489     //virtual void append(const OutputDocInterface *g) = 0;
 490
 491     /*! Pushes the state of the current generator (or list of
 492      *  generators) on a stack.
 493      */
 494     virtual void pushGeneratorState() = 0;
 495
 496     /*! Pops the state of the current generator (or list of
 497      *  generators) on a stack. Should be preceded by a call
 498      *  the pushGeneratorState().
 499      */
 500     virtual void popGeneratorState() = 0;
 501 };
 502
 503
 504 #endif