Parser.h revision 7a337af9e8bc752a2d3b227e4058ed2baf7a19d1 
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/VariantValue.h"
38#include "clang/Basic/LLVM.h"
39#include "llvm/ADT/ArrayRef.h"
40#include "llvm/ADT/StringRef.h"
41
42namespace clang {
43namespace ast_matchers {
44namespace dynamic {
45
46/// \brief Matcher expression parser.
47class Parser {
48public:
49  /// \brief Interface to connect the parser with the registry and more.
50  ///
51  /// The parser uses the Sema instance passed into
52  /// parseMatcherExpression() to handle all matcher tokens. The simplest
53  /// processor implementation would simply call into the registry to create
54  /// the matchers.
55  /// However, a more complex processor might decide to intercept the matcher
56  /// creation and do some extra work. For example, it could apply some
57  /// transformation to the matcher by adding some id() nodes, or could detect
58  /// specific matcher nodes for more efficient lookup.
59  class Sema {
60  public:
61    virtual ~Sema();
62
63    /// \brief Process a matcher expression.
64    ///
65    /// All the arguments passed here have already been processed.
66    ///
67    /// \param MatcherName The matcher name found by the parser.
68    ///
69    /// \param NameRange The location of the name in the matcher source.
70    ///   Useful for error reporting.
71    ///
72    /// \param BindID The ID to use to bind the matcher, or a null \c StringRef
73    ///   if no ID is specified.
74    ///
75    /// \param Args The argument list for the matcher.
76    ///
77    /// \return The matcher object constructed by the processor, or NULL
78    ///   if an error occurred. In that case, \c Error will contain a
79    ///   description of the error.
80    ///   The caller takes ownership of the DynTypedMatcher object returned.
81    virtual DynTypedMatcher *actOnMatcherExpression(
82        StringRef MatcherName, const SourceRange &NameRange, StringRef BindID,
83        ArrayRef<ParserValue> Args, Diagnostics *Error) = 0;
84  };
85
86  /// \brief Parse a matcher expression, creating matchers from the registry.
87  ///
88  /// This overload creates matchers calling directly into the registry. If the
89  /// caller needs more control over how the matchers are created, then it can
90  /// use the overload below that takes a Sema.
91  ///
92  /// \param MatcherCode The matcher expression to parse.
93  ///
94  /// \return The matcher object constructed, or NULL if an error occurred.
95  //    In that case, \c Error will contain a description of the error.
96  ///   The caller takes ownership of the DynTypedMatcher object returned.
97  static DynTypedMatcher *parseMatcherExpression(StringRef MatcherCode,
98                                                 Diagnostics *Error);
99
100  /// \brief Parse a matcher expression.
101  ///
102  /// \param MatcherCode The matcher expression to parse.
103  ///
104  /// \param S The Sema instance that will help the parser
105  ///   construct the matchers.
106  /// \return The matcher object constructed by the processor, or NULL
107  ///   if an error occurred. In that case, \c Error will contain a
108  ///   description of the error.
109  ///   The caller takes ownership of the DynTypedMatcher object returned.
110  static DynTypedMatcher *parseMatcherExpression(StringRef MatcherCode,
111                                                 Sema *S,
112                                                 Diagnostics *Error);
113
114  /// \brief Parse an expression, creating matchers from the registry.
115  ///
116  /// Parses any expression supported by this parser. In general, the
117  /// \c parseMatcherExpression function is a better approach to get a matcher
118  /// object.
119  static bool parseExpression(StringRef Code, VariantValue *Value,
120                              Diagnostics *Error);
121
122  /// \brief Parse an expression.
123  ///
124  /// Parses any expression supported by this parser. In general, the
125  /// \c parseMatcherExpression function is a better approach to get a matcher
126  /// object.
127  static bool parseExpression(StringRef Code, Sema *S,
128                              VariantValue *Value, Diagnostics *Error);
129
130private:
131  class CodeTokenizer;
132  struct TokenInfo;
133
134  Parser(CodeTokenizer *Tokenizer, Sema *S,
135         Diagnostics *Error);
136
137  bool parseExpressionImpl(VariantValue *Value);
138  bool parseMatcherExpressionImpl(VariantValue *Value);
139
140  CodeTokenizer *const Tokenizer;
141  Sema *const S;
142  Diagnostics *const Error;
143};
144
145}  // namespace dynamic
146}  // namespace ast_matchers
147}  // namespace clang
148
149#endif  // LLVM_CLANG_AST_MATCHERS_DYNAMIC_PARSER_H
150