/******************************************************************************

 *

 * 

 *

 *

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

 *

 * 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.

 *

 * Documents produced by Doxygen are derivative works derived from the

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

 *

 */

#ifndef _DOCPARSER_H

#define _DOCPARSER_H

#include <stdio.h>

#include <qlist.h>

#include <qstrlist.h>

#include <qstring.h>

#include "docvisitor.h"

#include "htmlattrib.h"

class DocNode;

class MemberDef;

class Definition;

class MemberGroup;

class SectionDict;

//---------------------------------------------------------------------------

/*! Initialize the documentation parser */

void initDocParser();

/*! Cleanup the documentation parser */

void finializeDocParser();

/*! Main entry point for the documentation parser.

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

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

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

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

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

 *                   Can be 0.

 *  @param input     String representation of the documentation block.

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

 *                   search index.

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

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

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

 *                   starting a new paragraph at the end.

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

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

 *                   the relative path when making a link.

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

 *                   pointer is handed over to the caller.

 */

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

                            Definition *context, MemberDef *md,

                            const char *input,bool indexWords,

                            bool isExample,const char *exampleName=0,

                            bool singleLine=FALSE,bool linkFromIndex=FALSE);

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

 *  fragments are limited to words, whitespace and symbols.

 */

DocNode *validatingParseText(const char *input);

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

void docFindSections(const char *input,

                     Definition *d,

                     MemberGroup *m,

                     const char *fileName);

//---------------------------------------------------------------------------

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

class DocNode

{

  public:

    /*! Available node types. */

    enum Kind { Kind_Root           = 0, 

                Kind_Word           = 1, 

                Kind_WhiteSpace     = 2, 

                Kind_Para           = 3, 

                Kind_AutoList       = 4, 

                Kind_AutoListItem   = 5,

                Kind_Symbol         = 6,

                Kind_URL            = 7,

                Kind_StyleChange    = 8,

                Kind_SimpleSect     = 9,

                Kind_Title          = 10,

                Kind_SimpleList     = 11,

                Kind_SimpleListItem = 12,

                Kind_Section        = 13,

                Kind_Verbatim       = 14,

                Kind_XRefItem       = 15,

                Kind_HtmlList       = 16,

                Kind_HtmlListItem   = 17,

                Kind_HtmlDescList   = 18,

                Kind_HtmlDescData   = 19,

                Kind_HtmlDescTitle  = 20,

                Kind_HtmlTable      = 21,

                Kind_HtmlRow        = 22,

                Kind_HtmlCell       = 23,

                Kind_HtmlCaption    = 24,

                Kind_LineBreak      = 25,

                Kind_HorRuler       = 26,

                Kind_Anchor         = 27,

                Kind_IndexEntry     = 28,

                Kind_Internal       = 29,

                Kind_HRef           = 30,

                Kind_Include        = 31,

                Kind_IncOperator    = 32,

                Kind_HtmlHeader     = 33,

                Kind_Image          = 34,

                Kind_DotFile        = 35,

                Kind_Link           = 36,

                Kind_Ref            = 37,

                Kind_Formula        = 38,

                Kind_SecRefItem     = 39,

                Kind_SecRefList     = 40,

                Kind_SimpleSectSep  = 41,

                Kind_LinkedWord     = 42,

                Kind_ParamSect      = 43,

                Kind_ParamList      = 44,

                Kind_InternalRef    = 45,

                Kind_Copy           = 46,

                Kind_Text           = 47

              };

    /*! Creates a new node */

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

    /*! Destroys a node. */

    virtual ~DocNode() {}

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

    virtual Kind kind() const = 0;

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

    virtual DocNode *parent() const = 0;

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

     *  @param v Abstract visitor.

     */

    virtual void accept(DocVisitor *v) = 0;

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

    bool isPreformatted() const { return m_insidePre; }

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

	Definition* getDefinition() { return m_definition; }

  protected:

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

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

  private:

    bool m_insidePre;

	Definition *m_definition;

};

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

 *  syntax tree.

 */

template<class T> class CompAccept

{

  public:

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

    virtual ~CompAccept() {}

    void accept(T *obj, DocVisitor *v) 

    { 

      v->visitPre(obj); 

      QListIterator<DocNode> cli(m_children);

      DocNode *n;

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

      v->visitPost(obj); 

    }

  protected:

    QList<DocNode> m_children;

};

/*! @brief Node representing a word 

 */

class DocWord : public DocNode

{

  public:

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

    QString word() const { return m_word; }

    Kind kind() const { return Kind_Word; }

    DocNode *parent() const { return m_parent; }

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

  private:

    DocNode *m_parent;

    QString  m_word;

};

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

 */

class DocLinkedWord : public DocNode

{

  public:

    DocLinkedWord(DocNode *parent,const QString &word,

                  const QString &ref,const QString &file,

                  const QString &anchor,const QString &tooltip);

    QString word() const       { return m_word; }

    Kind kind() const          { return Kind_LinkedWord; }

    DocNode *parent() const    { return m_parent; }

    QString file() const       { return m_file; }

    QString relPath() const    { return m_relPath; }

    QString ref() const        { return m_ref; }

    QString anchor() const     { return m_anchor; }

    QString tooltip() const    { return m_tooltip; }

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

  private:

    DocNode *m_parent;

    QString  m_word;

    QString  m_ref;

    QString  m_file;

    QString  m_relPath;

    QString  m_anchor;

    QString  m_tooltip;

};

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

class DocURL : public DocNode

{

  public:

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

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

    QString url() const        { return m_url; }

    Kind kind() const          { return Kind_URL; }

    DocNode *parent() const    { return m_parent; }

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

    bool isEmail() const       { return m_isEmail; }

  private:

    DocNode *m_parent;

    QString  m_url;

    bool m_isEmail;

};

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

class DocLineBreak : public DocNode

{

  public:

    DocLineBreak(DocNode *parent) : 

      m_parent(parent) {}

    Kind kind() const          { return Kind_LineBreak; }

    DocNode *parent() const    { return m_parent; }

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

  private:

    DocNode *m_parent;

};

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

class DocHorRuler : public DocNode

{

  public:

    DocHorRuler(DocNode *parent) : 

      m_parent(parent) {}

    Kind kind() const          { return Kind_HorRuler; }

    DocNode *parent() const    { return m_parent; }

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

  private:

    DocNode *m_parent;

};

/*! @brief Node representing an anchor */

class DocAnchor : public DocNode

{

  public:

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

    Kind kind() const          { return Kind_Anchor; }

    DocNode *parent() const    { return m_parent; }

    QString anchor() const     { return m_anchor; }

    QString file() const       { return m_file; }

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

  private:

    DocNode *m_parent;

    QString  m_anchor;

    QString  m_file;

};

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

class DocStyleChange : public DocNode

{

  public:

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

                 Subscript, Superscript, Preformatted,

                 Span, Div

               };

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

                   const HtmlAttribList *attribs=0) : 

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

      { if (attribs) m_attribs=*attribs; }

    Kind kind() const                     { return Kind_StyleChange; }

    Style style() const                   { return m_style; }

    const char *styleString() const;

    bool enable() const                   { return m_enable; }

    uint position() const                 { return m_position; }

    DocNode *parent() const               { return m_parent; }

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

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

  private:

    DocNode *m_parent;

    uint     m_position;

    Style    m_style;

    bool     m_enable;

    HtmlAttribList m_attribs;

};

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

class DocSymbol : public DocNode

{

  public:

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

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

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

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

                 };

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

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

    SymType symbol() const     { return m_symbol; }

    char letter() const        { return m_letter; }

    Kind kind() const          { return Kind_Symbol; }

    DocNode *parent() const    { return m_parent; }

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

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

  private:

    DocNode *m_parent;

    SymType  m_symbol;

    char     m_letter;

};

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

class DocWhiteSpace : public DocNode

{

  public:

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

      m_parent(parent), m_chars(chars) {}

    Kind kind() const          { return Kind_WhiteSpace; }

    QString chars() const      { return m_chars; }

    DocNode *parent() const    { return m_parent; }

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

  private:

    DocNode *m_parent;

    QString  m_chars;

};

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

class DocVerbatim : public DocNode

{

  public:

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

    DocVerbatim(DocNode *parent,const QString &context,

                const QString &text, Type t,bool isExample,

                const QString &exampleFile);

    Kind kind() const           { return Kind_Verbatim; }

    Type type() const           { return m_type; }

    QString text() const        { return m_text; }

    QString context() const     { return m_context; }

    DocNode *parent() const     { return m_parent; }

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

    bool isExample() const      { return m_isExample; }

    QString exampleFile() const { return m_exampleFile; }

    QString relPath() const     { return m_relPath; }

  private:

    DocNode *m_parent;

    QString  m_context;

    QString  m_text;

    Type     m_type;

    bool     m_isExample;

    QString  m_exampleFile;

    QString  m_relPath;

};

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

class DocInclude : public DocNode

{

  public:

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

    DocInclude(DocNode *parent,const QString &file,

               const QString context, Type t,

               bool isExample,const QString exampleFile) : 

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

      m_isExample(isExample), m_exampleFile(exampleFile) {}

    Kind kind() const           { return Kind_Include; }

    QString file() const        { return m_file; }

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

                                  if (i!=-1) 

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

                                  else 

                                    return ""; 

                                }

    Type type() const           { return m_type; }

    QString text() const        { return m_text; }

    QString context() const     { return m_context; }

    DocNode *parent() const     { return m_parent; }

    bool isExample() const      { return m_isExample; }

    QString exampleFile() const { return m_exampleFile; }

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

    void parse();

  private:

    DocNode *m_parent;

    QString  m_file;

    QString  m_context;

    QString  m_text;

    Type     m_type;

    bool     m_isExample;

    QString  m_exampleFile;

};

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

class DocIncOperator : public DocNode

{

  public:

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

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

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

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

      m_isFirst(FALSE), m_isLast(FALSE),

      m_isExample(isExample), m_exampleFile(exampleFile) {}

    Kind kind() const           { return Kind_IncOperator; }

    Type type() const           { return m_type; }

    QString text() const        { return m_text; }

    QString pattern() const     { return m_pattern; }

    QString context() const     { return m_context; }

    DocNode *parent() const     { return m_parent; }

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

    bool isFirst() const        { return m_isFirst; }

    bool isLast() const         { return m_isLast; }

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

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

    bool isExample() const      { return m_isExample; }

    QString exampleFile() const { return m_exampleFile; }

    void parse();

  private:

    DocNode *m_parent;

    Type     m_type;

    QString  m_text;

    QString  m_pattern;

    QString  m_context;

    bool     m_isFirst;

    bool     m_isLast;

    bool     m_isExample;

    QString  m_exampleFile;

};

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

class DocFormula : public DocNode

{

  public:

    DocFormula(DocNode *parent,int id);

    Kind kind() const          { return Kind_Formula; }

    QString name() const       { return m_name; }

    QString text() const       { return m_text; }

    QString relPath() const    { return m_relPath; }

    int id() const             { return m_id; }

    DocNode *parent() const    { return m_parent; }

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

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

  private:

    DocNode *m_parent;

    QString  m_name;

    QString  m_text;

    QString  m_relPath;

    int      m_id;

};

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

class DocIndexEntry : public DocNode

{

  public:

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

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

    Kind kind() const { return Kind_IndexEntry; }

    int parse();

    DocNode *parent() const      { return m_parent; }

    Definition *scope() const    { return m_scope;  }

    MemberDef *member() const    { return m_member; }

    QString entry() const        { return m_entry;  }

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

  private:

    DocNode    *m_parent;

    QString     m_entry;

    Definition *m_scope;

    MemberDef  *m_member;

};

//-----------------------------------------------------------------------

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

class DocCopy : public CompAccept<DocCopy>, public DocNode

{

  public:

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

      : m_parent(parent), m_link(link), 

        m_copyBrief(copyBrief), m_copyDetails(copyDetails) { }

    Kind kind() const          { return Kind_IndexEntry; }

    QString link() const       { return m_link; }

    DocNode *parent() const    { return m_parent; }

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

    void parse();

  private:

    DocNode *m_parent;

    QString  m_link;