docs(lua): explain and link to lua patterns (#18206)

also correct explanation of when it's allowed to omit parens in Lua function calls
This commit is contained in:
Christian Clason 2022-04-21 21:46:07 +02:00 committed by GitHub
parent 28fb40b16f
commit 6c8a3013ac
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 42 additions and 18 deletions

View File

@ -138,16 +138,16 @@ Lua functions can be called in multiple ways. Consider the function: >
end end
The first way to call a function is: > The first way to call this function is: >
example_func(1, 2) example_func(1, 2)
-- ==== Result ==== -- ==== Result ====
-- A is: 1 -- A is: 1
-- B is: 2 -- B is: 2
< <
This way of calling a function is familiar to most scripting languages. This way of calling a function is familiar from most scripting languages.
In Lua, it's important to understand that any function arguments that are In Lua, it's important to understand that any function arguments that are
not supplied are automatically set to `nil`. For example: > not supplied are automatically set to `nil`. For example: >
example_func(1) example_func(1)
-- ==== Result ==== -- ==== Result ====
@ -155,12 +155,13 @@ The first way to call a function is: >
-- B is: nil -- B is: nil
< <
Additionally, if any extra parameters are passed, they are discarded Additionally, if any extra parameters are passed, they are discarded
completely. completely.
In Lua, it is also possible (when only one argument is passed) to call the In Lua, it is also possible to omit the parentheses (only) if the function
function without any parentheses. This is most often used to approximate takes a single string or table literal (`"foo"` or "`{1,2,3}`", respectively).
"keyword"-style arguments with a single dictionary. For example: > The latter is most often used to approximate "keyword-style" arguments with a
single dictionary, for example: >
local func_with_opts = function(opts) local func_with_opts = function(opts)
local will_do_foo = opts.foo local will_do_foo = opts.foo
@ -172,15 +173,38 @@ function without any parentheses. This is most often used to approximate
func_with_opts { foo = true, filename = "hello.world" } func_with_opts { foo = true, filename = "hello.world" }
< <
In this style, each "parameter" is passed via keyword. It is still valid In this style, each "parameter" is passed via keyword. It is still valid
to call the function in this style: > to call the function in the standard style: >
func_with_opts({ foo = true, filename = "hello.world" }) func_with_opts({ foo = true, filename = "hello.world" })
< <
But often in the documentation, you will see the former rather than the But often in the documentation, you will see the former rather than the
latter style, due to its brevity (this is vim after all!). latter style due to its brevity.
==============================================================================
Lua Patterns *lua-patterns*
For performance reasons, Lua does not support regular expressions natively.
Instead, the Lua `string` standard library allows manipulations using a
restricted set of "patterns", see https://www.lua.org/manual/5.1/manual.html#5.4.1
Examples (`string.match` extracts the first match): >
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, Vim regular expressions can be used from Lua
through |vim.regex()|.
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
LUA PLUGIN EXAMPLE *lua-require-example* LUA PLUGIN EXAMPLE *lua-require-example*
@ -1924,9 +1948,9 @@ add({filetypes}) *vim.filetype.add()*
filename (either the "tail" or the full file path). The full filename (either the "tail" or the full file path). The full
file path is checked first, followed by the file name. If a file path is checked first, followed by the file name. If a
match is not found using the filename, then the filename is match is not found using the filename, then the filename is
matched against the list of patterns (sorted by priority) matched against the list of |lua-patterns| (sorted by
until a match is found. Lastly, if pattern matching does not priority) until a match is found. Lastly, if pattern matching
find a filetype, then the file extension is used. does not find a filetype, then the file extension is used.
The filetype can be either a string (in which case it is used The filetype can be either a string (in which case it is used
as the filetype directly) or a function. If a function, it as the filetype directly) or a function. If a function, it

View File

@ -1487,7 +1487,7 @@ end
--- Filetype mappings can be added either by extension or by filename (either --- Filetype mappings can be added either by extension or by filename (either
--- the "tail" or the full file path). The full file path is checked first, --- the "tail" or the full file path). The full file path is checked first,
--- followed by the file name. If a match is not found using the filename, then --- followed by the file name. If a match is not found using the filename, then
--- the filename is matched against the list of patterns (sorted by priority) --- the filename is matched against the list of |lua-patterns| (sorted by priority)
--- until a match is found. Lastly, if pattern matching does not find a --- until a match is found. Lastly, if pattern matching does not find a
--- filetype, then the file extension is used. --- filetype, then the file extension is used.
--- ---