src/librustc/hir/itemlikevisit.rs

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