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

docs: third-party licenses, TEST_COLORS, system() #15665

Browse Source
This commit is contained in:
Justin M. Keyes 2021-09-14 10:20:33 -07:00 committed by GitHub
parent 0a83017fe9
commit b63b4777ec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 157 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
LICENSE
View File

@ -189,8 +189,16 @@ contributed under the Vim license and (2) externally maintained libraries.
The externally maintained libraries used by Neovim are:
- Klib: a Generic Library in C. MIT/X11 license.
- libuv. Copyright Joyent, Inc. and other Node contributors. Node.js license.
- Lua: MIT license
- LuaJIT: a Just-In-Time Compiler for Lua. Copyright Mike Pall. MIT license.
- Luv: Apache 2.0 license
- libmpack: MIT license
- libtermkey: MIT license
- libuv. Copyright Joyent, Inc. and other Node contributors. Node.js license.
- libvterm: MIT license
- lua-compat: MIT license
- tree-sitter: MIT license
- xdiff: LGPL license
====

13
MAINTAIN.md
View File

@ -10,14 +10,13 @@ General guidelines
* Write down what was decided
* Constraints are good
* Use automation to solve problems
* Never break the API
* Never break the API... but sometimes break the UI
Ticket triage
-------------
In practice we haven't found a meaningful way to forecast more precisely than
"next" and "after next". That means there are usually one or two (at most)
planned milestones:
In practice we haven't found a way to forecast more precisely than "next" and
"after next". So there are usually one or two (at most) planned milestones:
- Next bugfix-release (1.0.x)
- Next feature-release (1.x.0)
@ -25,16 +24,16 @@ planned milestones:
The forecasting problem might be solved with an explicit priority system (like
Bram's todo.txt). Meanwhile the Neovim priority system is defined by:
- PRs nearing completion (RDY).
- PRs nearing completion.
- Issue labels. E.g. the `+plan` label increases the ticket's priority merely
for having a plan written down: it is _closer to completion_ than tickets
without a plan.
- Comment activity or new information.
Anything that isn't in the next milestone, and doesn't have a RDY PR ... is
Anything that isn't in the next milestone, and doesn't have a finished PR—is
just not something you care very much about, by construction. Post-release you
can review open issues, but chances are your next milestone is already getting
full :)
full... :)
Release policy
--------------

47
runtime/doc/eval.txt
View File

@ -9139,11 +9139,23 @@ synstack({lnum}, {col}) *synstack()*
valid positions.
system({cmd} [, {input}]) *system()* *E677*
Get the output of {cmd} as a |string| (use |systemlist()| to
get a |List|). {cmd} is treated exactly as in |jobstart()|.
Not to be used for interactive commands.
Gets the output of {cmd} as a |string| (|systemlist()| returns
a |List|) and sets |v:shell_error| to the error code.
{cmd} is treated as in |jobstart()|:
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}'])
If {input} is a string it is written to a pipe and passed as
< Not to be used for interactive commands.
Result is a String, filtered to avoid platform-specific quirks:
- <CR><NL> is replaced with <NL>
- NUL characters are replaced with SOH (0x01)
Example: >
:echo system(['ls', expand('%:h')])
< If {input} is a string it is written to a pipe and passed as
stdin to the command. The string is written as-is, line
separators are not changed.
If {input} is a |List| it is written to the pipe as
@ -9165,29 +9177,12 @@ system({cmd} [, {input}]) *system()* *E677*
Note: Use |shellescape()| or |::S| with |expand()| or
|fnamemodify()| to escape special characters in a command
argument. Newlines in {cmd} may cause the command to fail.
The characters in 'shellquote' and 'shellxquote' may also
cause trouble.
argument. 'shellquote' and 'shellxquote' must be properly
configured. Example: >
:echo system('ls '..shellescape(expand('%:h')))
:echo system('ls '..expand('%:h:S'))
Result is a String. Example: >
:let files = system("ls " . shellescape(expand('%:h')))
:let files = system('ls ' . expand('%:h:S'))
< To make the result more system-independent, the shell output
is filtered to replace <CR> with <NL> for Macintosh, and
<CR><NL> with <NL> for DOS-like systems.
To avoid the string being truncated at a NUL, all NUL
characters are replaced with SOH (0x01).
The command executed is constructed using several options when
{cmd} is a string: 'shell' 'shellcmdflag' {cmd}
The resulting error code can be found in |v:shell_error|.
Note that any wrong value in the options mentioned above may
make the function fail. It has also been reported to fail
when using a security agent application.
Unlike ":!cmd" there is no automatic check for changed files.
< Unlike ":!cmd" there is no automatic check for changed files.
Use |:checktime| to force a check.
Can also be used as a |method|: >

93
runtime/doc/lua.txt
View File

@ -27,8 +27,9 @@ are on 'runtimepath':
~/.config/nvim/lua/foo.lua
then `require('foo')` loads "~/.config/nvim/lua/foo.lua", and
"runtime/lua/foo.lua" is not used. See |lua-require| to understand how Nvim
finds and loads Lua modules. The conventions are similar to VimL plugins,
with some extra features. See |lua-require-example| for a walkthrough.
finds and loads Lua modules. The conventions are similar to those of
Vimscript |plugin|s, with some extra features. See |lua-require-example| for
a walkthrough.
==============================================================================
IMPORTING LUA MODULES *lua-require*
@ -301,10 +302,11 @@ arguments separated by " " (space) instead of "\t" (tab).
*:luafile*
:[range]luafile {file}
Execute Lua script in {file}.
The whole argument is used as a single file name.
The whole argument is used as the filename (like
|:edit|), spaces do not need to be escaped.
Alternatively you can |:source| Lua files.
Examples:
>
Examples: >
:luafile script.lua
:luafile %
<
@ -324,8 +326,7 @@ semantically equivalent in Lua to:
end
Lua nils, numbers, strings, tables and booleans are converted to their
respective VimL types. An error is thrown if conversion of any other Lua types
is attempted.
respective Vimscript types. Conversion of other Lua types is an error.
The magic global "_A" contains the second argument to luaeval().
@ -373,10 +374,10 @@ Examples: >
: endfunction
:echo Rand(1,10)
Note: second argument to `luaeval` undergoes VimL to Lua conversion
("marshalled"), so changes to Lua containers do not affect values in VimL.
Return value is also always converted. When converting,
|msgpack-special-dict|s are treated specially.
Note: second argument to `luaeval` is converted ("marshalled") from Vimscript
to Lua, so changes to Lua containers do not affect values in Vimscript. Return
value is also always converted. When converting, |msgpack-special-dict|s are
treated specially.
==============================================================================
Vimscript v:lua interface *v:lua-call*
@ -597,13 +598,11 @@ Vim regexes can be used directly from lua. Currently they only allow
matching within a single line.
vim.regex({re}) *vim.regex()*
Parse the Vim regex {re} and return a regex object. Regexes are
"magic" and case-insensitive by default, regardless of 'magic' and
'ignorecase'. The can be controlled with flags, see |/magic|.
Parse the regex {re} and return a regex object. 'magic' and
'ignorecase' options are ignored, lua regexes always defaults to magic
and ignoring case. The behavior can be changed with flags in
the beginning of the string |/magic|.
Regex objects support the following methods:
Methods on the regex object:
regex:match_str({str}) *regex:match_str()*
Match the string against the regex. If the string should match the
@ -708,7 +707,7 @@ vim.api.{func}({...}) *vim.api*
print(tostring(vim.api.nvim_get_current_line()))
vim.version() *vim.version*
Returns the version of the current neovim build.
Gets the version of the current Nvim build.
vim.in_fast_event() *vim.in_fast_event()*
Returns true if the code is executing as part of a "fast" event
@ -718,31 +717,29 @@ vim.in_fast_event() *vim.in_fast_event()*
may be subject to other restrictions such as |textlock|).
vim.NIL *vim.NIL*
Special value used to represent NIL in msgpack-rpc and |v:null| in
vimL interaction, and similar cases. Lua `nil` cannot be used as
part of a lua table representing a Dictionary or Array, as it
is equivalent to a missing value: `{"foo", nil}` is the same as
`{"foo"}`
Special value representing NIL in |RPC| and |v:null| in Vimscript
conversion, and similar cases. Lua `nil` cannot be used as part of
a Lua table representing a Dictionary or Array, because it is
treated as missing: `{"foo", nil}` is the same as `{"foo"}`.
vim.empty_dict() *vim.empty_dict()*
Creates a special table which will be converted to an empty
dictionary when converting lua values to vimL or API types. The
table is empty, and this property is marked using a metatable. An
empty table `{}` without this metatable will default to convert to
an array/list.
Creates a special empty table (marked with a metatable), which Nvim
converts to an empty dictionary when translating Lua values to
Vimscript or API types. Nvim by default converts an empty table `{}`
without this metatable to an list/array.
Note: if numeric keys are added to the table, the metatable will be
ignored and the dict converted to a list/array anyway.
Note: if numeric keys are present in the table, Nvim ignores the
metatable marker and converts the dict to a list/array anyway.
vim.rpcnotify({channel}, {method}[, {args}...]) *vim.rpcnotify()*
Sends {event} to {channel} via |RPC| and returns immediately.
If {channel} is 0, the event is broadcast to all channels.
Sends {event} to {channel} via |RPC| and returns immediately. If
{channel} is 0, the event is broadcast to all channels.
This function also works in a fast callback |lua-loop-callbacks|.
vim.rpcrequest({channel}, {method}[, {args}...]) *vim.rpcrequest()*
Sends a request to {channel} to invoke {method} via
|RPC| and blocks until a response is received.
Sends a request to {channel} to invoke {method} via |RPC| and blocks
until a response is received.
Note: NIL values as part of the return value is represented as
|vim.NIL| special value
@ -841,11 +838,11 @@ vim.wait({time} [, {callback}, {interval}, {fast_only}]) *vim.wait()*
<
vim.type_idx *vim.type_idx*
Type index for use in |lua-special-tbl|. Specifying one of the
values from |vim.types| allows typing the empty table (it is
unclear whether empty Lua table represents empty list or empty array)
and forcing integral numbers to be |Float|. See |lua-special-tbl| for
more details.
Type index for use in |lua-special-tbl|. Specifying one of the values
from |vim.types| allows typing the empty table (it is unclear whether
empty Lua table represents empty list or empty array) and forcing
integral numbers to be |Float|. See |lua-special-tbl| for more
details.
vim.val_idx *vim.val_idx*
Value index for tables representing |Float|s. A table representing
@ -857,9 +854,9 @@ vim.val_idx *vim.val_idx*
< See also |vim.type_idx| and |lua-special-tbl|.
vim.types *vim.types*
Table with possible values for |vim.type_idx|. Contains two sets
of key-value pairs: first maps possible values for |vim.type_idx|
to human-readable strings, second maps human-readable type names to
Table with possible values for |vim.type_idx|. Contains two sets of
key-value pairs: first maps possible values for |vim.type_idx| to
human-readable strings, second maps human-readable type names to
values for |vim.type_idx|. Currently contains pairs for `float`,
`array` and `dictionary` types.
@ -966,8 +963,8 @@ vim.env *vim.env*
*lua-vim-optlocal*
*lua-vim-setlocal*
In vimL, there is a succint and simple way to set options. For more
information, see |set-option|. In Lua, the corresponding method is `vim.opt`.
In Vimscript, there is an way to set options |set-option|. In Lua, the
corresponding method is `vim.opt`.
`vim.opt` provides several conveniences for setting and controlling options
from within Lua.
@ -975,18 +972,18 @@ from within Lua.
Examples: ~
To set a boolean toggle:
In vimL:
In Vimscript:
`set number`
In Lua:
`vim.opt.number = true`
To set an array of values:
In vimL:
In Vimscript:
`set wildignore=*.o,*.a,__pycache__`
In Lua, there are two ways you can do this now. One is very similar to
the vimL way:
the Vimscript form:
`vim.opt.wildignore = '*.o,*.a,__pycache__'`
However, vim.opt also supports a more elegent way of setting
@ -1019,7 +1016,7 @@ from within Lua.
vim.opt.wildignore:remove { "node_modules" }
<
To set a map of values:
In vimL:
In Vimscript:
`set listchars=space:_,tab:>~`
In Lua:

11
runtime/doc/repeat.txt
View File

@ -172,15 +172,16 @@ Using Vim scripts *using-scripts*
For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
*:so* *:source* *load-vim-script*
:so[urce] {file} Runs |Ex| commands or Lua code (".lua" files) read
from {file}.
:[range]so[urce] [file] Runs |Ex| commands or Lua code (".lua" files) from
[file], or from the current buffer if no [file] is
given.
Triggers the |SourcePre| autocommand.
*:source!*
:so[urce]! {file} Runs |Normal-mode| commands read from {file}. When
used after |:global|, |:argdo|, |:windo|, |:bufdo|, in
:[range]so[urce]! {file}
Runs |Normal-mode| commands from {file}. When used
after |:global|, |:argdo|, |:windo|, |:bufdo|, in
a loop or when another command follows the display
won't be updated while executing the commands.
Cannot be used in the |sandbox|.
*:ru* *:runtime*
:ru[ntime][!] [where] {file} ..

1
runtime/doc/vim_diff.txt
View File

@ -472,6 +472,7 @@ Compile-time features:
X11 integration (see |x11-selection|)
Eval:
Vim9script
*js_encode()*
*js_decode()*
*v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead.

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

@ -90,7 +90,7 @@ static void nlua_error(lua_State *const lstate, const char *const msg)
lua_pop(lstate, 1);
}
/// Return version of current neovim build
/// Gets the version of the current Nvim build.
///
/// @param lstate Lua interpreter state.
static int nlua_nvim_version(lua_State *const lstate) FUNC_ATTR_NONNULL_ALL

2
test/README.md
View File

@ -256,6 +256,8 @@ Number; !must be defined to function properly):
- `VALGRIND_LOG` (F) (S): overrides valgrind log file name used for `VALGRIND`.
- `TEST_COLORS` (F) (U) (D): enable pretty colors in test runner.
- `TEST_SKIP_FRAGILE` (F) (D): makes test suite skip some fragile tests.
- `TEST_TIMEOUT` (FU) (I): specifies maximum time, in seconds, before the test

2
test/busted/outputHandlers/nvim.lua
View File

@ -3,7 +3,7 @@ local global_helpers = require('test.helpers')
-- Colors are disabled by default. #15610
local colors = setmetatable({}, {__index = function() return function(s) return s end end})
if os.getenv "NVIM_COLORS" then
if os.getenv "TEST_COLORS" then
colors = require 'term.colors'
end