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