diff options
Diffstat (limited to 'trunk/src/parserintf.h')
| -rw-r--r-- | trunk/src/parserintf.h | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/trunk/src/parserintf.h b/trunk/src/parserintf.h new file mode 100644 index 0000000..db22088 --- /dev/null +++ b/trunk/src/parserintf.h @@ -0,0 +1,171 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2012 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 PARSERINTF_H +#define PARSERINTF_H + +#include <qdict.h> + +class Entry; +class FileDef; +class CodeOutputInterface; +class MemberDef; + +/** \brief Abstract interface for programming language parsers. + * + * By implementing the methods of this interface one can add + * a new language parser to doxygen. The parser can make use of the + * comment block parser to parse the contents of special comment blocks. + */ +class ParserInterface +{ + public: + virtual ~ParserInterface() {} + /** Parses a single input file with the goal to build an Entry tree. + * @param[in] fileName The full name of the file. + * @param[in] fileBuf The contents of the file (zero terminated). + * @param[in,out] root The root of the tree of Entry *nodes + * representing the information extracted from the file. + */ + virtual void parseInput(const char *fileName, + const char *fileBuf, + Entry *root) = 0; + + /** Returns TRUE if the language identified by \a extension needs + * the C preprocessor to be run before feed the result to the input + * parser. + * @see parseInput() + */ + virtual bool needsPreprocessing(const QCString &extension) = 0; + + /** Parses a source file or fragment with the goal to produce + * highlighted and cross-referenced output. + * @param[in] codeOutIntf Abstract interface for writing the result. + * @param[in] scopeName Name of scope to which the code belongs. + * @param[in] input Actual code in the form of a string + * @param[in] isExampleBlock TRUE iff the code is part of an example. + * @param[in] exampleName Name of the example. + * @param[in] fileDef File definition to which the code + * is associated. + * @param[in] startLine Starting line in case of a code fragment. + * @param[in] endLine Ending line of the code fragment. + * @param[in] inlineFragment Code fragment that is to be shown inline + * as part of the documentation. + * @param[in] memberDef Member definition to which the code + * is associated (non null in case of an inline fragment + * for a member). + * @param[in] showLineNumbers if set to TRUE and also fileDef is not 0, + * line numbers will be added to the source fragement + */ + virtual void parseCode(CodeOutputInterface &codeOutIntf, + const char *scopeName, + const QCString &input, + bool isExampleBlock, + const char *exampleName=0, + FileDef *fileDef=0, + int startLine=-1, + int endLine=-1, + bool inlineFragment=FALSE, + MemberDef *memberDef=0, + bool showLineNumbers=TRUE + ) = 0; + + /** Resets the state of the code parser. + * Since multiple code fragments can together form a single example, an + * explicit function is used to reset the code parser state. + * @see parseCode() + */ + virtual void resetCodeParserState() = 0; + + /** Callback function called by the comment block scanner. + * It provides a string \a text containing the prototype of a function + * or variable. The parser should parse this and store the information + * in the Entry node that corresponds with the node for which the + * comment block parser was invoked. + */ + virtual void parsePrototype(const char *text) = 0; + +}; + +//----------------------------------------------------------------------------- + +/** \brief Manages programming language parsers. + * + * This class manages the language parsers in the system. One can + * register parsers, and obtain a parser given a file extension. + */ +class ParserManager +{ + public: + /** Creates the parser manager object. + */ + ParserManager() + : m_defaultParser(0) { m_parsers.setAutoDelete(TRUE); } + + /** Registers an additional parser. + * @param[in] name A symbolic name of the parser, i.e. "c", + * "python", "fortran", "vhdl", ... + * @param[in] parser The parser that is to be used for the + * given name. + * @param[in] defParser Use this parser as the default parser, used + * for unregistered file extensions. + */ + void registerParser(const char *name,ParserInterface *parser,bool defParser=FALSE) + { + if (defParser && m_defaultParser==0) m_defaultParser=parser; + m_parsers.insert(name,parser); + } + + /** Registers a file \a extension with a parser with name \a parserName. + * Returns TRUE if the extension was successfully registered. + */ + bool registerExtension(const char *extension, const char *parserName) + { + if (parserName==0 || extension==0) return FALSE; + ParserInterface *intf = m_parsers.find(parserName); + if (intf==0) return FALSE; + if (m_extensions.find(extension)!=0) // extension already exists + { + m_extensions.remove(extension); // remove it + } + m_extensions.insert(extension,intf); // add new mapping + return TRUE; + } + + /** Gets the interface to the parser associated with given \a extension. + * If there is no parser explicitly registered for the supplied extension, + * the interface to the default parser will be returned. + */ + ParserInterface *getParser(const char *extension) + { + if (extension==0) return m_defaultParser; + QCString ext = QCString(extension).lower(); + ParserInterface *intf = m_extensions.find(ext); + if (intf==0 && ext.length()>4) + { + intf = m_extensions.find(ext.left(4)); + } + return intf ? intf : m_defaultParser; + } + + private: + QDict<ParserInterface> m_parsers; + QDict<ParserInterface> m_extensions; + ParserInterface *m_defaultParser; +}; + +#endif |