src/doc/unstable-book/src/language-features/use-nested-groups.md

   1 # `use_nested_groups`
   2
   3 The tracking issue for this feature is: [#44494]
   4
   5 [#44494]: https://github.com/rust-lang/rust/issues/44494
   6
   7 ------------------------
   8
   9 The `use_nested_groups` feature allows you to import multiple items from a
  10 complex module tree easily, by nesting different imports in the same
  11 declaration. For example:
  12
  13 ```rust
  14 #![feature(use_nested_groups)]
  15 # #![allow(unused_imports, dead_code)]
  16 #
  17 # mod foo {
  18 #     pub mod bar {
  19 #         pub type Foo = ();
  20 #     }
  21 #     pub mod baz {
  22 #         pub mod quux {
  23 #             pub type Bar = ();
  24 #         }
  25 #     }
  26 # }
  27
  28 use foo::{
  29     bar::{self, Foo},
  30     baz::{*, quux::Bar},
  31 };
  32 #
  33 # fn main() {}
  34 ```
  35
  36 ## Snippet for the book's new features appendix
  37
  38 When stabilizing, add this to
  39 `src/doc/book/second-edition/src/appendix-07-newest-features.md`:
  40
  41 ### Nested groups in `use` declarations
  42
  43 If you have a complex module tree with many different submodules and you need
  44 to import a few items from each one, it might be useful to group all the
  45 imports in the same declaration to keep your code clean and avoid repeating the
  46 base modules' name.
  47
  48 The `use` declaration supports nesting to help you in those cases, both with
  49 simple imports and glob ones. For example this snippets imports `bar`, `Foo`,
  50 all the items in `baz` and `Bar`:
  51
  52 ```rust
  53 # #![feature(use_nested_groups)]
  54 # #![allow(unused_imports, dead_code)]
  55 #
  56 # mod foo {
  57 #     pub mod bar {
  58 #         pub type Foo = ();
  59 #     }
  60 #     pub mod baz {
  61 #         pub mod quux {
  62 #             pub type Bar = ();
  63 #         }
  64 #     }
  65 # }
  66 #
  67 use foo::{
  68     bar::{self, Foo},
  69     baz::{*, quux::Bar},
  70 };
  71 #
  72 # fn main() {}
  73 ```
  74
  75 ## Updated reference
  76
  77 When stabilizing, replace the shortcut list in
  78 `src/doc/reference/src/items/use-declarations.md` with this updated one:
  79
  80 * Simultaneously binding a list of paths with a common prefix, using the
  81   glob-like brace syntax `use a::b::{c, d, e::f, g::h::i};`
  82 * Simultaneously binding a list of paths with a common prefix and their common
  83   parent module, using the `self` keyword, such as `use a::b::{self, c, d::e};`
  84 * Rebinding the target name as a new local name, using the syntax `use p::q::r
  85   as x;`. This can also be used with the last two features:
  86   `use a::b::{self as ab, c as abc}`.
  87 * Binding all paths matching a given prefix, using the asterisk wildcard syntax
  88   `use a::b::*;`.
  89 * Nesting groups of the previous features multiple times, such as
  90   `use a::b::{self as ab, c d::{*, e::f}};`