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