Parser.h revision 651f13cea278ec967336033dd032faef0e9fc2ec 
1//===--- Parser.h - Matcher expression parser -----*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9///
10/// \file
11/// \brief Simple matcher expression parser.
12///
13/// The parser understands matcher expressions of the form:
14///   MatcherName(Arg0, Arg1, ..., ArgN)
15/// as well as simple types like strings.
16/// The parser does not know how to process the matchers. It delegates this task
17/// to a Sema object received as an argument.
18///
19/// \code
20/// Grammar for the expressions supported:
21/// <Expression>        := <Literal> | <MatcherExpression>
22/// <Literal>           := <StringLiteral> | <Unsigned>
23/// <StringLiteral>     := "quoted string"
24/// <Unsigned>          := [0-9]+
25/// <MatcherExpression> := <MatcherName>(<ArgumentList>) |
26///                        <MatcherName>(<ArgumentList>).bind(<StringLiteral>)
27/// <MatcherName>       := [a-zA-Z]+
28/// <ArgumentList>      := <Expression> | <Expression>,<ArgumentList>
29/// \endcode
30///
31//===----------------------------------------------------------------------===//
32
33#ifndef LLVM_CLANG_AST_MATCHERS_DYNAMIC_PARSER_H
34#define LLVM_CLANG_AST_MATCHERS_DYNAMIC_PARSER_H
35
36#include "clang/ASTMatchers/Dynamic/Diagnostics.h"
37#include "clang/ASTMatchers/Dynamic/Registry.h"
38#include "clang/ASTMatchers/Dynamic/VariantValue.h"
39#include "clang/Basic/LLVM.h"
40#include "llvm/ADT/ArrayRef.h"
41#include "llvm/ADT/Optional.h"
42#include "llvm/ADT/StringRef.h"
43
44namespace clang {
45namespace ast_matchers {
46namespace dynamic {
47
48/// \brief Matcher expression parser.
49class Parser {
50public:
51  /// \brief Interface to connect the parser with the registry and more.
52  ///
53  /// The parser uses the Sema instance passed into
54  /// parseMatcherExpression() to handle all matcher tokens. The simplest
55  /// processor implementation would simply call into the registry to create
56  /// the matchers.
57  /// However, a more complex processor might decide to intercept the matcher
58  /// creation and do some extra work. For example, it could apply some
59  /// transformation to the matcher by adding some id() nodes, or could detect
60  /// specific matcher nodes for more efficient lookup.
61  class Sema {
62  public:
63    virtual ~Sema();
64
65    /// \brief Process a matcher expression.
66    ///
67    /// All the arguments passed here have already been processed.
68    ///
69    /// \param Ctor A matcher constructor looked up by lookupMatcherCtor.
70    ///
71    /// \param NameRange The location of the name in the matcher source.
72    ///   Useful for error reporting.
73    ///
74    /// \param BindID The ID to use to bind the matcher, or a null \c StringRef
75    ///   if no ID is specified.
76    ///
77    /// \param Args The argument list for the matcher.
78    ///
79    /// \return The matcher objects constructed by the processor, or a null
80    ///   matcher if an error occurred. In that case, \c Error will contain a
81    ///   description of the error.
82    virtual VariantMatcher actOnMatcherExpression(MatcherCtor Ctor,
83                                                  const SourceRange &NameRange,
84                                                  StringRef BindID,
85                                                  ArrayRef<ParserValue> Args,
86                                                  Diagnostics *Error) = 0;
87
88    /// \brief Look up a matcher by name.
89    ///
90    /// \param MatcherName The matcher name found by the parser.
91    ///
92    /// \param NameRange The location of the name in the matcher source.
93    ///   Useful for error reporting.
94    ///
95    /// \return The matcher constructor, or Optional<MatcherCtor>() if an error
96    ///   occurred. In that case, \c Error will contain a description of the
97    ///   error.
98    virtual llvm::Optional<MatcherCtor>
99    lookupMatcherCtor(StringRef MatcherName, const SourceRange &NameRange,
100                      Diagnostics *Error) = 0;
101  };
102
103  /// \brief Parse a matcher expression, creating matchers from the registry.
104  ///
105  /// This overload creates matchers calling directly into the registry. If the
106  /// caller needs more control over how the matchers are created, then it can
107  /// use the overload below that takes a Sema.
108  ///
109  /// \param MatcherCode The matcher expression to parse.
110  ///
111  /// \return The matcher object constructed, or an empty Optional if an error
112  ///   occurred.
113  ///   In that case, \c Error will contain a description of the error.
114  ///   The caller takes ownership of the DynTypedMatcher object returned.
115  static llvm::Optional<DynTypedMatcher>
116  parseMatcherExpression(StringRef MatcherCode, Diagnostics *Error);
117
118  /// \brief Parse a matcher expression.
119  ///
120  /// \param MatcherCode The matcher expression to parse.
121  ///
122  /// \param S The Sema instance that will help the parser
123  ///   construct the matchers.
124  /// \return The matcher object constructed by the processor, or an empty
125  ///   Optional if an error occurred. In that case, \c Error will contain a
126  ///   description of the error.
127  ///   The caller takes ownership of the DynTypedMatcher object returned.
128  static llvm::Optional<DynTypedMatcher>
129  parseMatcherExpression(StringRef MatcherCode, Sema *S, Diagnostics *Error);
130
131  /// \brief Parse an expression, creating matchers from the registry.
132  ///
133  /// Parses any expression supported by this parser. In general, the
134  /// \c parseMatcherExpression function is a better approach to get a matcher
135  /// object.
136  static bool parseExpression(StringRef Code, VariantValue *Value,
137                              Diagnostics *Error);
138
139  /// \brief Parse an expression.
140  ///
141  /// Parses any expression supported by this parser. In general, the
142  /// \c parseMatcherExpression function is a better approach to get a matcher
143  /// object.
144  static bool parseExpression(StringRef Code, Sema *S,
145                              VariantValue *Value, Diagnostics *Error);
146
147  /// \brief Complete an expression at the given offset.
148  ///
149  /// \return The list of completions, which may be empty if there are no
150  /// available completions or if an error occurred.
151  static std::vector<MatcherCompletion>
152  completeExpression(StringRef Code, unsigned CompletionOffset);
153
154private:
155  class CodeTokenizer;
156  struct ScopedContextEntry;
157  struct TokenInfo;
158
159  Parser(CodeTokenizer *Tokenizer, Sema *S,
160         Diagnostics *Error);
161
162  bool parseExpressionImpl(VariantValue *Value);
163  bool parseMatcherExpressionImpl(VariantValue *Value);
164
165  void addCompletion(const TokenInfo &CompToken, StringRef TypedText,
166                     StringRef Decl);
167  void addExpressionCompletions();
168
169  CodeTokenizer *const Tokenizer;
170  Sema *const S;
171  Diagnostics *const Error;
172
173  typedef std::vector<std::pair<MatcherCtor, unsigned> > ContextStackTy;
174  ContextStackTy ContextStack;
175  std::vector<MatcherCompletion> Completions;
176};
177
178}  // namespace dynamic
179}  // namespace ast_matchers
180}  // namespace clang
181
182#endif  // LLVM_CLANG_AST_MATCHERS_DYNAMIC_PARSER_H
183