From c59d09d2fbebd47831cae4e00966b7509dca3122 Mon Sep 17 00:00:00 2001
From: David Briscoe <idbrii@gmail.com>
Date: Thu, 28 Aug 2014 18:06:56 -0700
Subject: [PATCH] Add MapHelp command

MapHelp makes it easier to lookup what a command does. Most of the time,
it returns whatever you've mapped the input key sequence to, but if it's
built-in it shows vimdoc for the map (instead of an error like :map).

Useful whenever you know you use something a lot, but can't remember
where it comes from.

Also includes a bang variant to use :Verbose instead of verbose.

Passing no modes will search all modes unlike :map or maparg(). This is
the most useful use case. You can pass a mode to pinpoint entries in
vimdoc or for Verbose.
---
 autoload/scriptease.vim | 62 +++++++++++++++++++++++++++++++++++++++++
 doc/scriptease.txt      | 10 +++++++
 plugin/scriptease.vim   |  3 ++
 3 files changed, 75 insertions(+)

diff --git a/autoload/scriptease.vim b/autoload/scriptease.vim
index 61b4fc1..783e637 100644
--- a/autoload/scriptease.vim
+++ b/autoload/scriptease.vim
@@ -722,6 +722,68 @@ function! scriptease#helptopic() abort
   endif
 endfunction
 
+" Section: MapHelp
+
+function! s:ConvertCtrlFromMapToHelp(subject)
+  " Ctrl is input differently for maps and help. Users always use map-style
+  " input, so when we're looking in help we must convert to help-style.
+  let query = a:subject
+  let query = substitute(query, '\v\<C-((\w+|\S))\>', 'CTRL-\1', '')
+  let query = substitute(query, '\v\<C-((\w+|\S))\>', '_CTRL-\1', 'g')
+  return query
+endf
+function! scriptease#maphelp(verbose, subject, ...)
+  " First argument controls verbosity.
+  " Second argument is subject of map/help lookup.
+  " Optional third argument restricts search to a vim-mode.
+  let specific_query = ''
+  if a:0 == 1
+    let specific_query = a:1
+    let searching_modes = [ a:1 ]
+  else
+    let select = 's' " work around wonky syntax highlighting
+    let searching_modes = [ '', 'i', 'c', select, 'x', 'l' ]
+  endif
+
+  let found_map = 0
+  for mode in searching_modes
+    let map_lhs = maparg(a:subject, mode)
+    if len(map_lhs) > 0
+      exec a:verbose . mode .'map '. a:subject
+      let found_map = 1
+    endif
+  endfor
+
+  if found_map == 0
+    for mode in searching_modes
+      let prefix = ''
+      if mode != 'n' && len(mode) > 0
+        let prefix = mode .'_'
+      endif
+      try
+        exec 'help '. prefix . s:ConvertCtrlFromMapToHelp(a:subject)
+        let found_map = 1
+        " Can't open multiple help entries.
+        break
+
+      catch /^Vim\%((\a\+)\)\=:E149/
+      endtry
+    endfor
+  endif
+
+  if found_map == 0
+    if searching_modes[0] == ''
+      let searching_modes[0] = 'nvo'
+    endif
+    let searching_modes = join(searching_modes, '')
+    let plural = ''
+    if len(searching_modes) > 1
+      let plural = 's'
+    endif
+    echo 'No mapping found for '. a:subject .' for mode'. plural .' '. searching_modes .'.'
+  endif
+endf
+
 " Section: Settings
 
 function! s:build_path() abort
diff --git a/doc/scriptease.txt b/doc/scriptease.txt
index e6fc056..dfc06be 100644
--- a/doc/scriptease.txt
+++ b/doc/scriptease.txt
@@ -51,6 +51,16 @@ g!{motion}              Call |eval()| on the text the motion moves over and
                         number combinations will be translated to the
                         appropriate file name and line number.
 
+                                                *scriptease-:MapHelp*
+:MapHelp {subject} [mode]
+                        Similar to |:verbose| |map|, but falls back to help if
+                        no map is found (to show built-in maps). See
+                        |maparg()| for {mode}. Searches all modes if {mode} is
+                        not specified.
+
+:MapHelp! {subject} [mode]
+                        Like |:MapHelp|, but map output uses |:Verbose|.
+
                                                 *scriptease-:PP*
 :PP {expr}              Pretty print the value of {expr}.
 
diff --git a/plugin/scriptease.vim b/plugin/scriptease.vim
index 8978ab3..884041e 100644
--- a/plugin/scriptease.vim
+++ b/plugin/scriptease.vim
@@ -81,6 +81,9 @@ command! -bar -bang -range=1 -nargs=1 -complete=customlist,scriptease#complete V
 command! -bar -bang -range=1 -nargs=1 -complete=customlist,scriptease#complete Vread
       \ :execute scriptease#open_command(<count>,'read',<q-args>,<bang>0)
 
+command! -bang -nargs=+ -complete=mapping MapHelp
+      \ :call scriptease#maphelp(<bang>0 ? 'Verbose ' : 'verbose ', <f-args>)
+
 " Section: Maps
 
 nnoremap <silent> <Plug>ScripteaseFilter :<C-U>set opfunc=scriptease#filterop<CR>g@