From 111f0229da738ad4374c56c216b08c7cc403a0ef Mon Sep 17 00:00:00 2001
From: blyxyas <blyxyas@gmail.com>
Date: Thu, 13 Apr 2023 21:57:47 +0200
Subject: [PATCH] Add "Method Checking"
Co-authored-by: Nahua <kangnahua@gmail.com>
---
book/src/SUMMARY.md | 1 +
book/src/development/method_checking.md | 93 +++++++++++++++++++++++++
2 files changed, 94 insertions(+)
create mode 100644 book/src/development/method_checking.md
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index f6378b1fb90..daaefd06a97 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -16,6 +16,7 @@
- [Defining Lints](development/defining_lints.md)
- [Lint Passes](development/lint_passes.md)
- [Type Checking](development/type_checking.md)
+ - [Method Checking](development/method_checking.md)
- [Macro Expansions](development/macro_expansions.md)
- [Common Tools](development/common_tools_writing_lints.md)
- [Infrastructure](development/infrastructure/README.md)
diff --git a/book/src/development/method_checking.md b/book/src/development/method_checking.md
new file mode 100644
index 00000000000..604fcf193df
--- /dev/null
+++ b/book/src/development/method_checking.md
@@ -0,0 +1,93 @@
+# Method Checking
+
+In some scenarios we might want to check for methods when developing
+a lint. There are two kinds of questions that we might be curious about:
+
+- Invocation: Does an expression call a specific method?
+- Definition: Does the type `Ty` of an expression define a method?
+
+## Checking if an `expr` is calling a specific method
+
+Suppose we have an `expr`, we can check whether it calls a specific
+method, e.g. `our_fancy_method`, by performing a pattern match on
+the [ExprKind] that we can access from `expr.kind`:
+
+```rust
+use rustc_hir as hir;
+use rustc_lint::{LateContext, LateLintPass};
+use rustc_span::sym;
+
+impl<'tcx> LateLintPass<'tcx> for OurFancyMethodLint {
+ fn check_expr(&mut self, cx: &LateContext<'tcx>, expr: &'tcx hir::Expr<'_>) {
+ // Check our expr is calling a method with pattern matching
+ if let hir::ExprKind::MethodCall(path, _, [_self_arg, ..]) = &expr.kind
+ // Check if the name of this method is `our_fancy_method`
+ && path.ident.name == sym!(our_fancy_method)
+ // We can check the type of the self argument whenever necessary.
+ // (It's necessary if we want to check that method is specifically belonging to a specific trait,
+ // for example, a `map` method could belong to user-defined trait instead of to `Iterator`)
+ // See the "Type Checking" chapter of the Clippy book for more information.
+ {
+ println!("`expr` is a method call for `our_fancy_method`");
+ }
+ }
+}
+```
+
+Take a closer look at the `ExprKind` enum variant [MethodCall] for more
+information on the pattern matching.
+As mentioned in [Define Lints](define_lints.md#lint-types),
+the `methods` lint type is full of pattern matching with `Methodcall`
+in case the reader wishes to explore more.
+
+Additionally, we use the [`clippy_utils::sym!`][sym] macro to conveniently convert
+an input `our_fancy_method` into a `Symbol` and compare that symbol to the [ident][Ident]'s name in the [PathSegment]
+in the [MethodCall].
+
+## Checking if a type defines a specific method
+
+While sometimes we want to check whether a method is being called or not,
+other times we want to know if our type `Ty` defines a method.
+
+To check if our type defines a method called `our_fancy_method`,
+we will utilize the [check_impl_item] method that is available
+in our beloved [LateLintPass] (for more information, refer to the
+["Lint Passes"](lint_passes.md) chapter in Clippy book).
+This method provides us with an [ImplItem] struct, which represents
+anything within an `impl` block.
+
+Let us take a look at how we might check for the implementation of
+`our_fancy_method` on a type:
+
+```rust
+use clippy_utils::ty::is_type_diagnostic_item;
+use clippy_utils::return_ty;
+use rustc_hir::{ImplItem, ImplItemKind};
+use rustc_lint::{LateContext, LateLintPass};
+use rustc_span::symbol::sym;
+
+impl<'tcx> LateLintPass<'tcx> for MyTypeImpl {
+ fn check_impl_item(&mut self, cx: &LateContext<'tcx>, impl_item: &'tcx ImplItem<'_>) {
+ // Check if item is a method/function
+ if let ImplItemKind::Fn(ref signature, _) = impl_item.kind
+ // Check the method is named `our_fancy_method`
+ && impl_item.ident.name == sym!(our_fancy_method)
+ // We can also check it has a parameter `self`
+ && signature.decl.implicit_self.has_implicit_self()
+ // We can go even further and even check if its return type is `String`
+ && is_type_diagnostic_item(cx, return_ty(cx, impl_item.hir_id), sym::String)
+ {
+ println!("`our_fancy_method` is implemented!");
+ }
+ }
+}
+```
+
+[check_impl_item]: https://doc.rust-lang.org/stable/nightly-rustc/rustc_lint/trait.LateLintPass.html#method.check_impl_item
+[ExprKind]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_hir/hir/enum.ExprKind.html
+[Ident]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_span/symbol/struct.Ident.html
+[ImplItem]: https://doc.rust-lang.org/stable/nightly-rustc/rustc_hir/hir/struct.ImplItem.html
+[LateLintPass]: https://doc.rust-lang.org/stable/nightly-rustc/rustc_lint/trait.LateLintPass.html
+[MethodCall]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_hir/hir/enum.ExprKind.html#variant.MethodCall
+[PathSegment]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_hir/hir/struct.PathSegment.html
+[sym]: https://doc.rust-lang.org/stable/nightly-rustc/clippy_utils/macro.sym.html