mirror of
https://github.com/neovim/neovim.git
synced 2025-02-25 18:55:25 -06:00
runtime: Some nvim documentation fixes pointed by @oni-link
This commit is contained in:
parent
037ca796a0
commit
e59d1c5816
@ -303,7 +303,7 @@ Name triggered by ~
|
|||||||
|InsertLeave| when leaving Insert mode
|
|InsertLeave| when leaving Insert mode
|
||||||
|InsertCharPre| when a character was typed in Insert mode, before
|
|InsertCharPre| when a character was typed in Insert mode, before
|
||||||
inserting it
|
inserting it
|
||||||
|JobActivity| when something interesting happen with a job
|
|JobActivity| when something interesting happens with a job
|
||||||
|
|
||||||
|TextChanged| after a change was made to the text in Normal mode
|
|TextChanged| after a change was made to the text in Normal mode
|
||||||
|TextChangedI| after a change was made to the text in Insert mode
|
|TextChangedI| after a change was made to the text in Insert mode
|
||||||
|
@ -4019,7 +4019,12 @@ jobsend({job}, {data}) {Nvim} *jobsend()*
|
|||||||
jobstart({name}, {prog}[, {argv}]) {Nvim} *jobstart()*
|
jobstart({name}, {prog}[, {argv}]) {Nvim} *jobstart()*
|
||||||
Spawns {prog} as a job and associate it with the {name} string,
|
Spawns {prog} as a job and associate it with the {name} string,
|
||||||
which will be used to match the "filename pattern" in
|
which will be used to match the "filename pattern" in
|
||||||
|JobActivity| events. See |job-control| for more information.
|
|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()*
|
jobstop({job}) {Nvim} *jobstop()*
|
||||||
Stop a job created with |jobstart| by sending a `SIGTERM`
|
Stop a job created with |jobstart| by sending a `SIGTERM`
|
||||||
@ -5083,10 +5088,12 @@ rpcrequest({channel}, {method}[, {args}...]) {Nvim} *rpcrequest()*
|
|||||||
|
|
||||||
rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()*
|
rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()*
|
||||||
Spawns {prog} as a job(optionally passing the {argv} list),
|
Spawns {prog} as a job(optionally passing the {argv} list),
|
||||||
and open a |msgpack-rpc| channel with the spawned process
|
and opens a |msgpack-rpc| channel with the spawned process
|
||||||
stdin/stdout. Returns the channel id, which is used by
|
stdin/stdout. It returns:
|
||||||
|rpcrequest()|, |rpcnotify()| and |rpcstop()|
|
- The channel id on success, which is used by |rpcrequest()|,
|
||||||
It expects the rpc channel id as argument. Example: >
|
|rpcnotify()| and |rpcstop()|
|
||||||
|
- 0 on failure.
|
||||||
|
Example: >
|
||||||
:let rpc_chan = rpcstart('prog', ['arg1', 'arg2'])
|
:let rpc_chan = rpcstart('prog', ['arg1', 'arg2'])
|
||||||
|
|
||||||
rpcstop({channel}) {Nvim} *rpcstop()*
|
rpcstop({channel}) {Nvim} *rpcstop()*
|
||||||
|
@ -66,14 +66,14 @@ nvim instance:
|
|||||||
<
|
<
|
||||||
Here's what is happening:
|
Here's what is happening:
|
||||||
|
|
||||||
- Two bash instances are spawned |jobstart()| and their stdin/stdout/stderr
|
- Two bash instances are spawned by |jobstart()| and their stdin/stdout/stderr
|
||||||
are connected to nvim.
|
are connected to nvim.
|
||||||
- The first shell is idle, waiting to read commands from it's stdin
|
- 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
|
- 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
|
our case, the command is a for loop that will print numbers and exit after
|
||||||
a while.
|
a while.
|
||||||
- The JobHandler function is called by the JobActivity autocommand(notice how
|
- The JobHandler function is called by the JobActivity autocommand(notice how
|
||||||
it the shell* pattern matches the `shell1` and `shell2` names passed to
|
the shell* pattern matches the `shell1` and `shell2` names passed to
|
||||||
|jobstart()|), and it takes care of displaying stdout/stderr received from
|
|jobstart()|), and it takes care of displaying stdout/stderr received from
|
||||||
the shells.
|
the shells.
|
||||||
- The v:job_data is an array set by the JobActivity event. It has the
|
- The v:job_data is an array set by the JobActivity event. It has the
|
||||||
@ -86,9 +86,9 @@ Here's what is happening:
|
|||||||
To send data to the job's stdin, one can use the |jobsend()| function, like
|
To send data to the job's stdin, one can use the |jobsend()| function, like
|
||||||
this:
|
this:
|
||||||
>
|
>
|
||||||
:call jobsend(job1, 'ls\n')<cr>
|
:call jobsend(job1, 'ls\n')
|
||||||
:call jobsend(job1, 'invalid-command\n')<cr>
|
:call jobsend(job1, 'invalid-command\n')
|
||||||
:call jobsend(job1, 'exit\n')<cr>
|
:call jobsend(job1, 'exit\n')
|
||||||
<
|
<
|
||||||
A job may be killed at any time with the |jobstop()| function:
|
A job may be killed at any time with the |jobstop()| function:
|
||||||
>
|
>
|
||||||
|
@ -17,20 +17,20 @@ The Msgpack-RPC Interface to Nvim *msgpack-rpc*
|
|||||||
==============================================================================
|
==============================================================================
|
||||||
1. Introduction *msgpack-rpc-intro*
|
1. Introduction *msgpack-rpc-intro*
|
||||||
|
|
||||||
The primary means of controlling a running nvim instance is through
|
The primary means of controlling a running Nvim instance is through
|
||||||
MessagePack-RPC, a messaging protocol that uses the MessagePack serialization
|
MessagePack-RPC, a messaging protocol that uses the MessagePack serialization
|
||||||
format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md.
|
format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md.
|
||||||
From now on, we'll be referring to the protocol as msgpack-rpc.
|
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
|
At this point, only plugins use msgpack-rpc, but eventually even user
|
||||||
interaction will be achieved through the protocol, since user interfaces will
|
interaction will be achieved through the protocol, since user interfaces will
|
||||||
be separate programs that control a headless nvim instance.
|
be separate programs that control a headless Nvim instance.
|
||||||
|
|
||||||
This is what can be achieved by connecting to the msgpack-rpc interface:
|
This is what can be achieved by connecting to the msgpack-rpc interface:
|
||||||
|
|
||||||
- Call any nvim API function
|
- Call any Nvim API function
|
||||||
- Listen for nvim events
|
- Listen for Nvim events
|
||||||
- Receive remote calls from nvim
|
- Receive remote calls from Nvim
|
||||||
|
|
||||||
Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's
|
Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's
|
||||||
`clientserver` feature.
|
`clientserver` feature.
|
||||||
@ -69,7 +69,7 @@ python and the pyyaml/msgpack-python pip packages):
|
|||||||
|
|
||||||
There are four ways to open msgpack-rpc streams to nvim:
|
There are four ways to open msgpack-rpc streams to nvim:
|
||||||
|
|
||||||
1. Through nvim's stdin/stdout when started with the `--embed` option. This
|
1. Through nvim's stdin/stdout when started with the `--embed` option. This is
|
||||||
how other programs can embed nvim.
|
how other programs can embed nvim.
|
||||||
|
|
||||||
2. Through stdin/stdout of a program spawned by the |rpcstart()| function.
|
2. Through stdin/stdout of a program spawned by the |rpcstart()| function.
|
||||||
@ -122,7 +122,7 @@ functions can be called interactively:
|
|||||||
Nvim is still alpha and there's no in-depth documentation explaining how to
|
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)
|
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
|
will be always up-to-date with the latest API changes, so it's source code is
|
||||||
best documentation currently available. There are some guidelines however:
|
the best documentation currently available. There are some guidelines however:
|
||||||
|
|
||||||
- Separate the transport layer from the rest of the library(See
|
- Separate the transport layer from the rest of the library(See
|
||||||
|msgpack-rpc-connecting| for details of how a client can connect to nvim).
|
|msgpack-rpc-connecting| for details of how a client can connect to nvim).
|
||||||
@ -134,7 +134,7 @@ best documentation currently available. There are some guidelines however:
|
|||||||
- Use a fiber/coroutine library for the language you are implementing a client
|
- 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
|
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
|
blocking API on top of a non-blocking event loop without the complexity
|
||||||
that comes with preemptive multi-tasking.
|
that comes with preemptive multitasking.
|
||||||
- Don't assume anything about the order that responses to msgpack-rpc requests
|
- Don't assume anything about the order that responses to msgpack-rpc requests
|
||||||
will arrive.
|
will arrive.
|
||||||
- Clients should expect to receive msgpack-rpc requests, which need to be
|
- Clients should expect to receive msgpack-rpc requests, which need to be
|
||||||
@ -159,7 +159,7 @@ around C99 standard types). The types can be split into two groups:
|
|||||||
|
|
||||||
- Basic types that map natively to msgpack(and probably have a default
|
- Basic types that map natively to msgpack(and probably have a default
|
||||||
representation in msgpack-supported programming languages)
|
representation in msgpack-supported programming languages)
|
||||||
- Special Nvim types that map to msgpack ext with custom type codes.
|
- Special Nvim types that map to msgpack EXT with custom type codes.
|
||||||
|
|
||||||
Basic type mapping:
|
Basic type mapping:
|
||||||
|
|
||||||
@ -171,7 +171,7 @@ String -> msgpack binary
|
|||||||
Array -> msgpack array
|
Array -> msgpack array
|
||||||
Dictionary -> msgpack map
|
Dictionary -> msgpack map
|
||||||
|
|
||||||
Special Nvim types that use msgpack ext:
|
Special Nvim types that use msgpack EXT:
|
||||||
|
|
||||||
Buffer -> enum value kObjectTypeBuffer
|
Buffer -> enum value kObjectTypeBuffer
|
||||||
Window -> enum value kObjectTypeWindow
|
Window -> enum value kObjectTypeWindow
|
||||||
@ -231,7 +231,7 @@ Four functions related to msgpack-rpc are available to vimscript:
|
|||||||
- |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with
|
- |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
|
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
|
possible to process raw data to/from the process stdin/stdout/stderr(Since
|
||||||
the job's stdin/stdout combo are used as a msgpack channgel that is
|
the job's stdin/stdout combo are used as a msgpack channel that is
|
||||||
processed directly by Nvim C code).
|
processed directly by Nvim C code).
|
||||||
- |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
|
- |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
|
||||||
|rpcstart().|
|
|rpcstart().|
|
||||||
|
@ -6,9 +6,9 @@
|
|||||||
|
|
||||||
Introduction to Nvim *nvim-intro*
|
Introduction to Nvim *nvim-intro*
|
||||||
|
|
||||||
This is an introduction new Nvim users. It is meant for experienced Vim users
|
This is an introduction to Vim users that are just getting started with Nvim.
|
||||||
that want to get started with Nvim. For a basic introduction to Vim, see
|
It is not meant for Vim beginners. For a basic introduction to Vim,
|
||||||
|help.txt|.
|
see |help.txt|.
|
||||||
|
|
||||||
For now, it is just an index with the most relevant topics/features that
|
For now, it is just an index with the most relevant topics/features that
|
||||||
differentiate Nvim from Vim:
|
differentiate Nvim from Vim:
|
||||||
|
Loading…
Reference in New Issue
Block a user