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

LICENSE

@@ -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
 
 ====
 

MAINTAIN.md

@@ -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
+In practice we haven't found a way to forecast more precisely than "next" and
-"next" and "after next". That means there are usually one or two (at most)
+"after next". So there are usually one or two (at most) planned milestones:
-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
 --------------

runtime/doc/eval.txt

@@ -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
+		Gets the output of {cmd} as a |string| (|systemlist()| returns
-		get a |List|). {cmd} is treated exactly as in |jobstart()|.
+		a |List|) and sets |v:shell_error| to the error code.
-		Not to be used for interactive commands.
+		{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.
+		argument. 'shellquote' and 'shellxquote' must be properly
-		The characters in 'shellquote' and 'shellxquote' may also
+		configured. Example: >
-		cause trouble.
+		    :echo system('ls '..shellescape(expand('%:h')))
+		    :echo system('ls '..expand('%:h:S'))
 
-		Result is a String.  Example: >
+<		Unlike ":!cmd" there is no automatic check for changed files.
-		    :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.
 		Use |:checktime| to force a check.
 
 		Can also be used as a |method|: >

runtime/doc/lua.txt

@@ -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,
+finds and loads Lua modules.  The conventions are similar to those of
-with some extra features.  See |lua-require-example| for a walkthrough.
+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
+respective Vimscript types. Conversion of other Lua types is an error.
-is attempted.
 
 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
+Note: second argument to `luaeval` is converted ("marshalled") from Vimscript
-("marshalled"), so changes to Lua containers do not affect values in VimL.
+to Lua, so changes to Lua containers do not affect values in Vimscript. Return
-Return value is also always converted. When converting,
+value is also always converted. When converting, |msgpack-special-dict|s are
-|msgpack-special-dict|s are treated specially.
+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
+Methods on the regex object:
-        '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:
 
 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
+        Special value representing NIL in |RPC| and |v:null| in Vimscript
-	vimL interaction, and similar cases. Lua `nil` cannot be used as
+        conversion, and similar cases. Lua `nil` cannot be used as part of
-	part of a lua table representing a Dictionary or Array, as it
+        a Lua table representing a Dictionary or Array, because it is
-	is equivalent to a missing value: `{"foo", nil}` is the same as 
+        treated as missing: `{"foo", nil}` is the same as `{"foo"}`.
-	`{"foo"}`
 
 vim.empty_dict()                                            *vim.empty_dict()*
-	Creates a special table which will be converted to an empty
+        Creates a special empty table (marked with a metatable), which Nvim
-	dictionary when converting lua values to vimL or API types. The
+        converts to an empty dictionary when translating Lua values to
-	table is empty, and this property is marked using a metatable. An
+        Vimscript or API types. Nvim by default converts an empty table `{}`
-	empty table `{}` without this metatable will default to convert to
+        without this metatable to an list/array.
-	an array/list.
 
-	Note: if numeric keys are added to the table, the metatable will be
+        Note: if numeric keys are present in the table, Nvim ignores the
-	ignored and the dict converted to a list/array anyway.
+        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.
+        Sends {event} to {channel} via |RPC| and returns immediately. If
-	If {channel} is 0, the event is broadcast to all channels.
+        {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
+        Sends a request to {channel} to invoke {method} via |RPC| and blocks
-	|RPC| and blocks until a response is received.
+        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 
+        Type index for use in |lua-special-tbl|.  Specifying one of the values
-	values from |vim.types| allows typing the empty table (it is 
+        from |vim.types| allows typing the empty table (it is unclear whether
-	unclear whether empty Lua table represents empty list or empty array) 
+        empty Lua table represents empty list or empty array) and forcing
-	and forcing integral numbers to be |Float|.  See |lua-special-tbl| for 
+        integral numbers to be |Float|.  See |lua-special-tbl| for more
-	more details.
+        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 
+        Table with possible values for |vim.type_idx|.  Contains two sets of
-	of key-value pairs: first maps possible values for |vim.type_idx| 
+        key-value pairs: first maps possible values for |vim.type_idx| to
-	to human-readable strings, second maps human-readable type names 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
+In Vimscript, there is an way to set options |set-option|. In Lua, the
-information, see |set-option|. In Lua, the corresponding method is `vim.opt`.
+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:

runtime/doc/repeat.txt

@@ -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
+:[range]so[urce] [file]	Runs |Ex| commands or Lua code (".lua" files) from
-			from {file}.
+			[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
+:[range]so[urce]! {file}
-			used after |:global|, |:argdo|, |:windo|, |:bufdo|, in
+			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} ..

runtime/doc/vim_diff.txt

@@ -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.

src/nvim/lua/executor.c

@@ -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

test/README.md

@@ -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

test/busted/outputHandlers/nvim.lua

@@ -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