|
2 | 2 | We will be introducing breaking changes in the near future. See the [new node-host](https://github.com/neovim/node-host/tree/next) and [new node-client](https://github.com/neovim/node-client/tree/next) for more information about the changes
|
3 | 3 |
|
4 | 4 | # node-host
|
5 |
| - |
6 |
| -[](https://travis-ci.org/neovim/node-host) |
7 |
| -<br> |
8 |
| - |
9 | 5 | ## Installation
|
10 | 6 |
|
11 |
| -**Prerequisites:** You must have the `node` executable on your PATH and a copy of `npm` |
12 |
| - |
13 |
| -1. Install this plugin using Vundle or your favorite plugin manager |
14 |
| -2. Navigate to the `node-host` directory (e.g. `~/.nvim/bundle/node-host`) and run `npm install` |
15 |
| - |
16 |
| -## Usage |
17 |
| - |
18 |
| -To use a Node plugin, place the appropriate file or folder in `rplugin/node` in a `runtimepath` directory (e.g. `~/.nvim/rplugin/node`), run `npm install` if necessary, and then execute a `:UpdateRemotePlugins`. |
19 |
| -Once you restart Neovim, you will be able to use your new plugins! |
20 |
| - |
21 |
| -### Example |
22 |
| - |
23 |
| -```javascript |
24 |
| -var fmt = require('util').format, |
25 |
| - numCalls = 0 |
26 |
| - |
27 |
| -function incrementCalls() { |
28 |
| - if ( numCalls == 5 ) { |
29 |
| - throw new Error('Too many calls!') |
30 |
| - } |
31 |
| - numCalls++ |
32 |
| -} |
| 7 | +**Prerequisites:** You must have the `node` executable (currently only 7.x is supported) on your PATH and a copy of `npm` |
33 | 8 |
|
34 |
| -plugin.commandSync('Cmd', { |
35 |
| - range: '', |
36 |
| - nargs: '*', |
37 |
| -}, function( nvim, args, range, cb ) { |
38 |
| - try { |
39 |
| - incrementCalls() |
40 |
| - nvim.setCurrentLine( |
41 |
| - fmt('Command: Called', numCalls, 'times, args:', args, 'range:', range), |
42 |
| - cb ) |
43 |
| - } catch ( err ) { |
44 |
| - cb( err ) |
45 |
| - } |
46 |
| -}) |
| 9 | +1. Install this plugin using `vim-plug` or your favorite plugin manager |
| 10 | +2. Install `neovim` package globally: `npm install -g neovim@next` |
47 | 11 |
|
48 |
| -plugin.autocmdSync('BufEnter', { |
49 |
| - pattern: '*.js', |
50 |
| - eval: 'expand("<afile>")' |
51 |
| -}, function( nvim, filename, cb ) { |
52 |
| - try { |
53 |
| - incrementCalls() |
54 |
| - nvim.setCurrentLine( |
55 |
| - fmt('Autocmd: Called', numCalls, 'times, file:', filename), cb ) |
56 |
| - } catch ( err ) { |
57 |
| - cb( err ) |
58 |
| - } |
59 |
| -}) |
60 |
| - |
61 |
| -plugin.function('Func', function( nvim, args ) { |
62 |
| - try { |
63 |
| - incrementCalls() |
64 |
| - nvim.setCurrentLine( fmt('Function: Called', numCalls, 'times, args:', args) ) |
65 |
| - } catch ( err ) {} |
66 |
| -}) |
| 12 | +### Example config (vim-plug) |
| 13 | +```vim |
| 14 | +call plug#begin() |
| 15 | + Plug 'neovim/node-host', { 'branch': 'next', 'do': 'npm install -g neovim@next' } |
| 16 | +call plug#end() |
67 | 17 | ```
|
68 | 18 |
|
69 |
| -### Writing plugins |
70 |
| - |
71 |
| -A plugin can either be a file or folder with the `*.js` extension in the `rplugin/node` directory. |
72 |
| -If the plugin is a folder, the package "main" script will be loaded. |
73 |
| - |
74 |
| -The following functions, available on the global `plugin` object, can be used to register plugin commands/functions/autocmds on the attached Neovim instance. |
75 |
| - |
76 |
| -#### (command|function|autocmd)\[Sync](name, [opts], callback) |
77 |
| - |
78 |
| -If the `Sync` variant is used, Neovim will wait for the plugin to return a response via the errback passed as the final argument to the plugin function. |
79 |
| -Otherwise, Neovim will continue execution immediately, ignoring any return values or errors. |
80 |
| - |
81 |
| -`name` is the name of the plugin, `opts` is an optional hash of options, and `callback` is a function that is called whenever the command, function, or autocmd, is triggered. |
82 |
| - |
83 |
| -Note: since `require` caches modules, to see your changes, you will need to restart the host by restarting Neovim. |
84 |
| - |
85 |
| -#### Debugging |
| 19 | +## Usage |
| 20 | +To use a Node plugin, place the appropriate file or folder in `rplugin/node` in a `runtimepath` directory (e.g. `~/.nvim/rplugin/node`), run `npm install` if necessary, and then execute a `:UpdateRemotePlugins`. |
86 | 21 |
|
87 |
| -Also available in the global scope is the `debug` function, which can be used like `console.log` and writes to the file given by the `$NEOVIM_JS_DEBUG` environment variable. |
88 |
| -If you suspect that errors may be occurring in or propagating up to the host, itself, further error output can be found in `.nvimlog`. |
| 22 | +You *must* restart neovim after a `:UpdateRemotePlugins` before you can use your new plugin. |
89 | 23 |
|
90 |
| -## TODO |
| 24 | +## Writing plugins |
| 25 | +A plugin can either be a file or folder in the `rplugin/node` directory. If the plugin is a folder, the `main` script from `package.json` will be loaded. |
91 | 26 |
|
92 |
| -* Auto-install Node executable if missing |
93 |
| -* Plugin manager that allows post-install hooks for `npm install` |
94 |
| -* Better isolation of global variables |
| 27 | +Please see the [neovim repository](https://github.com/billyvg/node-client) for documentation on how to write a plugin (API is currently a WIP) |
0 commit comments