Session keys

Session keys is a plugin for Neovim that allows creating temporary key mappings that you can enable on demand for a specific need (starting keys session) and then disable them when not needed anymore (stopping keys session), which restores mappings to their original state.

This way you can define a number of sessions for different needs without worrying about reusing keys.

Installation

With lazy.nvim:

   'shmerl/session-keys'

Configuration

You need to set up your session keys by adding mappings to sessions table which you can access through require('session-keys').sessions.

Give your session a name and then assign mappings per mode. See a detailed example below.

Usage of mode, rhs, lhs (and opts if any) is the same as described in :help vim.keymap.set, except that mode (key of the table) has to be a single value, not a list.

See also :help key-notation.

Example of setting up DAP debugging session keys for Neovim + Konsole

require('session-keys').sessions.dap = {
   n = { -- mode 'n'
      { lhs = '<F5>',  rhs = function() require('dap').continue() end },
      { lhs = '<F9>',  rhs = function() require('dap').toggle_breakpoint() end },
      { lhs = '<F10>', rhs = function() require('dap').step_over() end },
      { lhs = '<F11>', rhs = function() require('dap').step_into() end },
      { lhs = '<F23>', rhs = function() require('dap').step_out() end },

      { lhs = '<F6>',  rhs = function() require('dap').down() end },
      { lhs = '<F18>', rhs = function() require('dap').up() end },

      { lhs = '<F8>',  rhs = function() require('dap').terminate() end },
      { lhs = '<F20>', rhs = function() require('dap').disconnect({ terminateDebuggee = false }) end },

      { lhs = '<F17>', rhs = function() require('dap').run_last() end },

      { lhs = '<F7>',  rhs = function() require('dap').pause() end },
      { lhs = '<F29>', rhs = function() require('dap').reverse_continue() end },
      { lhs = '<F22>', rhs = function() require('dap').step_back() end }
   }
}

Explanation:

F5          - run, continue
F9          - toggle breakpoint
F10         - step over
F11         - step into      
Shift + F11 - step out

F6          - go down in current stacktrace without stepping
Shift + F6  - go up in current stacktrace without stepping

F8          - terminate
Shift + F8  - disconnect

Shift + F5  - run last

F7          - pause thread
Ctrl  + F5  - reverse continue
Shift + F10 - step back

DAP function calls above are wrapped in function() ... end to allow lazy loading of DAP plugin if needed. If you don't need that, you can simply use something like rhs = require('dap').continue for simplicity.

Note: in Konsole, function keys with modifiers result in keycodes that neovim understands as higher function keys such as F17, F22 and etc., so those are used above:

Shift + F5  = F17
Ctrl  + F5  = F29
Shift + F6  = F18
Shift + F8  = F20
Shift + F11 = F23
Shift + F10 = F22

To check the combo codes use keys.log generated by:

nvim -V3keys.log
:q

For details, see: neovim/neovim#7384

Usage

Once you enabled this set up, you can start your named session (in the above case - dap) as follows:

:lua require('session-keys'):start('dap')

Do some debugging using F9, F5, etc. When you are done, stop the session with:

:lua require('session-keys'):stop('dap')

This will restore your key mappings to what they were before you started the session.

To toggle a session back and forth between active and inactive you can do:

:lua require('session-keys'):toggle('dap')

Toggle especially can be assigned to its own permanent key mapping for easier control.

For example:

-- Alt + F11 (= F59) for toggling dap session keys itself
vim.keymap.set('n', '<F59>', function() require('session-keys'):toggle('dap') end)

You can define and start multiple sessions. To see the list of currently active sessions:

:lua require('session-keys'):show_active()

Known limitations

Local buffer mapping

Sessions by nature of being defined without relation to buffers are currently assuming global buffer mappings.

Local buffer mappings scenario isn't supported, so avoid using buffer in the opts for keys.

Not sure yet if there is a use case for local buffers, but it could be added in theory if there would be one.

Session hierarchy

Session hierarchy isn't handled. I.e., if you start a bunch of sessions that conflict with each other and then stop them in the wrong order, you'll mess up your mappings until next neovim restart, so make sure to stop sessions in the right sequence to get back to the original state.

Supporting sessions' hierarchy could be added later.