From ae289a88c76fe69531293eb6ce311028d3e78dfd Mon Sep 17 00:00:00 2001
From: Ben Jackson <puremourning@gmail.com>
Date: Sun, 21 Feb 2021 21:16:54 +0000
Subject: [PATCH] Update readme with example

---
 README.md               | 30 ++++++++++++++++++++++++++-
 support/custom_ui_vimrc | 46 +++++++++++++++++++++++++++++++----------
 2 files changed, 64 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index b3088b7..e13aae0 100644
--- a/README.md
+++ b/README.md
@@ -85,12 +85,13 @@ For detailed explanatin of the `.vimspector.json` format, see the
     * [Sign priority](#sign-priority)
     * [Changing the default window sizes](#changing-the-default-window-sizes)
     * [Changing the terminal size](#changing-the-terminal-size)
+    * [Custom mappings while debugging](#custom-mappings-while-debugging)
     * [Advanced UI customisation](#advanced-ui-customisation)
     * [Customising the WinBar](#customising-the-winbar)
     * [Example](#example)
  * [FAQ](#faq)
 
-<!-- Added by: ben, at: Sun 21 Feb 2021 16:59:12 GMT -->
+<!-- Added by: ben, at: Sun 21 Feb 2021 21:15:32 GMT -->
 
 <!--te-->
 
@@ -675,6 +676,10 @@ appropriate place, such as your `vimrc` (hint: run `:e $MYVIMRC`).
 nmap <F5> <Plug>VimspectorContinue
 ```
 
+In addition, many users probably want to only enable certain Vimspector mappings
+while debugging is active. This is also possible, though it requires writing
+[some vimscipt](#custom-mappings-while-debugging).
+
 That said, many people are familiar with particular debuggers, so the following
 mappings can be enabled by setting `g:vimspector_enable_mappings` to the
 specified value.
@@ -1821,6 +1826,29 @@ let g:vimspector_terminal_maxwidth = 75
 let g:vimspector_terminal_minwidth = 20
 ```
 
+## Custom mappings while debugging
+
+It's useful to be able to define mappings only while debugging and remove those
+mappings when debugging is complete. For this purpose, Vimspector provides 2
+`User` autocommds:
+
+* `VimspectorJumpedToFrame` - triggered whenever a 'break' event happens, or
+  when selecting a stack from to jump to. This can be used to create (for
+  example) buffer-local mappings for any files opened in the code window.
+* `VimspectorDebugEnded` - triggered when the debug session is terminated
+  (actually when Vimspector is fully reset)
+
+An example way to use this is included in `support/custom_ui_vimrc`. In there,
+these autocommands are used to create buffer-local mappings for any files
+visited while debugging and to clear them when completing debugging. This is
+particularly useful for commadns like `<Plug>VimspectorBalloonEval` which only
+make sense while debugging (and only in the code window). Check the commented
+section `Custom mappings while debugging`.
+
+NOTE: This is a fairly advanced feature requiring some nontrivial vimscript.
+It's possible that this feature will be incorporated into Vimspector in future
+as it is a common requirement.
+
 ## Advanced UI customisation
 
 > ***Please Note***: This cusomiation API is ***unstable***, meaning that it may
diff --git a/support/custom_ui_vimrc b/support/custom_ui_vimrc
index 4e9f635..51a7304 100644
--- a/support/custom_ui_vimrc
+++ b/support/custom_ui_vimrc
@@ -1,7 +1,12 @@
+" setup boilerplate to make this file usable with vim -Nu <tihs file> {{{
+scriptencoding utf-8
 execute 'source' expand( '<sfile>:p:h' ) . '/minimal_vimrc'
 set noequalalways
 let mapleader = ','
 let maplocalleader = "\<Space>"
+" }}}
+
+" Custom Layout {{{
 
 function! s:CustomiseUI()
   let wins = g:vimspector_session_windows
@@ -61,6 +66,27 @@ function! s:CustomiseWinBar()
     nnoremenu WinBar.✕\ ᶠ⁸ :call vimspector#Reset()<CR>
 endfunction
 
+augroup TestUICustomistaion
+  autocmd!
+  autocmd User VimspectorUICreated call s:CustomiseUI()
+  autocmd User VimspectorTerminalOpened call s:SetUpTerminal()
+  autocmd User VimspectorUICreated call s:CustomiseWinBar()
+augroup END
+
+" }}}
+
+" Custom sign priority {{{
+
+let g:vimspector_sign_priority = {
+  \    'vimspectorBP':         3,
+  \    'vimspectorBPCond':     2,
+  \    'vimspectorBPDisabled': 1,
+  \    'vimspectorPC':         999,
+  \ }
+
+" }}}
+
+" Custom mappings while debuggins {{{
 let s:mapped = {}
 
 function! s:OnJumpToFrame() abort
@@ -72,6 +98,8 @@ function! s:OnJumpToFrame() abort
   nmap <silent> <buffer> <LocalLeader>ds <Plug>VimspectorStepInto
   nmap <silent> <buffer> <LocalLeader>df <Plug>VimspectorStepOut
   nmap <silent> <buffer> <LocalLeader>dc <Plug>VimspectorContinue
+  nmap <silent> <buffer> <LocalLeader>di <Plug>VimspectorBalloonEval
+  xmap <silent> <buffer> <LocalLeader>di <Plug>VimspectorBalloonEval
 
   let s:mapped[ string( bufnr() ) ] = 1
 endfunction
@@ -90,6 +118,8 @@ function! s:OnDebugEnd() abort
         silent! nunmap <buffer> <LocalLeader>ds
         silent! nunmap <buffer> <LocalLeader>df
         silent! nunmap <buffer> <LocalLeader>dc
+        silent! nunmap <buffer> <LocalLeader>di
+        silent! xunmap <buffer> <LocalLeader>di
       endtry
     endfor
   finally
@@ -100,18 +130,12 @@ function! s:OnDebugEnd() abort
   let s:mapped = {}
 endfunction
 
-augroup TestUICustomistaion
-  autocmd!
-  autocmd User VimspectorUICreated call s:CustomiseUI()
-  autocmd User VimspectorTerminalOpened call s:SetUpTerminal()
-  autocmd User VimspectorUICreated call s:CustomiseWinBar()
+augroup TestCustomMappings
+  au!
   autocmd User VimspectorJumpedToFrame call s:OnJumpToFrame()
   autocmd User VimspectorDebugEnded call s:OnDebugEnd()
 augroup END
 
-let g:vimspector_sign_priority = {
-  \    'vimspectorBP':         3,
-  \    'vimspectorBPCond':     2,
-  \    'vimspectorBPDisabled': 1,
-  \    'vimspectorPC':         999,
-  \ }
+" }}}
+
+" vim: foldmethod=marker