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

 *

 * $Id: doxmlintf.h 645 2008-08-19 13:23:22Z dimitri $

 *

 *

 * Copyright (C) 1997-2006 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.

 *

 */

#ifndef _DOXMLINTF_H

#define _DOXMLINTF_H

/*! \file

 *  \brief The interface to the object model provided by the XML parser 

 *         library.

 *

 *  To start using this library one calls createObjectModel() and then

 *  uses the returned IDoxygen interface to read doxygen generated

 *  XML output and navigate through the information contained in it.

 *

 *  @see createObjectModel()

 */

class IMember;

class IDocIterator;

class ICompound;

class ISection;

class INode;

class IDocInternal;

class IDocRoot;

#define VIRTUAL_DESTRUCTOR(x) virtual ~x() {}

/*! \brief Read only interface to a string. 

 */

class IString

{

  public:

    VIRTUAL_DESTRUCTOR(IString)

    /*! Returns a latin1 character representation of the string. */

    virtual const char *latin1() const = 0;

    /*! Returns a utf8 character representation of the string. */

    virtual const char *utf8() const = 0;

    /*! Returns a 16-bit unicode character representation of the character at 

     *  position \a index in the string. The first character is at index 0.

     */

    virtual unsigned short unicodeCharAt(int index) const = 0;

    /*! Returns true if this string is empty or false otherwise */

    virtual bool isEmpty() const = 0;

    /*! Returns the number of characters in the string. */

    virtual int length() const = 0;

};

/*! \brief Base interface for hyperlinked text

 *

 *  Depending on the result of kind() the interface is extended by

 *  ILT_Text or ILT_Ref.

 */

class ILinkedText

{

  public:

    VIRTUAL_DESTRUCTOR(ILinkedText)

    enum Kind { Kind_Text, Kind_Ref };

    virtual Kind kind() const = 0;

};

/*! \brief Plain text fragment.

 */

class ILT_Text : public ILinkedText

{

  public:

    VIRTUAL_DESTRUCTOR(ILT_Text)

    virtual const IString *text() const = 0;

};

/*! \brief Reference to an object.

 */

class ILT_Ref : public ILinkedText

{

  public:

    VIRTUAL_DESTRUCTOR(ILT_Ref)

    enum TargetKind { Member, Compound };

    virtual const IString *id() const = 0;

    virtual TargetKind targetKind() const = 0;

    virtual const IString *external() const = 0;

    virtual const IString *text() const = 0;

};

/*! \brief Iterates over a list of ILinkedText fragments.

 */

class ILinkedTextIterator 

{

  public:

    VIRTUAL_DESTRUCTOR(ILinkedTextIterator)

    virtual ILinkedText *toFirst() = 0;

    virtual ILinkedText *toLast() = 0;

    virtual ILinkedText *toNext() = 0;

    virtual ILinkedText *toPrev() = 0;

    virtual ILinkedText *current() const = 0;

    virtual void release() = 0;

};

/*! \brief Representation of a parameter of a function. */

class IParam 

{

  public:

    VIRTUAL_DESTRUCTOR(IParam)

    virtual ILinkedTextIterator *type() const = 0;

    virtual const IString * declarationName() const = 0;

    virtual const IString * definitionName() const = 0;

    virtual const IString * attrib() const = 0;

    virtual const IString * arraySpecifier() const = 0;

    virtual ILinkedTextIterator *defaultValue() const = 0;

    virtual IDocRoot *briefDescription() const = 0;

};

class IParamIterator

{

  public:

    VIRTUAL_DESTRUCTOR(IParamIterator)

    virtual IParam *toFirst() = 0;

    virtual IParam *toLast() = 0;

    virtual IParam *toNext() = 0;

    virtual IParam *toPrev() = 0;

    virtual IParam *current() const = 0;

    virtual void release() = 0;

};

class IMemberReference 

{

  public:

    VIRTUAL_DESTRUCTOR(IMemberReference)

    virtual IMember *member() const = 0;

    virtual const IString * name() const = 0;

    virtual const IString * scope() const = 0;

    virtual const IString * protection() const = 0;

    virtual const IString * virtualness() const = 0;

    virtual const IString * ambiguityScope() const = 0;

};

class IMemberReferenceIterator 

{

  public:

    VIRTUAL_DESTRUCTOR(IMemberReferenceIterator)

    virtual IMemberReference *toFirst() = 0;

    virtual IMemberReference *toLast() = 0;

    virtual IMemberReference *toNext() = 0;

    virtual IMemberReference *toPrev() = 0;

    virtual IMemberReference *current() const = 0;

    virtual void release() = 0;

};

class IDoc

{

  public:

    VIRTUAL_DESTRUCTOR(IDoc)

    enum Kind 

    { 

      Invalid = 0,        //  0

      Para,               //  1 -> IDocPara

      Text,               //  2 -> IDocText

      MarkupModifier,     //  3 -> IDocMarkupModifier

      ItemizedList,       //  4 -> IDocItemizedList

      OrderedList,        //  5 -> IDocOrderedList

      ListItem,           //  6 -> IDocListItem

      ParameterList,      //  7 -> IDocParameterList

      Parameter,          //  8 -> IDocParameter

      SimpleSect,         //  9 -> IDocSimpleSect

      Title,              // 10 -> IDocTitle

      Ref,                // 11 -> IDocRef

      VariableList,       // 12 -> IDocVariableList

      VariableListEntry,  // 13 -> IDocVariableListEntry

      HRuler,             // 14 -> IDocHRuler

      LineBreak,          // 15 -> IDocLineBreak

      ULink,              // 16 -> IDocULink

      EMail,              // 17 -> IDocEMail

      Link,               // 18 -> IDocLink

      ProgramListing,     // 19 -> IDocProgramListing

      CodeLine,           // 20 -> IDocCodeLine

      Highlight,          // 21 -> IDocHighlight

      Formula,            // 22 -> IDocFormula

      Image,              // 23 -> IDocImage

      DotFile,            // 24 -> IDocDotFile

      IndexEntry,         // 25 -> IDocIndexEntry

      Table,              // 26 -> IDocTable

      Row,                // 27 -> IDocRow

      Entry,              // 28 -> IDocEntry

      Section,            // 29 -> IDocSection

      Verbatim,           // 30 -> IDocVerbatim

      Copy,               // 31 -> IDocCopy

      TocList,            // 32 -> IDocTocList

      TocItem,            // 33 -> IDocTocItem

      Anchor,             // 34 -> IDocAnchor

      Symbol,             // 35 -> IDocSymbol

      Internal,           // 36 -> IDocInternal

      Root,               // 37 -> IDocRoot

      ParameterItem       // 38 -> IDocParameterItem

    };

    virtual Kind kind() const = 0;

};

class IDocMarkup : public IDoc

{

  public:

    enum Markup 

    { 

      Normal         = 0x000,

      Bold           = 0x001,

      Emphasis       = 0x002,

      ComputerOutput = 0x004,

      Subscript      = 0x008,

      Superscript    = 0x010,

      SmallFont      = 0x020,

      Center         = 0x040,

      Preformatted   = 0x080,

      Heading        = 0x100

    };

};

class IDocPara : public IDoc

{

  public:

    virtual IDocIterator *contents() const = 0; 

};

class IDocText : public IDocMarkup

{

  public:

    virtual const IString * text() const = 0;

    virtual int markup() const = 0;

    virtual int headingLevel() const = 0;

};

class IDocMarkupModifier : public IDoc

{

  public:

    virtual bool enabled() const = 0;

    virtual int markup() const = 0;

    virtual int headingLevel() const = 0;

};

class IDocItemizedList : public IDoc

{

  public:

    virtual IDocIterator *elements() const = 0;

};

class IDocOrderedList : public IDoc

{

  public:

    virtual IDocIterator *elements() const = 0;

};

class IDocListItem : public IDoc

{

  public:

    virtual IDocIterator *contents() const = 0;

};

class IDocParameterList : public IDoc

{

  public:

    enum Types { Param, RetVal, Exception };

    virtual Types sectType() const = 0;

    virtual IDocIterator *params() const = 0;

};

class IDocParameterItem : public IDoc

{

  public:

    virtual IDocIterator *paramNames() const = 0;

    virtual IDocPara *description() const = 0;

};

class IDocParameter : public IDoc

{

  public:

    virtual const IString * name() const = 0;

};

class IDocTitle : public IDoc

{

  public:

    virtual IDocIterator *title() const = 0;

};

class IDocSimpleSect : public IDoc

{

  public:

    enum Types { Invalid = 0,

                 See, Return, Author, Version, 

                 Since, Date, Bug, Note,

                 Warning, Par, Deprecated, Pre, 

                 Post, Invar, Remark, Attention,

                 Todo, Test, RCS, EnumValues, 

                 Examples

    };

    virtual Types type() const = 0;

    virtual const IString * typeString() const = 0;

    virtual IDocTitle *title() const = 0;

    virtual IDocPara *description() const = 0;

};

class IDocRef : public IDoc

{

  public:

    enum TargetKind { Member, Compound };

    virtual const IString * refId() const = 0;

    virtual TargetKind targetKind() const = 0;

    virtual const IString * external() const = 0;

    virtual const IString * text() const = 0;

};

class IDocVariableList : public IDoc

{

  public:

    virtual IDocIterator *entries() const = 0;

};

class IDocVariableListEntry : public IDoc

{

  public:

    virtual ILinkedTextIterator * term() const = 0;

    virtual IDocPara *description() const = 0;

};

class IDocHRuler : public IDoc

{

};

class IDocLineBreak : public IDoc

{

};

class IDocULink : public IDoc

{

  public:

    virtual const IString * url() const = 0;

    virtual const IString * text() const = 0;

};

class IDocEMail : public IDoc

{

  public:

    virtual const IString * address() const = 0;

};

class IDocLink : public IDoc

{

  public:

    virtual const IString * refId() const = 0;

    virtual const IString * text() const = 0;

};

class IDocProgramListing : public IDoc

{

  public:

    virtual IDocIterator *codeLines() const = 0;

};

class IDocCodeLine : public IDoc

{

  public:

    virtual int lineNumber() const = 0;

    virtual const IString * refId() const = 0;

    virtual IDocIterator *codeElements() const = 0;

};

class IDocHighlight : public IDoc

{

  public:

    enum HighlightKind 

    { Invalid=0,

      Comment, Keyword, 

      KeywordType, KeywordFlow, CharLiteral, 

      StringLiteral, Preprocessor

    };

    virtual HighlightKind highlightKind() const = 0;

    virtual IDocIterator *codeElements() const = 0;

};

class IDocFormula : public IDoc

{

  public:

    virtual const IString * id() const = 0;

    virtual const IString * text() const = 0;

};

class IDocImage : public IDoc

{

  public:

    virtual const IString * name() const = 0;

    virtual const IString * caption() const = 0;

};

class IDocDotFile : public IDoc

{

  public:

    virtual const IString * name() const = 0;

    virtual const IString * caption() const = 0;

};

class IDocIndexEntry : public IDoc

{

  public:

    virtual const IString * primary() const = 0;

    virtual const IString * secondary() const = 0;

};

class IDocTable : public IDoc

{

  public:

    virtual IDocIterator *rows() const = 0;

    virtual int numColumns() const = 0;

    virtual const IString * caption() const = 0;

};

class IDocRow : public IDoc

{

  public:

    virtual IDocIterator *entries() const = 0;

};

class IDocEntry : public IDoc

{

  public:

    virtual IDocIterator *contents() const = 0;

};

class IDocSection : public IDoc

{

  public:

    virtual const IString * id() const = 0; 

    virtual int level() const = 0;

    virtual IDocTitle *title() const = 0;

    virtual IDocIterator *paragraphs() const = 0;

    virtual IDocIterator *subSections() const = 0;

    virtual IDocInternal *internal() const = 0;

};

class IDocInternal : public IDoc

{

  public:

    virtual IDocIterator *paragraphs() const = 0;

    virtual IDocIterator *subSections() const = 0;

};

class IDocTocList : public IDoc

{

  public:

    virtual IDocIterator *elements() const = 0;

};

class IDocTocItem : public IDoc

{

  public:

    virtual const IString *id() const = 0; 

    virtual const IString *title() const = 0;

};

class IDocCopy : public IDoc

{

  public:

    virtual IDocIterator *contents() const = 0; 

};

class IDocVerbatim : public IDoc

{

  public:

    enum Types { Invalid = 0, HtmlOnly, LatexOnly, Verbatim };

    virtual const IString *text() const = 0; 

    virtual Types type() const = 0;

};

class IDocAnchor : public IDoc

{

  public:

    virtual const IString *id() const = 0; 

};

class IDocSymbol : public IDoc

{

  public:

    enum Types 

    { Invalid = 0,

      Umlaut, Acute, Grave, Circ, Tilde, Szlig, Cedil, Ring, Nbsp, Copy

    };

    virtual Types type() const = 0;

    virtual const IString * typeString() const = 0;

    virtual char letter() const = 0;

};

class IDocRoot : public IDoc

{

  public:

    virtual IDocIterator *contents() const = 0; 

    virtual IDocInternal *internal() const = 0; 

};

class IDocIterator 

{

  public:

    VIRTUAL_DESTRUCTOR(IDocIterator)

    virtual IDoc *toFirst() = 0;

    virtual IDoc *toLast() = 0;

    virtual IDoc *toNext() = 0;

    virtual IDoc *toPrev() = 0;

    virtual IDoc *current() const = 0;

    virtual void release() = 0;

};

class IEdgeLabel

{

  public:

    VIRTUAL_DESTRUCTOR(IEdgeLabel)

    virtual const IString * label() const = 0;

};

class IEdgeLabelIterator 

{

  public:

    VIRTUAL_DESTRUCTOR(IEdgeLabelIterator)