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 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 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 177 private: 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
