:h[elp] command and documentation

book/src/generated/typable-cmd.md

@@ -88,3 +88,4 @@
 | `:move` | Move the current buffer and its corresponding file to a different path |
 | `:yank-diagnostic` | Yank diagnostic(s) under primary cursor to register, or clipboard by default |
 | `:read`, `:r` | Load a file into buffer |
+| `:help`, `:h` | Open documentation for a command or keybind. |

helix-term/src/commands/typed.rs

@@ -2401,7 +2401,6 @@ fn move_buffer(
     if event != PromptEvent::Validate {
         return Ok(());
     }
-
     ensure!(args.len() == 1, format!(":move takes one argument"));
     let doc = doc!(cx.editor);
     let old_path = doc
@@ -2488,6 +2487,116 @@ fn read(cx: &mut compositor::Context, args: &[Cow<str>], event: PromptEvent) ->
     Ok(())
 }
 
+fn help(cx: &mut compositor::Context, args: &[Cow<str>], event: PromptEvent) -> anyhow::Result<()> {
+    if event != PromptEvent::Validate {
+        return Ok(());
+    }
+
+    const STATIC_HELP_DIR: &str = "static-commands";
+    const TYPABLE_HELP_DIR: &str = "typable-commands";
+
+    let args_msg = args.join(" ");
+    let open_help =
+        move |help_dir: &str, command: &str, editor: &mut Editor| -> anyhow::Result<()> {
+            let path = Path::new("help").join(help_dir).join(command);
+            let path = helix_loader::runtime_file(&path);
+            ensure!(path.is_file(), "No help available for '{args_msg}'");
+            let id = editor.open(&path, Action::HorizontalSplit)?;
+            editor.document_mut(id).unwrap().set_path(None);
+
+            Ok(())
+        };
+
+    if args.is_empty() {
+        return open_help(TYPABLE_HELP_DIR, "help", cx.editor);
+    }
+
+    if args[0] == "topics" {
+        let dir_path = helix_loader::runtime_file(Path::new("help/topics"));
+
+        let callback = async move {
+            let call: job::Callback = job::Callback::EditorCompositor(Box::new(
+                move |editor: &mut Editor, compositor: &mut Compositor| {
+                    let picker = ui::file_picker(dir_path, &editor.config());
+                    compositor.push(Box::new(overlaid(picker)));
+                },
+            ));
+            Ok(call)
+        };
+        cx.jobs.callback(callback);
+
+        return Ok(());
+    }
+
+    let (help_dir, command): (&str, &str) = {
+        let arg = &args[0];
+        if let Some(command) = arg.strip_prefix(':').and_then(|arg| {
+            TYPABLE_COMMAND_LIST.iter().find_map(|command| {
+                (command.name == arg || command.aliases.contains(&arg)).then_some(command.name)
+            })
+        }) {
+            (TYPABLE_HELP_DIR, command)
+        } else if MappableCommand::STATIC_COMMAND_LIST
+            .iter()
+            .any(|command| command.name() == arg)
+        {
+            (STATIC_HELP_DIR, arg)
+        } else {
+            let arg = arg.clone().into_owned();
+            let keys = arg
+                .parse::<KeyEvent>()
+                .map(|key| vec![key])
+                .or_else(|_| helix_view::input::parse_macro(&arg))?;
+            let callback = async move {
+                let call: job::Callback = job::Callback::EditorCompositor(Box::new(
+                    move |editor: &mut Editor, compositor: &mut Compositor| {
+                        use crate::keymap::KeymapResult;
+                        let editor_view = compositor.find::<ui::EditorView>().unwrap();
+                        let mode = editor.mode;
+                        let keymaps = &mut editor_view.keymaps;
+                        let (keys, last_key) = (&keys[..keys.len() - 1], keys.last().unwrap());
+                        keys.iter().for_each(|key| {
+                            keymaps.get(mode, *key);
+                        });
+                        let key_result = keymaps.get(mode, *last_key);
+                        let result: anyhow::Result<(&str, &str)> = match &key_result {
+                            KeymapResult::Matched(command) => match command {
+                                MappableCommand::Static { name, .. } => Ok((STATIC_HELP_DIR, name)),
+                                MappableCommand::Typable { name, .. } => {
+                                    Ok((TYPABLE_HELP_DIR, name))
+                                }
+                            },
+                            KeymapResult::NotFound | KeymapResult::Cancelled(_) => {
+                                Err(anyhow!("No command found for '{}'", arg))
+                            }
+                            KeymapResult::Pending(_) => {
+                                // Clear pending keys
+                                keymaps.get(mode, crate::keymap::macros::key!(Esc));
+                                Err(anyhow!(
+                                    "`:help` for branching keybinds is not yet supported."
+                                ))
+                            }
+                            KeymapResult::MatchedSequence(_) => Err(anyhow!(
+                                "`:help` for sequence bindings is not yet supported."
+                            )),
+                        };
+                        if let Err(e) = result
+                            .and_then(|(help_dir, command)| open_help(help_dir, command, editor))
+                        {
+                            editor.set_error(e.to_string());
+                        }
+                    },
+                ));
+                Ok(call)
+            };
+            cx.jobs.callback(callback);
+            return Ok(());
+        }
+    };
+
+    open_help(help_dir, command, cx.editor)
+}
+
 pub const TYPABLE_COMMAND_LIST: &[TypableCommand] = &[
     TypableCommand {
         name: "quit",
@@ -3109,6 +3218,13 @@ pub const TYPABLE_COMMAND_LIST: &[TypableCommand] = &[
         fun: read,
         signature: CommandSignature::positional(&[completers::filename]),
     },
+    TypableCommand {
+        name: "help",
+        aliases: &["h"],
+        doc: "Open documentation for a command or keybind.",
+        fun: help,
+        signature: CommandSignature::positional(&[completers::help]),
+    },
 ];
 
 pub static TYPABLE_COMMAND_MAP: Lazy<HashMap<&'static str, &'static TypableCommand>> =

helix-term/src/ui/mod.rs

@@ -397,6 +397,42 @@ pub mod completers {
         })
     }
 
+    pub fn help(_editor: &Editor, input: &str) -> Vec<Completion> {
+        use std::path::Path;
+        let static_cmds_path = helix_loader::runtime_file(Path::new("help/static-commands"));
+        let typable_cmds_path = helix_loader::runtime_file(Path::new("help/typable-commands"));
+
+        let static_cmds = std::fs::read_dir(static_cmds_path)
+            .into_iter()
+            .flat_map(|entries| {
+                entries.filter_map(|entry| {
+                    let path = entry.ok()?.path();
+                    path.extension()
+                        .is_none()
+                        .then(|| path.file_stem().unwrap().to_string_lossy().into_owned())
+                })
+            });
+        let typable_cmds = std::fs::read_dir(typable_cmds_path)
+            .into_iter()
+            .flat_map(|entries| {
+                entries.filter_map(|entry| {
+                    let path = entry.ok()?.path();
+                    path.extension()
+                        .is_none()
+                        .then(|| format!(":{}", path.file_stem().unwrap().to_string_lossy()))
+                })
+            });
+
+        let items = std::iter::once("topics".to_owned())
+            .chain(static_cmds)
+            .chain(typable_cmds);
+
+        fuzzy_match(input, items, false)
+            .into_iter()
+            .map(|(name, _)| (0.., name.into()))
+            .collect()
+    }
+
     #[derive(Copy, Clone, PartialEq, Eq)]
     enum FileMatch {
         /// Entry should be ignored

runtime/help/static-commands/append_mode

@@ -0,0 +1,5 @@
+`append_mode`
+
+Enters Insert mode at the end of the selection.
+
+For information about Insert mode, see "Primary Modes".

runtime/help/static-commands/append_to_line

@@ -0,0 +1,5 @@
+`append_to_line`
+
+Enters Insert mode at the end of the line.
+
+For information about Insert mode, see "Primary Modes".

runtime/help/static-commands/copy_selection_on_next_line

@@ -0,0 +1,18 @@
+`copy_selection_on_next_line`
+
+Copies the current primary selection to the next line long enough to accomodate it.
+
+--- Examples ---
+
+The selection is copied from line 1 to line 2.
+┌───────────────────────────┐     ┌───────────────────────────┐
+│ This is text (on line 1]. │ --> │ This is text (on line 1]. │
+│ This is text on line 2.   │     │ This is text (on line 2]. │
+└───────────────────────────┘     └───────────────────────────┘
+
+The selection duplication skips line 2 because it is too short.
+┌──────────────────────────────────┐     ┌──────────────────────────────────┐
+│ This is a longer li(ne of t]ext. │     │ This is a longer li(ne of t]ext. │
+│ This is a shorter line.          │ --> │ This is a shorter line.          │
+│ This is another longer line.     │     │ This is another lon(ger lin]e.   │
+└──────────────────────────────────┘     └──────────────────────────────────┘

runtime/help/static-commands/copy_selection_on_prev_line

@@ -0,0 +1,18 @@
+`copy_selection_on_prev_line`
+
+Copies the current primary selection to the first previous line long enough to accomodate it.
+
+--- Examples ---
+
+The selection is copied from line 2 to line 1.
+┌───────────────────────────┐     ┌───────────────────────────┐
+│ This is text on line 1.   │ --> │ This is text (on line 1]. │
+│ This is text (on line 2]. │     │ This is text (on line 2]. │
+└───────────────────────────┘     └───────────────────────────┘
+
+The selection duplication skips line 2 because it is too short.
+┌──────────────────────────────────┐     ┌──────────────────────────────────┐
+│ This is a longer line of text.   │     │ This is a longer li(ne of t]ext. │
+│ This is a shorter line.          │ --> │ This is a shorter line.          │
+│ This is another lon(ger lin]e.   │     │ This is another lon(ger lin]e.   │
+└──────────────────────────────────┘     └──────────────────────────────────┘

runtime/help/static-commands/extend_char_left

@@ -0,0 +1,3 @@
+`extend_char_left`
+
+Extending version of `move_char_left`.

runtime/help/static-commands/extend_char_right

@@ -0,0 +1,3 @@
+`extend_char_right`
+
+Extending version of `move_char_right`.

runtime/help/static-commands/extend_line_down

@@ -0,0 +1,3 @@
+`extend_line_down`
+
+Extending version of `move_line_down`.

runtime/help/static-commands/extend_line_up

@@ -0,0 +1,3 @@
+`extend_line_up`
+
+Extending version of `move_line_up`.

runtime/help/static-commands/extend_next_char

@@ -0,0 +1,3 @@
+`extend_next_char`
+
+Extending version of `find_next_char`.

runtime/help/static-commands/extend_next_long_word_end

@@ -0,0 +1,3 @@
+`extend_next_long_word_end`
+
+Extending version of `move_next_long_word_end`.

runtime/help/static-commands/extend_next_long_word_start

@@ -0,0 +1,3 @@
+`extend_next_long_word_start`
+
+Extending version of `move_next_long_word_start`.

runtime/help/static-commands/extend_next_word_end

@@ -0,0 +1,3 @@
+`extend_next_word_end`
+
+Extending version of `move_next_word_end`.

runtime/help/static-commands/extend_next_word_start

@@ -0,0 +1,3 @@
+`extend_next_word_start`
+
+Extending version of `move_next_word_start`.

runtime/help/static-commands/extend_prev_char

@@ -0,0 +1,3 @@
+`extend_prev_char`
+
+Extending version of `find_prev_char`.

runtime/help/static-commands/extend_prev_long_word_start

@@ -0,0 +1,3 @@
+`extend_prev_long_word_start`
+
+Extending version of `move_prev_long_word_start`.

runtime/help/static-commands/extend_prev_word_start

@@ -0,0 +1,3 @@
+`extend_prev_word_start`
+
+Extending version of `move_prev_word_start`.

runtime/help/static-commands/extend_till_char

@@ -0,0 +1,3 @@
+`extend_till_char`
+
+Extending version of `find_till_char`.

runtime/help/static-commands/extend_till_prev_char

@@ -0,0 +1,3 @@
+`extend_till_prev_char`
+
+Extending version of `till_prev_char`.

runtime/help/static-commands/find_next_char

@@ -0,0 +1,22 @@
+`find_next_char`
+
+Waits for another keypress, then moves and
+selects forward, stopping at the first
+instance of the pressed key. Can take
+a count, which will cause it to stop
+at the nth instance of the keypress,
+rather than the first.
+
+--- Examples ---
+
+The cursor moves forward, stopping at 'c'
+and selecting everything along the way.
+┌───────────────────────┐  c  ┌───────────────────────┐
+│ This i[s] a sentence. │ --> │ This i(s a sentenc]e. │
+└───────────────────────┘     └───────────────────────┘
+
+The cursor is not stopped by line breaks.
+┌───────────────────────────┐     ┌────────────────────────────┐
+│ This is the fi[r]st line. │  Q  │ This is the fi(rst line.   │
+│ This second line has a Q. │ --> │ This second line has a Q]. │
+└───────────────────────────┘     └────────────────────────────┘

runtime/help/static-commands/find_prev_char

@@ -0,0 +1,22 @@
+`find_prev_char`
+
+Waits for another keypress, then moves and
+selects backward, stopping at the first
+instance of the pressed key. Can take
+a count, which will cause it to stop
+at the nth instance of the keypress,
+rather than the first.
+
+--- Examples ---
+
+The cursor moves backward, stopping at 'h'
+and selecting everything along the way.
+┌───────────────────────┐  h  ┌───────────────────────┐
+│ This is a sent[e]nce. │ --> │ T[his is a sente)nce. │
+└───────────────────────┘     └───────────────────────┘
+
+The cursor is not stopped by line breaks.
+┌──────────────────────────────────┐     ┌───────────────────────────────────┐
+│ There is a Q in this first line. │  Q  │ There is a [Q in this first line. │
+│ This is the se[c]ond line.       │ --> │ This is the sec)ond line.         │
+└──────────────────────────────────┘     └───────────────────────────────────┘

runtime/help/static-commands/find_till_char

@@ -0,0 +1,22 @@
+`find_till_char`
+
+Waits for another keypress, then moves and
+selects forward, stopping before the first
+instance of the pressed key. Can take
+a count, which will cause it to stop
+before the nth instance of the keypress,
+rather than the first.
+
+--- Examples ---
+
+The cursor moves forward, stopping before 'c'
+and selecting everything along the way.
+┌───────────────────────┐  c  ┌───────────────────────┐
+│ This i[s] a sentence. │ --> │ This i(s a senten]ce. │
+└───────────────────────┘     └───────────────────────┘
+
+The cursor is not stopped by line breaks.
+┌───────────────────────────┐     ┌────────────────────────────┐
+│ This is the fi[r]st line. │  Q  │ This is the fi(rst line.   │
+│ This second line has a Q. │ --> │ This second line has a ]Q. │
+└───────────────────────────┘     └────────────────────────────┘

runtime/help/static-commands/half_page_down

@@ -0,0 +1,3 @@
+`half_page_down`
+
+Scrolls down by half of a screen.

runtime/help/static-commands/half_page_up

@@ -0,0 +1,3 @@
+`half_page_up`
+
+Scrolls up by half of a screen.

runtime/help/static-commands/insert_mode

@@ -0,0 +1,5 @@
+`insert_mode`
+
+Enters Insert mode at the start of the selection.
+
+For information about Insert mode, see "Primary Modes".

runtime/help/static-commands/move_char_left

@@ -0,0 +1,4 @@
+`move_char_left`
+
+Moves all cursors 1 character left, removing
+any selections and wrapping across line breaks.

runtime/help/static-commands/move_char_right

@@ -0,0 +1,4 @@
+`move_char_right`
+
+Moves all cursors 1 character right, removing
+any selections and wrapping across line breaks.