Merge pull request #7 from TunaCuma/feature/emacs-insert-mode-support

feat: add emacs mode and vi insert mode support

Author: TunaCuma

.github/workflows/test.yml

@@ -128,6 +128,11 @@ jobs:
           zsh test_config.zsh
         shell: bash
 
+      - name: Test multi-mode support (emacs and insert modes)
+        run: |
+          zsh test_modes.zsh
+        shell: zsh {0}
+      
       - name: Test integration with zsh-vi-mode (simulation)
         run: |
           cat > test_zvm_integration.zsh << 'EOF'

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test test-load test-keybinding test-config test-all check clean help
+.PHONY: test test-load test-keybinding test-config test-modes test-all check clean help
 
 # Default target
 .DEFAULT_GOAL := help
@@ -46,7 +46,11 @@ test-config: ## Test custom configuration
 			exit 1; \
 		fi'
 
-test-all: test test-load test-keybinding test-config ## Run all tests
+test-modes: ## Test emacs and insert mode support
+	@echo "Testing multi-mode support..."
+	@zsh test_modes.zsh
+
+test-all: test test-load test-keybinding test-config test-modes ## Run all tests
 	@echo ""
 	@echo "All tests completed successfully"
 
@@ -56,7 +60,7 @@ check: test-all ## Run all tests (alias for test-all)
 
 clean: ## Clean up temporary files
 	@echo "Cleaning up..."
-	@rm -f test_*.zsh 2>/dev/null || true
+	@rm -f test_load.zsh test_keybinding.zsh test_config.zsh test_zvm_integration.zsh 2>/dev/null || true
 	@echo "Cleanup complete"
 
 install-local: ## Install to local zsh config
@@ -73,15 +77,23 @@ demo: ## Show a quick demo of the plugin
 	@echo "  zsh-vi-man Demo"
 	@echo "==================================="
 	@echo ""
-	@echo "1. Type a command:    ls -la"
-	@echo "2. Press Escape:      (enter vi normal mode)"
-	@echo "3. Move cursor:       to 'ls' or '-la'"
-	@echo "4. Press K:           opens man page"
+	@echo "Vi Normal Mode (default):"
+	@echo "  1. Type a command:    ls -la"
+	@echo "  2. Press Escape:      (enter vi normal mode)"
+	@echo "  3. Move cursor:       to 'ls' or '-la'"
+	@echo "  4. Press K:           opens man page"
+	@echo ""
+	@echo "Emacs Mode:"
+	@echo "  1. Type a command:    grep --color pattern"
+	@echo "  2. Move cursor:       to 'grep' or '--color'"
+	@echo "  3. Press Ctrl-X k:    opens man page"
 	@echo ""
-	@echo "Try it yourself!"
+	@echo "Vi Insert Mode:"
+	@echo "  1. Type a command:    git commit -m"
+	@echo "  2. Press Ctrl-K:      opens man page (no Escape needed!)"
 	@echo ""
 	@echo "To test the plugin interactively:"
 	@echo "  zsh"
 	@echo "  source ./zsh-vi-man.plugin.zsh"
-	@echo "  # Now type commands and press Esc, then K"
+	@echo "  # Try the keybindings above!"
 

README.md

@@ -2,9 +2,9 @@
 
 # 📖 zsh-vi-man
 
-**Smart man page lookup for zsh vi mode**
+**Smart man page lookup for zsh vi mode (now with emacs mode support!)**
 
-Press `Shift-K` on any command or option to instantly open its man page
+Press `K` (vi normal mode), `Ctrl-X k` (emacs mode), or `Ctrl-K` (vi insert mode) on any command or option to instantly open its man page
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Zsh](https://img.shields.io/badge/Shell-Zsh-green.svg)](https://www.zsh.org/)
@@ -156,11 +156,19 @@ echo 'source ~/.zsh-vi-man/zsh-vi-man.plugin.zsh' >> ~/.zshrc
 
 ## 🚀 Usage
 
+### Vi Normal Mode (Default)
+
 1. Type a command (e.g., `ls -la` or `git commit --amend`)
 2. Press `Escape` to enter vi normal mode
 3. Move cursor to any word
 4. Press **`K`** to open the man page
 
+### Emacs Mode / Vi Insert Mode
+
+Without leaving insert mode or if using emacs mode:
+- **Emacs mode**: Press **`Ctrl-X`** then **`k`**
+- **Vi insert mode**: Press **`Ctrl-K`**
+
 <br>
 
 ### Examples
@@ -181,13 +189,61 @@ echo 'source ~/.zsh-vi-man/zsh-vi-man.plugin.zsh' >> ~/.zshrc
 Set these variables **before** sourcing the plugin:
 
 ```zsh
-# Change the trigger key (default: K)
+# Vi normal mode key (default: K)
 ZVM_MAN_KEY='?'
 
+# Emacs mode key sequence (default: ^Xk, i.e., Ctrl-X k)
+ZVM_MAN_KEY_EMACS='^X^K'  # Example: Ctrl-X Ctrl-K
+
+# Vi insert mode key (default: ^K, i.e., Ctrl-K)
+ZVM_MAN_KEY_INSERT='^H'   # Example: Ctrl-H
+
+# Enable/disable emacs mode binding (default: true)
+ZVM_MAN_ENABLE_EMACS=false
+
+# Enable/disable vi insert mode binding (default: true)
+ZVM_MAN_ENABLE_INSERT=false
+
 # Use a different pager (default: less)
 ZVM_MAN_PAGER='bat'
 ```
 
+### Troubleshooting
+
+**Keybindings not working?**
+
+If keybindings don't work after sourcing the plugin, try running:
+
+```zsh
+zvm_man_rebind
+```
+
+This can happen if:
+- Your plugin manager loads plugins before setting up keymaps
+- You call `bindkey -e` or `bindkey -v` after the plugin loads
+- Another plugin resets your keybindings
+
+**For persistent issues**, add this to your `.zshrc` **after** sourcing the plugin:
+
+```zsh
+# Ensure zsh-vi-man bindings are set
+zvm_man_rebind
+```
+
+<details>
+<summary><b>Key Binding Examples</b></summary>
+
+| Key Notation | Description |
+|:-------------|:------------|
+| `^K` | Ctrl-K |
+| `^Xk` | Ctrl-X then k |
+| `^X^K` | Ctrl-X then Ctrl-K |
+| `\ek` | Alt-k (or Escape then k) |
+
+For special keys, use zsh notation: `^[` for Escape, `^?` for Backspace, etc.
+
+</details>
+
 <br>
 
 ## 🔌 Integration with zsh-vi-mode

test_modes.zsh

@@ -0,0 +1,72 @@
+#!/usr/bin/env zsh
+# Test script for emacs mode and vi insert mode support
+
+echo "Testing zsh-vi-man mode support..."
+echo
+
+# Source the plugin
+source "${0:h}/zsh-vi-man.zsh"
+
+# Test 1: Check if the widget is registered
+echo "✓ Test 1: Widget registration"
+if zle -l | grep -q "zvm-man"; then
+  echo "  PASS: zvm-man widget is registered"
+else
+  echo "  FAIL: zvm-man widget not found"
+fi
+echo
+
+# Test 2: Check vicmd binding
+echo "✓ Test 2: Vi normal mode binding"
+if bindkey -M vicmd | grep -q "zvm-man"; then
+  echo "  PASS: Key bound in vicmd mode"
+  bindkey -M vicmd | grep "zvm-man"
+else
+  echo "  FAIL: No binding in vicmd mode"
+fi
+echo
+
+# Test 3: Check emacs binding
+echo "✓ Test 3: Emacs mode binding"
+if bindkey -M emacs | grep -q "zvm-man"; then
+  echo "  PASS: Key bound in emacs mode"
+  bindkey -M emacs | grep "zvm-man"
+else
+  echo "  FAIL: No binding in emacs mode"
+fi
+echo
+
+# Test 4: Check viins binding
+echo "✓ Test 4: Vi insert mode binding"
+if bindkey -M viins | grep -q "zvm-man"; then
+  echo "  PASS: Key bound in viins mode"
+  bindkey -M viins | grep "zvm-man"
+else
+  echo "  FAIL: No binding in viins mode"
+fi
+echo
+
+# Test 5: Test with emacs mode disabled
+echo "✓ Test 5: Disabling emacs mode"
+ZVM_MAN_ENABLE_EMACS=false
+_zvm_man_bind_key
+if bindkey -M emacs | grep -q "zvm-man"; then
+  echo "  FAIL: Key still bound in emacs mode (should be disabled)"
+else
+  echo "  PASS: Emacs mode binding correctly disabled"
+fi
+echo
+
+# Test 6: Test with insert mode disabled
+echo "✓ Test 6: Disabling vi insert mode"
+ZVM_MAN_ENABLE_INSERT=false
+_zvm_man_bind_key
+if bindkey -M viins | grep -q "zvm-man"; then
+  echo "  FAIL: Key still bound in viins mode (should be disabled)"
+else
+  echo "  PASS: Vi insert mode binding correctly disabled"
+fi
+echo
+
+echo "All tests completed!"
+

zsh-vi-man.zsh

@@ -1,18 +1,26 @@
-# zsh-vi-man.zsh -- Smart man page viewer for zsh vi mode
+# zsh-vi-man.zsh -- Smart man page viewer for zsh
 # https://github.com/TunaCuma/zsh-vi-man
 #
-# Press K in vi normal mode to open the man page for the current command.
-# If your cursor is on an option (like -r or --recursive), it will jump
-# directly to that option in the man page.
+# Press K in vi normal mode, Ctrl-X k in emacs mode, or Ctrl-K in vi insert mode
+# to open the man page for the current command. If your cursor is on an option
+# (like -r or --recursive), it will jump directly to that option in the man page.
 #
 # MIT License - Copyright (c) 2025 Tuna Cuma
 
 # Configuration variables (can be set before sourcing)
-# ZVM_MAN_KEY: the key to trigger man page lookup (default: K)
+# ZVM_MAN_KEY: the key to trigger man page lookup in vi normal mode (default: K)
+# ZVM_MAN_KEY_EMACS: the key sequence for emacs mode (default: ^Xk, i.e., Ctrl-X k)
+# ZVM_MAN_KEY_INSERT: the key for vi insert mode (default: ^K, i.e., Ctrl-K)
 # ZVM_MAN_PAGER: the pager to use (default: less)
+# ZVM_MAN_ENABLE_EMACS: enable emacs mode binding (default: true)
+# ZVM_MAN_ENABLE_INSERT: enable vi insert mode binding (default: true)
 
 : ${ZVM_MAN_KEY:=K}
+: ${ZVM_MAN_KEY_EMACS:='^Xk'}
+: ${ZVM_MAN_KEY_INSERT:='^K'}
 : ${ZVM_MAN_PAGER:=less}
+: ${ZVM_MAN_ENABLE_EMACS:=true}
+: ${ZVM_MAN_ENABLE_INSERT:=true}
 
 function zvm-man() {
   # Get the word at cursor position
@@ -87,7 +95,30 @@ function zvm-man() {
 zle -N zvm-man
 
 function _zvm_man_bind_key() {
-  bindkey -M vicmd "${ZVM_MAN_KEY}" zvm-man
+  # Bind in vi normal mode (always enabled)
+  bindkey -M vicmd "${ZVM_MAN_KEY}" zvm-man 2>/dev/null
+  
+  # Handle emacs mode binding
+  if [[ "${ZVM_MAN_ENABLE_EMACS}" == true ]]; then
+    bindkey -M emacs "${ZVM_MAN_KEY_EMACS}" zvm-man 2>/dev/null
+  else
+    # Remove existing binding if disabled
+    bindkey -M emacs -r "${ZVM_MAN_KEY_EMACS}" 2>/dev/null
+  fi
+  
+  # Handle vi insert mode binding
+  if [[ "${ZVM_MAN_ENABLE_INSERT}" == true ]]; then
+    bindkey -M viins "${ZVM_MAN_KEY_INSERT}" zvm-man 2>/dev/null
+  else
+    # Remove existing binding if disabled
+    bindkey -M viins -r "${ZVM_MAN_KEY_INSERT}" 2>/dev/null
+  fi
+}
+
+# Expose function so users can manually rebind if needed
+# Usage: zvm_man_rebind (if keybindings don't work after sourcing)
+function zvm_man_rebind() {
+  _zvm_man_bind_key
 }
 
 # Support both immediate binding and lazy loading with zsh-vi-mode
@@ -102,7 +133,7 @@ elif (( ${+functions[zvm_after_init]} )); then
   # zsh-vi-mode without lazy keybindings
   zvm_after_init_commands+=(_zvm_man_bind_key)
 else
-  # Standalone or other vi-mode setups
+  # Standalone or other vi-mode setups - bind immediately
   _zvm_man_bind_key
 fi