draft PR to discuss migration strategies for keymaps / on_attach

[kyazdani42]

No description provided.

[alex-courtis]

I went backwards with NvimTreeCreateOnAttach. That's a possible solution for migrating legacy mappings.

The real questions:

1. How do the users create a new mapping in on_attach?
2. How do we document the default mappings so that the users can copy/paste?

1 is simpler than I thought

inject_node is applied to the Api and we have no need to use it in set_keymaps. Therefore the default mappings can be very simply presented.

inject_node is only needed for custom user functions, and should be documented as the exceptional case.

Updating NvimTreeCreateOnAttach to remove unnecessary wrappers, as they are all simple mappings to Api.

2 has many possible solutions; one is

Generate vim.keymap.set calls from DEFAULT_KEYMAPS. This generation is scripted. These calls go into :help as the table and as lua examples.

Not sure how this would actually be done, as we need to somehow convert a function reference to an API call as a string. Perhaps storing the callback as a string and using something like loadstring("Api.node.open.edit()")().

A more pragmatic solution might be to just denormalise e.g.

  {
    key = "<C-e>",
    callbackFn = Api.node.open.replace_tree_buffer,
    callbackString = "Api.node.open.replace_tree_buffer",
    desc = "edit the file in place, effectively replacing the tree explorer",
  },

Needs more thought.

[alex-courtis]

a simpler on_attach c82d1b0

NvimTreeCreateOnAttach -> NvimTreeMappingsToOnAttach updated to demonstrate.

	local function on_attach(bufnr)
		local opts = { buffer = bufnr, noremap = true, silent = true, nowait = true, }

		vim.keymap.set('n', '<CR>',           Api.node.open.edit                , opts)
		vim.keymap.set('n', 'z',              Api.node.open.edit                , opts)
		vim.keymap.set('n', 'Z',              Api.tree.expand_all               , opts)
		vim.keymap.set('n', 'o',              Api.node.open.edit                , opts)
		vim.keymap.set('n', '<2-LeftMouse>',  Api.node.open.edit                , opts)
...

We can go further...

[alex-courtis]

on_attach passed mode and opts 92a0ad9

	local function on_attach(bufnr, mode, opts)
		vim.keymap.set(mode, '<CR>',           Api.node.open.edit                , opts)
		vim.keymap.set(mode, 'o',              Api.node.open.edit                , opts)
		vim.keymap.set(mode, '<2-LeftMouse>',  Api.node.open.edit                , opts)
		vim.keymap.set(mode, '<C-e>',          Api.node.open.replace_tree_buffer , opts)
		vim.keymap.set(mode, 'z',              Api.node.open.edit                , opts)
...

There is no need for the user to set mode or opts. They can do so if they have some reason to.

bufnr is retained so that we do not break existing users.

[kyazdani42]

I would very much like to do this under the hood as much as possible. It wouldn't be hard i believe to convert all the existing mappings table into vim.keymap.set in the attach module. This way we could just migrate all the users config in one go.

There is also the help menu that needs refactoring. Because actions are not named anymore, and user mappings will not be registered in our table.
I wonder if we could make the help UI not coupled to our implementation, something like parsing the buffer autocmd/keymaps and displaying them in a way that would not change unless neovim changes it internally.

[kyazdani42]

Also does the jit compiler offers introspection on the lua code ? maybe this could help us generate the code executed in the on_attach call.

[alex-courtis]

Also does the jit compiler offers introspection on the lua code ? maybe this could help us generate the code executed in the on_attach call.

loadstring("Api.node.open.edit()")() didn't work quite as I expected, as the local Api was not available.

loadstring("require('nvim-tree.api').open.edit()")() might be necessary.

[alex-courtis]

It wouldn't be hard i believe to convert all the existing mappings table into vim.keymap.set in the attach module.

That works and would be more consistent. We could put the actions in DEFAULT_KEYMAPS, along with some introspectable string for the callback.

[alex-courtis]

parsing the buffer autocmd/keymaps and displaying them in a way that would not change unless neovim changes it internally

That will resolve many problems. We could map the Api function back to the table with the description.

[kyazdani42]

CF #1476 for automatic migration

[kyazdani42]

i've tried the keymap introspection but i don't think it will work :/

  for _, v in pairs(vim.api.nvim_buf_get_keymap(require"nvim-tree.view".get_bufnr(), "")) do
    if v.callback then
      local info = debug.getinfo(v.callback)
      local line, source = info.linedefined, string.sub(info.source, 2)
      local file = vim.fn.readfile(source, '', line)
      local l = file[line]
      print(l)
    end
  end

results in

function M.help()
  return function(node)
  return function(node)
  return function(node)
  return function(node)
function M.close()
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)
  return function(node)

which are callbacks from inject_node unfortunately.

[alex-courtis]

which are callbacks from inject_node unfortunately.

Of course. It was worth a try...

[alex-courtis]

See #1579