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_AST_MATCHERS_DYNAMIC_PARSER_H
35#define LLVM_CLANG_AST_MATCHERS_DYNAMIC_PARSER_H
36
37#include "clang/ASTMatchers/Dynamic/Diagnostics.h"
38#include "clang/ASTMatchers/Dynamic/Registry.h"
39#include "clang/ASTMatchers/Dynamic/VariantValue.h"
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
45namespace clang {
46namespace ast_matchers {
47namespace dynamic {
48
49/// \brief Matcher expression parser.
50class Parser {
51public:
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 Lookup a value by name.
67    ///
68    /// This can be used in the Sema layer to declare known constants or to
69    /// allow to split an expression in pieces.
70    ///
71    /// \param Name The name of the value to lookup.
72    ///
73    /// \return The named value. It could be any type that VariantValue
74    ///   supports. An empty value means that the name is not recognized.
75    virtual VariantValue getNamedValue(StringRef Name);
76
77    /// \brief Process a matcher expression.
78    ///
79    /// All the arguments passed here have already been processed.
80    ///
81    /// \param Ctor A matcher constructor looked up by lookupMatcherCtor.
82    ///
83    /// \param NameRange The location of the name in the matcher source.
84    ///   Useful for error reporting.
85    ///
86    /// \param BindID The ID to use to bind the matcher, or a null \c StringRef
87    ///   if no ID is specified.
88    ///
89    /// \param Args The argument list for the matcher.
90    ///
91    /// \return The matcher objects constructed by the processor, or a null
92    ///   matcher if an error occurred. In that case, \c Error will contain a
93    ///   description of the error.
94    virtual VariantMatcher actOnMatcherExpression(MatcherCtor Ctor,
95                                                  const SourceRange &NameRange,
96                                                  StringRef BindID,
97                                                  ArrayRef<ParserValue> Args,
98                                                  Diagnostics *Error) = 0;
99
100    /// \brief Look up a matcher by name.
101    ///
102    /// \param MatcherName The matcher name found by the parser.
103    ///
104    /// \return The matcher constructor, or Optional<MatcherCtor>() if not
105    /// found.
106    virtual llvm::Optional<MatcherCtor>
107    lookupMatcherCtor(StringRef MatcherName) = 0;
108  };
109
110  /// \brief Sema implementation that uses the matcher registry to process the
111  ///   tokens.
112  class RegistrySema : public Parser::Sema {
113   public:
114    virtual ~RegistrySema();
115
116    llvm::Optional<MatcherCtor>
117    lookupMatcherCtor(StringRef MatcherName) override;
118
119    VariantMatcher actOnMatcherExpression(MatcherCtor Ctor,
120                                          const SourceRange &NameRange,
121                                          StringRef BindID,
122                                          ArrayRef<ParserValue> Args,
123                                          Diagnostics *Error) override;
124  };
125
126  /// \brief Parse a matcher expression, creating matchers from the registry.
127  ///
128  /// This overload creates matchers calling directly into the registry. If the
129  /// caller needs more control over how the matchers are created, then it can
130  /// use the overload below that takes a Sema.
131  ///
132  /// \param MatcherCode The matcher expression to parse.
133  ///
134  /// \return The matcher object constructed, or an empty Optional if an error
135  ///   occurred.
136  ///   In that case, \c Error will contain a description of the error.
137  ///   The caller takes ownership of the DynTypedMatcher object returned.
138  static llvm::Optional<DynTypedMatcher>
139  parseMatcherExpression(StringRef MatcherCode, Diagnostics *Error);
140
141  /// \brief Parse a matcher expression.
142  ///
143  /// \param MatcherCode The matcher expression to parse.
144  ///
145  /// \param S The Sema instance that will help the parser
146  ///   construct the matchers.
147  /// \return The matcher object constructed by the processor, or an empty
148  ///   Optional if an error occurred. In that case, \c Error will contain a
149  ///   description of the error.
150  ///   The caller takes ownership of the DynTypedMatcher object returned.
151  static llvm::Optional<DynTypedMatcher>
152  parseMatcherExpression(StringRef MatcherCode, Sema *S, Diagnostics *Error);
153
154  /// \brief Parse an expression, creating matchers from the registry.
155  ///
156  /// Parses any expression supported by this parser. In general, the
157  /// \c parseMatcherExpression function is a better approach to get a matcher
158  /// object.
159  static bool parseExpression(StringRef Code, VariantValue *Value,
160                              Diagnostics *Error);
161
162  /// \brief Parse an expression.
163  ///
164  /// Parses any expression supported by this parser. In general, the
165  /// \c parseMatcherExpression function is a better approach to get a matcher
166  /// object.
167  static bool parseExpression(StringRef Code, Sema *S,
168                              VariantValue *Value, Diagnostics *Error);
169
170  /// \brief Complete an expression at the given offset.
171  ///
172  /// \return The list of completions, which may be empty if there are no
173  /// available completions or if an error occurred.
174  static std::vector<MatcherCompletion>
175  completeExpression(StringRef Code, unsigned CompletionOffset);
176
177private:
178  class CodeTokenizer;
179  struct ScopedContextEntry;
180  struct TokenInfo;
181
182  Parser(CodeTokenizer *Tokenizer, Sema *S,
183         Diagnostics *Error);
184
185  bool parseExpressionImpl(VariantValue *Value);
186  bool parseMatcherExpressionImpl(const TokenInfo &NameToken,
187                                  VariantValue *Value);
188  bool parseIdentifierPrefixImpl(VariantValue *Value);
189
190  void addCompletion(const TokenInfo &CompToken, StringRef TypedText,
191                     StringRef Decl);
192  void addExpressionCompletions();
193
194  CodeTokenizer *const Tokenizer;
195  Sema *const S;
196  Diagnostics *const Error;
197
198  typedef std::vector<std::pair<MatcherCtor, unsigned> > ContextStackTy;
199  ContextStackTy ContextStack;
200  std::vector<MatcherCompletion> Completions;
201};
202
203}  // namespace dynamic
204}  // namespace ast_matchers
205}  // namespace clang
206
207#endif  // LLVM_CLANG_AST_MATCHERS_DYNAMIC_PARSER_H
208