From 81d00f71a92bdc46c91b9ae9204039d6216c4587 Mon Sep 17 00:00:00 2001
From: Eric Hodel <drbrain@segment7.net>
Date: Sat, 4 Nov 2023 13:12:58 -0700
Subject: [PATCH] Show plugin extra usage and search terms (#10952)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# Description

The `PluginSignature` type supports extra usage but this was not
available in `plugin_name --help`. It also supports search terms but
these did not appear in `help commands`

New behavior show below is the "Extra usage for nu-example-1" line and
the "Search terms:" line

```
❯ nu-example-1 --help
PluginSignature test 1 for plugin. Returns Value::Nothing

Extra usage for nu-example-1

Search terms: example

Usage:
  > nu-example-1 {flags} <a> <b> (opt) ...(rest)

Flags:
  -h, --help - Display the help message for this command
  -f, --flag - a flag for the signature
  -n, --named <String> - named string

Parameters:
  a <int>: required integer value
  b <string>: required string value
  opt <int>: Optional number (optional)
  ...rest <string>: rest value string

Examples:
  running example with an int value and string value
  > nu-example-1 3 bb
```

Search terms are also available in `help commands`:

```
❯ help commands | where name == "nu-example-1" | select name search_terms
╭──────────────┬──────────────╮
│     name     │ search_terms │
├──────────────┼──────────────┤
│ nu-example-1 │ example      │
╰──────────────┴──────────────╯
```

# User-Facing Changes

Users can now see plugin extra usage and search terms

# Tests + Formatting

- :green_circle: `toolkit fmt`
- :green_circle: `toolkit clippy`
- :green_circle: `toolkit test`
- :green_circle: `toolkit test stdlib`

# After Submitting

N/A
---
 crates/nu-plugin/src/plugin/declaration.rs | 13 ++++++++++
 crates/nu_plugin_example/src/nu/mod.rs     |  2 ++
 tests/plugins/mod.rs                       |  1 +
 tests/plugins/register.rs                  | 29 ++++++++++++++++++++++
 4 files changed, 45 insertions(+)
 create mode 100644 tests/plugins/register.rs

diff --git a/crates/nu-plugin/src/plugin/declaration.rs b/crates/nu-plugin/src/plugin/declaration.rs
index 3a37f4c3d9..84f3a49acb 100644
--- a/crates/nu-plugin/src/plugin/declaration.rs
+++ b/crates/nu-plugin/src/plugin/declaration.rs
@@ -43,6 +43,19 @@ impl Command for PluginDeclaration {
         self.signature.sig.usage.as_str()
     }
 
+    fn extra_usage(&self) -> &str {
+        self.signature.sig.extra_usage.as_str()
+    }
+
+    fn search_terms(&self) -> Vec<&str> {
+        self.signature
+            .sig
+            .search_terms
+            .iter()
+            .map(|term| term.as_str())
+            .collect()
+    }
+
     fn examples(&self) -> Vec<Example> {
         let mut res = vec![];
         for e in self.signature.examples.iter() {
diff --git a/crates/nu_plugin_example/src/nu/mod.rs b/crates/nu_plugin_example/src/nu/mod.rs
index 1a1d5f8cfc..2eb5dc1fd5 100644
--- a/crates/nu_plugin_example/src/nu/mod.rs
+++ b/crates/nu_plugin_example/src/nu/mod.rs
@@ -10,6 +10,8 @@ impl Plugin for Example {
         vec![
             PluginSignature::build("nu-example-1")
                 .usage("PluginSignature test 1 for plugin. Returns Value::Nothing")
+                .extra_usage("Extra usage for nu-example-1")
+                .search_terms(vec!["example".into()])
                 .required("a", SyntaxShape::Int, "required integer value")
                 .required("b", SyntaxShape::String, "required string value")
                 .switch("flag", "a flag for the signature", Some('f'))
diff --git a/tests/plugins/mod.rs b/tests/plugins/mod.rs
index ec49b88a8b..a51d777eef 100644
--- a/tests/plugins/mod.rs
+++ b/tests/plugins/mod.rs
@@ -1,3 +1,4 @@
 mod core_inc;
 mod custom_values;
 mod formats;
+mod register;
diff --git a/tests/plugins/register.rs b/tests/plugins/register.rs
new file mode 100644
index 0000000000..4e95c8eb85
--- /dev/null
+++ b/tests/plugins/register.rs
@@ -0,0 +1,29 @@
+use nu_test_support::nu_with_plugins;
+use nu_test_support::playground::Playground;
+
+#[test]
+fn help() {
+    Playground::setup("help", |dirs, _| {
+        let actual = nu_with_plugins!(
+        cwd: dirs.test(),
+            plugin: ("nu_plugin_example"),
+            "nu-example-1 --help"
+        );
+
+        assert!(actual.out.contains("PluginSignature test 1"));
+        assert!(actual.out.contains("Extra usage for nu-example-1"));
+    })
+}
+
+#[test]
+fn search_terms() {
+    Playground::setup("search_terms", |dirs, _| {
+        let actual = nu_with_plugins!(
+        cwd: dirs.test(),
+            plugin: ("nu_plugin_example"),
+            r#"help commands | where name == "nu-example-1" | echo $"search terms: ($in.search_terms)""#
+        );
+
+        assert!(actual.out.contains("search terms: [example]"));
+    })
+}