# async.vim

**Repository Path**: space-vim/async.vim

## Basic Information

- **Project Name**: async.vim
- **Description**: mirror from github
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-12-06
- **Last Updated**: 2024-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## 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!!!)