clang  3.7.0
ASTMatchers/Dynamic/Parser.h
Go to the documentation of this file.
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> | <NamedValue> | <MatcherExpression>
22 /// <Literal> := <StringLiteral> | <Unsigned>
23 /// <StringLiteral> := "quoted string"
24 /// <Unsigned> := [0-9]+
25 /// <NamedValue> := <Identifier>
26 /// <MatcherExpression> := <Identifier>(<ArgumentList>) |
27 /// <Identifier>(<ArgumentList>).bind(<StringLiteral>)
28 /// <Identifier> := [a-zA-Z]+
29 /// <ArgumentList> := <Expression> | <Expression>,<ArgumentList>
30 /// \endcode
31 ///
32 //===----------------------------------------------------------------------===//
33 
34 #ifndef LLVM_CLANG_ASTMATCHERS_DYNAMIC_PARSER_H
35 #define LLVM_CLANG_ASTMATCHERS_DYNAMIC_PARSER_H
36 
40 #include "clang/Basic/LLVM.h"
41 #include "llvm/ADT/ArrayRef.h"
42 #include "llvm/ADT/Optional.h"
43 #include "llvm/ADT/StringRef.h"
44 
45 namespace clang {
46 namespace ast_matchers {
47 namespace dynamic {
48 
49 /// \brief Matcher expression parser.
50 class Parser {
51 public:
52  /// \brief Interface to connect the parser with the registry and more.
53  ///
54  /// The parser uses the Sema instance passed into
55  /// parseMatcherExpression() to handle all matcher tokens. The simplest
56  /// processor implementation would simply call into the registry to create
57  /// the matchers.
58  /// However, a more complex processor might decide to intercept the matcher
59  /// creation and do some extra work. For example, it could apply some
60  /// transformation to the matcher by adding some id() nodes, or could detect
61  /// specific matcher nodes for more efficient lookup.
62  class Sema {
63  public:
64  virtual ~Sema();
65 
66  /// \brief Process a matcher expression.
67  ///
68  /// All the arguments passed here have already been processed.
69  ///
70  /// \param Ctor A matcher constructor looked up by lookupMatcherCtor.
71  ///
72  /// \param NameRange The location of the name in the matcher source.
73  /// Useful for error reporting.
74  ///
75  /// \param BindID The ID to use to bind the matcher, or a null \c StringRef
76  /// if no ID is specified.
77  ///
78  /// \param Args The argument list for the matcher.
79  ///
80  /// \return The matcher objects constructed by the processor, or a null
81  /// matcher if an error occurred. In that case, \c Error will contain a
82  /// description of the error.
84  const SourceRange &NameRange,
85  StringRef BindID,
87  Diagnostics *Error) = 0;
88 
89  /// \brief Look up a matcher by name.
90  ///
91  /// \param MatcherName The matcher name found by the parser.
92  ///
93  /// \return The matcher constructor, or Optional<MatcherCtor>() if not
94  /// found.
96  lookupMatcherCtor(StringRef MatcherName) = 0;
97 
98  /// \brief Compute the list of completion types for \p Context.
99  ///
100  /// Each element of \p Context represents a matcher invocation, going from
101  /// outermost to innermost. Elements are pairs consisting of a reference to
102  /// the matcher constructor and the index of the next element in the
103  /// argument list of that matcher (or for the last element, the index of
104  /// the completion point in the argument list). An empty list requests
105  /// completion for the root matcher.
106  virtual std::vector<ArgKind> getAcceptedCompletionTypes(
107  llvm::ArrayRef<std::pair<MatcherCtor, unsigned>> Context);
108 
109  /// \brief Compute the list of completions that match any of
110  /// \p AcceptedTypes.
111  ///
112  /// \param AcceptedTypes All types accepted for this completion.
113  ///
114  /// \return All completions for the specified types.
115  /// Completions should be valid when used in \c lookupMatcherCtor().
116  /// The matcher constructed from the return of \c lookupMatcherCtor()
117  /// should be convertible to some type in \p AcceptedTypes.
118  virtual std::vector<MatcherCompletion>
120  };
121 
122  /// \brief Sema implementation that uses the matcher registry to process the
123  /// tokens.
124  class RegistrySema : public Parser::Sema {
125  public:
126  ~RegistrySema() override;
127 
129  lookupMatcherCtor(StringRef MatcherName) override;
130 
132  const SourceRange &NameRange,
133  StringRef BindID,
135  Diagnostics *Error) override;
136 
137  std::vector<ArgKind> getAcceptedCompletionTypes(
138  llvm::ArrayRef<std::pair<MatcherCtor, unsigned>> Context) override;
139 
140  std::vector<MatcherCompletion>
141  getMatcherCompletions(llvm::ArrayRef<ArgKind> AcceptedTypes) override;
142  };
143 
144  typedef llvm::StringMap<VariantValue> NamedValueMap;
145 
146  /// \brief Parse a matcher expression.
147  ///
148  /// \param MatcherCode The matcher expression to parse.
149  ///
150  /// \param S The Sema instance that will help the parser
151  /// construct the matchers. If null, it uses the default registry.
152  ///
153  /// \param NamedValues A map of precomputed named values. This provides
154  /// the dictionary for the <NamedValue> rule of the grammar.
155  /// If null, it is ignored.
156  ///
157  /// \return The matcher object constructed by the processor, or an empty
158  /// Optional if an error occurred. In that case, \c Error will contain a
159  /// description of the error.
160  /// The caller takes ownership of the DynTypedMatcher object returned.
162  parseMatcherExpression(StringRef MatcherCode, Sema *S,
163  const NamedValueMap *NamedValues,
164  Diagnostics *Error);
166  parseMatcherExpression(StringRef MatcherCode, Sema *S,
167  Diagnostics *Error) {
168  return parseMatcherExpression(MatcherCode, S, nullptr, Error);
169  }
171  parseMatcherExpression(StringRef MatcherCode, Diagnostics *Error) {
172  return parseMatcherExpression(MatcherCode, nullptr, Error);
173  }
174 
175  /// \brief Parse an expression.
176  ///
177  /// Parses any expression supported by this parser. In general, the
178  /// \c parseMatcherExpression function is a better approach to get a matcher
179  /// object.
180  ///
181  /// \param S The Sema instance that will help the parser
182  /// construct the matchers. If null, it uses the default registry.
183  ///
184  /// \param NamedValues A map of precomputed named values. This provides
185  /// the dictionary for the <NamedValue> rule of the grammar.
186  /// If null, it is ignored.
187  static bool parseExpression(StringRef Code, Sema *S,
188  const NamedValueMap *NamedValues,
189  VariantValue *Value, Diagnostics *Error);
190  static bool parseExpression(StringRef Code, Sema *S,
191  VariantValue *Value, Diagnostics *Error) {
192  return parseExpression(Code, S, nullptr, Value, Error);
193  }
194  static bool parseExpression(StringRef Code, VariantValue *Value,
195  Diagnostics *Error) {
196  return parseExpression(Code, nullptr, Value, Error);
197  }
198 
199  /// \brief Complete an expression at the given offset.
200  ///
201  /// \param S The Sema instance that will help the parser
202  /// construct the matchers. If null, it uses the default registry.
203  ///
204  /// \param NamedValues A map of precomputed named values. This provides
205  /// the dictionary for the <NamedValue> rule of the grammar.
206  /// If null, it is ignored.
207  ///
208  /// \return The list of completions, which may be empty if there are no
209  /// available completions or if an error occurred.
210  static std::vector<MatcherCompletion>
211  completeExpression(StringRef Code, unsigned CompletionOffset, Sema *S,
212  const NamedValueMap *NamedValues);
213  static std::vector<MatcherCompletion>
214  completeExpression(StringRef Code, unsigned CompletionOffset, Sema *S) {
215  return completeExpression(Code, CompletionOffset, S, nullptr);
216  }
217  static std::vector<MatcherCompletion>
218  completeExpression(StringRef Code, unsigned CompletionOffset) {
219  return completeExpression(Code, CompletionOffset, nullptr);
220  }
221 
222 private:
223  class CodeTokenizer;
224  struct ScopedContextEntry;
225  struct TokenInfo;
226 
227  Parser(CodeTokenizer *Tokenizer, Sema *S,
228  const NamedValueMap *NamedValues,
229  Diagnostics *Error);
230 
231  bool parseExpressionImpl(VariantValue *Value);
232  bool parseMatcherExpressionImpl(const TokenInfo &NameToken,
234  bool parseIdentifierPrefixImpl(VariantValue *Value);
235 
236  void addCompletion(const TokenInfo &CompToken,
237  const MatcherCompletion &Completion);
238  void addExpressionCompletions();
239 
240  std::vector<MatcherCompletion>
241  getNamedValueCompletions(ArrayRef<ArgKind> AcceptedTypes);
242 
243  CodeTokenizer *const Tokenizer;
244  Sema *const S;
245  const NamedValueMap *const NamedValues;
246  Diagnostics *const Error;
247 
248  typedef std::vector<std::pair<MatcherCtor, unsigned> > ContextStackTy;
249  ContextStackTy ContextStack;
250  std::vector<MatcherCompletion> Completions;
251 };
252 
253 } // namespace dynamic
254 } // namespace ast_matchers
255 } // namespace clang
256 
257 #endif // LLVM_CLANG_AST_MATCHERS_DYNAMIC_PARSER_H
virtual VariantMatcher actOnMatcherExpression(MatcherCtor Ctor, const SourceRange &NameRange, StringRef BindID, ArrayRef< ParserValue > Args, Diagnostics *Error)=0
Process a matcher expression.
static std::vector< MatcherCompletion > completeExpression(StringRef Code, unsigned CompletionOffset, Sema *S, const NamedValueMap *NamedValues)
Complete an expression at the given offset.
static bool parseExpression(StringRef Code, Sema *S, const NamedValueMap *NamedValues, VariantValue *Value, Diagnostics *Error)
Parse an expression.
static bool parseExpression(StringRef Code, VariantValue *Value, Diagnostics *Error)
Registry of all known matchers.
virtual llvm::Optional< MatcherCtor > lookupMatcherCtor(StringRef MatcherName)=0
Look up a matcher by name.
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified...
llvm::Optional< MatcherCtor > lookupMatcherCtor(StringRef MatcherName) override
Look up a matcher by name.
Sema - This implements semantic analysis and AST building for C.
Definition: Sema.h:258
ASTContext * Context
static llvm::Optional< DynTypedMatcher > parseMatcherExpression(StringRef MatcherCode, Sema *S, Diagnostics *Error)
Sema implementation that uses the matcher registry to process the tokens.
static std::vector< MatcherCompletion > completeExpression(StringRef Code, unsigned CompletionOffset, Sema *S)
static std::vector< MatcherCompletion > completeExpression(StringRef Code, unsigned CompletionOffset)
VariantMatcher actOnMatcherExpression(MatcherCtor Ctor, const SourceRange &NameRange, StringRef BindID, ArrayRef< ParserValue > Args, Diagnostics *Error) override
Process a matcher expression.
Diagnostics class to manage error messages.
static llvm::Optional< DynTypedMatcher > parseMatcherExpression(StringRef MatcherCode, Diagnostics *Error)
Helper class to manage error messages.
Definition: Diagnostics.h:51
std::vector< ArgKind > getAcceptedCompletionTypes(llvm::ArrayRef< std::pair< MatcherCtor, unsigned >> Context) override
Compute the list of completion types for Context.
static llvm::Optional< DynTypedMatcher > parseMatcherExpression(StringRef MatcherCode, Sema *S, const NamedValueMap *NamedValues, Diagnostics *Error)
Parse a matcher expression.
static bool parseExpression(StringRef Code, Sema *S, VariantValue *Value, Diagnostics *Error)
Interface to connect the parser with the registry and more.
virtual std::vector< ArgKind > getAcceptedCompletionTypes(llvm::ArrayRef< std::pair< MatcherCtor, unsigned >> Context)
Compute the list of completion types for Context.
std::vector< MatcherCompletion > getMatcherCompletions(llvm::ArrayRef< ArgKind > AcceptedTypes) override
Compute the list of completions that match any of AcceptedTypes.
virtual std::vector< MatcherCompletion > getMatcherCompletions(llvm::ArrayRef< ArgKind > AcceptedTypes)
Compute the list of completions that match any of AcceptedTypes.
Polymorphic value type.
llvm::StringMap< VariantValue > NamedValueMap