[ASTMatcher] Add a new matcher called isInTopNamespace

[junaire]

Summary

This patch adds a new AST matcher called isInTopNamespace. It is used to
check if a Decl is in a specific top-level namespace. before this, we can
only check if a Decl in std namespace or not. I believe that it is
useful to implement some clang-tidy checks like replacing some old
3rd-party component to new STL facility, like boost::shared_ptr.

[junaire]

Format patch.

[aaron.ballman]

These changes lack test coverage or uses of the new API, so it's a bit hard to tell whether it's being used correctly or not.

clang/include/clang/AST/DeclBase.h

470

I think this API needs some comments and explanation. Is the given namespace expected to be fully qualified or will this match partial namespaces? Is it checking whether the declaration is lexically in the namespace or semantically? How does it handle inline namespaces? That sort of thing. e.g.,

namespace foo {
void decl();

namespace bar {
int x; // Does isInNamespace("foo") return true for this declaration?
}

inline namespace baz {
int y; // Does isInNamespace("foo") return true for this declaration?
}
}

void foo::decl() {} // Does isInNamespace("foo") return true for this specific declaration?

clang/lib/AST/DeclBase.cpp

396

Same concerns here as above. It's not at all clear what "in" means for this.

[junaire]

After Aarron's comments, I realize what I really want to do is add a new
ASTMatcher that matches declarations what in the top level namespace like std.

This update fixed previous broken one, added some comments and unit tests.

[aaron.ballman]

clang/include/clang/AST/DeclBase.h

465–467

I'm not entirely sold on this API as it's super specific to just one use case of checking the initial namespace component -- that can already be done trivially by calling getQualifiedNameAsString() and doing a string compare up to the first ::, basically (at least for named declarations).

Also, it's still not clear whether this is talking about a lexical or semantic lookup. e.g.,

namespace foo {
void bar(); // This decl is lexically and semantically in foo
}
void foo::bar() {} // This decl is lexically in the global namespace but is semantically within foo.

Does isInTopNamespace("foo") return true for both declarations, or just the first?

I think it'd be nice to generalize this a bit more, into something like bool isInNamespace(llvm::StringRef FullyQualifiedNamespace, LookupContext Kind) (and make a new enum for LookupContext [feel free to pick a better name, too] that specifies semantic vs lexical so the user can pick which behavior they want).

However, even this is a bit of a tough API because of namespace aliases. e.g.,

namespace foo {
  void bar();
}

namespace frobble = foo;

void frobble::bar() {} // What should isInNamespace("foo") do here? My inclination is to return true, maybe?

clang/include/clang/AST/DeclBase.h

public:
 
   TranslationUnitDecl *getTranslationUnitDecl();
   const TranslationUnitDecl *getTranslationUnitDecl() const {
     return const_cast<Decl*>(this)->getTranslationUnitDecl();
   }
 
   bool isInAnonymousNamespace() const;
 
+  /// Helper to check if a Decl in a specific top level namespace, while inline
+  /// namespaces will be skipped.
+  bool isInTopNamespace(llvm::StringRef) const;
+
   bool isInStdNamespace() const;
 
   ASTContext &getASTContext() const LLVM_READONLY;
 
   /// Helper to get the language options from the ASTContext.
   /// Defined out of line to avoid depending on ASTContext.h.
   const LangOptions &getLangOpts() const LLVM_READONLY;
 
   void setAccess(AccessSpecifier AS) {
     Access = AS;
public:
 
   bool isRecord() const {
     return getDeclKind() >= Decl::firstRecord &&
            getDeclKind() <= Decl::lastRecord;
   }
 
   bool isNamespace() const { return getDeclKind() == Decl::Namespace; }
 
+  bool isTopNamespace(llvm::StringRef Namespace) const;
+
   bool isStdNamespace() const;
 
   bool isInlineNamespace() const;
 
   /// Determines whether this context is dependent on a
   /// template parameter.
   bool isDependentContext() const;
 

clang/include/clang/ASTMatchers/ASTMatchers.h

 ///   namespace {} // #1
 ///   }
 /// \endcode
 /// namespaceDecl(isAnonymous()) will match #1 but not ::n.
 AST_MATCHER(NamespaceDecl, isAnonymous) {
   return Node.isAnonymousNamespace();
 }
 
+/// Matches declarations in the top level namespace, but not in nested
+/// namespaces. This is because nested namespaces are designed for
+/// implementation details, we don't need to match them.
+///
+/// Given
+/// \code
+///   class shared_ptr {};
+///   namespace boost {
+///     class shared_ptr {}; #1
+///     namespace detail {
+///       class shared_ptr {};
+///     }
+///     inline namespace __1 {
+///       class shared_ptr {}; #2
+///     }
+///   }
+/// \endcode
+/// cxxRecordDecl(hasName("shared_ptr"), isInTopNamespace("boost")) will match
+/// #1 and #2.
+AST_MATCHER_P(Decl, isInTopNamespace, llvm::StringRef, Namespace) {
+  return Node.isInTopNamespace(Namespace);
+}
+
 /// Matches declarations in the namespace `std`, but not in nested namespaces.
 ///
 /// Given
 /// \code
 ///   class vector {};
 ///   namespace foo {
 ///     class vector {};
 ///     namespace std {

clang/lib/AST/DeclBase.cpp

for (const DeclContext *DC = getDeclContext(); DC; DC = DC->getParent()) {
     if (const auto *ND = dyn_cast<NamespaceDecl>(DC))
       if (ND->isAnonymousNamespace())
         return true;
   }
 
   return false;
 }
 
-bool Decl::isInStdNamespace() const {
+bool Decl::isInStdNamespace() const { return isInTopNamespace("std"); }
+
+bool Decl::isInTopNamespace(llvm::StringRef Namespace) const {
   const DeclContext *DC = getDeclContext();
-  return DC && DC->isStdNamespace();
+  return DC && DC->isTopNamespace(Namespace);
 }
 
 TranslationUnitDecl *Decl::getTranslationUnitDecl() {
   if (auto *TUD = dyn_cast<TranslationUnitDecl>(this))
     return TUD;
 
   DeclContext *DC = getDeclContext();
   assert(DC && "This decl is not contained in a translation unit!");
const BlockDecl *DeclContext::getInnermostBlockDecl() const {
   return nullptr;
 }
 
 bool DeclContext::isInlineNamespace() const {
   return isNamespace() &&
          cast<NamespaceDecl>(this)->isInline();
 }
 
-bool DeclContext::isStdNamespace() const {
+bool DeclContext::isStdNamespace() const { return isTopNamespace("std"); }
+bool DeclContext::isTopNamespace(llvm::StringRef Namespace) const {
   if (!isNamespace())
     return false;
 
   const auto *ND = cast<NamespaceDecl>(this);
   if (ND->isInline()) {
-    return ND->getParent()->isStdNamespace();
+    return ND->getParent()->isTopNamespace(Namespace);
   }
 
   if (!getParent()->getRedeclContext()->isTranslationUnit())
     return false;
 
   const IdentifierInfo *II = ND->getIdentifier();
-  return II && II->isStr("std");
+  return II && II->isStr(Namespace);
 }
 
 bool DeclContext::isDependentContext() const {
   if (isFileContext())
     return false;
 
   if (isa<ClassTemplatePartialSpecializationDecl>(this))
     return true;

clang/unittests/ASTMatchers/ASTMatchersNarrowingTest.cpp

TEST_P(ASTMatchersTest, IsAnonymous) {
   if (!GetParam().isCXX()) {
     return;
   }
 
   EXPECT_TRUE(notMatches("namespace N {}", namespaceDecl(isAnonymous())));
   EXPECT_TRUE(matches("namespace {}", namespaceDecl(isAnonymous())));
 }
 
+TEST_P(ASTMatchersTest, InTopNamespace) {
+  if (!GetParam().isCXX()) {
+    return;
+  }
+  EXPECT_TRUE(notMatches(
+      "namespace boost {"
+      "  namespace detail {"
+      "    class shared_ptr {};"
+      "  }"
+      "}",
+      cxxRecordDecl(hasName("shared_ptr"), isInTopNamespace("boost"))));
+
+  EXPECT_TRUE(
+      matches("namespace boost {"
+              "  class shared_ptr {};"
+              "}",
+              cxxRecordDecl(hasName("shared_ptr"), isInTopNamespace("boost"))));
+
+  EXPECT_TRUE(
+      matches("namespace boost {"
+              "  inline namespace __1 {"
+              "    class shared_ptr {};"
+              "  }"
+              "}",
+              cxxRecordDecl(hasName("shared_ptr"), isInTopNamespace("boost"))));
+}
+
 TEST_P(ASTMatchersTest, InStdNamespace) {
   if (!GetParam().isCXX()) {
     return;
   }
 
   EXPECT_TRUE(notMatches("class vector {};"
                          "namespace foo {"
                          "  class vector {};"