https://github.com/prabirshrestha/async.vim

normalize async job control api for vim and neovim
https://github.com/prabirshrestha/async.vim

async neovim vim

Last synced: 6 days ago
JSON representation

normalize async job control api for vim and neovim

• Host: GitHub
• URL: https://github.com/prabirshrestha/async.vim
• Owner: prabirshrestha
• License: mit
• Created: 2016-03-20T19:29:59.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2022-11-01T23:03:33.000Z (about 2 years ago)
• Last Synced: 2024-11-07T02:51:54.813Z (14 days ago)
• Topics: async, neovim, vim
• Language: Vim script
• Size: 57.6 KB
• Stars: 279
• Watchers: 12
• Forks: 19
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# async.vim

normalize async job control api for vim and neovim

## sample usage

```vim

function! s:handler(job_id, data, event_type)

    echo a:job_id . ' ' . a:event_type

    echo join(a:data, "\n")

endfunction

if has('win32') || has('win64')

    let argv = ['cmd', '/c', 'dir c:\ /b']

else

    let argv = ['bash', '-c', 'ls']

endif

let jobid = async#job#start(argv, {

    \ 'on_stdout': function('s:handler'),

    \ 'on_stderr': function('s:handler'),

    \ 'on_exit': function('s:handler'),

    \ 'normalize': 'array'

\ })

if jobid > 0

    echom 'job started'

else

    echom 'job failed to start'

endif

" If you want to get the process id of the job

let pid = async#job#pid(jobid)

" If you want to wait the job:

call async#job#wait([jobid], 5000)  " timeout: 5 sec

" If you want to stop the job:

call async#job#stop(jobid)

```

## APIs

APIs are based on neovim's job control APIs.

* [job-control](https://neovim.io/doc/user/job_control.html#job-control)

* [jobsend()](https://neovim.io/doc/user/eval.html#jobsend%28%29)

* [jobstart()](https://neovim.io/doc/user/eval.html#jobstart%28%29)

* [jobstop()](https://neovim.io/doc/user/eval.html#jobstop%28%29)

* [jobwait()](https://neovim.io/doc/user/eval.html#jobwait%28%29)

* [jobpid()](https://neovim.io/doc/user/eval.html#jobpid%28%29)

### Normalizing data

By default `stdout` and `stderr` data is an array. This is a noop for neovim

but requiring using `split` in vim. This can tend to be costly if you are want

a string since you are joining the splited string. To avoid this unncessary

conversion you can normalize it to `string` so it is a noop in vim but a `join`

for neovim. If you prefer to disable normalization pass normalization as `raw`.

```

normalize: 'array' " Valid values are 'array', 'string' or 'raw'

```

## Embedding

Async.vim can be either embedded with other plugins or be used as an external plugin.

If you want to embed run the following vim command.

```vim

:AsyncEmbed path=./autoload/myplugin/job.vim namespace=myplugin#job

```

## Todos

* Fallback to sync `system()` calls in vim that doesn't support `job`

* `job_stop` and `job_send` is treated as noop when using `system()`

* `on_stderr` doesn't work when using `system()`

* Fallback to python/ruby threads and vimproc instead of using `system()` for better compatibility (PRs welcome!!!)