kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-20 19:25:11 -07:00
Code Issues Packages Projects Releases Wiki Activity

Merge #7188 from justinmk/doc

Browse Source 
doc; minor runtime bug fixes
This commit is contained in:
Justin M. Keyes 2017-11-06 05:04:37 +01:00 committed by GitHub
commit d31b94ac20
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
19 changed files with 368 additions and 276 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -34,6 +34,11 @@ Install from source
make CMAKE_BUILD_TYPE=RelWithDebInfo
sudo make install
To install to a non-default location, specify `CMAKE_INSTALL_PREFIX`:
make CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=/full/path/"
make install
See [the wiki](https://github.com/neovim/neovim/wiki/Building-Neovim) for details.
Install from package

6
runtime/autoload/spellfile.vim
View File

@ -88,8 +88,8 @@ function! spellfile#LoadFile(lang)
endif
endif
if newbufnr == winbufnr(0)
" We are back the old buffer, remove any (half-finished) download.
g/^/d_
" We are back to the old buffer, remove any (half-finished) download.
keeppatterns g/^/d_
else
let newbufnr = winbufnr(0)
endif
@ -127,7 +127,7 @@ function! spellfile#LoadFile(lang)
exe "write " . dirname . '/' . fname
" Also download the .sug file.
g/^/d_
keeppatterns g/^/d_
let fname = substitute(fname, '\.spl$', '.sug', '')
echo 'Downloading ' . fname . '...'
call spellfile#Nread(fname)

116
runtime/doc/api.txt
View File

@ -7,7 +7,7 @@
Nvim API *API* *api*
Nvim exposes a powerful API that can be used by plugins and external processes
via |msgpack-rpc|, Lua and VimL (|eval-api|).
via |RPC|, |Lua| and VimL (|eval-api|).
Applications can also embed libnvim to work with the C API directly.
@ -135,6 +135,26 @@ nvim_command({command}) *nvim_command()*
Parameters:~
{command} Ex-command string
nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()*
Gets a highlight definition by name.
Parameters:~
{name} Highlight group name
{rgb} Export RGB colors
Return:~
Highlight definition map
nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()*
Gets a highlight definition by id. |hlID()|
Parameters:~
{hl_id} Highlight id as returned by |hlID()|
{rgb} Export RGB colors
Return:~
Highlight definition map
nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()*
Passes input keys to Nvim. On VimL error: Does not fail, but
updates v:errmsg.
@ -151,7 +171,11 @@ nvim_input({keys}) *nvim_input()*
Unlike `nvim_feedkeys`, this uses a lower-level input buffer
and the call is not deferred. This is the most reliable way to
emulate real user input.
send real user input.
Note:
|keycodes| like <CR> are translated, so "<" is special. To
input a literal "<", send <LT>.
Attributes:~
{async}
@ -204,14 +228,11 @@ nvim_call_function({fname}, {args}) *nvim_call_function()*
Result of the function call
nvim_execute_lua({code}, {args}) *nvim_execute_lua()*
Execute lua code. Parameters might be passed, they are
available inside the chunk as `...`. The chunk can return a
value.
Execute lua code. Parameters (if any) are available as `...`
inside the chunk. The chunk can return a value.
To evaluate an expression, it must be prefixed with "return ".
For instance, to call a lua function with arguments sent in
and get its return value back, use the code "return
my_function(...)".
Only statements are executed. To evaluate an expression,
prefix it with `return`: return my_function(...)
Parameters:~
{code} lua code to execute
@ -220,7 +241,7 @@ nvim_execute_lua({code}, {args}) *nvim_execute_lua()*
Return:~
Return value of lua code if present or NIL.
nvim_strwidth({str}) *nvim_strwidth()*
nvim_strwidth({text}) *nvim_strwidth()*
Calculates the number of display cells occupied by `text`.
<Tab> counts as one cell.
@ -347,7 +368,7 @@ nvim_set_current_buf({buffer}) *nvim_set_current_buf()*
Sets the current buffer
Parameters:~
{id} Buffer handle
{buffer} Buffer handle
nvim_list_wins() *nvim_list_wins()*
Gets the current list of window handles
@ -365,7 +386,7 @@ nvim_set_current_win({window}) *nvim_set_current_win()*
Sets the current window
Parameters:~
{handle} Window handle
{window} Window handle
nvim_list_tabpages() *nvim_list_tabpages()*
Gets the current list of tabpage handles
@ -383,7 +404,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
Sets the current tabpage
Parameters:~
{handle} Tabpage handle
{tabpage} Tabpage handle
nvim_subscribe({event}) *nvim_subscribe()*
Subscribes to event broadcasts
@ -404,26 +425,25 @@ nvim_get_color_map() *nvim_get_color_map()*
TODO: Documentation
nvim_get_mode() *nvim_get_mode()*
Gets the current mode.
mode: Mode string. |mode()|
blocking: true if Nvim is waiting for input.
Attributes:~
{async}
Gets the current mode. |mode()| "blocking" is true if Nvim is
waiting for input.
Return:~
Dictionary { "mode": String, "blocking": Boolean }
Attributes:~
{async}
nvim_get_keymap({mode}) *nvim_get_keymap()*
Get a list of dictionaries describing global (i.e. non-buffer)
mappings Note that the "buffer" key will be 0 to represent
false.
Gets a list of dictionaries describing global (non-buffer)
mappings. The "buffer" key in the returned dictionary is
always zero.
Parameters:~
{mode} The abbreviation for the mode
{mode} Mode short-name ("n", "i", "v", ...)
Return:~
An array of maparg() like dictionaries describing mappings
Array of maparg()-like dictionaries describing mappings
nvim_get_api_info() *nvim_get_api_info()*
TODO: Documentation
@ -584,16 +604,16 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()*
b:changedtickvalue.
nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()*
Get a list of dictionaries describing buffer-local mappings
Note that the buffer key in the dictionary will represent the
buffer handle where the mapping is present
Gets a list of dictionaries describing buffer-local mappings.
The "buffer" key in the returned dictionary reflects the
buffer handle where the mapping is present.
Parameters:~
{mode} The abbreviation for the mode
{buffer_id} Buffer handle
{mode} Mode short-name ("n", "i", "v", ...)
{buffer} Buffer handle
Return:~
An array of maparg() like dictionaries describing mappings
Array of maparg()-like dictionaries describing mappings
nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
Sets a buffer-scoped (b:) variable
@ -670,24 +690,24 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
{col_start}, {col_end})
Adds a highlight to buffer.
This can be used for plugins which dynamically generate
highlights to a buffer (like a semantic highlighter or
linter). The function adds a single highlight to a buffer.
Unlike matchaddpos() highlights follow changes to line
numbering (as lines are inserted/removed above the highlighted
line), like signs and marks do.
Useful for plugins that dynamically generate highlights to a
buffer (like a semantic highlighter or linter). The function
adds a single highlight to a buffer. Unlike matchaddpos()
highlights follow changes to line numbering (as lines are
inserted/removed above the highlighted line), like signs and
marks do.
"src_id" is useful for batch deletion/updating of a set of
highlights. When called with src_id = 0, an unique source id
is generated and returned. Succesive calls can pass in it as
"src_id" to add new highlights to the same source group. All
highlights in the same group can then be cleared with
nvim_buf_clear_highlight. If the highlight never will be
manually deleted pass in -1 for "src_id".
`src_id` is useful for batch deletion/updating of a set of
highlights. When called with `src_id = 0`, an unique source id
is generated and returned. Successive calls can pass that
`src_id` to associate new highlights with the same source
group. All highlights in the same group can be cleared with
`nvim_buf_clear_highlight`. If the highlight never will be
manually deleted, pass `src_id = -1`.
If "hl_group" is the empty string no highlight is added, but a
new src_id is still returned. This is useful for an external
plugin to synchrounously request an unique src_id at
If `hl_group` is the empty string no highlight is added, but a
new `src_id` is still returned. This is useful for an external
plugin to synchrounously request an unique `src_id` at
initialization, and later asynchronously add and clear
highlights in response to buffer changes.
@ -696,7 +716,7 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
{src_id} Source group to use or 0 to use a new group,
or -1 for ungrouped highlight
{hl_group} Name of the highlight group to use
{line} Line to highlight
{line} Line to highlight (zero-indexed)
{col_start} Start of range of columns to highlight
{col_end} End of range of columns to highlight, or -1
to highlight to end of line
@ -948,4 +968,4 @@ nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()*
TODO: Documentation
vim:tw=78:ts=8:ft=help:norl:
vim:tw=78:ts=8:ft=help:norl:

44
runtime/doc/develop.txt
View File

@ -142,6 +142,8 @@ shell The Vim application. This can cover the whole screen (e.g.,
window View on a buffer. There can be several windows in Vim,
together with the command line, menubar, toolbar, etc. they
fit in the shell.
frame Windows are kept in a tree of frames. Each frame contains
a column, row, or window ("leaf" frame).
PROVIDERS *dev-provider*
@ -230,23 +232,47 @@ _not_ a Buffer). The common {action} "list" indicates that it lists all
bufs (plural) in the global context.
API-CLIENT *dev-api-client*
Package Naming ~
API client packages should NOT be named something ambiguous like "neovim" or
"python-client". Use "nvim" as a prefix/suffix to some other identifier
following ecosystem conventions.
For example, Python packages tend to have "py" in the name, so "pynvim" is
a good name: it's idiomatic and unambiguous. If the package is named "neovim",
it confuses users, and complicates documentation and discussions.
Examples of API-client package names:
GOOD: nvim-racket
GOOD: pynvim
BAD: python-client
BAD: neovim
Implementation ~
Consider using libmpack instead of the msgpack.org C/C++ library. libmpack is
small, efficient, and C89-compatible. It can be easily inlined in your
C project source, too. https://github.com/libmpack/libmpack/
EXTERNAL UI *dev-ui*
Compatibility ~
External UIs should be aware of the |api-contract|. In particular, future
versions of Nvim may add optional, new items to existing events. The API is
strongly backwards-compatible, but clients must not break if new fields are
added to existing events.
versions of Nvim may add new items to existing events. The API is strongly
backwards-compatible, but clients must not break if new fields are added to
existing events.
External UIs are expected to implement some common features.
Common Features ~
External UIs are expected to implement these common features:
- Cursor style (shape, color) should respond to the 'guicursor' properties
delivered with the mode_info_set UI event.
- Send the "super" key (Windows key, Apple key) as a |<D-| chord.
- Users may want to configure UI-specific options. The UI should publish the
|GUIEnter| autocmd after attaching to Nvim: >
doautocmd GUIEnter
Implementation ~
- Options can be monitored for changes by the |OptionSet| autocmd. E.g. if the
user sets the 'guifont' option, this autocmd notifies channel 42: >
autocmd OptionSet guifont call rpcnotify(42, 'option-changed', 'guifont', &guifont)
- cursor-shape change: 'guicursor' properties are sent in the mode_info_set UI
event.
vim:tw=78:ts=8:ft=help:norl:

125
runtime/doc/eval.txt
View File

@ -1785,7 +1785,7 @@ v:scrollstart String describing the script or function that caused the
*v:servername* *servername-variable*
*$NVIM_LISTEN_ADDRESS*
v:servername Default {Nvim} server address. Equivalent to
v:servername Default Nvim server address. Equivalent to
|$NVIM_LISTEN_ADDRESS| on startup. |serverstop()|
Read-only.
@ -4915,42 +4915,48 @@ items({dict}) *items()*
entry and the value of this entry. The |List| is in arbitrary
order.
jobclose({job}[, {stream}]) {Nvim} *jobclose()*
Close {job}'s {stream}, which can be one of "stdin", "stdout",
"stderr" or "rpc" (closes the rpc channel for a job started
with the "rpc" option.) If {stream} is omitted, all streams
are closed. If the job is a pty job, this will then close the
pty master, sending SIGHUP to the job process.
jobclose({job}[, {stream}]) *jobclose()*
Close {stream} of |job-id| {job}, where {stream} is one of:
"stdin", "stdout", "stderr", "rpc" (RPC channel of a job
started with `"rpc":v:true`). If {stream} is omitted, all
streams are closed. If the job is a pty job, this will close
the pty master, sending SIGHUP to the job process.
jobpid({job}) {Nvim} *jobpid()*
Return the pid (process id) of {job}.
jobpid({job}) *jobpid()*
Return the PID (process id) of |job-id| {job}.
jobresize({job}, {width}, {height}) {Nvim} *jobresize()*
Resize {job}'s pseudo terminal window to {width} and {height}.
This function will fail if used on jobs started without the
"pty" option.
jobresize({job}, {width}, {height}) *jobresize()*
Resize the pseudo terminal window of |job-id| {job} to {width}
columns and {height} rows.
Fails if the job was not started with `"pty":v:true`.
jobsend({job}, {data}) {Nvim} *jobsend()*
Send data to {job} by writing it to the stdin of the process.
jobsend({job}, {data}) *jobsend()*
Writes to stdin of the process associated with |job-id| {job}.
Returns 1 if the write succeeded, 0 otherwise.
See |job-control| for more information.
See |job-control|.
{data} may be a string, string convertible, or a list. If
{data} is a list, the items will be separated by newlines and
any newlines in an item will be sent as a NUL. A final newline
can be sent by adding a final empty string. For example: >
{data} is a list, the items will be joined by newlines; any
newlines in an item will be sent as NUL. To send a final
newline, include a final empty string. Example: >
:call jobsend(j, ["abc", "123\n456", ""])
< will send "abc<NL>123<NUL>456<NL>".
If the job was started with the rpc option this function
cannot be used, instead use |rpcnotify()| and |rpcrequest()|
to communicate with the job.
jobsend() writes raw data, not RPC messages. If the job was
created with `"rpc":v:true` then the channel expects RPC
messages, use |rpcnotify()| and |rpcrequest()| instead.
jobstart({cmd}[, {opts}]) {Nvim} *jobstart()*
Spawns {cmd} as a job. If {cmd} is a |List| it is run
directly. If {cmd} is a |String| it is processed like this: >
jobstart({cmd}[, {opts}]) *jobstart()*
Spawns {cmd} as a job.
If {cmd} is a List it runs directly (no 'shell').
If {cmd} is a String it runs in the 'shell', like this: >
:call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}'])
< (Only shows the idea; see |shell-unquoting| for full details.)
< (See |shell-unquoting| for details.)
Returns |job-id| on success, 0 on invalid arguments (or job
table is full), -1 if {cmd}[0] or 'shell' is not executable.
See |job-control| and |rpc|.
NOTE: on Windows if {cmd} is a List:
- cmd[0] must be an executable (not a "built-in"). If it is
@ -4962,6 +4968,7 @@ jobstart({cmd}[, {opts}]) {Nvim} *jobstart()*
by CommandLineToArgvW https://msdn.microsoft.com/bb776391
unless cmd[0] is some form of "cmd.exe".
*jobstart-options*
{opts} is a dictionary with these keys:
|on_stdout|: stdout event handler (function name or |Funcref|)
|on_stderr|: stderr event handler (function name or |Funcref|)
@ -4972,9 +4979,9 @@ jobstart({cmd}[, {opts}]) {Nvim} *jobstart()*
with the job over stdin and stdout. "on_stdout" is
then ignored, but "on_stderr" can still be used.
pty : If set, the job will be connected to a new pseudo
terminal, and the job streams are connected to
the master file descriptor. "on_stderr" is ignored
as all output will be received on stdout.
terminal and the job streams are connected to the
master file descriptor. "on_stderr" is ignored,
"on_stdout" receives all output.
width : (pty only) Width of the terminal screen
height : (pty only) Height of the terminal screen
@ -4982,43 +4989,31 @@ jobstart({cmd}[, {opts}]) {Nvim} *jobstart()*
detach : (non-pty only) Detach the job process from the
nvim process. The process will not get killed
when nvim exits. If the process dies before
nvim exits, on_exit will still be invoked.
nvim exits, "on_exit" will still be invoked.
{opts} is passed as |self| to the callback; the caller may
pass arbitrary data by setting other keys.
Returns:
- The job ID on success, which is used by |jobsend()| (or
|rpcnotify()| and |rpcrequest()| if "rpc" option was used)
and |jobstop()|
- 0 on invalid arguments or if the job table is full
- -1 if {cmd}[0] is not executable.
See |job-control| and |msgpack-rpc| for more information.
{opts} is passed as |self| dictionary to the callback; the
caller may set other keys to pass application-specific data.
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, the exit handler provided to |jobstart()| or
|termopen()| will be run.
See |job-control| for more information.
jobstop({job}) *jobstop()*
Stop |job-id| {job} by sending SIGTERM to the job process. If
the process does not terminate after a timeout then SIGKILL
will be sent. When the job terminates its |on_exit| handler
(if any) will be invoked.
See |job-control|.
jobwait({ids}[, {timeout}]) {Nvim} *jobwait()*
jobwait({ids}[, {timeout}]) *jobwait()*
Wait for a set of jobs to finish. The {ids} argument is a list
of ids for jobs that will be waited for. If passed, {timeout}
is the maximum number of milliseconds to wait. While this
function is executing, callbacks for jobs not in the {ids}
list can be executed. Also, the screen wont be updated unless
|:redraw| is invoked by one of the callbacks.
of |job-id|s to wait for. {timeout} is the maximum number of
milliseconds to wait. During jobwait(), callbacks for jobs not
in the {ids} list may be invoked. The screen will not redraw
unless |:redraw| is invoked by a callback.
Returns a list of integers with the same length as {ids}, with
each integer representing the wait result for the
corresponding job id. The possible values for the resulting
integers are:
* the job return code if the job exited
* -1 if the wait timed out for the job
* -2 if the job was interrupted
* -3 if the job id is invalid.
Returns a list of len({ids}) integers, where each integer is
the wait-result of the corresponding job. Each wait-result is:
Job exit-code, if the job exited
-1 if the wait timed out for the job
-2 if the job was interrupted
-3 if the |job-id| is invalid.
join({list} [, {sep}]) *join()*
Join the items in {list} together into one String.
@ -5652,7 +5647,7 @@ mode([expr]) Return a string that indicates the current mode.
i Insert
R Replace |R|
Rv Virtual Replace |gR|
t Terminal {Nvim}
t Terminal
c Command-line
cv Vim Ex mode |gQ|
ce Normal Ex mode |Q|
@ -8201,9 +8196,9 @@ There are four types of features:
Example: >
:if has("win32")
< *has-patch*
3. {Nvim} version. The "nvim-1.2.3" feature means that the Nvim version is
1.2.3 or later. Example: >
:if has("nvim-1.2.3")
3. Nvim version. The "nvim-0.2.1" feature means that the Nvim version is
0.2.1 or later. Example: >
:if has("nvim-0.2.1")
<
4. Included patches. The "patch123" feature means that patch 123 has been
included. Note that this form does not check the version of Vim, you need

22
runtime/doc/if_lua.txt
View File

@ -24,7 +24,7 @@ the existing `package.cpath` are used. Example:
1. Given that
- 'runtimepath' contains `/foo/bar,/xxx;yyy/baz,/abc`;
- initial (defined at compile time or derived from
- initial (defined at compile-time or derived from
`$LUA_CPATH`/`$LUA_INIT`) `package.cpath` contains
`./?.so;/def/ghi/a?d/j/g.elf;/def/?.so`.
2. It finds `?`-containing suffixes `/?.so`, `/a?d/j/g.elf` and `/?.so`, in
@ -159,14 +159,17 @@ Examples:
>
:lua vim.api.nvim_command('echo "Hello, Nvim!"')
<
To see the Lua version: >
:lua print(_VERSION)
To see the LuaJIT version: >
:lua print(jit.version)
<
:[range]lua << {endmarker}
{script}
{endmarker}
Execute Lua script {script}.
Note: This command doesn't work when the Lua
feature wasn't compiled in. To avoid errors, see
|script-here|.
{endmarker} must NOT be preceded by any white space. If {endmarker} is
omitted from after the "<<", a dot '.' must be used after {script}, like
@ -186,15 +189,8 @@ Example:
EOF
endfunction
Note that the variables are prefixed with `local`: they will disappear when
block finishes. This is not the case for globals.
To see what version of Lua you have: >
:lua print(_VERSION)
If you use LuaJIT you can also use this: >
:lua print(jit.version)
<
Note that the `local` variables will disappear when block finishes. This is
not the case for globals.
*:luado*
:[range]luado {body} Execute Lua function "function (line, linenr) {body}

3
runtime/doc/intro.txt
View File

@ -373,8 +373,7 @@ CTRL-{char} {char} typed as a control character; that is, typing {char}
*key-notation* *key-codes* *keycodes*
These names for keys are used in the documentation. They can also be used
with the ":map" command (insert the key name by pressing CTRL-K and then the
key you want the name for).
with the ":map" command.
notation meaning equivalent decimal value(s) ~
-----------------------------------------------------------------------

129
runtime/doc/job_control.txt
View File

@ -4,41 +4,30 @@
NVIM REFERENCE MANUAL by Thiago de Arruda
Nvim's facilities for job control *job-control*
Nvim job control *job-control*
Job control is a way to perform multitasking in Nvim, so scripts can spawn and
control multiple processes without blocking the current Nvim instance.
Type |gO| to see the table of contents.
==============================================================================
1. Introduction *job-control-intro*
Concepts
Job control is a simple way to perform multitasking in vimscript. Wikipedia
contains a more generic/detailed description:
Job Id *job-id*
"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
available shells, instead relying on OS functionality for process management.
Internally, Nvim job control is powered by libuv, which has a nice
cross-platform API for managing processes. See https://github.com/libuv/libuv
for details.
When a job starts it is assigned a number, unique for the life of the current
Nvim session. Functions like |jobstart()| return job ids. Functions like
|jobsend()|, |jobstop()|, |rpcnotify()|, and |rpcrequest()| take job ids.
==============================================================================
2. Usage *job-control-usage*
Usage *job-control-usage*
To control jobs, use the "job…" family of functions: |jobstart()|,
|jobsend()|, |jobstop()|.
Example: >
Job control is achieved by calling a combination of the |jobstart()|,
|jobsend()| and |jobstop()| functions. Here's an example:
>
function! s:JobHandler(job_id, data, event) dict
if a:event == 'stdout'
let str = self.shell.' stdout: '.join(a:data)
@ -58,35 +47,41 @@ Job control is achieved by calling a combination of the |jobstart()|,
let job1 = jobstart(['bash'], extend({'shell': 'shell 1'}, s:callbacks))
let job2 = jobstart(['bash', '-c', 'for i in {1..10}; do echo hello $i!; sleep 1; done'], extend({'shell': 'shell 2'}, s:callbacks))
To test the above script, copy it to a file ~/foo.vim and run it: >
nvim -u ~/foo.vim
<
To test the above, copy it to the file ~/jobcontrol.vim and start with a clean
nvim instance:
>
nvim -u NONE -S ~/jobcontrol.vim
<
Here's what is happening:
Description of what happens:
- Two bash shells are spawned by |jobstart()| with their stdin/stdout/stderr
streams connected to nvim.
- The first shell is idle, waiting to read commands from its stdin.
- The second shell is started with -c which executes the command (a for-loop
printing 0 through 9) and then exits.
- `JobHandler()` callback is passed to |jobstart()| to handle various job
events. It displays stdout/stderr data received from the shells.
- Two bash instances are spawned by |jobstart()| with their stdin/stdout/stderr
connected to nvim.
- The first shell is idle, waiting to read commands from its stdin.
- The second shell is started with the -c argument, causing it to execute a
command then exit. In this case, the command is a for loop that will print 0
through 9 then exit.
- The `JobHandler()` function is a callback passed to |jobstart()| to handle
various job events. It takes care of displaying stdout/stderr received from
the shells.
*on_stdout* *on_stderr* *on_exit*
- The arguments passed to `JobHandler()` are:
0: The job id
1: If the event is "stdout" or "stderr", a list with lines read from the
corresponding stream. For "exit", it is the status returned by the
program.
2: The event type, which is "stdout", "stderr" or "exit".
*on_stdout*
Arguments passed to on_stdout callback:
0: |job-id|
1: List of lines read from the stream. If the last item is not "" (empty
string), then it is an incomplete line that might be continued at the
next on_stdout invocation. See Note 2 below.
2: Event type: "stdout"
*on_stderr*
Arguments passed to on_stderr callback:
0: |job-id|
1: List of lines read from the stream. If the last item is not "" (empty
string), then it is an incomplete line that might be continued at the
next on_stderr invocation. See Note 2 below.
2: Event type: "stderr"
*on_exit*
Arguments passed to on_exit callback:
0: |job-id|
1: Exit-code of the process.
2: Event type: "exit"
Note: Buffered stdout/stderr data which has not been flushed by the sender
will not trigger the "stdout" callback (but if the process ends, the
"exit" callback will be triggered).
will not trigger the on_stdout/on_stderr callback (but if the process
ends, the on_exit callback will be invoked).
For example, "ruby -e" buffers output, so small strings will be
buffered unless "auto-flushing" ($stdout.sync=true) is enabled. >
function! Receive(job_id, data, event)
@ -97,9 +92,25 @@ Here's what is happening:
\ {'on_stdout': 'Receive'})
< https://github.com/neovim/neovim/issues/1592
The options dictionary is passed as the "self" variable to the callback
function. Here's a more object-oriented version of the above:
>
Note 2:
Job event handlers may receive partial (incomplete) lines. For a given
invocation of on_stdout/on_stderr, `a:data` is not guaranteed to end
with a newline.
- `abcdefg` may arrive as `['abc']`, `['defg']`.
- `abc\nefg` may arrive as `['abc', '']`, `['efg']` or `['abc']`,
`['','efg']`, or even `['ab']`, `['c','efg']`.
Easy way to deal with this: initialize a list as `['']`, then append
to it as follows: >
let s:chunks = ['']
func! s:on_stdout(job_id, data, event) dict
let s:chunks[-1] .= a:data[0]
call extend(s:chunks, a:data[1:])
endf
<
The |jobstart-options| dictionary is passed as |self| to the callback.
The above example could be written in this "object-oriented" style: >
let Shell = {}
function Shell.on_stdout(_job_id, data, event)
@ -126,19 +137,13 @@ function. Here's a more object-oriented version of the above:
let instance = Shell.new('bomb',
\ 'for i in $(seq 9 -1 1); do echo $i 1>&$((i % 2 + 1)); sleep 1; done')
<
To send data to the job's stdin, one can use the |jobsend()| function, like
this:
>
To send data to the job's stdin, use |jobsend()|: >
: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:
>
A job may be killed with |jobstop()|: >
:call jobstop(job1)
<
When |jobstop()| is called, `SIGTERM` will be sent to the job. If a job does
not exit after 2 seconds, `SIGKILL` will be sent.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

2
runtime/doc/msgpack_rpc.txt
View File

@ -175,7 +175,7 @@ contains information that makes this task easier (see also |rpc-types|):
even more strongly-typed APIs.
- Functions that are considered to be methods that operate on instances of
Nvim special types (msgpack EXT) will have the `"method"` attribute set to
`true`. The reciever type is the type of the first argument. The method
`true`. The receiver type is the type of the first argument. The method
names are prefixed with `nvim_` plus a shortened type name, e.g.
`nvim_buf_get_lines` represents the `get_lines` method of a Buffer instance.
- Global functions have `"method"` set to `false` and are prefixed with just

2
runtime/doc/options.txt
View File

@ -6759,7 +6759,7 @@ A jump table for the options with a short description can be found at |Q_op|.
Highlights of vertical separators are determined by the window to the
left of the separator. The highlight of a tabpage in |tabline| is
determine by the last-focused window of the tabpage. Highlights of
determined by the last-focused window of the tabpage. Highlights of
the popupmenu are determined by the current window. Highlights in the
message area cannot be overridden.

14
runtime/doc/provider.txt
View File

@ -133,8 +133,8 @@ registers. Nvim looks for these clipboard tools, in order of priority:
- |g:clipboard|
- pbcopy/pbpaste (macOS)
- xclip
- xsel (newer alternative to xclip)
- xsel (if $DISPLAY is set)
- xclip (if $DISPLAY is set)
- lemonade (for SSH) https://github.com/pocke/lemonade
- doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/
- win32yank (Windows)
@ -162,13 +162,11 @@ process has not died, the cached selection is applied.
==============================================================================
X11 selection mechanism *clipboard-x11* *x11-selection*
The clipboard providers for X11 store text in what is known as "selections".
Selections are "owned" by an application, so when the application is closed,
the selection text is lost.
X11 clipboard providers store text in "selections". Selections are owned by an
application, so when the application gets closed, the selection text is lost.
The contents of selections are held by the originating application (e.g., upon
a copy), and only passed on to another application when that other application
asks for them (e.g., upon a paste).
a copy), and only passed to another application when that other application
requests them (e.g., upon a paste).
*quoteplus* *quote+*

26
runtime/doc/vim_diff.txt
View File

@ -60,14 +60,17 @@ a complete and centralized reference of those differences.
MAJOR COMPONENTS ~
Embedded terminal emulator |terminal|
RPC API |RPC|
Shared data |shada|
XDG base directories |xdg|
API |API|
Lua scripting |lua|
Job control |job-control|
Remote plugins |remote-plugin|
Python plugins |provider-python|
Clipboard integration |provider-clipboard|
Providers
Clipboard |provider-clipboard|
Python plugins |provider-python|
Ruby plugins |provider-ruby|
Shared data |shada|
Embedded terminal |terminal|
XDG base directories |xdg|
USER EXPERIENCE ~
@ -87,6 +90,16 @@ Working intuitively and consistently is a major goal of Nvim.
- Vim's internal test functions (test_autochdir(), test_settime(), etc.) are
not exposed (nor implemented); instead Nvim has a robust API.
- Behaviors, options, documentation are removed if they cost users more time
than they save.
Usability details have been improved where the benefit outweighs any
backwards-compatibility cost. Some examples:
- |K| in help documents can be used like |CTRL-]|.
- Directories for 'directory' and 'undodir' are auto-created.
- Terminal features such as 'guicursor' are enabled where possible.
ARCHITECTURE ~
External plugins run in separate processes. |remote-plugin| This improves
@ -130,6 +143,7 @@ Commands:
|:checkhealth|
|:drop| is available on all platforms
|:Man| is available by default, with many improvements such as completion
|:tchdir| tab-local |current-directory|
Functions:
|dictwatcheradd()| notifies a callback whenever a |Dict| is modified

2
runtime/plugin/man.vim
View File

@ -5,7 +5,7 @@ if exists('g:loaded_man')
endif
let g:loaded_man = 1
command! -range=0 -complete=customlist,man#complete -nargs=* Man call man#open_page(v:count, v:count1, <q-mods>, <f-args>)
command! -bar -range=0 -complete=customlist,man#complete -nargs=* Man call man#open_page(v:count, v:count1, <q-mods>, <f-args>)
augroup man
autocmd!

22
scripts/gen_api_vimdoc.py
View File

@ -38,6 +38,10 @@ import subprocess
from xml.dom import minidom
if sys.version_info[0] < 3:
print("use Python 3")
sys.exit(1)
doc_filename = 'api.txt'
# String used to find the start of the generated part of the doc.
section_start_token = '*api-global*'
@ -69,7 +73,7 @@ text_width = 78
script_path = os.path.abspath(__file__)
base_dir = os.path.dirname(os.path.dirname(script_path))
src_dir = os.path.join(base_dir, 'src/nvim/api')
out_dir = os.path.join(base_dir, 'tmp/api_doc')
out_dir = os.path.join(base_dir, 'tmp-api-doc')
filter_cmd = '%s %s' % (sys.executable, script_path)
seen_funcs = set()
@ -217,7 +221,12 @@ def parse_para(parent, width=62):
width=width) + '\n')
elif child.nodeName == 'simplesect':
kind = child.getAttribute('kind')
if kind == 'return':
if kind == 'note':
lines.append('Note:')
lines.append(doc_wrap(parse_para(child),
prefix=' ',
width=width))
elif kind == 'return':
lines.append('%s:~' % kind.title())
lines.append(doc_wrap(parse_para(child),
prefix=' ',
@ -280,14 +289,19 @@ def parse_source_xml(filename):
parts = return_type.strip('_').split('_')
return_type = '%s(%s)' % (parts[0], ', '.join(parts[1:]))
name = get_text(get_child(member, 'name'))
annotations = get_text(get_child(member, 'argsstring'))
if annotations and ')' in annotations:
annotations = annotations.rsplit(')', 1)[-1].strip()
# XXX: (doxygen 1.8.11) 'argsstring' only includes FUNC_ATTR_*
# attributes if the function signature is non-void.
# Force attributes here for such functions.
if name == 'nvim_get_mode' and len(annotations) == 0:
annotations += 'FUNC_API_ASYNC'
annotations = filter(None, map(lambda x: annotation_map.get(x),
annotations.split()))
name = get_text(get_child(member, 'name'))
vimtag = '*%s()*' % name
args = []
type_length = 0

37
src/nvim/api/buffer.c
View File

@ -439,6 +439,7 @@ Object nvim_buf_get_var(Buffer buffer, String name, Error *err)
/// Gets a changed tick of a buffer
///
/// @param[in] buffer Buffer handle.
/// @param[out] err Error details, if any
///
/// @return `b:changedtick` value.
Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
@ -453,14 +454,14 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
return buf->b_changedtick;
}
/// Get a list of dictionaries describing buffer-local mappings
/// Note that the buffer key in the dictionary will represent the buffer
/// handle where the mapping is present
/// Gets a list of dictionaries describing buffer-local mappings.
/// The "buffer" key in the returned dictionary reflects the buffer
/// handle where the mapping is present.
///
/// @param mode The abbreviation for the mode
/// @param buffer_id Buffer handle
/// @param mode Mode short-name ("n", "i", "v", ...)
/// @param buffer Buffer handle
/// @param[out] err Error details, if any
/// @returns An array of maparg() like dictionaries describing mappings
/// @returns Array of maparg()-like dictionaries describing mappings
ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
FUNC_API_SINCE(3)
{
@ -739,29 +740,29 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
/// Adds a highlight to buffer.
///
/// This can be used for plugins which dynamically generate highlights to a
/// buffer (like a semantic highlighter or linter). The function adds a single
/// Useful for plugins that dynamically generate highlights to a buffer
/// (like a semantic highlighter or linter). The function adds a single
/// highlight to a buffer. Unlike matchaddpos() highlights follow changes to
/// line numbering (as lines are inserted/removed above the highlighted line),
/// like signs and marks do.
///
/// "src_id" is useful for batch deletion/updating of a set of highlights. When
/// called with src_id = 0, an unique source id is generated and returned.
/// Succesive calls can pass in it as "src_id" to add new highlights to the same
/// source group. All highlights in the same group can then be cleared with
/// nvim_buf_clear_highlight. If the highlight never will be manually deleted
/// pass in -1 for "src_id".
/// `src_id` is useful for batch deletion/updating of a set of highlights. When
/// called with `src_id = 0`, an unique source id is generated and returned.
/// Successive calls can pass that `src_id` to associate new highlights with
/// the same source group. All highlights in the same group can be cleared
/// with `nvim_buf_clear_highlight`. If the highlight never will be manually
/// deleted, pass `src_id = -1`.
///
/// If "hl_group" is the empty string no highlight is added, but a new src_id
/// If `hl_group` is the empty string no highlight is added, but a new `src_id`
/// is still returned. This is useful for an external plugin to synchrounously
/// request an unique src_id at initialization, and later asynchronously add and
/// clear highlights in response to buffer changes.
/// request an unique `src_id` at initialization, and later asynchronously add
/// and clear highlights in response to buffer changes.
///
/// @param buffer Buffer handle
/// @param src_id Source group to use or 0 to use a new group,
/// or -1 for ungrouped highlight
/// @param hl_group Name of the highlight group to use
/// @param line Line to highlight
/// @param line Line to highlight (zero-indexed)
/// @param col_start Start of range of columns to highlight
/// @param col_end End of range of columns to highlight,
/// or -1 to highlight to end of line

30
src/nvim/api/vim.c
View File

@ -166,7 +166,10 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_csi)
/// On VimL error: Does not fail, but updates v:errmsg.
///
/// Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call
/// is not deferred. This is the most reliable way to emulate real user input.
/// is not deferred. This is the most reliable way to send real user input.
///
/// @note |keycodes| like <CR> are translated, so "<" is special.
/// To input a literal "<", send <LT>.
///
/// @param keys to be typed
/// @return Number of bytes actually written (can be fewer than
@ -320,15 +323,15 @@ Object nvim_execute_lua(String code, Array args, Error *err)
/// @param text Some text
/// @param[out] err Error details, if any
/// @return Number of cells
Integer nvim_strwidth(String str, Error *err)
Integer nvim_strwidth(String text, Error *err)
FUNC_API_SINCE(1)
{
if (str.size > INT_MAX) {
if (text.size > INT_MAX) {
api_set_error(err, kErrorTypeValidation, "String length is too high");
return 0;
}
return (Integer) mb_string2cells((char_u *) str.data);
return (Integer)mb_string2cells((char_u *)text.data);
}
/// Gets the paths contained in 'runtimepath'.
@ -578,7 +581,7 @@ Buffer nvim_get_current_buf(void)
/// Sets the current buffer
///
/// @param id Buffer handle
/// @param buffer Buffer handle
/// @param[out] err Error details, if any
void nvim_set_current_buf(Buffer buffer, Error *err)
FUNC_API_SINCE(1)
@ -632,7 +635,7 @@ Window nvim_get_current_win(void)
/// Sets the current window
///
/// @param handle Window handle
/// @param window Window handle
void nvim_set_current_win(Window window, Error *err)
FUNC_API_SINCE(1)
{
@ -685,7 +688,7 @@ Tabpage nvim_get_current_tabpage(void)
/// Sets the current tabpage
///
/// @param handle Tabpage handle
/// @param tabpage Tabpage handle
/// @param[out] err Error details, if any
void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
FUNC_API_SINCE(1)
@ -755,9 +758,8 @@ Dictionary nvim_get_color_map(void)
}
/// Gets the current mode.
/// mode: Mode string. |mode()|
/// blocking: true if Nvim is waiting for input.
/// Gets the current mode. |mode()|
/// "blocking" is true if Nvim is waiting for input.
///
/// @returns Dictionary { "mode": String, "blocking": Boolean }
Dictionary nvim_get_mode(void)
@ -773,11 +775,11 @@ Dictionary nvim_get_mode(void)
return rv;
}
/// Get a list of dictionaries describing global (i.e. non-buffer) mappings
/// Note that the "buffer" key will be 0 to represent false.
/// Gets a list of dictionaries describing global (non-buffer) mappings.
/// The "buffer" key in the returned dictionary is always zero.
///
/// @param mode The abbreviation for the mode
/// @returns An array of maparg() like dictionaries describing mappings
/// @param mode Mode short-name ("n", "i", "v", ...)
/// @returns Array of maparg()-like dictionaries describing mappings
ArrayOf(Dictionary) nvim_get_keymap(String mode)
FUNC_API_SINCE(3)
{

4
src/nvim/lua/executor.c
View File

@ -336,8 +336,8 @@ static lua_State *nlua_init(void)
/// Calls nlua_init() if needed. Is responsible for pre-lua call initalization
/// like updating `package.[c]path` with directories derived from &runtimepath.
///
/// @return Interprter instance to use. Will either be initialized now or taken
/// from previous initalization.
/// @return Interpreter instance to use. Will either be initialized now or
/// taken from previous initialization.
static lua_State *nlua_enter(void)
FUNC_ATTR_NONNULL_RET FUNC_ATTR_WARN_UNUSED_RESULT
{

2
src/nvim/ops.c
View File

@ -2735,7 +2735,7 @@ void do_put(int regname, yankreg_T *reg, int dir, long count, int flags)
// Autocommands may be executed when saving lines for undo, which may make
// y_array invalid. Start undo now to avoid that.
if (u_save(curwin->w_cursor.lnum, curwin->w_cursor.lnum + 1) == FAIL) {
ELOG(_("Failed to save undo information"));
ELOG("Failed to save undo information");
return;
}
}

53
test/README.md
View File

@ -1,31 +1,48 @@
# Tests
Tests
=====
Tests are run by `/cmake/RunTests.cmake` file, using busted.
For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight.
## Directory structure
Lint
----
Directories with tests: `/test/benchmark` for benchmarks, `/test/functional` for
functional tests, `/test/unit` for unit tests. `/test/config` contains `*.in`
files (currently a single one) which are transformed into `*.lua` files using
`configure_file` CMake command: this is for acessing CMake variables in lua
tests. `/test/includes` contains include files for use by luajit `ffi.cdef`
C definitions parser: normally used to make macros not accessible via this
mechanism accessible the other way.
`make lint` (and `make testlint`) runs [luacheck](https://github.com/mpeterv/luacheck)
on the test code.
Files `/test/*/preload.lua` contain modules which will be preloaded by busted,
via `--helper` option. `/test/**/helpers.lua` contain various “library”
functions, (intended to be) used by a number of tests and not just a single one.
If a luacheck warning must be ignored, specify the warning code. Example:
`/test/*/**/*_spec.lua` are files containing actual tests. Files that do not end
with a `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they
have some common topic.
-- luacheck: ignore 621
Tests inside `/test/unit` and `/test/functional` are normally divided into
groups by the semantic component they are testing.
http://luacheck.readthedocs.io/en/stable/warnings.html
## Environment variables
Ignore the smallest applicable scope (e.g. inside a function, not at the top of
the file).
Layout
------
- `/test/benchmark` : benchmarks
- `/test/functional` : functional tests
- `/test/unit` : unit tests
- `/test/config` : contains `*.in` files which are transformed into `*.lua`
files using `configure_file` CMake command: this is for acessing CMake
variables in lua tests.
- `/test/includes` : include-files for use by luajit `ffi.cdef` C definitions
parser: normally used to make macros not accessible via this mechanism
accessible the other way.
- `/test/*/preload.lua` : modules preloaded by busted `--helper` option
- `/test/**/helpers.lua` : common utility functions for test code
- `/test/*/**/*_spec.lua` : actual tests. Files that do not end with
`_spec.lua` are libraries like `/test/**/helpers.lua`, except that they have
some common topic.
Tests in `/test/unit` and `/test/functional` are normally divided into groups
by the semantic component they are testing.
Environment variables
---------------------
Test behaviour is affected by environment variables. Currently supported
(Functional, Unit, Benchmarks) (when Defined; when set to _1_; when defined,