1 /******************************************************************************

     2  *

     3  * 

     4  *

     5  * Copyright (C) 1997-2008 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 <qtextstream.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 /*! \brief 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() = 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 /*! \brief 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 parseDoc(const char *,int, const char *,MemberDef *,

   101                           const QCString &,bool)  {} 

   102     virtual void parseText(const QCString &)  {}

   103     

   104     /*! Start of a bullet list: e.g. \c \<ul\> in html. startItemListItem() is

   105      *  Used for the bullet items.

   106      */

   107     virtual void startItemList()  = 0;

   108 

   109     /*! Writes a list item for a bullet or enumerated 

   110      *  list: e.g. \c \<li\> in html 

   111      */

   112     virtual void startItemListItem()  = 0;

   113 

   114     /*! Writes a list item for a bullet or enumerated 

   115      *  list: e.g. \c \</li\> in html 

   116      */

   117     virtual void endItemListItem()  = 0;

   118 

   119     /*! Ends a bullet list: e.g. \c \</ul\> in html */

   120     virtual void endItemList()    = 0;

   121 

   122     /*! Writes an ASCII string to the output. Converts characters that have

   123      *  A special meaning, like \c & in html. 

   124      */

   125     virtual void docify(const char *s) = 0;

   126 

   127     /*! Writes a single ASCII character to the output. Converts characters

   128      *  that have a special meaning.

   129      */

   130     virtual void writeChar(char c) = 0;

   131 

   132     /*! Writes an ASCII string to the output, \e without converting 

   133      *  special characters. 

   134      */

   135     virtual void writeString(const char *text) = 0;

   136 

   137     /*! Starts a new paragraph */

   138     //virtual void newParagraph()   = 0;

   139 

   140     /*! Starts a new paragraph */

   141     virtual void startParagraph() = 0;

   142     /*! Ends a paragraph */

   143     virtual void endParagraph() = 0;

   144 

   145     /*! Writes a link to an object in the documentation.

   146      *  \param ref    If this is non-zero, the object is to be found in

   147      *                an external documentation file.

   148      *  \param file   The file in which the object is located.

   149      *  \param anchor The anchor uniquely identifying the object within 

   150      *                the file. 

   151      *  \param name   The text to display as a placeholder for the link.

   152      */

   153     virtual void writeObjectLink(const char *ref,const char *file,

   154                                  const char *anchor, const char *name) = 0;

   155 

   156 

   157     /*! Starts a (link to an) URL found in the documentation.

   158      *  \param url    The URL to link to.

   159      */

   160     virtual void startHtmlLink(const char *url) = 0;

   161 

   162     /*! Ends a link started by startHtmlLink().

   163      */

   164     virtual void endHtmlLink() = 0;

   165 

   166     

   167     /*! Changes the text font to bold face. The bold section ends with

   168      *  endBold()

   169      */

   170     virtual void startBold()      = 0;

   171 

   172     /*! End a section of text displayed in bold face. */

   173     virtual void endBold()        = 0;

   174 

   175     /*! Changes the text font to fixed size. The section ends with

   176      *  endTypewriter()

   177      */

   178     virtual void startTypewriter() = 0;

   179 

   180     /*! End a section of text displayed in typewriter style. */

   181     virtual void endTypewriter() = 0;

   182 

   183     /*! Changes the text font to italic. The italic section ends with

   184      *  endEmphasis()

   185      */

   186     virtual void startEmphasis() = 0;

   187 

   188     /*! Ends a section of text displayed in italic. */

   189     virtual void endEmphasis() = 0;

   190 

   191     /*! Starts a source code fragment. The fragment will be

   192      *  fed to the code parser (see code.h) for syntax highlighting

   193      *  and cross-referencing. The fragment ends by a call to

   194      *  endCodeFragment()

   195      */

   196     virtual void startCodeFragment() = 0;

   197 

   198     /*! Ends a source code fragment

   199      */

   200     virtual void endCodeFragment() = 0;

   201 

   202     

   203 

   204     

   205     /*! Writes a horizontal ruler to the output */

   206     virtual void writeRuler() = 0;

   207     

   208     /*! Starts a description list: e.g. \c \<dl\> in HTML 

   209      *  Items are surrounded by startDescItem() and endDescItem()

   210      */

   211     virtual void startDescription() = 0;

   212 

   213     /*! Ends a description list: e.g. \c \</dl\> in HTML */

   214     virtual void endDescription() = 0;

   215 

   216     /*! Starts an item of a description list: e.g. \c \<dt\> in HTML. */

   217     virtual void startDescItem() = 0;

   218 

   219     virtual void startDescForItem() = 0;

   220     virtual void endDescForItem() = 0;

   221 

   222     /*! Ends an item of a description list and starts the 

   223      *  description itself: e.g. \c \</dt\> in HTML. 

   224      */

   225     virtual void endDescItem() = 0;

   226 

   227     virtual void startCenter() = 0;

   228     virtual void endCenter() = 0;

   229     virtual void startSmall() = 0;

   230     virtual void endSmall() = 0;

   231 

   232     virtual void startSimpleSect(SectionTypes t,const char *file,

   233                                  const char *anchor,const char *title) = 0;

   234     virtual void endSimpleSect() = 0;

   235     virtual void startParamList(ParamListTypes t,const char *title) = 0;

   236     virtual void endParamList() = 0;

   237 

   238     //virtual void writeDescItem() = 0;

   239     virtual void startTitle() = 0;

   240     virtual void endTitle()   = 0;

   241 

   242     virtual void writeAnchor(const char *fileName,const char *name) = 0;

   243     virtual void startSection(const char *,const char *,SectionInfo::SectionType) = 0;

   244     virtual void endSection(const char *,SectionInfo::SectionType) = 0;

   245 

   246     virtual void lineBreak(const char *style) = 0;

   247     virtual void addIndexItem(const char *s1,const char *s2) = 0;

   248 

   249     virtual void writeNonBreakableSpace(int) = 0;

   250     virtual void startDescTable() = 0;

   251     virtual void endDescTable() = 0;

   252     virtual void startDescTableTitle() = 0;

   253     virtual void endDescTableTitle() = 0;

   254     virtual void startDescTableData() = 0;

   255     virtual void endDescTableData() = 0;

   256     virtual void startTextLink(const char *file,const char *anchor) = 0;

   257     virtual void endTextLink() = 0;

   258     virtual void startPageRef() = 0;

   259     virtual void endPageRef(const char *,const char *) = 0;

   260     virtual void startSubsection() = 0;

   261     virtual void endSubsection() = 0;

   262     virtual void startSubsubsection() = 0;

   263     virtual void endSubsubsection() = 0;

   264 };

   265 

   266 /*! \brief Abstract output generator.

   267  *

   268  *  Subclass this class to add support for a new output format

   269  */

   270 class OutputGenerator : public BaseOutputDocInterface

   271 {

   272   public:

   273     enum OutputType { Html, Latex, Man, RTF, XML, DEF, Perl };

   274 

   275     OutputGenerator();

   276     virtual ~OutputGenerator();

   277 

   278     ///////////////////////////////////////////////////////////////

   279     // generic generator methods

   280     ///////////////////////////////////////////////////////////////

   281     virtual void enable() = 0;

   282     virtual void disable() = 0;

   283     virtual void enableIf(OutputType o) = 0;

   284     virtual void disableIf(OutputType o) = 0;

   285     virtual void disableIfNot(OutputType o) = 0;

   286     virtual bool isEnabled(OutputType o) = 0;

   287     virtual OutputGenerator *get(OutputType o) = 0;

   288     void startPlainFile(const char *name);

   289     void endPlainFile();

   290     QCString getContents() const;

   291     bool isEnabled() const { return active; }

   292     void pushGeneratorState();

   293     void popGeneratorState();

   294     void setEncoding(const QCString &enc) { encoding = enc; }

   295     virtual void postProcess(QByteArray &) { }

   296 

   297     virtual void printDoc(DocNode *,const char *langExt) = 0;

   298 

   299     ///////////////////////////////////////////////////////////////

   300     // structural output interface

   301     ///////////////////////////////////////////////////////////////

   302     virtual void startFile(const char *name,const char *manName,

   303                            const char *title) = 0;

   304     virtual void writeFooter() = 0;

   305     virtual void endFile() = 0;

   306     virtual void startIndexSection(IndexSections) = 0;

   307     virtual void endIndexSection(IndexSections) = 0;

   308     virtual void writePageLink(const char *,bool) = 0;

   309     virtual void startProjectNumber() = 0;

   310     virtual void endProjectNumber() = 0;

   311     virtual void writeStyleInfo(int part) = 0;

   312     virtual void startTitleHead(const char *) = 0;

   313     virtual void endTitleHead(const char *fileName,const char *name) = 0;

   314     virtual void startIndexListItem() = 0;

   315     virtual void endIndexListItem()   = 0;

   316     virtual void startIndexList() = 0;

   317     virtual void endIndexList()   = 0;

   318     virtual void startIndexKey() = 0;

   319     virtual void endIndexKey()   = 0;

   320     virtual void startIndexValue(bool) = 0;

   321     virtual void endIndexValue(const char *,bool) = 0;

   322     virtual void startIndexItem(const char *ref,const char *file) = 0;

   323     virtual void endIndexItem(const char *ref,const char *file) = 0;

   324     virtual void startGroupHeader() = 0;

   325     virtual void endGroupHeader() = 0;

   326     virtual void startMemberSections() = 0;

   327     virtual void endMemberSections() = 0;

   328     virtual void startMemberHeader() = 0;

   329     virtual void endMemberHeader() = 0;

   330     virtual void startMemberSubtitle() = 0;

   331     virtual void endMemberSubtitle() = 0;

   332     virtual void startMemberDocList() = 0;

   333     virtual void endMemberDocList() = 0;

   334     virtual void startMemberList() = 0;

   335     virtual void endMemberList() = 0;

   336     virtual void startAnonTypeScope(int) = 0;

   337     virtual void endAnonTypeScope(int) = 0;

   338     virtual void startMemberItem(int) = 0;

   339     virtual void endMemberItem() = 0;

   340     virtual void startMemberTemplateParams() = 0;

   341     virtual void endMemberTemplateParams() = 0;

   342     virtual void startMemberGroupHeader(bool) = 0;

   343     virtual void endMemberGroupHeader() = 0;

   344     virtual void startMemberGroupDocs() = 0;

   345     virtual void endMemberGroupDocs() = 0;

   346     virtual void startMemberGroup() = 0;

   347     virtual void endMemberGroup(bool) = 0;

   348     virtual void insertMemberAlign(bool) = 0;

   349     virtual void startMemberDoc(const char *,const char *,

   350                                 const char *,const char *) = 0;

   351     virtual void endMemberDoc(bool) = 0;

   352     virtual void startDoxyAnchor(const char *fName,const char *manName,

   353                                  const char *anchor,const char *name,

   354                                  const char *args) = 0;

   355     virtual void endDoxyAnchor(const char *fileName,const char *anchor) = 0;

   356     virtual void writeLatexSpacing() = 0;

   357     virtual void writeStartAnnoItem(const char *type,const char *file,

   358                                     const char *path,const char *name) = 0;

   359     virtual void writeEndAnnoItem(const char *name) = 0;

   360     virtual void startMemberDescription() = 0;

   361     virtual void endMemberDescription() = 0;

   362     virtual void startIndent() = 0;

   363     virtual void endIndent() = 0;

   364     virtual void writeSynopsis() = 0;

   365     virtual void startClassDiagram() = 0;

   366     virtual void endClassDiagram(const ClassDiagram &,const char *,const char *) = 0;

   367     virtual void startDotGraph() = 0;

   368     virtual void endDotGraph(const DotClassGraph &g) = 0;

   369     virtual void startInclDepGraph() = 0;

   370     virtual void endInclDepGraph(const DotInclDepGraph &g) = 0;

   371     virtual void startGroupCollaboration() = 0;

   372     virtual void endGroupCollaboration(const DotGroupCollaboration &g) = 0;

   373     virtual void startCallGraph() = 0;

   374     virtual void endCallGraph(const DotCallGraph &g) = 0;

   375     virtual void startDirDepGraph() = 0;

   376     virtual void endDirDepGraph(const DotDirDeps &g) = 0;

   377     virtual void writeGraphicalHierarchy(const DotGfxHierarchyTable &g) = 0;

   378     virtual void startQuickIndices() = 0;

   379     virtual void endQuickIndices() = 0;

   380     virtual void writeQuickLinks(bool compact,HighlightedItem hli) = 0;

   381     virtual void startContents() = 0;

   382     virtual void endContents() = 0;

   383     virtual void startTextBlock(bool) = 0;

   384     virtual void endTextBlock(bool) = 0;

   385     virtual void lastIndexPage() = 0;

   386     virtual void startMemberDocPrefixItem() = 0;

   387     virtual void endMemberDocPrefixItem() = 0;

   388     virtual void startMemberDocName(bool) = 0;

   389     virtual void endMemberDocName() = 0;

   390     virtual void startParameterType(bool,const char *) = 0;

   391     virtual void endParameterType() = 0;

   392     virtual void startParameterName(bool) = 0;

   393     virtual void endParameterName(bool,bool,bool) = 0;

   394     virtual void startParameterList(bool) = 0;

   395     virtual void endParameterList() = 0;

   396 

   397     virtual void startConstraintList(const char *) = 0;

   398     virtual void startConstraintParam() = 0;

   399     virtual void endConstraintParam() = 0;

   400     virtual void startConstraintType() = 0;

   401     virtual void endConstraintType() = 0;

   402     virtual void startConstraintDocs() = 0;

   403     virtual void endConstraintDocs() = 0;

   404     virtual void endConstraintList() = 0;

   405 

   406   protected:

   407     QTextStream fs;

   408     QByteArray a;

   409     QBuffer b;

   410     QTextStream t;

   411     QFile *file;

   412     QCString dir;

   413     bool active;

   414     QStack<bool> *genStack;

   415     QString encoding;

   416 

   417   private:

   418     OutputGenerator(const OutputGenerator &o);

   419     OutputGenerator &operator=(const OutputGenerator &o);

   420 };

   421 

   422 /*! \brief Interface used for generating documentation.

   423  *

   424  *  This abstract class is used by several functions

   425  *  to generate the output for a specific format. 

   426  *  This interface contains some state saving and changing

   427  *  functions for dealing with format specific output.

   428  */

   429 class OutputDocInterface : public BaseOutputDocInterface

   430 {

   431   public:

   432     virtual ~OutputDocInterface() {}

   433 

   434     /*! Create a new output generator. This can later by appended

   435      *  to the current one using append().

   436      */

   437     //virtual OutputDocInterface *clone() = 0;

   438 

   439     /*! Disables all output formats except format \a o 

   440      *  (useful for OutputList only) 

   441      */

   442     virtual void disableAllBut(OutputGenerator::OutputType o) = 0;

   443 

   444     /*! Enables all output formats as far as they have been enabled in

   445      *  the config file. (useful for OutputList only) 

   446      */

   447     virtual void enableAll() = 0;

   448 

   449     /*! Disables all output formats (useful for OutputList only) */

   450     virtual void disableAll()= 0;

   451 

   452     /*! Disables a specific output format (useful for OutputList only) */

   453     virtual void disable(OutputGenerator::OutputType o) = 0;

   454 

   455     /*! Enables a specific output format (useful for OutputList only) */

   456     virtual void enable(OutputGenerator::OutputType o) = 0;

   457 

   458     /*! Check whether a specific output format is currenly enabled 

   459      *  (useful for OutputList only) 

   460      */

   461     virtual bool isEnabled(OutputGenerator::OutputType o) = 0;

   462 

   463     /*! Appends the output generated by generator \a g to this

   464      *  generator.

   465      */ 

   466     //virtual void append(const OutputDocInterface *g) = 0;

   467 

   468     /*! Pushes the state of the current generator (or list of 

   469      *  generators) on a stack.

   470      */

   471     virtual void pushGeneratorState() = 0;

   472 

   473     /*! Pops the state of the current generator (or list of 

   474      *  generators) on a stack. Should be preceded by a call

   475      *  the pushGeneratorState().

   476      */

   477     virtual void popGeneratorState() = 0;

   478 };

   479 

   480 

   481 #endif