Doxygen
Loading...
Searching...
No Matches
parserintf.h
Go to the documentation of this file.
1/******************************************************************************
2 *
3 * Copyright (C) 1997-2023 by Dimitri van Heesch.
4 *
5 * Permission to use, copy, modify, and distribute this software and its
6 * documentation under the terms of the GNU General Public License is hereby
7 * granted. No representations are made about the suitability of this software
8 * for any purpose. It is provided "as is" without express or implied warranty.
9 * See the GNU General Public License for more details.
10 *
11 * Documents produced by Doxygen are derivative works derived from the
12 * input used in their production; they are not affected by this license.
13 *
14 */
15
16#ifndef PARSERINTF_H
17#define PARSERINTF_H
18
19#include <functional>
20#include <memory>
21#include <map>
22#include <string>
23
24#include "types.h"
25#include "containers.h"
26#include "construct.h"
27
28class Entry;
29class FileDef;
30class OutputCodeList;
31class MemberDef;
32class Definition;
33class ClangTUParser;
34
35/** \brief Abstract interface for outline parsers.
36 *
37 * By implementing the methods of this interface one can add
38 * a new language parser to doxygen. The parser implementation can make use of the
39 * comment block parser to parse the contents of special comment blocks.
40 */
42{
43 public:
44 ABSTRACT_BASE_CLASS(OutlineParserInterface)
45
46 /** Parses a single input file with the goal to build an Entry tree.
47 * @param[in] fileName The full name of the file.
48 * @param[in] fileBuf The contents of the file (zero terminated).
49 * @param[in,out] root The root of the tree of Entry *nodes
50 * representing the information extracted from the file.
51 * @param[in] clangParser The clang translation unit parser object
52 * or nullptr if disabled.
53 */
54 virtual void parseInput(const QCString &fileName,
55 const char *fileBuf,
56 const std::shared_ptr<Entry> &root,
57 ClangTUParser *clangParser) = 0;
58
59 /** Returns TRUE if the language identified by \a extension needs
60 * the C preprocessor to be run before feed the result to the input
61 * parser.
62 * @see parseInput()
63 */
64 virtual bool needsPreprocessing(const QCString &extension) const = 0;
65
66 /** Callback function called by the comment block scanner.
67 * It provides a string \a text containing the prototype of a function
68 * or variable. The parser should parse this and store the information
69 * in the Entry node that corresponds with the node for which the
70 * comment block parser was invoked.
71 */
72 virtual void parsePrototype(const QCString &text) = 0;
73
74};
75
76/** \brief Abstract interface for code parsers.
77 *
78 * By implementing the methods of this interface one can add
79 * a new language parser to doxygen. This interface is used for
80 * syntax highlighting, but also to extract cross references and call graphs.
81 */
82class CodeParserInterface
83{
84 public:
85 ABSTRACT_BASE_CLASS(CodeParserInterface)
86
87 /** Parses a source file or fragment with the goal to produce
88 * highlighted and cross-referenced output.
89 * @param[in] codeOutList interface for writing the result.
90 * @param[in] scopeName Name of scope to which the code belongs.
91 * @param[in] input Actual code in the form of a string
92 * @param[in] lang The programming language of the code fragment.
93 * @param[in] stripCodeComments signals whether or not for the code block the doxygen comments should be stripped.
94 * @param[in] isExampleBlock TRUE iff the code is part of an example.
95 * @param[in] exampleName Name of the example.
96 * @param[in] fileDef File definition to which the code
97 * is associated.
98 * @param[in] startLine Starting line in case of a code fragment.
99 * @param[in] endLine Ending line of the code fragment.
100 * @param[in] inlineFragment Code fragment that is to be shown inline
101 * as part of the documentation.
102 * @param[in] memberDef Member definition to which the code
103 * is associated (non null in case of an inline fragment
104 * for a member).
105 * @param[in] showLineNumbers if set to TRUE and also fileDef is not 0,
106 * line numbers will be added to the source fragment
107 * @param[in] searchCtx context under which search data has to be stored.
108 * @param[in] collectXRefs collect cross-reference relations.
109 */
110 virtual void parseCode(OutputCodeList &codeOutList,
111 const QCString &scopeName,
112 const QCString &input,
113 SrcLangExt lang,
114 bool stripCodeComments,
115 bool isExampleBlock,
116 const QCString &exampleName=QCString(),
117 const FileDef *fileDef=nullptr,
118 int startLine=-1,
119 int endLine=-1,
120 bool inlineFragment=FALSE,
121 const MemberDef *memberDef=nullptr,
122 bool showLineNumbers=TRUE,
123 const Definition *searchCtx=nullptr,
124 bool collectXRefs=TRUE
125 ) = 0;
126
127 /** Resets the state of the code parser.
128 * Since multiple code fragments can together form a single example, an
129 * explicit function is used to reset the code parser state.
130 * @see parseCode()
131 */
132 virtual void resetCodeParserState() = 0;
133
134};
135
136//-----------------------------------------------------------------------------
137
138using OutlineParserFactory = std::function<std::unique_ptr<OutlineParserInterface>()>;
139using CodeParserFactory = std::function<std::unique_ptr<CodeParserInterface>()>;
140
141/** \brief Manages programming language parsers.
142 *
143 * This class manages the language parsers in the system. One can
144 * register parsers, and obtain a parser given a file extension.
145 */
146class ParserManager
147{
148
149 struct ParserPair
150 {
151 ParserPair(OutlineParserFactory opf, const CodeParserFactory &cpf, const QCString &pn)
152 : outlineParserFactory(opf), codeParserFactory(cpf), parserName(pn)
153 {
154 }
155
156 OutlineParserFactory outlineParserFactory;
157 CodeParserFactory codeParserFactory;
158 QCString parserName;
159 };
160
161 public:
162 /** Create the parser manager
163 * @param outlineParserFactory the fallback outline parser factory to use for unknown extensions
164 * @param codeParserFactory the fallback code parser factory to use for unknown extensions
165 */
166 ParserManager(const OutlineParserFactory &outlineParserFactory,
167 const CodeParserFactory &codeParserFactory)
168 : m_defaultParsers(outlineParserFactory,codeParserFactory, QCString())
169 {
170 }
171
172 /** Registers an additional parser.
173 * @param[in] name A symbolic name of the parser, i.e. "c",
174 * "python", "fortran", "vhdl", ...
175 * @param[in] outlineParserFactory A factory method to create a language parser (scanner) that
176 * is to be used for the given name.
177 * @param[in] codeParserFactory A factory method to create a code parser that is to be used
178 * for the given name.
179 */
180 void registerParser(const QCString &name,const OutlineParserFactory &outlineParserFactory,
181 const CodeParserFactory &codeParserFactory)
182 {
183 m_parsers.emplace(name.str(),ParserPair(outlineParserFactory,codeParserFactory,name));
184 }
185
186 /** Registers a file \a extension with a parser with name \a parserName.
187 * Returns TRUE if the extension was successfully registered.
188 */
189 bool registerExtension(const QCString &extension, const QCString &parserName)
190 {
191 if (parserName.isEmpty() || extension.isEmpty()) return FALSE;
192
193 const auto &parserIt = m_parsers.find(parserName.str());
194 if (parserIt == m_parsers.end()) return FALSE;
195
196 auto extensionIt = m_extensions.find(extension.str());
197 if (extensionIt != m_extensions.end()) // extension already exists
198 {
199 m_extensions.erase(extensionIt); // remove it (e.g. user specified extension overrules built in one)
200 }
201 m_extensions.emplace(extension.str(),parserIt->second); // add new mapping
202 return TRUE;
203 }
204
205 /** Gets the interface to the parser associated with a given \a extension.
206 * If there is no parser explicitly registered for the supplied extension,
207 * the interface to the default parser will be returned.
208 */
209 std::unique_ptr<OutlineParserInterface> getOutlineParser(const QCString &extension)
210 {
211 return getParsers(extension).outlineParserFactory();
212 }
213
214 /** Gets the interface to the parser associated with a given \a extension.
215 * If there is no parser explicitly registered for the supplied extension,
216 * the interface to the default parser will be returned.
217 */
218 std::unique_ptr<CodeParserInterface> getCodeParser(const QCString &extension)
219 {
220 auto factory = getCodeParserFactory(extension);
221 return factory();
222 }
223
224 /** Get the factory for create code parser objects with a given \a extension. */
225 CodeParserFactory &getCodeParserFactory(const QCString &extension)
226 {
227 return getParsers(extension).codeParserFactory;
228 }
229
230 /** Gets the name of the parser associated with given \a extension.
231 * If there is no parser explicitly registered for the supplied extension,
232 * te empty string will be reurned.
233 */
234 QCString getParserName(const QCString &extension)
235 {
236 return getParsers(extension).parserName;
237 }
238
239 private:
240 ParserPair &getParsers(const QCString &extension)
241 {
242 QCString ext = extension.lower();
243 if (ext.isEmpty()) ext=".no_extension";
244 auto it = m_extensions.find(ext.data());
245 if (it==m_extensions.end() && ext.length()>4)
246 {
247 it = m_extensions.find(ext.left(4).data());
248 }
249 return it!=m_extensions.end() ? it->second : m_defaultParsers;
250 }
251
252 std::map<std::string,ParserPair> m_parsers;
253 std::map<std::string,ParserPair &> m_extensions;
254 ParserPair m_defaultParsers;
255};
256
257#endif
Clang parser object for a single translation unit, which consists of a source file and the directly o...
Definition clangparser.h:25
The common base class of all entity definitions found in the sources.
Definition definition.h:76
Represents an unstructured piece of information, about an entity found in the sources.
Definition entry.h:116
A model of a file symbol.
Definition filedef.h:99
A model of a class/file/namespace member symbol.
Definition memberdef.h:48
Abstract interface for outline parsers.
Definition parserintf.h:42
virtual bool needsPreprocessing(const QCString &extension) const =0
Returns TRUE if the language identified by extension needs the C preprocessor to be run before feed t...
virtual void parseInput(const QCString &fileName, const char *fileBuf, const std::shared_ptr< Entry > &root, ClangTUParser *clangParser)=0
Parses a single input file with the goal to build an Entry tree.
virtual void parsePrototype(const QCString &text)=0
Callback function called by the comment block scanner.
Class representing a list of different code generators.
Definition outputlist.h:164
bool registerExtension(const QCString &extension, const QCString &parserName)
Registers a file extension with a parser with name parserName.
Definition parserintf.h:189
void registerParser(const QCString &name, const OutlineParserFactory &outlineParserFactory, const CodeParserFactory &codeParserFactory)
Registers an additional parser.
Definition parserintf.h:180
std::unique_ptr< OutlineParserInterface > getOutlineParser(const QCString &extension)
Gets the interface to the parser associated with a given extension.
Definition parserintf.h:209
std::unique_ptr< CodeParserInterface > getCodeParser(const QCString &extension)
Gets the interface to the parser associated with a given extension.
Definition parserintf.h:218
CodeParserFactory & getCodeParserFactory(const QCString &extension)
Get the factory for create code parser objects with a given extension.
Definition parserintf.h:225
ParserManager(const OutlineParserFactory &outlineParserFactory, const CodeParserFactory &codeParserFactory)
Create the parser manager.
Definition parserintf.h:166
ParserPair & getParsers(const QCString &extension)
Definition parserintf.h:240
QCString getParserName(const QCString &extension)
Gets the name of the parser associated with given extension.
Definition parserintf.h:234
int find(char c, int index=0, bool cs=TRUE) const
Definition qcstring.cpp:43
size_t length() const
Returns the length of the string, not counting the 0-terminator.
Definition qcstring.h:153
QCString lower() const
Definition qcstring.h:234
bool isEmpty() const
Returns TRUE iff the string is empty.
Definition qcstring.h:150
const std::string & str() const
Definition qcstring.h:526
const char * data() const
Returns a pointer to the contents of the string in the form of a 0-terminated C string.
Definition qcstring.h:159
QCString left(size_t len) const
Definition qcstring.h:214
#define ABSTRACT_BASE_CLASS(cls)
Macro to implement rule of 5 for an abstract base class.
Definition construct.h:20
std::function< std::unique_ptr< CodeParserInterface >()> CodeParserFactory
Definition parserintf.h:139
std::function< std::unique_ptr< OutlineParserInterface >()> OutlineParserFactory
Definition parserintf.h:138
#define TRUE
Definition qcstring.h:37
#define FALSE
Definition qcstring.h:34
ParserPair(OutlineParserFactory opf, const CodeParserFactory &cpf, const QCString &pn)
Definition parserintf.h:151
This file contains a number of basic enums and types.
SrcLangExt
Language as given by extension.
Definition types.h:42