diff options
Diffstat (limited to 'runtime/doc')
| -rw-r--r-- | runtime/doc/autocmd.txt | 7 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 61 | ||||
| -rw-r--r-- | runtime/doc/job_control.txt | 101 | ||||
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 245 | ||||
| -rw-r--r-- | runtime/doc/nvim_clipboard.txt | 47 | ||||
| -rw-r--r-- | runtime/doc/nvim_intro.txt | 22 | ||||
| -rw-r--r-- | runtime/doc/nvim_python.txt | 40 | ||||
| -rw-r--r-- | runtime/doc/options.txt | 9 |
8 files changed, 529 insertions, 3 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 2a8becebff..734202cd6c 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -303,6 +303,7 @@ Name triggered by ~ |InsertLeave| when leaving Insert mode |InsertCharPre| when a character was typed in Insert mode, before inserting it +|JobActivity| when something interesting happens with a job |TextChanged| after a change was made to the text in Normal mode |TextChangedI| after a change was made to the text in Insert mode @@ -712,6 +713,10 @@ InsertEnter Just before starting Insert mode. Also for *InsertLeave* InsertLeave When leaving Insert mode. Also when using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. + {Nvim} *JobActivity* +JobActivity When something interesting happens with a job + spawned by |jobstart()|. See |job-control| for + details. *MenuPopup* MenuPopup Just before showing the popup menu (under the right mouse button). Useful for adjusting the @@ -1383,4 +1388,4 @@ This will write the file without triggering the autocommands defined by the gzip plugin. - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index cdad6a9d7e..ec2086e3eb 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1865,6 +1865,10 @@ invert( {expr}) Number bitwise invert isdirectory( {directory}) Number TRUE if {directory} is a directory islocked( {expr}) Number TRUE if {expr} is locked items( {dict}) List key-value pairs in {dict} +job_close({job}) Closes a job with id {job} +job_send({job}, {data}) Writes {data} to {job}'s stdin +job_spawn({name}, {prog}[, {argv}]) + Spawns {prog} as a job associated with {name} join( {list} [, {sep}]) String join {list} items into one String keys( {dict}) List keys in {dict} len( {expr}) Number the length of {expr} @@ -1934,6 +1938,12 @@ repeat( {expr}, {count}) String repeat {expr} {count} times resolve( {filename}) String get filename a shortcut points to reverse( {list}) List reverse {list} in-place round( {expr}) Float round off {expr} +rpcnotify({channel}, {event}[, {args}...]) + Sends a |msgpack-rpc| notification to {channel} +rpcrequest({channel}, {method}[, {args}...]) + Sends a |msgpack-rpc| request to {channel} +rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |msgpack-rpc| channel +rpcstop({channel}) Closes a |msgpack-rpc| {channel} screenattr( {row}, {col}) Number attribute at screen position screenchar( {row}, {col}) Number character at screen position screencol() Number current cursor column @@ -4002,6 +4012,27 @@ items({dict}) *items()* entry and the value of this entry. The |List| is in arbitrary order. +jobsend({job}, {data}) {Nvim} *jobsend()* + Send data to {job} by writing it to the stdin of the process. + See |job-control| for more information. + +jobstart({name}, {prog}[, {argv}]) {Nvim} *jobstart()* + Spawns {prog} as a job and associate it with the {name} string, + which will be used to match the "filename pattern" in + |JobActivity| events. It returns: + - The job id on success, which is used by |jobsend()| and + |jobstop()| + - 0 when the job table is full or on invalid arguments + - -1 when {prog} is not executable + See |job-control| for more information. + +jobstop({job}) {Nvim} *jobstop()* + Stop a job created with |jobstart| by sending a `SIGTERM` + to the corresponding process. If the process doesn't exit + cleanly soon, a `SIGKILL` will be sent. When the job is + finally closed, a |JobActivity| event will trigger with + `v:job_data[0]` set to `exited`. See |job-control| for more + information. join({list} [, {sep}]) *join()* Join the items in {list} together into one String. @@ -5043,6 +5074,34 @@ round({expr}) *round()* < -5.0 {only available when compiled with the |+float| feature} +rpcnotify({channel}, {event}[, {args}...]) {Nvim} *rpcnotify()* + Sends {event} to {channel} via |msgpack-rpc| and returns + immediately. If {channel} is 0, the event is broadcast to all + channels. Example: > + :au VimLeave call rpcnotify(0, "leaving") + +rpcrequest({channel}, {method}[, {args}...]) {Nvim} *rpcrequest()* + Sends a request to {channel} to invoke {method} via + |msgpack-rpc| and blocks until a response is received. + Example: > + :let result = rpcrequest(rpc_chan, "func", 1, 2, 3) + +rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()* + Spawns {prog} as a job(optionally passing the {argv} list), + and opens a |msgpack-rpc| channel with the spawned process + stdin/stdout. It returns: + - The channel id on success, which is used by |rpcrequest()|, + |rpcnotify()| and |rpcstop()| + - 0 on failure. + Example: > + :let rpc_chan = rpcstart('prog', ['arg1', 'arg2']) + +rpcstop({channel}) {Nvim} *rpcstop()* + Closes a |msgpack-rpc| channel, possibly created via + |rpcspawn()| (Though it will also close channels created by + connections to |NVIM_LISTEN_ADDRESS|). It accepts the rpc + channel id as only argument. + screenattr(row, col) *screenattr()* Like screenchar(), but return the attribute. This is a rather arbitrary number that can only be used to compare to the @@ -8874,4 +8933,4 @@ This is not allowed when the textlock is active: - etc. - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt new file mode 100644 index 0000000000..49ee3889bc --- /dev/null +++ b/runtime/doc/job_control.txt @@ -0,0 +1,101 @@ +*job_control.txt* For Nvim. {Nvim} + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +Nvim's facilities for job control *job-control* + +1. Introduction |job-control-intro| +2. Usage |job-control-usage| + +============================================================================== +1. Introduction *job-control-intro* + +Job control is a simple way to perform multitasking in vimscript. Wikipedia +contains a more generic/detailed description: + +"Job control in computing refers to the control of multiple tasks or Jobs on a +computer system, ensuring that they each have access to adequate resources to +perform correctly, that competition for limited resources does not cause a +deadlock where two or more jobs are unable to complete, resolving such +situations where they do occur, and terminating jobs that, for any reason, are +not performing as expected." + +In a few words: It allows a vimscript programmer to concurrently spawn and +control multiple processes without blocking the current Nvim instance. + +Nvim's job control was designed to be simple and familiar to vimscript +programmers, instead of being very powerful but complex. Unlike Vim's +facilities for calling with external commands, job control does not depend +on installed shells, calling OS functions for process management directly. + +Internally, Nvim job control is powered by libuv, which has a nice +cross-platform API for managing processes. See https://github.com/joyent/libuv +for details + +============================================================================== +2. Usage *job-control-usage* + +Job control is achieved by calling a combination of the |jobstart()|, +|jobsend()| and |jobstop()| functions, and by listening to the |JobActivity| +event. The best way to understand is with a complete example: +> + set nocp + let job1 = jobstart('shell1', 'bash') + let job2 = jobstart('shell2', 'bash', ['-c', 'for ((i = 0; i < 10; i++)); do echo -n hello $i!; sleep 2; done']) + + function JobHandler() + if v:job_data[1] == 'stdout' + let str = 'shell '. v:job_data[0].' stdout: '.v:job_data[2] + elseif v:job_data[1] == 'stderr' + let str = 'shell '.v:job_data[0].' stderr: '.v:job_data[2] + else + let str = 'shell '.v:job_data[0].' exited' + endif + + call append(line('$'), str) + endfunction + + au JobActivity shell* call JobHandler() +< +To test the above, copy it to the ~/jobcontrol.vim file and start with a clean +nvim instance: + > + nvim -u NONE -S ~/jobcontrol.vim +< +Here's what is happening: + +- Two bash instances are spawned by |jobstart()| and their stdin/stdout/stderr + are connected to nvim. +- The first shell is idle, waiting to read commands from it's stdin +- The second shell is passed the -c option to execute a command and exit. In + our case, the command is a for loop that will print numbers and exit after + a while. +- The JobHandler function is called by the JobActivity autocommand(notice how + the shell* pattern matches the `shell1` and `shell2` names passed to + |jobstart()|), and it takes care of displaying stdout/stderr received from + the shells. +- The v:job_data is an array set by the JobActivity event. It has the + following elements: + 0: The job id + 1: The kind of activity: one of "stdout", "stderr" or "exit" + 2: When "activity" is "stdout" or "stderr", this will contain the data read + from stdout or stderr + +To send data to the job's stdin, one can use the |jobsend()| function, like +this: +> + :call jobsend(job1, 'ls\n') + :call jobsend(job1, 'invalid-command\n') + :call jobsend(job1, 'exit\n') +< +A job may be killed at any time with the |jobstop()| function: +> + :call jobstop(job1) +< +When |jobstop()| is called, it will send `SIGTERM` to the job. If a job +doesn't exit after a while, `SIGKILL` will be sent. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt new file mode 100644 index 0000000000..eb15075d85 --- /dev/null +++ b/runtime/doc/msgpack_rpc.txt @@ -0,0 +1,245 @@ +*msgpack_rpc.txt* For Nvim. {Nvim} + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +The Msgpack-RPC Interface to Nvim *msgpack-rpc* + +1. Introduction |msgpack-rpc-intro| +2. API |msgpack-rpc-api| +3. Connecting |msgpack-rpc-connecting| +4. Clients |msgpack-rpc-clients| +5. Types |msgpack-rpc-types| +6. Wrapping methods |msgpack-rpc-wrap-methods| +7. Vimscript functions |msgpack-rpc-vim-functions| + +============================================================================== +1. Introduction *msgpack-rpc-intro* + +The primary means of controlling a running Nvim instance is through +MessagePack-RPC, a messaging protocol that uses the MessagePack serialization +format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md. +From now on, we'll be referring to the protocol as msgpack-rpc. + +At this point, only plugins use msgpack-rpc, but eventually even user +interaction will be achieved through the protocol, since user interfaces will +be separate programs that control a headless Nvim instance. + +This is what can be achieved by connecting to the msgpack-rpc interface: + +- Call any Nvim API function +- Listen for Nvim events +- Receive remote calls from Nvim + +Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's +`clientserver` feature. + +============================================================================== +2. API *msgpack-rpc-api* + +Nvim C API is automatically exposed to the msgpack-rpc interface by the +build system, which parses headers at src/nvim/api from the project root. A +dispatch function is generated, and it will match msgpack-rpc method names +with non-static API functions, converting/validating arguments and return +values back to msgpack. + +Client libraries will normally provide wrappers that hide msgpack-rpc details +from programmers, which can be automatically generated by reading bundled api +metadata from a compiled nvim instance. + +There are two ways to obtain API metadata: + +- By connecting to a running nvim instance and calling `vim_get_api_metadata` + via msgpack-rpc. This is the preferred way for clients written in + dynamically-typed languages, which can define functions at runtime. +- Through the `--api-info` command-line option, which makes nvim to dump a + msgpack blob containing the metadata to stdout and exit. This is preferred + when writing clients for statically-typed languages, which require a + separate compilation step. + +Here's a simple way to get human-readable description of the API(requires +python and the pyyaml/msgpack-python pip packages): +> + nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml + +============================================================================== +3. Connecting *msgpack-rpc-connecting* + + +There are four ways to open msgpack-rpc streams to nvim: + +1. Through nvim's stdin/stdout when started with the `--embed` option. This is + how other programs can embed nvim. + +2. Through stdin/stdout of a program spawned by the |rpcstart()| function. + +3. Through the socket automatically created with every instance. To find out + the socket location(which is random by default) from a running nvim + instance, one can inspect the *$NVIM_LISTEN_ADDRESS* environment variable + like this: +> + :echo $NVIM_LISTEN_ADDRESS +< +4. Through a tcp/ip socket. To make nvim listen on a tcp/ip socket, you need + to set the NVIM_LISTEN_ADDRESS environment variable before starting, like + this: +> + NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim +< +Connecting to the socket is the easiest way a programmer can test the API, +which can be done through any msgpack-rpc client library or a fully-featured +Nvim client(which we'll see below). Here's a ruby script that will print the +string 'hello world!' on the current nvim instance: +> + #!/usr/bin/env ruby + # Requires msgpack-rpc: gem install msgpack-rpc + # + # To run this script, execute it from a running nvim instance(notice the + # trailing '&' which is required since nvim won't process events while + # running a blocking command): + # + # :!./hello.rb & + # + # Or from another shell by setting NVIM_LISTEN_ADDRESS: + # $ NVIM_LISTEN_ADDRESS=[address] ./hello.rb + + require 'msgpack/rpc' + require 'msgpack/rpc/transport/unix' + + vim = MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS']) + result = vim.call(:vim_command, 'echo "hello world!"') +< +A better way is to use the python REPL with the `neovim` package, where API +functions can be called interactively: +> + >>> import neovim; vim = neovim.connect('[address]') + >>> vim.command('echo "hello world!"') +< +============================================================================== +4. Implementing new clients *msgpack-rpc-clients* + +Nvim is still alpha and there's no in-depth documentation explaining how to +properly implement a client library. The python client(neovim pip package) +will be always up-to-date with the latest API changes, so it's source code is +the best documentation currently available. There are some guidelines however: + +- Separate the transport layer from the rest of the library(See + |msgpack-rpc-connecting| for details of how a client can connect to nvim). +- Use a msgpack library that implements the spec version 5, Nvim uses the + BIN/EXT types. +- Read api metadata in order to create client-side wrappers for all + msgpack-rpc methods. +- Use a single-threaded event loop library/pattern. +- Use a fiber/coroutine library for the language you are implementing a client + for. These greatly simplify concurrency and allow the library to expose a + blocking API on top of a non-blocking event loop without the complexity + that comes with preemptive multitasking. +- Don't assume anything about the order that responses to msgpack-rpc requests + will arrive. +- Clients should expect to receive msgpack-rpc requests, which need to be + handled immediately since Nvim is blocked while waiting for the client + response. +- Clients should expect to receive msgpack-rpc notifications, but these don't + need to be handled immediately because they won't block Nvim(Though you + probably want to handle them immediately anyway). + + +Most of the complexity could be handled by a msgpack-rpc library that supports +server->client requests and notifications, but it's not clear if this is part +of the msgpack-rpc spec. At least the ruby msgpack-rpc library does not seem +to support it: +https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/transport/tcp.rb#L150-L158 + +============================================================================== +5. Types *msgpack-rpc-types* + +Nvim's C API uses custom types for all functions(some are just typedefs +around C99 standard types). The types can be split into two groups: + +- Basic types that map natively to msgpack(and probably have a default + representation in msgpack-supported programming languages) +- Special Nvim types that map to msgpack EXT with custom type codes. + +Basic type mapping: + +Nil -> msgpack nil +Boolean -> msgpack boolean +Integer (signed 64-bit integer) -> msgpack integer +Float (IEEE 754 double precision) -> msgpack float +String -> msgpack binary +Array -> msgpack array +Dictionary -> msgpack map + +Special Nvim types that use msgpack EXT: + +Buffer -> enum value kObjectTypeBuffer +Window -> enum value kObjectTypeWindow +Tabpage -> enum value kObjectTypeTabpage + +The most reliable way of determining the type codes for the special nvim types +is at runtime by inspecting the `types` key of metadata dictionary returned by +`vim_get_api_metadata` method. Here's an example json representation of the +`types` object: +> + "types": { + "Buffer": { + "id": 0 + }, + "Window": { + "id": 1 + }, + "Tabpage": { + "id": 2 + } + } +< +Even for statically compiled clients, it's a good practice to avoid hardcoding +the type codes, because a client may build for a Nvim version and connect to +another that may have different type codes. + +============================================================================== +6. Wrapping methods *msgpack-rpc-wrap-methods* + +As mentioned before, clients should provide an API that hides msgpack-rpc +details from programmers, and the API metadata object contains information +that makes this task easier: + +- The "functions" key contains a list of metadata objects for individual + functions. +- Each function metadata object has type information about the return value + and parameters. These can be used for generating strongly-typed APIs in + static languages. +- Container types may be decorated with type/size constraints, eg: + ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate even + more strongly-typed APIs. +- Methods that operate instances of Nvim's types are prefixed with the type + name in lower case. Eg: `buffer_get_line` represents the `get_line` method + of a Buffer instance. +- Global methods are prefixed with `vim`. Eg: `vim_list_buffers` + +So, for a object-oriented language, a client library would have the classes +that represent Nvim's types, and the methods of each class could be defined +by inspecting the method name prefix. There could also be a singleton Vim +class with methods mapped to functions prefixed with `vim_` + +============================================================================== +7. Vimscript functions *msgpack-rpc-vim-functions* + +Four functions related to msgpack-rpc are available to vimscript: + +- |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with + it's standard handles connected to Nvim, the difference is that it's not + possible to process raw data to/from the process stdin/stdout/stderr(Since + the job's stdin/stdout combo are used as a msgpack channel that is + processed directly by Nvim C code). +- |rpcstop()|: Same as |jobstop()|, but operates on handles returned by + |rpcstart().| +- |rpcrequest()|: Sends a msgpack-rpc request to the process. +- |rpcnotify()|: Sends a msgpack-rpc notification to the process. + +The last two functions may also be used with channels created from +connections to |NVIM_LISTEN_ADDRESS|. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_clipboard.txt b/runtime/doc/nvim_clipboard.txt new file mode 100644 index 0000000000..3dd5fb5fcb --- /dev/null +++ b/runtime/doc/nvim_clipboard.txt @@ -0,0 +1,47 @@ +*nvim_clipboard.txt* For Nvim. {Nvim} + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +Clipboard integration for Nvim *nvim-clipboard* + +By default, Nvim has no connection to the system clipboard. Eventually that +will be implemented by UI programs, which connect to Nvim via |msgpack-rpc|. + +Even though externalized UIs are not available yet, there's a workaround that +enables clipboard usage through the python interface(which also uses +|msgpack-rpc| and consequently can implement the clipboard methods required +by Nvim): + +- Make sure you follow the setup instructions in |nvim-python-quickstart|. +- Install the `xerox` python module: + > + $ pip install xerox +< +- Create a ~/.vim/pythonx/nvim_clipboard.py file with the following contents: + > + import xerox + + class NvimClipboard(object): + def __init__(self, vim): + self.provides = ['clipboard'] + + def clipboard_get(self): + return xerox.paste().split('\n') + + def clipboard_set(self, lines): + xerox.copy(u'\n'.join([line.decode('utf-8') for line in lines])) +< +This should enable the '+' and '*' registers. As an optional step, set the +'unnamedclip' option to transparently access clipboard using the unnamed +register. If you use the same |vimrc| for both Vim and Nvim, make sure you +only set the option when `has('nvim')` is true: +> + if has('nvim') + set unnamedclip + endif +< + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_intro.txt b/runtime/doc/nvim_intro.txt new file mode 100644 index 0000000000..d3aa459ba2 --- /dev/null +++ b/runtime/doc/nvim_intro.txt @@ -0,0 +1,22 @@ +*nvim_intro.txt* For Nvim. {Nvim} + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +Introduction to Nvim *nvim-intro* + +This is an introduction to Vim users that are just getting started with Nvim. +It is not meant for Vim beginners. For a basic introduction to Vim, +see |help.txt|. + +For now, it is just an index with the most relevant topics/features that +differentiate Nvim from Vim: + +1. Msgpack-RPC |msgpack-rpc| +2. Job control |job-control| +3. Python plugins |nvim-python| +4. Clipboard integration |nvim-clipboard| + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_python.txt b/runtime/doc/nvim_python.txt new file mode 100644 index 0000000000..b618562900 --- /dev/null +++ b/runtime/doc/nvim_python.txt @@ -0,0 +1,40 @@ +*nvim_python.txt* For Nvim. {Nvim} + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +Python plugins and scripting in Nvim *nvim-python* + +1. Introduction |nvim-python-intro| +2. Quickstart |nvim-python-quickstart| + +============================================================================== +1. Introduction *nvim-python-intro* + +Through an external python interpreter connected via |msgpack-rpc|, Nvim +offers some support for the classic |python-vim| interface. For now only the +old Vim 7.3 API is supported. + +============================================================================== +2. Quickstart *nvim-python-quickstart* + +If you just want to start using python plugins with Nvim quickly, here's a +simple step-by-step: + +- Make sure python 2.6 or 2.7 is available on your `$PATH` +- Install the `neovim` python package: + > + $ pip install neovim +< +- Add the following snippet to your `vimrc`, before any python plugins are + loaded: +> + if has('nvim') + runtime! plugin/python_setup.vim + endif +< +Most python plugins created for Vim 7.3 should work after these steps. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index d38fb84f10..293d113c1f 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -7647,6 +7647,13 @@ A jump table for the options with a short description can be found at |Q_op|. Note that this causes the whole buffer to be stored in memory. Set this option to a lower value if you run out of memory. + {Nvim} *'unnamedclip'* *ucp'* +'unnamedclip' 'ucp' boolean (default off) + global + Use the unnamed register to access the clipboard(when available). + This option has the same effect of setting 'clipboard' to + 'unnamed/unnamedplus' in Vim. + *'updatecount'* *'uc'* 'updatecount' 'uc' number (default: 200) global @@ -8311,4 +8318,4 @@ A jump table for the options with a short description can be found at |Q_op|. screen. When non-zero, characters are sent to the terminal one by one. For MS-DOS pcterm this does not work. For debugging purposes. - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:ft=help:noet:norl: |