User-defined runners provide you the possibility to run commands in any way you want, which could be helpful when you want a command run in atmux split, a newgnome-terminal window, or afloaterm window.

A runner is a function with one argumentopts as a dictionary, from which stores the command string, working directory, and other parameters passed with:AsyncRun command. All the runners are required to register ing:asyncrun_runner so that AsyncRun can recognize them.

function!s:my_runner(opts)echo"run:" .a:opts.cmdendfunctionletg:asyncrun_runner=get(g:,'asyncrun_runner', {})letg:asyncrun_runner.test=function('s:my_runner')

Than use:

:AsyncRun -mode=term -pos=testls-la$(VIM_FILEDIR)

When-mode=term and-pos=test are provided, runnertest will be called. In this example, runner functions:my_runner does nothing but display the command in the bottom of your vim.

There is aopts argument in the runner function, which contains necessary information:

If-cwd=xxx is provided after:AsyncRun command, AsyncRun will temporarily change thecurrent working directory to the target position when calling runner function. So, you caneither pick the value ina:opts.cwd or use the return value fromgetcwd() .

When use the:AsyncRun command in the range mode, additional information can be use:

Range support is not compulsory for runners, but it would be nice to provide this feature.

It is very easy to make the command run in a tmux pane withvimux:

function!s:run_tmux(opts)" asyncrun has temporarily changed working directory for you" getcwd() in the runner function is the target directory defined in `-cwd=xxx`let cwd=getcwd()callVimuxRunCommand('cd' .shellescape(cwd) .';' .a:opts.cmd)endfunctionletg:asyncrun_runner=get(g:,'asyncrun_runner', {})letg:asyncrun_runner.tmux=function('s:run_tmux')

And you are able to use:

:AsyncRun -mode=term -pos=tmuxls-la

screenshot:

You can specify pane position (vertical or horizontal) and size, just check vimux's doc.

Another way to create a runner is to create a separated.vim file in the folder:

autoload/asyncrun/runner/

In one of yourruntimepath, it will be automatically loaded in need. The script is required to provide arun function with the full name:

asyncrun#runner#{name}#run(opts)

For example, seegnome.vim in theautoload/asyncrun/runner folder:

function!asyncrun#runner#gnome#run(opts)if!executable('gnome-terminal')returnasyncrun#utils#errmsg('gnome-terminal executable not find !')endiflet cmds= []let cmds+= ['cd' .shellescape(getcwd()) ]let cmds+= [a:opts.cmd]let cmds+= ['echo ""']let cmds+= ['read -n1 -rsp "press any key to continue ..."']let text=shellescape(join(cmds,";"))letcommand='gnome-terminal -- bash -c' . textcallsystem(command .' &')endfunction

Try it with:

:AsyncRun -mode=term -pos=gnomels-la

Screenshot:

In therunner folder, some pre-included runner script can be found:

They can be a good reference if you want to create a new runner.