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

     2  *

     3  * 

     4  *

     5  *

     6  * Copyright (C) 1997-2008 by Dimitri van Heesch.

     7  *

     8  * Permission to use, copy, modify, and distribute this software and its

     9  * documentation under the terms of the GNU General Public License is hereby 

    10  * granted. No representations are made about the suitability of this software 

    11  * for any purpose. It is provided "as is" without express or implied warranty.

    12  * See the GNU General Public License for more details.

    13  *

    14  * Documents produced by Doxygen are derivative works derived from the

    15  * input used in their production; they are not affected by this license.

    16  *

    17  */

    18 

    19 #ifndef _DOCPARSER_H

    20 #define _DOCPARSER_H

    21 

    22 #include <stdio.h>

    23 

    24 #include <qlist.h>

    25 #include <qstrlist.h>

    26 #include <qstring.h>

    27 

    28 #include "docvisitor.h"

    29 #include "htmlattrib.h"

    30 

    31 class DocNode;

    32 class MemberDef;

    33 class Definition;

    34 class MemberGroup;

    35 class SectionDict;

    36 

    37 //---------------------------------------------------------------------------

    38 

    39 /*! Initialize the documentation parser */

    40 void initDocParser();

    41 /*! Cleanup the documentation parser */

    42 void finializeDocParser();

    43 

    44 /*! Main entry point for the documentation parser.

    45  *  @param fileName  File in which the documentation block is found (or the

    46  *                   name of the example file in case isExample is TRUE).

    47  *  @param startLine Line at which the documentation block is found.

    48  *  @param context   Class or namespace to which this block belongs.

    49  *  @param md        Member definition to which the documentation belongs.

    50  *                   Can be 0.

    51  *  @param input     String representation of the documentation block.

    52  *  @param indexWords Indicates whether or not words should be put in the 

    53  *                   search index.

    54  *  @param isExample TRUE if the documentation belongs to an example.

    55  *  @param exampleName Base name of the example file (0 if isExample is FALSE).

    56  *  @param singleLine Output should be presented on a single line, so without

    57  *                   starting a new paragraph at the end.

    58  *  @param linkFromIndex TRUE if the documentation is generated from an

    59  *                   index page. In this case context is not used to determine

    60  *                   the relative path when making a link.

    61  *  @returns         Root node of the abstract syntax tree. Ownership of the

    62  *                   pointer is handed over to the caller.

    63  */

    64 DocNode *validatingParseDoc(const char *fileName,int startLine,

    65                             Definition *context, MemberDef *md,

    66                             const char *input,bool indexWords,

    67                             bool isExample,const char *exampleName=0,

    68                             bool singleLine=FALSE,bool linkFromIndex=FALSE);

    69 

    70 /*! Main entry point for parsing simple text fragments. These 

    71  *  fragments are limited to words, whitespace and symbols.

    72  */

    73 DocNode *validatingParseText(const char *input);

    74 

    75 /*! Searches for section and anchor commands in the input */

    76 void docFindSections(const char *input,

    77                      Definition *d,

    78                      MemberGroup *m,

    79                      const char *fileName);

    80 

    81 //---------------------------------------------------------------------------

    82 

    83 /*! @brief Abstract node interface with type information. */

    84 class DocNode

    85 {

    86   public:

    87     /*! Available node types. */

    88     enum Kind { Kind_Root           = 0, 

    89                 Kind_Word           = 1, 

    90                 Kind_WhiteSpace     = 2, 

    91                 Kind_Para           = 3, 

    92                 Kind_AutoList       = 4, 

    93                 Kind_AutoListItem   = 5,

    94                 Kind_Symbol         = 6,

    95                 Kind_URL            = 7,

    96                 Kind_StyleChange    = 8,

    97                 Kind_SimpleSect     = 9,

    98                 Kind_Title          = 10,

    99                 Kind_SimpleList     = 11,

   100                 Kind_SimpleListItem = 12,

   101                 Kind_Section        = 13,

   102                 Kind_Verbatim       = 14,

   103                 Kind_XRefItem       = 15,

   104                 Kind_HtmlList       = 16,

   105                 Kind_HtmlListItem   = 17,

   106                 Kind_HtmlDescList   = 18,

   107                 Kind_HtmlDescData   = 19,

   108                 Kind_HtmlDescTitle  = 20,

   109                 Kind_HtmlTable      = 21,

   110                 Kind_HtmlRow        = 22,

   111                 Kind_HtmlCell       = 23,

   112                 Kind_HtmlCaption    = 24,

   113                 Kind_LineBreak      = 25,

   114                 Kind_HorRuler       = 26,

   115                 Kind_Anchor         = 27,

   116                 Kind_IndexEntry     = 28,

   117                 Kind_Internal       = 29,

   118                 Kind_HRef           = 30,

   119                 Kind_Include        = 31,

   120                 Kind_IncOperator    = 32,

   121                 Kind_HtmlHeader     = 33,

   122                 Kind_Image          = 34,

   123                 Kind_DotFile        = 35,

   124                 Kind_Link           = 36,

   125                 Kind_Ref            = 37,

   126                 Kind_Formula        = 38,

   127                 Kind_SecRefItem     = 39,

   128                 Kind_SecRefList     = 40,

   129                 Kind_SimpleSectSep  = 41,

   130                 Kind_LinkedWord     = 42,

   131                 Kind_ParamSect      = 43,

   132                 Kind_ParamList      = 44,

   133                 Kind_InternalRef    = 45,

   134                 Kind_Copy           = 46,

   135                 Kind_Text           = 47

   136               };

   137     /*! Creates a new node */

   138     DocNode() : m_insidePre(FALSE), m_definition(0) {}

   139 

   140     /*! Destroys a node. */

   141     virtual ~DocNode() {}

   142 

   143     /*! Returns the kind of node. Provides runtime type information */

   144     virtual Kind kind() const = 0;

   145 

   146     /*! Returns the parent of this node or 0 for the root node. */

   147     virtual DocNode *parent() const = 0;

   148 

   149     /*! Acceptor function for node visitors. Part of the visitor pattern. 

   150      *  @param v Abstract visitor.

   151      */

   152     virtual void accept(DocVisitor *v) = 0;

   153 

   154     /*! Returns TRUE iff this node is inside a preformatted section */

   155     bool isPreformatted() const { return m_insidePre; }

   156 

   157 	void setDefinition(Definition *definition) { m_definition = definition; }

   158 	Definition* getDefinition() { return m_definition; }

   159   protected:

   160     /*! Sets whether or not this item is inside a preformatted section */

   161     void setInsidePreformatted(bool p) { m_insidePre = p; }

   162   private:

   163 

   164     bool m_insidePre;

   165 	Definition *m_definition;

   166 };

   167 

   168 /*! @brief Default accept implementation for compound nodes in the abstract

   169  *  syntax tree.

   170  */

   171 template<class T> class CompAccept

   172 {

   173   public:

   174     CompAccept() { m_children.setAutoDelete(TRUE); }

   175     virtual ~CompAccept() {}

   176     void accept(T *obj, DocVisitor *v) 

   177     { 

   178       v->visitPre(obj); 

   179       QListIterator<DocNode> cli(m_children);

   180       DocNode *n;

   181       for (cli.toFirst();(n=cli.current());++cli) n->accept(v);

   182       v->visitPost(obj); 

   183     }

   184   

   185   protected:

   186     QList<DocNode> m_children;

   187 };

   188 

   189 

   190 /*! @brief Node representing a word 

   191  */

   192 class DocWord : public DocNode

   193 {

   194   public:

   195     DocWord(DocNode *parent,const QString &word);

   196     QString word() const { return m_word; }

   197     Kind kind() const { return Kind_Word; }

   198     DocNode *parent() const { return m_parent; }

   199     void accept(DocVisitor *v) { v->visit(this); }

   200 

   201   private:

   202     DocNode *m_parent;

   203     QString  m_word;

   204 };

   205 

   206 /*! @brief Node representing a word that can be linked to something

   207  */

   208 class DocLinkedWord : public DocNode

   209 {

   210   public:

   211     DocLinkedWord(DocNode *parent,const QString &word,

   212                   const QString &ref,const QString &file,

   213                   const QString &anchor,const QString &tooltip);

   214     QString word() const       { return m_word; }

   215     Kind kind() const          { return Kind_LinkedWord; }

   216     DocNode *parent() const    { return m_parent; }

   217     QString file() const       { return m_file; }

   218     QString relPath() const    { return m_relPath; }

   219     QString ref() const        { return m_ref; }

   220     QString anchor() const     { return m_anchor; }

   221     QString tooltip() const    { return m_tooltip; }

   222     void accept(DocVisitor *v) { v->visit(this); }

   223 

   224   private:

   225     DocNode *m_parent;

   226     QString  m_word;

   227     QString  m_ref;

   228     QString  m_file;

   229     QString  m_relPath;

   230     QString  m_anchor;

   231     QString  m_tooltip;

   232 };

   233 

   234 /*! @brief Node representing an URL (or email address) */

   235 class DocURL : public DocNode

   236 {

   237   public:

   238     DocURL(DocNode *parent,const QString &url,bool isEmail) : 

   239       m_parent(parent), m_url(url), m_isEmail(isEmail) {}

   240     QString url() const        { return m_url; }

   241     Kind kind() const          { return Kind_URL; }

   242     DocNode *parent() const    { return m_parent; }

   243     void accept(DocVisitor *v) { v->visit(this); }

   244     bool isEmail() const       { return m_isEmail; }

   245 

   246   private:

   247     DocNode *m_parent;

   248     QString  m_url;

   249     bool m_isEmail;

   250 };

   251 

   252 /*! @brief Node representing a line break */

   253 class DocLineBreak : public DocNode

   254 {

   255   public:

   256     DocLineBreak(DocNode *parent) : 

   257       m_parent(parent) {}

   258     Kind kind() const          { return Kind_LineBreak; }

   259     DocNode *parent() const    { return m_parent; }

   260     void accept(DocVisitor *v) { v->visit(this); }

   261 

   262   private:

   263     DocNode *m_parent;

   264 };

   265 

   266 /*! @brief Node representing a horizonal ruler */

   267 class DocHorRuler : public DocNode

   268 {

   269   public:

   270     DocHorRuler(DocNode *parent) : 

   271       m_parent(parent) {}

   272     Kind kind() const          { return Kind_HorRuler; }

   273     DocNode *parent() const    { return m_parent; }

   274     void accept(DocVisitor *v) { v->visit(this); }

   275 

   276   private:

   277     DocNode *m_parent;

   278 };

   279 

   280 /*! @brief Node representing an anchor */

   281 class DocAnchor : public DocNode

   282 {

   283   public:

   284     DocAnchor(DocNode *parent,const QString &id,bool newAnchor);

   285     Kind kind() const          { return Kind_Anchor; }

   286     DocNode *parent() const    { return m_parent; }

   287     QString anchor() const     { return m_anchor; }

   288     QString file() const       { return m_file; }

   289     void accept(DocVisitor *v) { v->visit(this); }

   290 

   291   private:

   292     DocNode *m_parent;

   293     QString  m_anchor;

   294     QString  m_file;

   295 };

   296 

   297 /*! @brief Node representing a style change */

   298 class DocStyleChange : public DocNode

   299 {

   300   public:

   301     enum Style { Bold, Italic, Code, Center, Small, 

   302                  Subscript, Superscript, Preformatted,

   303                  Span, Div

   304                };

   305     DocStyleChange(DocNode *parent,uint position,Style s,bool enable,

   306                    const HtmlAttribList *attribs=0) : 

   307       m_parent(parent), m_position(position), m_style(s), m_enable(enable)

   308       { if (attribs) m_attribs=*attribs; }

   309     Kind kind() const                     { return Kind_StyleChange; }

   310     Style style() const                   { return m_style; }

   311     const char *styleString() const;

   312     bool enable() const                   { return m_enable; }

   313     uint position() const                 { return m_position; }

   314     DocNode *parent() const               { return m_parent; }

   315     void accept(DocVisitor *v)            { v->visit(this); }

   316     const HtmlAttribList &attribs() const { return m_attribs; }

   317 

   318   private:

   319     DocNode *m_parent;

   320     uint     m_position;

   321     Style    m_style;

   322     bool     m_enable;

   323     HtmlAttribList m_attribs;

   324 };

   325 

   326 /*! @brief Node representing a special symbol */

   327 class DocSymbol : public DocNode

   328 {

   329   public:

   330     enum SymType { Unknown=0, BSlash, At, Less, Greater, Amp, Dollar, Hash,

   331                    Percent, Copy, Tm, Reg, Apos, Quot, Uml, Acute, 

   332                    Grave, Circ, Tilde, Szlig, Cedil, Ring, Nbsp, Slash, 

   333                    Lsquo, Rsquo, Ldquo, Rdquo, Ndash, Mdash, Aelig, AElig

   334                  };

   335     DocSymbol(DocNode *parent,SymType s,char letter='\0') : 

   336       m_parent(parent), m_symbol(s), m_letter(letter) {}

   337     SymType symbol() const     { return m_symbol; }

   338     char letter() const        { return m_letter; }

   339     Kind kind() const          { return Kind_Symbol; }

   340     DocNode *parent() const    { return m_parent; }

   341     void accept(DocVisitor *v) { v->visit(this); }

   342     static SymType decodeSymbol(const QString &symName,char *letter);

   343 

   344   private:

   345     DocNode *m_parent;

   346     SymType  m_symbol;

   347     char     m_letter;

   348 };

   349 

   350 /*! @brief Node representing some amount of white space */

   351 class DocWhiteSpace : public DocNode

   352 {

   353   public:

   354     DocWhiteSpace(DocNode *parent,const QString &chars) : 

   355       m_parent(parent), m_chars(chars) {}

   356     Kind kind() const          { return Kind_WhiteSpace; }

   357     QString chars() const      { return m_chars; }

   358     DocNode *parent() const    { return m_parent; }

   359     void accept(DocVisitor *v) { v->visit(this); }

   360   private:

   361     DocNode *m_parent;

   362     QString  m_chars;

   363 };

   364 

   365 /*! @brief Node representing a verbatim, unparsed text fragment */

   366 class DocVerbatim : public DocNode

   367 {

   368   public:

   369     enum Type { Code, HtmlOnly, ManOnly, LatexOnly, XmlOnly, Verbatim, Dot, Msc };

   370     DocVerbatim(DocNode *parent,const QString &context,

   371                 const QString &text, Type t,bool isExample,

   372                 const QString &exampleFile);

   373     Kind kind() const           { return Kind_Verbatim; }

   374     Type type() const           { return m_type; }

   375     QString text() const        { return m_text; }

   376     QString context() const     { return m_context; }

   377     DocNode *parent() const     { return m_parent; }

   378     void accept(DocVisitor *v)  { v->visit(this); }

   379     bool isExample() const      { return m_isExample; }

   380     QString exampleFile() const { return m_exampleFile; }

   381     QString relPath() const     { return m_relPath; }

   382 

   383   private:

   384     DocNode *m_parent;

   385     QString  m_context;

   386     QString  m_text;

   387     Type     m_type;

   388     bool     m_isExample;

   389     QString  m_exampleFile;

   390     QString  m_relPath;

   391 };

   392 

   393 

   394 /*! @brief Node representing an included text block from file */

   395 class DocInclude : public DocNode

   396 {

   397   public:

   398     enum Type { Include, DontInclude, VerbInclude, HtmlInclude, IncWithLines };

   399     DocInclude(DocNode *parent,const QString &file,

   400                const QString context, Type t,

   401                bool isExample,const QString exampleFile) : 

   402       m_parent(parent), m_file(file), m_context(context), m_type(t),

   403       m_isExample(isExample), m_exampleFile(exampleFile) {}

   404     Kind kind() const           { return Kind_Include; }

   405     QString file() const        { return m_file; }

   406     QString extension() const   { int i=m_file.findRev('.'); 

   407                                   if (i!=-1) 

   408                                     return m_file.right(m_file.length()-i); 

   409                                   else 

   410                                     return ""; 

   411                                 }

   412     Type type() const           { return m_type; }

   413     QString text() const        { return m_text; }

   414     QString context() const     { return m_context; }

   415     DocNode *parent() const     { return m_parent; }

   416     bool isExample() const      { return m_isExample; }

   417     QString exampleFile() const { return m_exampleFile; }

   418     void accept(DocVisitor *v)  { v->visit(this); }

   419     void parse();

   420 

   421   private:

   422     DocNode *m_parent;

   423     QString  m_file;

   424     QString  m_context;

   425     QString  m_text;

   426     Type     m_type;

   427     bool     m_isExample;

   428     QString  m_exampleFile;

   429 };

   430 

   431 /*! @brief Node representing a include/dontinclude operator block */

   432 class DocIncOperator : public DocNode

   433 {

   434   public:

   435     enum Type { Line, SkipLine, Skip, Until };

   436     DocIncOperator(DocNode *parent,Type t,const QString &pat,

   437                    const QString &context,bool isExample,const QString &exampleFile) : 

   438       m_parent(parent), m_type(t), m_pattern(pat), m_context(context), 

   439       m_isFirst(FALSE), m_isLast(FALSE),

   440       m_isExample(isExample), m_exampleFile(exampleFile) {}

   441     Kind kind() const           { return Kind_IncOperator; }

   442     Type type() const           { return m_type; }

   443     QString text() const        { return m_text; }

   444     QString pattern() const     { return m_pattern; }

   445     QString context() const     { return m_context; }

   446     DocNode *parent() const     { return m_parent; }

   447     void accept(DocVisitor *v)  { v->visit(this); }

   448     bool isFirst() const        { return m_isFirst; }

   449     bool isLast() const         { return m_isLast; }

   450     void markFirst(bool v=TRUE) { m_isFirst = v; }

   451     void markLast(bool v=TRUE)  { m_isLast = v; }

   452     bool isExample() const      { return m_isExample; }

   453     QString exampleFile() const { return m_exampleFile; }

   454     void parse();

   455 

   456   private:

   457     DocNode *m_parent;

   458     Type     m_type;

   459     QString  m_text;

   460     QString  m_pattern;

   461     QString  m_context;

   462     bool     m_isFirst;

   463     bool     m_isLast;

   464     bool     m_isExample;

   465     QString  m_exampleFile;

   466 };

   467 

   468 /*! @brief Node representing an item of a cross-referenced list */

   469 class DocFormula : public DocNode

   470 {

   471   public:

   472     DocFormula(DocNode *parent,int id);

   473     Kind kind() const          { return Kind_Formula; }

   474     QString name() const       { return m_name; }

   475     QString text() const       { return m_text; }

   476     QString relPath() const    { return m_relPath; }

   477     int id() const             { return m_id; }

   478     DocNode *parent() const    { return m_parent; }

   479     void accept(DocVisitor *v) { v->visit(this); }

   480     bool isInline()            { return text().at(0)!='\\'; }

   481 

   482   private:

   483     DocNode *m_parent;

   484     QString  m_name;

   485     QString  m_text;

   486     QString  m_relPath;

   487     int      m_id;

   488 };

   489 

   490 /*! @brief Node representing an entry in the index. */

   491 class DocIndexEntry : public DocNode

   492 {

   493   public:

   494     DocIndexEntry(DocNode *parent,Definition *scope,MemberDef *md) 

   495       : m_parent(parent), m_scope(scope), m_member(md) { }

   496     Kind kind() const { return Kind_IndexEntry; }

   497     int parse();

   498     DocNode *parent() const      { return m_parent; }

   499     Definition *scope() const    { return m_scope;  }

   500     MemberDef *member() const    { return m_member; }

   501     QString entry() const        { return m_entry;  }

   502     void accept(DocVisitor *v)   { v->visit(this);  }

   503 

   504   private:

   505     DocNode    *m_parent;

   506     QString     m_entry;

   507     Definition *m_scope;

   508     MemberDef  *m_member;

   509 };

   510 

   511 //-----------------------------------------------------------------------

   512 

   513 /*! @brief Node representing a copy of documentation block. */

   514 class DocCopy : public CompAccept<DocCopy>, public DocNode

   515 {

   516   public:

   517     DocCopy(DocNode *parent,const QString &link,bool copyBrief,bool copyDetails) 

   518       : m_parent(parent), m_link(link), 

   519         m_copyBrief(copyBrief), m_copyDetails(copyDetails) { }

   520     Kind kind() const          { return Kind_IndexEntry; }

   521     QString link() const       { return m_link; }

   522     DocNode *parent() const    { return m_parent; }

   523     void accept(DocVisitor *v) { CompAccept<DocCopy>::accept(this,v); }

   524     void parse();

   525 

   526   private:

   527     DocNode *m_parent;

   528     QString  m_link;

   529     bool     m_copyBrief;

   530     bool     m_copyDetails;

   531 };

   532 

   533 /*! @brief Node representing an auto List */

   534 class DocAutoList : public CompAccept<DocAutoList>, public DocNode

   535 {

   536   public:

   537     DocAutoList(DocNode *parent,int indent,bool isEnumList,

   538                 int depth) : 

   539       m_parent(parent), m_indent(indent), m_isEnumList(isEnumList),

   540       m_depth(depth) {}

   541     Kind kind() const          { return Kind_AutoList; }

   542     bool isEnumList() const    { return m_isEnumList; }

   543     int  indent() const        { return m_indent; }

   544     DocNode *parent() const    { return m_parent; }

   545     int depth() const          { return m_depth; }

   546     void accept(DocVisitor *v) { CompAccept<DocAutoList>::accept(this,v); }

   547     int parse();

   548 

   549   private:

   550     DocNode *m_parent;

   551     int      m_indent;

   552     bool     m_isEnumList;

   553     int      m_depth;

   554 };

   555 

   556 

   557 /*! @brief Node representing a simple section title */

   558 class DocTitle : public CompAccept<DocTitle>, public DocNode

   559 {

   560   public:

   561     DocTitle(DocNode *parent) : m_parent(parent) {}

   562     void parse();

   563     void parseFromString(const QString &title);

   564     Kind kind() const          { return Kind_Title; }

   565     DocNode *parent() const    { return m_parent; }

   566     void accept(DocVisitor *v) { CompAccept<DocTitle>::accept(this,v); }

   567 

   568   private:

   569     DocNode *m_parent;

   570 };

   571 

   572 /*! @brief Node representing an item of a cross-referenced list */

   573 class DocXRefItem : public CompAccept<DocXRefItem>, public DocNode

   574 {

   575   public:

   576     //enum Type { Bug, Test, Todo, Deprecated };

   577     DocXRefItem(DocNode *parent,int id,const char *key);

   578     Kind kind() const          { return Kind_XRefItem; }

   579     QString file() const       { return m_file; }

   580     QString anchor() const     { return m_anchor; }

   581     QString title() const      { return m_title; }

   582     DocNode *parent() const    { return m_parent; }

   583     QString relPath() const    { return m_relPath; }

   584     QString key() const        { return m_key; }

   585     void accept(DocVisitor *v) { CompAccept<DocXRefItem>::accept(this,v); }

   586     bool parse();

   587     const QList<DocNode> &children() const { return m_children; }

   588 

   589   private:

   590     DocNode *m_parent;

   591     int      m_id;

   592     QString  m_key;

   593     QString  m_file;

   594     QString  m_anchor;

   595     QString  m_title;

   596     QString  m_relPath;

   597 };

   598 

   599 /*! @brief Node representing an image */

   600 class DocImage : public CompAccept<DocImage>, public DocNode

   601 {

   602   public:

   603     enum Type { Html, Latex, Rtf };

   604     DocImage(DocNode *parent,const HtmlAttribList &attribs,const QString &name,Type t);

   605     Kind kind() const          { return Kind_Image; }

   606     Type type() const          { return m_type; }

   607     QString name() const       { return m_name; }

   608     DocNode *parent() const    { return m_parent; }

   609     bool hasCaption() const    { return !m_children.isEmpty(); }

   610     QString width() const      { return m_width; }

   611     QString height() const     { return m_height; }

   612     QString relPath() const    { return m_relPath; }

   613     const HtmlAttribList &attribs() const { return m_attribs; }

   614     void accept(DocVisitor *v) { CompAccept<DocImage>::accept(this,v); }

   615     void parse();

   616 

   617   private:

   618     DocNode *m_parent;

   619     HtmlAttribList m_attribs;

   620     QString  m_name;

   621     Type     m_type;

   622     QString  m_width;

   623     QString  m_height;

   624     QString  m_relPath;

   625 };

   626 

   627 /*! @brief Node representing a dot file */

   628 class DocDotFile : public CompAccept<DocDotFile>, public DocNode

   629 {

   630   public:

   631     DocDotFile(DocNode *parent,const QString &name,const QString &context);

   632     void parse();

   633     Kind kind() const          { return Kind_DotFile; }

   634     QString name() const       { return m_name; }

   635     QString file() const       { return m_file; }

   636     QString relPath() const    { return m_relPath; }

   637     bool hasCaption() const    { return !m_children.isEmpty(); }

   638     QString width() const      { return m_width; }

   639     QString height() const     { return m_height; }

   640     DocNode *parent() const    { return m_parent; }

   641     QString context() const    { return m_context; }

   642     void accept(DocVisitor *v) { CompAccept<DocDotFile>::accept(this,v); }

   643   private:

   644     DocNode *m_parent;

   645     QString  m_name;

   646     QString  m_file;

   647     QString  m_relPath;

   648     QString  m_width;

   649     QString  m_height;

   650     QString  m_context;

   651 };

   652 

   653 /*! @brief Node representing a link to some item */

   654 class DocLink : public CompAccept<DocLink>, public DocNode

   655 {

   656   public:

   657     DocLink(DocNode *parent,const QString &target);

   658     QString parse(bool,bool isXmlLink=FALSE);

   659     Kind kind() const          { return Kind_Link; }

   660     QString file() const       { return m_file; }

   661     QString relPath() const    { return m_relPath; }

   662     QString ref() const        { return m_ref; }

   663     QString anchor() const     { return m_anchor; }

   664     DocNode *parent() const    { return m_parent; }

   665     void accept(DocVisitor *v) { CompAccept<DocLink>::accept(this,v); }

   666 

   667   private:

   668     DocNode *m_parent;

   669     QString  m_file;

   670     QString  m_relPath;

   671     QString  m_ref;

   672     QString  m_anchor;

   673     QString  m_refText;

   674 };

   675 

   676 /*! @brief Node representing a reference to some item */

   677 class DocRef : public CompAccept<DocRef>, public DocNode

   678 {

   679   public:

   680     DocRef(DocNode *parent,const QString &target,const QString &context);

   681     void parse();

   682     Kind kind() const            { return Kind_Ref; }

   683     QString file() const         { return m_file; }

   684     QString relPath() const      { return m_relPath; }

   685     QString ref() const          { return m_ref; }

   686     QString anchor() const       { return m_anchor; }

   687     QString targetTitle() const  { return m_text; }

   688     DocNode *parent() const      { return m_parent; }

   689     bool hasLinkText() const     { return !m_children.isEmpty(); }

   690     bool refToAnchor() const     { return m_refToAnchor; }

   691     bool refToSection() const    { return m_refToSection; }

   692     void accept(DocVisitor *v)   { CompAccept<DocRef>::accept(this,v); }

   693 

   694   private:

   695     DocNode * m_parent;

   696     bool      m_refToSection;

   697     bool      m_refToAnchor;

   698     QString   m_file;

   699     QString   m_relPath;

   700     QString   m_ref;

   701     QString   m_anchor;

   702     QString   m_text;

   703 };

   704 

   705 /*! @brief Node representing an internal reference to some item */

   706 class DocInternalRef : public CompAccept<DocInternalRef>, public DocNode

   707 {

   708   public:

   709     DocInternalRef(DocNode *parent,const QString &target);

   710     void parse();

   711     Kind kind() const            { return Kind_Ref; }

   712     QString file() const         { return m_file; }

   713     QString relPath() const      { return m_relPath; }

   714     QString anchor() const       { return m_anchor; }

   715     DocNode *parent() const      { return m_parent; }

   716     void accept(DocVisitor *v)   { CompAccept<DocInternalRef>::accept(this,v); }

   717 

   718   private:

   719     DocNode * m_parent;

   720     QString   m_file;

   721     QString   m_relPath;

   722     QString   m_anchor;

   723 };

   724 

   725 /*! @brief Node representing a Language specific section */

   726 //class DocLanguage : public CompAccept<DocLanguage>, public DocNode

   727 //{

   728 //  public:

   729 //    DocLanguage(DocNode *parent,const QString &id) : 

   730 //      m_parent(parent), m_id(id) {}

   731 //    QString id() const         { return m_id; }

   732 //    Kind kind() const          { return Kind_Language; }

   733 //    DocNode *parent() const    { return m_parent; }

   734 //    void accept(DocVisitor *v) { CompAccept<DocLanguage>::accept(this,v); }

   735 //    int parse();

   736 //    

   737 //  private:

   738 //    DocNode * m_parent;

   739 //    QString   m_id;

   740 //};

   741 

   742 /*! @brief Node representing a Hypertext reference */

   743 class DocHRef : public CompAccept<DocHRef>, public DocNode

   744 {

   745   public:

   746     DocHRef(DocNode *parent,const HtmlAttribList &attribs,const QString &url) : 

   747       m_parent(parent), m_attribs(attribs), m_url(url) {}

   748     int parse();

   749     QString url() const        { return m_url; }

   750     Kind kind() const          { return Kind_HRef; }

   751     DocNode *parent() const    { return m_parent; }

   752     void accept(DocVisitor *v) { CompAccept<DocHRef>::accept(this,v); }

   753     const HtmlAttribList &attribs() const { return m_attribs; }

   754 

   755   private:

   756     DocNode * m_parent;

   757     HtmlAttribList m_attribs;

   758     QString   m_url;

   759 };

   760 

   761 /*! @brief Node Html heading */

   762 class DocHtmlHeader : public CompAccept<DocHtmlHeader>, public DocNode

   763 {

   764   public:

   765     DocHtmlHeader(DocNode *parent,const HtmlAttribList &attribs,int level) : 

   766        m_parent(parent), m_level(level), m_attribs(attribs) {}

   767     int level() const                     { return m_level; }

   768     Kind kind() const                     { return Kind_HtmlHeader; }

   769     const HtmlAttribList &attribs() const { return m_attribs; }

   770     DocNode *parent() const               { return m_parent; }

   771     void accept(DocVisitor *v) { CompAccept<DocHtmlHeader>::accept(this,v); }

   772     int parse();

   773 

   774   private:

   775     DocNode *     m_parent;

   776     int           m_level;

   777     HtmlAttribList m_attribs;

   778 };

   779 

   780 /*! @brief Node representing a Html description item */

   781 class DocHtmlDescTitle : public CompAccept<DocHtmlDescTitle>, public DocNode

   782 {

   783   public:

   784     DocHtmlDescTitle(DocNode *parent,const HtmlAttribList &attribs) : 

   785       m_parent(parent), m_attribs(attribs) {}

   786     Kind kind() const                     { return Kind_HtmlDescTitle; }

   787     DocNode *parent() const               { return m_parent; }

   788     const HtmlAttribList &attribs() const { return m_attribs; }

   789     void accept(DocVisitor *v) { CompAccept<DocHtmlDescTitle>::accept(this,v); }

   790     int parse();

   791 

   792   private:

   793     DocNode *     m_parent;

   794     HtmlAttribList m_attribs;

   795 };

   796 

   797 /*! @brief Node representing a Html description list */

   798 class DocHtmlDescList : public CompAccept<DocHtmlDescList>, public DocNode

   799 {

   800   public:

   801     DocHtmlDescList(DocNode *parent,const HtmlAttribList &attribs) 

   802       : m_parent(parent), m_attribs(attribs) {}

   803     Kind kind() const                     { return Kind_HtmlDescList; }

   804     DocNode *parent() const               { return m_parent; }

   805     const HtmlAttribList &attribs() const { return m_attribs; }

   806     void accept(DocVisitor *v) { CompAccept<DocHtmlDescList>::accept(this,v); }

   807     int parse();

   808 

   809   private:

   810     DocNode *     m_parent;

   811     HtmlAttribList m_attribs;

   812 };

   813 

   814 /*! @brief Node representing a normal section */

   815 class DocSection : public CompAccept<DocSection>, public DocNode

   816 {

   817   public:

   818     DocSection(DocNode *parent,int level,const QString &id) :

   819       m_parent(parent), m_level(level), m_id(id) {} 

   820     Kind kind() const          { return Kind_Section; }

   821     int level() const          { return m_level; }

   822     QString title() const      { return m_title; }

   823     QString anchor() const     { return m_anchor; }

   824     QString id() const         { return m_id; }

   825     QString file() const       { return m_file; }

   826     DocNode *parent() const    { return m_parent; }

   827     void accept(DocVisitor *v) { CompAccept<DocSection>::accept(this,v); }

   828     int parse();

   829 

   830   private:

   831     DocNode *m_parent;

   832     int      m_level;

   833     QString  m_id;

   834     QString  m_title;

   835     QString  m_anchor;

   836     QString  m_file;

   837 };

   838 

   839 /*! @brief Node representing a reference to a section */

   840 class DocSecRefItem : public CompAccept<DocSecRefItem>, public DocNode

   841 {

   842   public:

   843     DocSecRefItem(DocNode *parent,const QString &target) : 

   844       m_parent(parent), m_target(target) {}

   845     Kind kind() const          { return Kind_SecRefItem; }

   846     QString target() const     { return m_target; }

   847     QString file() const       { return m_file; }

   848     QString anchor() const     { return m_anchor; }

   849     DocNode *parent() const    { return m_parent; }

   850     void accept(DocVisitor *v) { CompAccept<DocSecRefItem>::accept(this,v); }

   851     void parse();

   852     const QList<DocNode> &children() const { return m_children; }

   853 

   854   private:

   855     DocNode *m_parent;

   856     QString  m_target;

   857     QString  m_file;

   858     QString  m_anchor;

   859 };

   860 

   861 /*! @brief Node representing a list of section references */

   862 class DocSecRefList : public CompAccept<DocSecRefList>, public DocNode

   863 {

   864   public:

   865     DocSecRefList(DocNode *parent) : m_parent(parent) {}

   866     void parse();

   867     Kind kind() const          { return Kind_SecRefList; }

   868     DocNode *parent() const    { return m_parent; }

   869     void accept(DocVisitor *v) { CompAccept<DocSecRefList>::accept(this,v); }

   870 

   871   private:

   872     DocNode  *m_parent;

   873 };

   874 

   875 /*! @brief Node representing an internal section of documentation */

   876 class DocInternal : public CompAccept<DocInternal>, public DocNode

   877 {

   878   public:

   879     DocInternal(DocNode *parent) : m_parent(parent) {}

   880     int parse(int);

   881     Kind kind() const          { return Kind_Internal; }

   882     DocNode *parent() const    { return m_parent; }

   883     void accept(DocVisitor *v) { CompAccept<DocInternal>::accept(this,v); }

   884 

   885   private:

   886     DocNode  *m_parent;

   887 };

   888 

   889 /*! @brief Node representing a simple list */

   890 class DocSimpleList : public CompAccept<DocSimpleList>, public DocNode

   891 {

   892   public:

   893     DocSimpleList(DocNode *parent) : m_parent(parent) {}

   894     Kind kind() const          { return Kind_SimpleList; }

   895     DocNode *parent() const    { return m_parent; }

   896     void accept(DocVisitor *v) { CompAccept<DocSimpleList>::accept(this,v); }

   897     int parse();

   898 

   899   private:

   900     DocNode *m_parent;

   901 };

   902 

   903 /*! @brief Node representing a Html list */

   904 class DocHtmlList : public CompAccept<DocHtmlList>, public DocNode

   905 {

   906   public:

   907     enum Type { Unordered, Ordered };

   908     DocHtmlList(DocNode *parent,const HtmlAttribList &attribs,Type t) : 

   909       m_parent(parent), m_type(t), m_attribs(attribs) {}

   910     Kind kind() const          { return Kind_HtmlList; }

   911     Type type() const          { return m_type; }

   912     DocNode *parent() const    { return m_parent; }

   913     void accept(DocVisitor *v) { CompAccept<DocHtmlList>::accept(this,v); }

   914     const HtmlAttribList &attribs() const { return m_attribs; }

   915     int parse();

   916     int parseXml();

   917 

   918   private:

   919     DocNode *     m_parent;

   920     Type          m_type;

   921     HtmlAttribList m_attribs;

   922 };

   923 

   924 /*! Node representing a simple section */

   925 class DocSimpleSect : public CompAccept<DocSimpleSect>, public DocNode

   926 {

   927   public:

   928     enum Type 

   929     {  

   930        Unknown, See, Return, Author, Authors, Version, Since, Date,

   931        Note, Warning, Pre, Post, Invar, Remark, Attention, User, Rcs

   932     };

   933     DocSimpleSect(DocNode *parent,Type t);

   934     virtual ~DocSimpleSect();

   935     Kind kind() const       { return Kind_SimpleSect; }

   936     Type type() const       { return m_type; }

   937     QCString typeString() const;

   938     DocNode *parent() const { return m_parent; }

   939     void accept(DocVisitor *v);

   940     int parse(bool userTitle,bool needsSeparator);

   941     int parseRcs();

   942     int parseXml();

   943     void appendLinkWord(const QString &word);

   944     const QList<DocNode> &children() const { return m_children; }

   945 

   946   private:

   947     DocNode *       m_parent;

   948     Type            m_type;

   949     DocTitle *      m_title;

   950 };

   951 

   952 /*! Node representing a separator between two simple sections of the

   953  *  same type. 

   954  */

   955 class DocSimpleSectSep : public DocNode

   956 {

   957   public:

   958     DocSimpleSectSep(DocNode *parent) : m_parent(parent) {}

   959     Kind kind() const { return Kind_SimpleSectSep; }

   960     DocNode *parent() const { return m_parent; }

   961     void accept(DocVisitor *v) { v->visit(this); }

   962 

   963   private:

   964     DocNode *m_parent;

   965 };

   966 

   967 /*! Node representing a parameter section */

   968 class DocParamSect : public CompAccept<DocParamSect>, public DocNode

   969 {

   970   public:

   971     enum Type 

   972     {  

   973        Unknown, Param, RetVal, Exception, TemplateParam

   974     };

   975     enum Direction

   976     {

   977        In=1, Out=2, InOut=3, Unspecified=0

   978     };

   979     DocParamSect(DocNode *parent,Type t) 

   980       : m_parent(parent), m_type(t) {}

   981     int parse(const QString &cmdName,bool xmlContext,Direction d);

   982     Kind kind() const          { return Kind_ParamSect; }

   983     Type type() const          { return m_type; }

   984     DocNode *parent() const    { return m_parent; }

   985     void accept(DocVisitor *v) { CompAccept<DocParamSect>::accept(this,v); }

   986 

   987   private:

   988     DocNode *       m_parent;

   989     Type            m_type;

   990     Direction       m_dir;

   991 };

   992 

   993 /*! Node representing a paragraph in the documentation tree */

   994 class DocPara : public CompAccept<DocPara>, public DocNode

   995 {

   996   public:

   997     DocPara(DocNode *parent) : m_parent(parent), 

   998              m_isFirst(FALSE), m_isLast(FALSE) {}

   999     int parse();

  1000     Kind kind() const           { return Kind_Para; }

  1001     DocNode *parent() const     { return m_parent; }

  1002     bool isEmpty() const        { return m_children.isEmpty(); }

  1003     void accept(DocVisitor *v)  { CompAccept<DocPara>::accept(this,v); }

  1004     void markFirst(bool v=TRUE) { m_isFirst=v; }

  1005     void markLast(bool v=TRUE)  { m_isLast=v; }

  1006     bool isFirst() const        { return m_isFirst; }

  1007     bool isLast() const         { return m_isLast; }

  1008     const QList<DocNode> &children() const { return m_children; }

  1009     QList<DocNode> &children()  { return m_children; }

  1010 

  1011     int handleCommand(const QString &cmdName);

  1012     int handleHtmlStartTag(const QString &tagName,const HtmlAttribList &tagHtmlAttribs);

  1013     int handleHtmlEndTag(const QString &tagName);

  1014     int handleSimpleSection(DocSimpleSect::Type t,bool xmlContext=FALSE);

  1015     int handleXRefItem();

  1016     int handleParamSection(const QString &cmdName,DocParamSect::Type t,

  1017                            bool xmlContext,

  1018                            int direction);

  1019     void handleIncludeOperator(const QString &cmdName,DocIncOperator::Type t);

  1020     void handleImage(const QString &cmdName);

  1021     void handleDotFile(const QString &cmdName);

  1022     void handleInclude(const QString &cmdName,DocInclude::Type t);

  1023     void handleLink(const QString &cmdName,bool isJavaLink);

  1024     void handleRef(const QString &cmdName);

  1025     void handleSection(const QString &cmdName);

  1026     void handleInheritDoc();

  1027     int handleStartCode();

  1028     int handleHtmlHeader(const HtmlAttribList &tagHtmlAttribs,int level);

  1029     bool injectToken(int tok,const QString &tokText);

  1030 

  1031   private:

  1032     DocNode *m_parent;

  1033     QString  m_sectionId;

  1034     bool     m_isFirst;

  1035     bool     m_isLast;

  1036 };

  1037 

  1038 /*! @brief Node representing a parameter list. */

  1039 class DocParamList : public DocNode

  1040 {

  1041   public:

  1042     DocParamList(DocNode *parent,DocParamSect::Type t,DocParamSect::Direction d) 

  1043       : m_parent(parent) , m_type(t), m_dir(d), m_isFirst(TRUE), m_isLast(TRUE)

  1044     { m_paragraphs.setAutoDelete(TRUE); }

  1045     virtual ~DocParamList()         { }

  1046     Kind kind() const               { return Kind_ParamList; }

  1047     DocNode *parent() const         { return m_parent; }

  1048     const QList<DocNode> &parameters()    { return m_params; }

  1049     DocParamSect::Type type() const { return m_type; }

  1050     DocParamSect::Direction direction() const { return m_dir; }

  1051     void markFirst(bool b=TRUE)     { m_isFirst=b; }

  1052     void markLast(bool b=TRUE)      { m_isLast=b; }

  1053     bool isFirst() const            { return m_isFirst; }

  1054     bool isLast() const             { return m_isLast; }

  1055     void accept(DocVisitor *v)

  1056     { 

  1057       v->visitPre(this); 

  1058       QListIterator<DocPara> cli(m_paragraphs);

  1059       DocNode *n;

  1060       for (cli.toFirst();(n=cli.current());++cli) n->accept(v);

  1061       v->visitPost(this); 

  1062     }

  1063     int parse(const QString &cmdName);

  1064     int parseXml(const QString &paramName);

  1065 

  1066   private:

  1067     DocNode *               m_parent;

  1068     QList<DocPara>          m_paragraphs;

  1069     QList<DocNode>          m_params;

  1070     DocParamSect::Type      m_type;

  1071     DocParamSect::Direction m_dir;

  1072     bool                    m_isFirst;

  1073     bool                    m_isLast;

  1074 };

  1075 

  1076 /*! @brief Node representing an item of a auto list */

  1077 class DocAutoListItem : public DocNode

  1078 {

  1079   public:

  1080     DocAutoListItem(DocNode *parent,int num) : m_parent(parent), m_itemNum(num)

  1081     { m_paragraph=new DocPara(this); }

  1082     virtual ~DocAutoListItem() { delete m_paragraph; }

  1083     Kind kind() const          { return Kind_AutoListItem; }

  1084     DocNode *parent() const    { return m_parent; }

  1085     int itemNumber() const     { return m_itemNum; }

  1086     void accept(DocVisitor *v) 

  1087     { 

  1088       v->visitPre(this); 

  1089       m_paragraph->accept(v);

  1090       v->visitPost(this); 

  1091     }

  1092     int parse();

  1093 

  1094   private:

  1095     DocNode *m_parent;

  1096     DocPara *m_paragraph;

  1097     int m_itemNum;

  1098 };

  1099 

  1100 /*! @brief Node representing a simple list item */

  1101 class DocSimpleListItem : public DocNode

  1102 {

  1103   public:

  1104     DocSimpleListItem(DocNode *parent) : m_parent(parent) 

  1105     { m_paragraph=new DocPara(this); }

  1106     int parse();

  1107     virtual ~DocSimpleListItem() { delete m_paragraph; }

  1108     Kind kind() const            { return Kind_SimpleListItem; }

  1109     DocNode *parent() const      { return m_parent; }

  1110     void accept(DocVisitor *v)

  1111     {

  1112       v->visitPre(this); 

  1113       m_paragraph->accept(v);

  1114       v->visitPost(this); 

  1115     }

  1116 

  1117   private:

  1118     DocNode *m_parent;

  1119     DocPara *m_paragraph;

  1120 };

  1121 

  1122 /*! @brief Node representing a HTML list item */

  1123 class DocHtmlListItem : public CompAccept<DocHtmlListItem>, public DocNode

  1124 {

  1125   public:

  1126     DocHtmlListItem(DocNode *parent,const HtmlAttribList &attribs,int num) : 

  1127       m_parent(parent), m_attribs(attribs), m_itemNum(num) {}

  1128     Kind kind() const                     { return Kind_HtmlListItem; }

  1129     int itemNumber() const                { return m_itemNum; }

  1130     const HtmlAttribList &attribs() const { return m_attribs; }

  1131     DocNode *parent() const               { return m_parent; }

  1132     void accept(DocVisitor *v) { CompAccept<DocHtmlListItem>::accept(this,v); }

  1133     int parse();

  1134     int parseXml();