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 42 namespace clang { 43 namespace ast_matchers { 44 namespace dynamic { 45 46 /// \brief Matcher expression parser. 47 class Parser { 48 public: 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 objects constructed by the processor, or an empty 78 /// list if an error occurred. In that case, \c Error will contain a 79 /// description of the error. 80 virtual MatcherList actOnMatcherExpression(StringRef MatcherName, 81 const SourceRange &NameRange, 82 StringRef BindID, 83 ArrayRef<ParserValue> Args, 84 Diagnostics *Error) = 0; 85 }; 86 87 /// \brief Parse a matcher expression, creating matchers from the registry. 88 /// 89 /// This overload creates matchers calling directly into the registry. If the 90 /// caller needs more control over how the matchers are created, then it can 91 /// use the overload below that takes a Sema. 92 /// 93 /// \param MatcherCode The matcher expression to parse. 94 /// 95 /// \return The matcher object constructed, or NULL if an error occurred. 96 // In that case, \c Error will contain a description of the error. 97 /// The caller takes ownership of the DynTypedMatcher object returned. 98 static DynTypedMatcher *parseMatcherExpression(StringRef MatcherCode, 99 Diagnostics *Error); 100 101 /// \brief Parse a matcher expression. 102 /// 103 /// \param MatcherCode The matcher expression to parse. 104 /// 105 /// \param S The Sema instance that will help the parser 106 /// construct the matchers. 107 /// \return The matcher object constructed by the processor, or NULL 108 /// if an error occurred. In that case, \c Error will contain a 109 /// description of the error. 110 /// The caller takes ownership of the DynTypedMatcher object returned. 111 static DynTypedMatcher *parseMatcherExpression(StringRef MatcherCode, 112 Sema *S, 113 Diagnostics *Error); 114 115 /// \brief Parse an expression, creating matchers from the registry. 116 /// 117 /// Parses any expression supported by this parser. In general, the 118 /// \c parseMatcherExpression function is a better approach to get a matcher 119 /// object. 120 static bool parseExpression(StringRef Code, VariantValue *Value, 121 Diagnostics *Error); 122 123 /// \brief Parse an expression. 124 /// 125 /// Parses any expression supported by this parser. In general, the 126 /// \c parseMatcherExpression function is a better approach to get a matcher 127 /// object. 128 static bool parseExpression(StringRef Code, Sema *S, 129 VariantValue *Value, Diagnostics *Error); 130 131 private: 132 class CodeTokenizer; 133 struct TokenInfo; 134 135 Parser(CodeTokenizer *Tokenizer, Sema *S, 136 Diagnostics *Error); 137 138 bool parseExpressionImpl(VariantValue *Value); 139 bool parseMatcherExpressionImpl(VariantValue *Value); 140 141 CodeTokenizer *const Tokenizer; 142 Sema *const S; 143 Diagnostics *const Error; 144 }; 145 146 } // namespace dynamic 147 } // namespace ast_matchers 148 } // namespace clang 149 150 #endif // LLVM_CLANG_AST_MATCHERS_DYNAMIC_PARSER_H 151
