How to create a lua function that gets called for a vim (neovim) motion

Question

Vim has the concept of actions, which can act on text objects via motions. For example diw will delete (the action) the inner word (the motion). I want to create a function that can be applied/executed with those motions. For example, if my function appends to certain register, I can append whatever I want by doing myFunction + motion for what I want to add.

Answer 1

1. Scripting language does not matter. The help for mappings is in :h map.txt. Specific topic is :h :map-operator.

2. There is g@ normal operator and opfunc global string option.

3. In order to perform "custom action" we must

   1. Make sure opfunc is set to the name of appropriate VimScript callable object;

   2. Execute g@ in normal mode (that triggers the transition into operator-pending mode);

   3. Make sure Vim is left hanging in operator-pending mode;

4. After operator-pending mode is done g@ saves the selected range to the "brackets" bookmark and invokes opfunc value passing an extra string parameter.

5. The quick and dumb test is set opfunc=v:lua.print and then type g@aw (prints "char"), g@as (prints "line"), g@^VG (prints "block") and so on.

6. As we probably want more than one user-defined operator, we should pack all of that 1-2-3 into a new mapping.

7. Implement actual opfunc function to do something useful.

BTW. appending text to a register is a builtin. Like "Ayiw etc.

UPD. Some example implementation for 1-2-3:

By :h :map-expression

function! Gat(method) abort
    let &opfunc = a:method
    return "g@"
endfunction

nnoremap <expr><f12> Gat("v:lua.print")

By :h :map-cmd

nnoremap <f12> <cmd>set opfunc=v:lua.print<CR>g@

Answer 2

As the other answer from Matt has pointed out, it is required to modify the opfunc to point to a global callable object and then call the g@ + motion keymap. This is even suggested by the vim docs, where they create a mapping where both the opfunc is set and then the g@ motion is called on the same command. This seems to be the closer you can get using lua until they provide a better lua integration

function format_range_operator()
  local old_func = vim.go.operatorfunc -- backup previous reference
  -- set a globally callable object/function
  _G.op_func_formatting = function()
    -- the content covered by the motion is between the [ and ] marks, so get those
    local start = vim.api.nvim_buf_get_mark(0, '[')
    local finish = vim.api.nvim_buf_get_mark(0, ']')
    vim.lsp.buf.range_formatting({}, start, finish)
    vim.go.operatorfunc = old_func -- restore previous opfunc
    _G.op_func_formatting = nil -- deletes itself from global namespace
  end
  vim.go.operatorfunc = 'v:lua.op_func_formatting'
  vim.api.nvim_feedkeys('g@', 'n', false)
end
vim.api.nvim_set_keymap("n", "gm", "<cmd>lua format_range_operator()<CR>", {noremap = true})

Picked from: https://github.com/neovim/nvim-lspconfig/wiki/User-contributed-tips#range-formatting-with-a-motion