contrib/llvm/tools/clang/include/clang/ASTMatchers/Dynamic/Parser.h

   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