From 6f9b9914cff34e0c5bba531b8d613a96bc7a4767 Mon Sep 17 00:00:00 2001
From: TrMen <31260183+TrMen@users.noreply.github.com>
Date: Thu, 27 Apr 2023 22:58:07 +0200
Subject: [PATCH] Add more examples to `help use` (#9024)

# Description
The `members` parameter of `use` is specified as type `any`, but it's
really a string or list of strings or `*`. So add some examples that
mention what you can specify for `members`.

Also mention `help modules` and `help std`, since you probably want to
use the standard library or another defined modules.

Sidenote: I tried to run the examples for `use` as tests like is done
for the other commands. That panics with `missing module command`. I
assume this is known.

# User-Facing Changes
`help use` now looks like this:
```nushell
Use definitions from a module, making them available in your shell.

See `help std` for the standard library module.
See `help modules` to list all available modules.

This command is a parser keyword. For details, check:
  https://www.nushell.sh/book/thinking_in_nu.html

Usage:
  > use <module> (members)

Flags:
  -h, --help - Display the help message for this command

Parameters:
  module <string>: Module or module file
  (optional) members <any>: Which members of the module to import

Examples:
  Define a custom command in a module and call it
  > module spam { export def foo [] { "foo" } }; use spam foo; foo
  foo

  Define a custom command that participates in the environment in a module and call it
  > module foo { export def-env bar [] { let-env FOO_BAR = "BAZ" } }; use foo bar; bar; $env.FOO_BAR
  BAZ

  Use a plain module name to import its definitions qualified by the module name
  > module spam { export def foo [] { "foo" }; export def bar [] { "bar" } }; use spam; (spam foo) + (spam bar)
  foobar

  Specify * to use all definitions in a module
  > module spam { export def foo [] { "foo" }; export def bar [] { "bar" } }; use spam *; (foo) + (bar)
  foobar

  To use commands with spaces, like subcommands, surround them with quotes
  > module spam { export def 'foo bar' [] { "baz" } }; use spam 'foo bar'; foo bar
  baz

  To use multiple definitions from a module, wrap them in a list
  > module spam { export def foo [] { "foo" }; export def 'foo bar' [] { "baz" } }; use spam ['foo', 'foo bar']; (foo) + (foo bar)
  foobaz
```
---
 crates/nu-cmd-lang/src/core_commands/use_.rs | 27 ++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/crates/nu-cmd-lang/src/core_commands/use_.rs b/crates/nu-cmd-lang/src/core_commands/use_.rs
index d6ea0c08b3..67e8b814c7 100644
--- a/crates/nu-cmd-lang/src/core_commands/use_.rs
+++ b/crates/nu-cmd-lang/src/core_commands/use_.rs
@@ -14,7 +14,7 @@ impl Command for Use {
     }
 
     fn usage(&self) -> &str {
-        "Use definitions from a module."
+        "Use definitions from a module, making them available in your shell."
     }
 
     fn signature(&self) -> nu_protocol::Signature {
@@ -30,7 +30,10 @@ impl Command for Use {
     }
 
     fn extra_usage(&self) -> &str {
-        r#"This command is a parser keyword. For details, check:
+        r#"See `help std` for the standard library module.
+See `help modules` to list all available modules.
+
+This command is a parser keyword. For details, check:
   https://www.nushell.sh/book/thinking_in_nu.html"#
     }
 
@@ -134,6 +137,26 @@ impl Command for Use {
                 example: r#"module foo { export def-env bar [] { let-env FOO_BAR = "BAZ" } }; use foo bar; bar; $env.FOO_BAR"#,
                 result: Some(Value::test_string("BAZ")),
             },
+            Example {
+                description: "Use a plain module name to import its definitions qualified by the module name",
+                example: r#"module spam { export def foo [] { "foo" }; export def bar [] { "bar" } }; use spam; (spam foo) + (spam bar)"#,
+                result: Some(Value::test_string("foobar")),
+            },
+            Example {
+                description: "Specify * to use all definitions in a module",
+                example: r#"module spam { export def foo [] { "foo" }; export def bar [] { "bar" } }; use spam *; (foo) + (bar)"#,
+                result: Some(Value::test_string("foobar")),
+            },
+            Example {
+                description: "To use commands with spaces, like subcommands, surround them with quotes",
+                example: r#"module spam { export def 'foo bar' [] { "baz" } }; use spam 'foo bar'; foo bar"#,
+                result: Some(Value::test_string("baz")),
+            },
+            Example {
+                description: "To use multiple definitions from a module, wrap them in a list",
+                example: r#"module spam { export def foo [] { "foo" }; export def 'foo bar' [] { "baz" } }; use spam ['foo', 'foo bar']; (foo) + (foo bar)"#,
+                result: Some(Value::test_string("foobaz")),
+            },
         ]
     }
 }