From 8501024546311ee86af50a2877d48584779d6dee Mon Sep 17 00:00:00 2001
From: David Laban <alsuren@gmail.com>
Date: Sat, 9 Sep 2023 15:42:37 +0100
Subject: [PATCH] signpost 'input list --types [key]' from 'keybindings list'
 (#10287)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Supercedes https://github.com/nushell/nushell/pull/10196

# Description

After reading
https://github.com/nushell/nushell/pull/10196#issuecomment-1703986359 I
added a signpost from `keybindings listen` to `input listen`

When I initially tried `input listen` it always immediately returned
with:
```
╭───────┬────────╮
│ type  │ focus  │
│ event │ gained │
╰───────┴────────╯
```

I added an example to `input listen --help` to suggest only listening to
key events

Initially I also included a `result` but it prints as:

```
  ╭───────────┬───────────────╮
  │ type      │ key           │
  │ key_type  │ char          │
  │ code      │ c             │
  │ modifiers │ [list 1 item] │
  ╰───────────┴───────────────╯
```

rather than:

```
╭───────────┬───────────────────────────────╮
│ type      │ key                           │
│ key_type  │ char                          │
│ code      │ c                             │
│           │ ╭───┬───────────────────────╮ │
│ modifiers │ │ 0 │ keymodifiers(control) │ │
│           │ ╰───┴───────────────────────╯ │
╰───────────┴───────────────────────────────╯
```
so I removed it.

# User-Facing Changes

<!-- List of all changes that impact the user experience here. This
helps us keep track of breaking changes. -->

* Example describing how to use `input list --types [key]` to listen for
keybindings.
* Signpost pointing at `use std input; input list --types [key]` from
`keybindings list`.

## After merging

It is probably worth:

a) signposting to the keybindings section of the book from both of these
subcommands (like I did in
https://github.com/nushell/nushell/pull/10193),
b) giving an example in the book of how to take the output from `input
listen --types [key]` and format it for including in `config nu`
c) there are not currently any examples in
crates/nu-utils/src/sample_config/default_config.nu for keybindings with
multiple modifiers. Should I add alt+backspace-in-macos-vscode as an
example (gets translated to `{ modifier: control_alt keycode: char_h }`
for historical reasons)?

---------

Co-authored-by: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
---
 crates/nu-cli/src/commands/keybindings_listen.rs     |  4 ++++
 crates/nu-command/src/platform/input/input_listen.rs | 12 +++++++++---
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/crates/nu-cli/src/commands/keybindings_listen.rs b/crates/nu-cli/src/commands/keybindings_listen.rs
index cdda374ae..96d8f4f32 100644
--- a/crates/nu-cli/src/commands/keybindings_listen.rs
+++ b/crates/nu-cli/src/commands/keybindings_listen.rs
@@ -20,6 +20,10 @@ impl Command for KeybindingsListen {
         "Get input from the user."
     }
 
+    fn extra_usage(&self) -> &str {
+        "This is an internal debugging tool. For better output, try `input listen --types [key]`"
+    }
+
     fn signature(&self) -> Signature {
         Signature::build(self.name())
             .category(Category::Platform)
diff --git a/crates/nu-command/src/platform/input/input_listen.rs b/crates/nu-command/src/platform/input/input_listen.rs
index f0ad136c5..7ed6b31a1 100644
--- a/crates/nu-command/src/platform/input/input_listen.rs
+++ b/crates/nu-command/src/platform/input/input_listen.rs
@@ -7,8 +7,8 @@ use nu_engine::CallExt;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
 use nu_protocol::{
-    record, Category, IntoPipelineData, PipelineData, ShellError, Signature, Span, SyntaxShape,
-    Type, Value,
+    record, Category, Example, IntoPipelineData, PipelineData, ShellError, Signature, Span,
+    SyntaxShape, Type, Value,
 };
 use num_traits::AsPrimitive;
 use std::io::stdout;
@@ -69,7 +69,13 @@ There are 4 `key_type` variants:
     media - dedicated media keys (play, pause, tracknext ...)
     other - keys not falling under previous categories (up, down, backspace, enter ...)"#
     }
-
+    fn examples(&self) -> Vec<Example> {
+        vec![Example {
+            description: "Listen for a keyboard shortcut and find out how nu receives it",
+            example: "input listen --types [key]",
+            result: None,
+        }]
+    }
     fn run(
         &self,
         engine_state: &EngineState,