diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/doc/lua.txt | 34 | ||||
| -rw-r--r-- | runtime/doc/news.txt | 5 | ||||
| -rw-r--r-- | runtime/doc/starting.txt | 59 |
3 files changed, 62 insertions, 36 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 9cb189b927..16d0bcb612 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -21,15 +21,19 @@ Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the which can be used from Lua code (|lua-vimscript| |vim.api|). Together these "namespaces" form the Nvim programming interface. -See the |lua-guide| for an introduction to using Lua in Neovim. +Lua plugins and user config are automatically discovered and loaded, just like +Vimscript. See |lua-guide| for practical guidance. +You can also run Lua scripts from your shell using the |-l| argument: > + nvim -l foo.lua [args...] +< *lua-compat* Lua 5.1 is the permanent interface for Nvim Lua. Plugins need only consider Lua 5.1, not worry about forward-compatibility with future Lua versions. If Nvim ever ships with Lua 5.4+, a Lua 5.1 compatibility shim will be provided so that old plugins continue to work transparently. ------------------------------------------------------------------------------- +============================================================================== LUA CONCEPTS AND IDIOMS *lua-concepts* Lua is very simple: this means that, while there are some quirks, once you @@ -73,25 +77,24 @@ In Lua, any missing arguments are passed as `nil`. Example: >lua Furthermore it is not an error if extra parameters are passed, they are just discarded. -It is also allowed to omit the parentheses (only) if the function takes -exactly one string (`"foo"`) or table literal (`{1,2,3}`). The latter is often -used to approximate the "named parameters" feature of languages like Python -("kwargs" or "keyword args"). Example: >lua + *kwargs* +When calling a function, you can omit the parentheses if the function takes +exactly one string literal (`"foo"`) or table literal (`{1,2,3}`). The latter +is often used to approximate "named parameters" ("kwargs" or "keyword args") +as in languages like Python and C#. Example: >lua local func_with_opts = function(opts) local will_do_foo = opts.foo local filename = opts.filename - ... end func_with_opts { foo = true, filename = "hello.world" } < -There is nothing special going on here except that parentheses are treated as +There's nothing special going on here except that parentheses are treated as whitespace. But visually, this small bit of sugar gets reasonably close to a "keyword args" interface. It is of course also valid to call the function with parentheses: >lua - func_with_opts({ foo = true, filename = "hello.world" }) < Nvim tends to prefer the keyword args style. @@ -100,25 +103,20 @@ Nvim tends to prefer the keyword args style. LUA PATTERNS *lua-patterns* Lua intentionally does not support regular expressions, instead it has limited -"patterns" which avoid the performance pitfalls of extended regex. -|luaref-patterns| +"patterns" |luaref-patterns| which avoid the performance pitfalls of extended +regex. Lua scripts can also use Vim regex via |vim.regex()|. -Examples using |string.match()|: >lua +These examples use |string.match()| to demonstrate Lua patterns: >lua print(string.match("foo123bar123", "%d+")) -- 123 - print(string.match("foo123bar123", "[^%d]+")) -- foo - print(string.match("foo123bar123", "[abc]+")) -- ba - print(string.match("foo.bar", "%.bar")) -- .bar -For more complex matching you can use Vim regex from Lua via |vim.regex()|. - ============================================================================== IMPORTING LUA MODULES *require()* *lua-require* @@ -389,7 +387,7 @@ For example consider the following Lua omnifunc handler: >lua vim.api.nvim_buf_set_option(0, 'omnifunc', 'v:lua.mymod.omnifunc') Note: The module ("mymod" in the above example) must either be a Lua global, -or use the require syntax as specified above to access it from a package. +or use require() as shown above to access it from a package. Note: `v:lua` without a call is not allowed in a Vimscript expression: |Funcref|s cannot represent Lua functions. The following are errors: >vim diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index a764b2b882..3e291e59c9 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -57,6 +57,11 @@ The following new APIs or features were added. < (or the Vimscript equivalent) to their |config| file. +• Run Lua scripts from your shell using |-l|. > + nvim -l foo.lua --arg1 --arg2 +< Also works with stdin: > + echo "print(42)" | nvim -l - + • Added a |vim.lsp.codelens.clear()| function to clear codelenses. • |vim.inspect_pos()|, |vim.show_pos()| and |:Inspect| allow a user to get or show items diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 8b662ab1bf..fa9e23eb00 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -9,7 +9,7 @@ Starting Vim *starting* Type |gO| to see the table of contents. ============================================================================== -Nvim arguments *vim-arguments* +Nvim arguments *cli-arguments* Most often, Nvim is started to edit a single file with the command: > @@ -31,8 +31,8 @@ filename One or more file names. The first one will be the current To avoid a file name starting with a '-' being interpreted as an option, precede the arglist with "--", e.g.: > nvim -- -filename -< All arguments after the "--" will be interpreted as file names, - no other options or "+command" argument can follow. +< All arguments after "--" are interpreted as file names, no + other options or "+command" arguments can follow. *--* `-` Alias for stdin (standard input). @@ -143,15 +143,13 @@ argument. these commands, independently from "-c" commands. *-S* --S {file} Vimscript or Lua (".lua") {file} will be |:source|d after the - first file has been read. Equivalent to: > +-S [file] Executes Vimscript or Lua (".lua") [file] after the first file + has been read. See also |:source|. If [file] is not given, + defaults to "Session.vim". Equivalent to: > -c "source {file}" < Can be repeated like "-c", subject to the same limit of 10 "-c" arguments. {file} cannot start with a "-". --S Works like "-S Session.vim". Only when used as the last - argument or when another "-" option follows. - -L *-L* *-r* -r Recovery mode. Without a file name argument, a list of existing swap files is given. With a file name, a swap file @@ -192,8 +190,9 @@ argument. -E reads stdin as text (into buffer 1). -es *-es* *-Es* *-s-ex* *silent-mode* --Es Silent mode (no UI), for scripting. Unrelated to |-s|. - Disables most prompts, messages, warnings and errors. +-Es Script mode, aka "silent mode", aka "batch mode". No UI, + disables most prompts and messages. Unrelated to |-s|. + See also |-S| to run script files. -es reads/executes stdin as Ex commands. > printf "put ='foo'\n%%print\n" | nvim -es @@ -211,10 +210,37 @@ argument. nvim -es +":verbose echo 'foo'" nvim -V1 -es +foo -< User |config| is skipped (unless given with |-u|). +< User |config| is skipped unless |-u| was given. Swap file is skipped (like |-n|). User |shada| is loaded (unless "-i NONE" is given). + *-l* +-l {script} [args] + Executes Lua {script} non-interactively (no UI) with optional + [args] after processing any preceding Nvim |cli-arguments|, + then exits. See |-S| to run multiple Lua scripts without args, + or in an interactive session. + *lua-args* + All [args] are treated as {script} arguments and passed + literally to Lua (in the conventional `_G.arg` global table), + thus "-l" ends processing of Nvim arguments. + + Exits with code 1 on Lua error. + + Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to + output. + + Arguments before "-l" are processed before executing {script}. + This example quits before executing "foo.lua": > + nvim +q -l foo.lua +< This loads Lua module "bar" before executing "foo.lua": > + nvim +"lua require('bar')" -l foo.lua +< + Skips user |config| unless |-u| was given. + Disables plugins unless 'loadplugins' was set. + Disables |shada| unless |-i| was given. + Disables swapfile (like |-n|). + *-b* -b Binary mode. File I/O will only recognize <NL> to separate lines. The 'expandtab' option will be reset. The 'textwidth' @@ -222,9 +248,6 @@ argument. is set. This is done after reading the |vimrc| but before reading any file in the arglist. See also |edit-binary|. - *-l* --l Lisp mode. Sets the 'lisp' and 'showmatch' options on. - *-A* -A Arabic mode. Sets the 'arabic' option on. @@ -239,10 +262,10 @@ argument. Example: > nvim -V8 --V[N]{filename} - Like -V and set 'verbosefile' to {filename}. Messages are not - displayed; instead they are written to the file {filename}. - {filename} must not start with a digit. +-V[N]{file} + Like -V and sets 'verbosefile' to {file} (must not start with + a digit). Messages are not displayed, instead they are + written to {file}. Example: > nvim -V20vimlog < |