outputgen.h 17 KB
Newer Older
Dimitri van Heesch's avatar
Dimitri van Heesch committed
1 2
/******************************************************************************
 *
3
 * 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
4
 *
5
 * Copyright (C) 1997-2008 by Dimitri van Heesch.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
6 7 8 9 10 11 12
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby 
 * granted. No representations are made about the suitability of this software 
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
13 14
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
15 16 17 18 19 20
 *
 */

#ifndef OUTPUTGEN_H
#define OUTPUTGEN_H

21
#include "qtbc.h"
22
#include <qtextstream.h>
Dimitri van Heesch's avatar
Dimitri van Heesch committed
23 24
#include <qbuffer.h>
#include <qfile.h>
Dimitri van Heesch's avatar
Dimitri van Heesch committed
25
#include <qstack.h>
Dimitri van Heesch's avatar
Dimitri van Heesch committed
26
#include "index.h"
27
#include "section.h"
Dimitri van Heesch's avatar
Dimitri van Heesch committed
28 29

class ClassDiagram;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
30
class DotClassGraph;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
31
class DotInclDepGraph;
32
class DotCallGraph;
33
class DotDirDeps;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
34
class DotGfxHierarchyTable;
35
class DotGroupCollaboration;
36 37
class DocNode;
class MemberDef;
38
class GroupDef;
39
class Definition;
40 41 42

/*! \brief Output interface for code parser. 
 */
43
class CodeOutputInterface
44 45
{
  public:
46
    virtual ~CodeOutputInterface() {}
47 48 49 50 51 52 53
    /*! Writes an ASCII string to the output. This function should keep 
     *  spaces visible, should break lines at a newline and should convert 
     *  tabs to the right number of spaces.
     */
    virtual void codify(const char *s) = 0;

    /*! Writes a link to an object in a code fragment.
54 55 56 57 58 59 60
     *  \param ref      If this is non-zero, the object is to be found in
     *                  an external documentation file.
     *  \param file     The file in which the object is located.
     *  \param anchor   The anchor uniquely identifying the object within 
     *                  the file. 
     *  \param name     The text to display as a placeholder for the link.
     *  \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 64
                               const char *anchor,const char *name,
                               const char *tooltip) = 0;
65 66 67 68 69 70 71 72 73 74

    virtual void writeLineNumber(const char *ref,const char *file,
                                 const char *anchor,int lineNumber) = 0;
    virtual void startCodeLine() = 0;
    virtual void endCodeLine() = 0;
    virtual void startCodeAnchor(const char *label) = 0;
    virtual void endCodeAnchor() = 0;
    virtual void startFontClass(const char *) = 0;
    virtual void endFontClass() = 0;
    virtual void writeCodeAnchor(const char *name) = 0;
75 76
    virtual void linkableSymbol(int line,const char *symName,
                 Definition *symDef,Definition *context) = 0;
77
};
Dimitri van Heesch's avatar
Dimitri van Heesch committed
78

79 80
/*! \brief Base Interface used for generating output outside of the
 *  comment blocks.
81
 *
82 83
 *  This abstract class is used by output generation functions
 *  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
Dimitri van Heesch's avatar
Dimitri van Heesch committed
88 89
{
  public:
90
    virtual ~BaseOutputDocInterface() {}
91
    enum ParamListTypes { Param, RetVal, Exception };
92
    enum SectionTypes { /*See, Return, Author, Version, 
93 94 95
                        Since, Date, Bug, Note,
                        Warning, Par, Deprecated, Pre, 
                        Post, Invar, Remark, Attention, 
96
                        Todo, Test, RCS, */ EnumValues, 
97 98
                        Examples 
                      };
Dimitri van Heesch's avatar
Dimitri van Heesch committed
99

100
    virtual void parseDoc(const char *,int, const char *,MemberDef *,
101 102
                          const QCString &,bool)  {} 
    virtual void parseText(const QCString &)  {}
103
    
104
    /*! Start of a bullet list: e.g. \c \<ul\> in html. writeListItem() is
105 106 107
     *  Used for the bullet items.
     */
    virtual void startItemList()  = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
108

109
    /*! Writes a list item for a bullet or enumerated 
110
     *  list: e.g. \c \<li\> in html 
111 112
     */
    virtual void writeListItem()  = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
113

114
    /*! Ends a bullet list: e.g. \c \</ul\> in html */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
115
    virtual void endItemList()    = 0;
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134

    /*! Writes an ASCII string to the output. Converts characters that have
     *  A special meaning, like \c & in html. 
     */
    virtual void docify(const char *s) = 0;

    /*! Writes a single ASCII character to the output. Converts characters
     *  that have a special meaning.
     */
    virtual void writeChar(char c) = 0;

    /*! Writes an ASCII string to the output, \e without converting 
     *  special characters. 
     */
    virtual void writeString(const char *text) = 0;

    /*! Starts a new paragraph */
    virtual void newParagraph()   = 0;

135 136 137 138 139
    /*! Starts a new paragraph */
    virtual void startParagraph() = 0;
    /*! End a paragraph */
    virtual void endParagraph() = 0;

140 141 142 143 144 145
    /*! Writes a link to an object in the documentation.
     *  \param ref    If this is non-zero, the object is to be found in
     *                an external documentation file.
     *  \param file   The file in which the object is located.
     *  \param anchor The anchor uniquely identifying the object within 
     *                the file. 
146
     *  \param name   The text to display as a placeholder for the link.
147
     */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
148
    virtual void writeObjectLink(const char *ref,const char *file,
149
                                 const char *anchor, const char *name) = 0;
150 151


Dimitri van Heesch's avatar
Dimitri van Heesch committed
152 153 154 155 156 157
    /*! Starts a (link to an) URL found in the documentation.
     *  \param url    The URL to link to.
     */
    virtual void startHtmlLink(const char *url) = 0;

    /*! Ends a link started by startHtmlLink().
158
     */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
159
    virtual void endHtmlLink() = 0;
160 161 162 163 164 165 166 167 168 169 170 171 172

    
    /*! Changes the text font to bold face. The bold section ends with
     *  endBold()
     */
    virtual void startBold()      = 0;

    /*! End a section of text displayed in bold face. */
    virtual void endBold()        = 0;

    /*! Changes the text font to fixed size. The section ends with
     *  endTypewriter()
     */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
173
    virtual void startTypewriter() = 0;
174 175

    /*! End a section of text displayed in typewriter style. */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
176 177
    virtual void endTypewriter() = 0;

178 179 180 181
    /*! Changes the text font to italic. The italic section ends with
     *  endEmphasis()
     */
    virtual void startEmphasis() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
182

183 184 185 186 187 188 189 190
    /*! Ends a section of text displayed in italic. */
    virtual void endEmphasis() = 0;

    /*! Starts a source code fragment. The fragment will be
     *  fed to the code parser (see code.h) for syntax highlighting
     *  and cross-referencing. The fragment ends by a call to
     *  endCodeFragment()
     */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
191
    virtual void startCodeFragment() = 0;
192 193 194

    /*! Ends a source code fragment
     */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
195
    virtual void endCodeFragment() = 0;
196

197 198 199
    

    
200 201 202
    /*! Writes a horizontal ruler to the output */
    virtual void writeRuler() = 0;
    
203
    /*! Starts a description list: e.g. \c \<dl\> in HTML 
204 205
     *  Items are surrounded by startDescItem() and endDescItem()
     */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
206
    virtual void startDescription() = 0;
207

208
    /*! Ends a description list: e.g. \c \</dl\> in HTML */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
209
    virtual void endDescription() = 0;
210

211
    /*! Starts an item of a description list: e.g. \c \<dt\> in HTML. */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
212
    virtual void startDescItem() = 0;
213 214

    /*! Ends an item of a description list and starts the 
215
     *  description itself: e.g. \c \<dd\> in HTML. 
216
     */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
217
    virtual void endDescItem() = 0;
218

Dimitri van Heesch's avatar
Dimitri van Heesch committed
219 220 221 222
    virtual void startCenter() = 0;
    virtual void endCenter() = 0;
    virtual void startSmall() = 0;
    virtual void endSmall() = 0;
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237

    virtual void startSimpleSect(SectionTypes t,const char *file,
                                 const char *anchor,const char *title) = 0;
    virtual void endSimpleSect() = 0;
    virtual void startParamList(ParamListTypes t,const char *title) = 0;
    virtual void endParamList() = 0;

    virtual void writeDescItem() = 0;
    virtual void startTitle() = 0;
    virtual void endTitle()   = 0;

    virtual void writeAnchor(const char *fileName,const char *name) = 0;
    virtual void startSection(const char *,const char *,SectionInfo::SectionType) = 0;
    virtual void endSection(const char *,SectionInfo::SectionType) = 0;

Dimitri van Heesch's avatar
Dimitri van Heesch committed
238
    virtual void lineBreak(const char *style) = 0;
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255
    virtual void addIndexItem(const char *s1,const char *s2) = 0;

    virtual void writeNonBreakableSpace(int) = 0;
    virtual void startDescTable() = 0;
    virtual void endDescTable() = 0;
    virtual void startDescTableTitle() = 0;
    virtual void endDescTableTitle() = 0;
    virtual void startDescTableData() = 0;
    virtual void endDescTableData() = 0;
    virtual void startTextLink(const char *file,const char *anchor) = 0;
    virtual void endTextLink() = 0;
    virtual void startPageRef() = 0;
    virtual void endPageRef(const char *,const char *) = 0;
    virtual void startSubsection() = 0;
    virtual void endSubsection() = 0;
    virtual void startSubsubsection() = 0;
    virtual void endSubsubsection() = 0;
256
};
257

258 259 260 261 262 263 264
/*! \brief Abstract output generator.
 *
 *  Subclass this class to add support for a new output format
 */
class OutputGenerator : public BaseOutputDocInterface
{
  public:
265
    enum OutputType { Html, Latex, Man, RTF, XML, DEF, Perl };
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285

    OutputGenerator();
    virtual ~OutputGenerator();

    ///////////////////////////////////////////////////////////////
    // generic generator methods
    ///////////////////////////////////////////////////////////////
    virtual void enable() = 0;
    virtual void disable() = 0;
    virtual void enableIf(OutputType o) = 0;
    virtual void disableIf(OutputType o) = 0;
    virtual void disableIfNot(OutputType o) = 0;
    virtual bool isEnabled(OutputType o) = 0;
    virtual OutputGenerator *get(OutputType o) = 0;
    void startPlainFile(const char *name);
    void endPlainFile();
    QCString getContents() const;
    bool isEnabled() const { return active; }
    void pushGeneratorState();
    void popGeneratorState();
286 287
    void setEncoding(const QCString &enc) { encoding = enc; }
    virtual void postProcess(QByteArray &) { }
288

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

291 292 293
    ///////////////////////////////////////////////////////////////
    // structural output interface
    ///////////////////////////////////////////////////////////////
294
    virtual void startFile(const char *name,const char *manName,
295 296
                           const char *title) = 0;
    virtual void writeFooter() = 0;
297 298 299
    virtual void endFile() = 0;
    virtual void startIndexSection(IndexSections) = 0;
    virtual void endIndexSection(IndexSections) = 0;
300
    virtual void writePageLink(const char *,bool) = 0;
301 302 303 304 305 306 307
    virtual void startProjectNumber() = 0;
    virtual void endProjectNumber() = 0;
    virtual void writeStyleInfo(int part) = 0;
    virtual void startTitleHead(const char *) = 0;
    virtual void endTitleHead(const char *fileName,const char *name) = 0;
    virtual void startIndexList() = 0;
    virtual void endIndexList()   = 0;
308 309
    virtual void startIndexKey() = 0;
    virtual void endIndexKey()   = 0;
310 311
    virtual void startIndexValue(bool) = 0;
    virtual void endIndexValue(const char *,bool) = 0;
312 313
    virtual void startIndexItem(const char *ref,const char *file) = 0;
    virtual void endIndexItem(const char *ref,const char *file) = 0;
314 315 316 317 318 319 320 321
    virtual void startGroupHeader() = 0;
    virtual void endGroupHeader() = 0;
    virtual void startMemberSections() = 0;
    virtual void endMemberSections() = 0;
    virtual void startMemberHeader() = 0;
    virtual void endMemberHeader() = 0;
    virtual void startMemberSubtitle() = 0;
    virtual void endMemberSubtitle() = 0;
322 323 324 325
    virtual void startMemberDocList() = 0;
    virtual void endMemberDocList() = 0;
    virtual void startMemberList() = 0;
    virtual void endMemberList() = 0;
326 327
    virtual void startAnonTypeScope(int) = 0;
    virtual void endAnonTypeScope(int) = 0;
328
    virtual void startMemberItem(int) = 0;
329
    virtual void endMemberItem() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
330 331
    virtual void startMemberTemplateParams() = 0;
    virtual void endMemberTemplateParams() = 0;
332 333 334 335 336 337
    virtual void startMemberGroupHeader(bool) = 0;
    virtual void endMemberGroupHeader() = 0;
    virtual void startMemberGroupDocs() = 0;
    virtual void endMemberGroupDocs() = 0;
    virtual void startMemberGroup() = 0;
    virtual void endMemberGroup(bool) = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
338
    virtual void insertMemberAlign(bool) = 0;
339 340
    virtual void startMemberDoc(const char *,const char *,
                                const char *,const char *) = 0;
341
    virtual void endMemberDoc(bool) = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
342
    virtual void startDoxyAnchor(const char *fName,const char *manName,
343 344
                                 const char *anchor,const char *name,
                                 const char *args) = 0;
345 346 347 348 349 350 351 352 353 354 355
    virtual void endDoxyAnchor(const char *fileName,const char *anchor) = 0;
    virtual void writeLatexSpacing() = 0;
    virtual void writeStartAnnoItem(const char *type,const char *file,
                                    const char *path,const char *name) = 0;
    virtual void writeEndAnnoItem(const char *name) = 0;
    virtual void startMemberDescription() = 0;
    virtual void endMemberDescription() = 0;
    virtual void startIndent() = 0;
    virtual void endIndent() = 0;
    virtual void writeSynopsis() = 0;
    virtual void startClassDiagram() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
356
    virtual void endClassDiagram(const ClassDiagram &,const char *,const char *) = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
357
    virtual void startDotGraph() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
358
    virtual void endDotGraph(const DotClassGraph &g) = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
359
    virtual void startInclDepGraph() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
360
    virtual void endInclDepGraph(const DotInclDepGraph &g) = 0;
361
    virtual void startGroupCollaboration() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
362
    virtual void endGroupCollaboration(const DotGroupCollaboration &g) = 0;
363
    virtual void startCallGraph() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
364
    virtual void endCallGraph(const DotCallGraph &g) = 0;
365
    virtual void startDirDepGraph() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
366 367
    virtual void endDirDepGraph(const DotDirDeps &g) = 0;
    virtual void writeGraphicalHierarchy(const DotGfxHierarchyTable &g) = 0;
368 369
    virtual void startQuickIndices() = 0;
    virtual void endQuickIndices() = 0;
370
    virtual void writeQuickLinks(bool compact,HighlightedItem hli) = 0;
371 372
    virtual void startContents() = 0;
    virtual void endContents() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
373
    virtual void startTextBlock(bool) = 0;
374
    virtual void endTextBlock(bool) = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
375
    virtual void lastIndexPage() = 0;
376 377
    virtual void startMemberDocPrefixItem() = 0;
    virtual void endMemberDocPrefixItem() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
378
    virtual void startMemberDocName(bool) = 0;
379
    virtual void endMemberDocName() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
380
    virtual void startParameterType(bool,const char *) = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
381
    virtual void endParameterType() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
382
    virtual void startParameterName(bool) = 0;
383
    virtual void endParameterName(bool,bool,bool) = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
384
    virtual void startParameterList(bool) = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
385
    virtual void endParameterList() = 0;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
386

387 388 389 390 391 392 393 394 395
    virtual void startConstraintList(const char *) = 0;
    virtual void startConstraintParam() = 0;
    virtual void endConstraintParam() = 0;
    virtual void startConstraintType() = 0;
    virtual void endConstraintType() = 0;
    virtual void startConstraintDocs() = 0;
    virtual void endConstraintDocs() = 0;
    virtual void endConstraintList() = 0;

Dimitri van Heesch's avatar
Dimitri van Heesch committed
396 397 398 399 400 401
  protected:
    QTextStream fs;
    QByteArray a;
    QBuffer b;
    QTextStream t;
    QFile *file;
402
    QCString dir;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
403
    bool active;
404
    QStack<bool> *genStack;
405
    QString encoding;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
406 407 408 409 410 411

  private:
    OutputGenerator(const OutputGenerator &o);
    OutputGenerator &operator=(const OutputGenerator &o);
};

412
/*! \brief Interface used for generating documentation.
413
 *
414 415
 *  This abstract class is used by several functions
 *  to generate the output for a specific format. 
416 417 418 419 420 421
 *  This interface contains some state saving and changing
 *  functions for dealing with format specific output.
 */
class OutputDocInterface : public BaseOutputDocInterface
{
  public:
Dimitri van Heesch's avatar
Dimitri van Heesch committed
422 423
    virtual ~OutputDocInterface() {}

424 425 426
    /*! Create a new output generator. This can later by appended
     *  to the current one using append().
     */
427
    //virtual OutputDocInterface *clone() = 0;
428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455

    /*! Disables all output formats except format \a o 
     *  (useful for OutputList only) 
     */
    virtual void disableAllBut(OutputGenerator::OutputType o) = 0;

    /*! Enables all output formats as far as they have been enabled in
     *  the config file. (useful for OutputList only) 
     */
    virtual void enableAll() = 0;

    /*! Disables all output formats (useful for OutputList only) */
    virtual void disableAll()= 0;

    /*! Disables a specific output format (useful for OutputList only) */
    virtual void disable(OutputGenerator::OutputType o) = 0;

    /*! Enables a specific output format (useful for OutputList only) */
    virtual void enable(OutputGenerator::OutputType o) = 0;

    /*! Check whether a specific output format is currenly enabled 
     *  (useful for OutputList only) 
     */
    virtual bool isEnabled(OutputGenerator::OutputType o) = 0;

    /*! Appends the output generated by generator \a g to this
     *  generator.
     */ 
456
    //virtual void append(const OutputDocInterface *g) = 0;
457 458 459 460 461 462 463 464 465 466 467 468 469 470

    /*! Pushes the state of the current generator (or list of 
     *  generators) on a stack.
     */
    virtual void pushGeneratorState() = 0;

    /*! Pops the state of the current generator (or list of 
     *  generators) on a stack. Should be preceded by a call
     *  the pushGeneratorState().
     */
    virtual void popGeneratorState() = 0;
};


Dimitri van Heesch's avatar
Dimitri van Heesch committed
471
#endif