compiler/rustc_hir/src/itemlikevisit.rs

   1 use super::{ImplItem, Item, TraitItem};
   2
   3 /// The "item-like visitor" defines only the top-level methods
   4 /// that can be invoked by `Crate::visit_all_item_likes()`. Whether
   5 /// this trait is the right one to implement will depend on the
   6 /// overall pattern you need. Here are the three available patterns,
   7 /// in roughly the order of desirability:
   8 ///
   9 /// 1. **Shallow visit**: Get a simple callback for every item (or item-like thing) in the HIR.
  10 ///    - Example: find all items with a `#[foo]` attribute on them.
  11 ///    - How: Implement `ItemLikeVisitor` and call `tcx.hir().krate().visit_all_item_likes()`.
  12 ///    - Pro: Efficient; just walks the lists of item-like things, not the nodes themselves.
  13 ///    - Con: Don't get information about nesting
  14 ///    - Con: Don't have methods for specific bits of HIR, like "on
  15 ///      every expr, do this".
  16 /// 2. **Deep visit**: Want to scan for specific kinds of HIR nodes within
  17 ///    an item, but don't care about how item-like things are nested
  18 ///    within one another.
  19 ///    - Example: Examine each expression to look for its type and do some check or other.
  20 ///    - How: Implement `intravisit::Visitor` and override the `nested_visit_map()` method
  21 ///      to return `NestedVisitorMap::OnlyBodies` and use
  22 ///      `tcx.hir().krate().visit_all_item_likes(&mut visitor.as_deep_visitor())`. Within
  23 ///      your `intravisit::Visitor` impl, implement methods like `visit_expr()` (don't forget
  24 ///      to invoke `intravisit::walk_expr()` to keep walking the subparts).
  25 ///    - Pro: Visitor methods for any kind of HIR node, not just item-like things.
  26 ///    - Pro: Integrates well into dependency tracking.
  27 ///    - Con: Don't get information about nesting between items
  28 /// 3. **Nested visit**: Want to visit the whole HIR and you care about the nesting between
  29 ///    item-like things.
  30 ///    - Example: Lifetime resolution, which wants to bring lifetimes declared on the
  31 ///      impl into scope while visiting the impl-items, and then back out again.
  32 ///    - How: Implement `intravisit::Visitor` and override the `nested_visit_map()` method
  33 ///      to return `NestedVisitorMap::All`. Walk your crate with `intravisit::walk_crate()`
  34 ///      invoked on `tcx.hir().krate()`.
  35 ///    - Pro: Visitor methods for any kind of HIR node, not just item-like things.
  36 ///    - Pro: Preserves nesting information
  37 ///    - Con: Does not integrate well into dependency tracking.
  38 ///
  39 /// Note: the methods of `ItemLikeVisitor` intentionally have no
  40 /// defaults, so that as we expand the list of item-like things, we
  41 /// revisit the various visitors to see if they need to change. This
  42 /// is harder to do with `intravisit::Visitor`, so when you add a new
  43 /// `visit_nested_foo()` method, it is recommended that you search for
  44 /// existing `fn visit_nested` methods to see where changes are
  45 /// needed.
  46 pub trait ItemLikeVisitor<'hir> {
  47     fn visit_item(&mut self, item: &'hir Item<'hir>);
  48     fn visit_trait_item(&mut self, trait_item: &'hir TraitItem<'hir>);
  49     fn visit_impl_item(&mut self, impl_item: &'hir ImplItem<'hir>);
  50 }
  51
  52 /// A parallel variant of `ItemLikeVisitor`.
  53 pub trait ParItemLikeVisitor<'hir> {
  54     fn visit_item(&self, item: &'hir Item<'hir>);
  55     fn visit_trait_item(&self, trait_item: &'hir TraitItem<'hir>);
  56     fn visit_impl_item(&self, impl_item: &'hir ImplItem<'hir>);
  57 }