mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-03-06 09:07:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: luaref cleanup #24541

Browse Source 
- drop "luaref-" prefix in favor of "lua-" or nothing, where possible.
- remove redundant "luaref--lang…" and "luaref-api…" tags.
This commit is contained in:
Justin M. Keyes
2023-08-03 08:35:10 -07:00
committed by GitHub
parent 4d859d00d1
commit b034378cf5
8 changed files with 270 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
runtime/doc/lsp.txt
View File

@@ -67,7 +67,7 @@ To override the above defaults, set or unset the options on |LspAttach|: >lua
callback = function(ev)
vim.bo[ev.buf].formatexpr = nil
vim.bo[ev.buf].omnifunc = nil
vim.keymap.del("n", "K", { bufnr = ev.buf })
vim.keymap.del("n", "K", { buffer = ev.buf })
end,
})

6
runtime/doc/lua-guide.txt
View File

@@ -167,8 +167,8 @@ the cache manually first:
<
------------------------------------------------------------------------------
See also:
• |lua-require|
• |luaref-pcall()|
• |lua-module-load|
• |pcall()|
==============================================================================
Using Vim commands and functions from Lua *lua-guide-vimscript*
@@ -186,7 +186,7 @@ Note that special characters will need to be escaped with backslashes:
>lua
vim.cmd("%s/\\Vfoo/bar/g")
<
An alternative is to use a literal string (see |luaref-literal|) delimited by
An alternative is to use a literal string (see |lua-literal|) delimited by
double brackets `[[ ]]` as in
>lua
vim.cmd([[%s/\Vfoo/bar/g]])

53
runtime/doc/lua.txt
View File

@@ -62,10 +62,10 @@ programming": tables, closures, and coroutines.
https://www.lua.org/doc/cacm2018.pdf
- Tables are the "object" or container datastructure: they represent both
lists and maps, you can extend them to represent your own datatypes and
change their behavior using |luaref-metatable| (like Python's "datamodel").
change their behavior using |metatable|s (like Python's "datamodel").
- EVERY scope in Lua is a closure: a function is a closure, a module is
a closure, a `do` block (|luaref-do|) is a closure--and they all work the
same. A Lua module is literally just a big closure discovered on the "path"
a closure, a `do` block (|lua-do|) is a closure--and they all work the same.
A Lua module is literally just a big closure discovered on the "path"
(where your modules are found: |package.cpath|).
- Stackful coroutines enable cooperative multithreading, generators, and
versatile control for both Lua and its host (Nvim).
@@ -81,7 +81,7 @@ An "iterable" is anything that |vim.iter()| can consume: tables, dicts, lists,
iterator functions, tables implementing the |__call()| metamethod, and
|vim.iter()| objects.
*lua-call-function*
*lua-function-call*
Lua functions can be called in multiple ways. Consider the function: >lua
local foo = function(a, b)
print("A: ", a)
@@ -94,21 +94,19 @@ The first way to call this function is: >lua
-- A: 1
-- B: 2
This way of calling a function is familiar from most scripting languages.
In Lua, any missing arguments are passed as `nil`. Example: >lua
This way of calling a function is familiar from most scripting languages. In
Lua, any missing arguments are passed as `nil`, and extra parameters are
silently discarded. Example: >lua
foo(1)
-- ==== Result ====
-- A: 1
-- B: nil
Furthermore it is not an error if extra parameters are passed, they are just
discarded.
<
*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
is often used to mimic "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
@@ -119,21 +117,16 @@ as in languages like Python and C#. Example: >lua
<
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.
a "keyword args" interface. Nvim code tends to prefer this style.
------------------------------------------------------------------------------
LUA PATTERNS *lua-patterns*
Lua intentionally does not support regular expressions, instead it has limited
"patterns" |luaref-patterns| which avoid the performance pitfalls of extended
"patterns" |lua-pattern| which avoid the performance pitfalls of extended
regex. Lua scripts can also use Vim regex via |vim.regex()|.
These examples use |string.match()| to demonstrate Lua patterns: >lua
Examples: >lua
print(string.match("foo123bar123", "%d+"))
-- 123
@@ -145,7 +138,7 @@ These examples use |string.match()| to demonstrate Lua patterns: >lua
-- .bar
==============================================================================
IMPORTING LUA MODULES *require()* *lua-require*
IMPORTING LUA MODULES *lua-module-load*
Modules are searched for under the directories specified in 'runtimepath', in
the order they appear. Any "." in the module name is treated as a directory
@@ -159,7 +152,7 @@ back to Lua's default search mechanism. The first script found is run and
The return value is cached after the first call to `require()` for each module,
with subsequent calls returning the cached value without searching for, or
executing any script. For further details on `require()`, see |luaref-require()|.
executing any script. For further details see |require()|.
For example, if 'runtimepath' is `foo,bar` and |package.cpath| was
`./?.so;./?.dll` at startup, `require('mod')` searches these paths in order
@@ -332,22 +325,22 @@ Example: >vim
:echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123')
" foo
<
*lua-table*
*lua-table-ambiguous*
Lua tables are used as both dictionaries and lists, so it is impossible to
determine whether empty table is meant to be empty list or empty dictionary.
Additionally Lua does not have integer numbers. To distinguish between these
cases there is the following agreement:
*lua-list*
*lua-list*
0. Empty table is empty list.
1. Table with N incrementally growing integral numbers, starting from 1 and
ending with N is considered to be a list.
*lua-dict*
*lua-dict*
2. Table with string keys, none of which contains NUL byte, is considered to
be a dictionary.
3. Table with string keys, at least one of which contains NUL byte, is also
considered to be a dictionary, but this time it is converted to
a |msgpack-special-map|.
*lua-special-tbl*
*lua-special-tbl*
4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point
value:
- `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to
@@ -680,8 +673,8 @@ vim.regex:match_line({bufnr}, {line_idx}, {start}, {end_})
vim.regex:match_str({str}) *regex:match_str()*
Match the string against the regex. If the string should match the regex
precisely, surround the regex with `^` and `$` . If the was a match, the byte indices for the beginning and end of the
match is returned. When there is no match, `nil` is returned. As any integer is truth-y, `regex:match()` can be directly used as a condition in an if-statement.
precisely, surround the regex with `^` and `$` . If there was a match, the byte indices for the beginning and end of the
match are returned. When there is no match, `nil` is returned. Because any integer is "truthy", `regex:match()` can be directly used as a condition in an if-statement.
Parameters: ~
• {str} (string)
@@ -1952,7 +1945,7 @@ vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()*
See also: ~
• |string.gmatch()|
• |vim.split()|
• |luaref-patterns|
• |lua-patterns|
• https://www.lua.org/pil/20.2.html
• http://lua-users.org/wiki/StringLibraryTutorial
@@ -2333,7 +2326,7 @@ vim.trim({s}) *vim.trim()*
(string) String with whitespace removed from its beginning and end
See also: ~
• |luaref-patterns|
• |lua-patterns|
• https://www.lua.org/pil/20.2.html
vim.validate({opt}) *vim.validate()*

469
runtime/doc/luaref.txt
View File

File diff suppressed because it is too large Load Diff

8
runtime/doc/treesitter.txt
View File

@@ -34,8 +34,8 @@ TREESITTER TREES *treesitter-tree*
*TSTree*
A "treesitter tree" represents the parsed contents of a buffer, which can be
used to perform further analysis. It is a |luaref-userdata| reference to an
object held by the tree-sitter library.
used to perform further analysis. It is a |userdata| reference to an object
held by the tree-sitter library.
An instance `TSTree` of a treesitter tree supports the following methods.
@@ -50,8 +50,8 @@ TREESITTER NODES *treesitter-node*
*TSNode*
A "treesitter node" represents one specific element of the parsed contents of
a buffer, which can be captured by a |Query| for, e.g., highlighting. It is a
|luaref-userdata| reference to an object held by the tree-sitter library.
a buffer, which can be captured by a |Query| for, e.g., highlighting. It is
a |userdata| reference to an object held by the tree-sitter library.
An instance `TSNode` of a treesitter node supports the following methods.

2
runtime/doc/vim_diff.txt
View File

@@ -466,7 +466,7 @@ Lua interface (|lua.txt|):
< whereas Vim emits only "TEST".
- Lua has direct access to Nvim |API| via `vim.api`.
- Lua package.path and package.cpath are automatically updated according to
'runtimepath': |lua-require|.
'runtimepath'. |lua-module-load|
Commands:
|:doautocmd| does not warn about "No matching autocommands".

6
runtime/lua/vim/_meta/regex.lua
View File

@@ -18,9 +18,9 @@ function vim.regex(re) end
local regex = {} -- luacheck: no unused
--- Match the string against the regex. If the string should match the regex
--- precisely, surround the regex with `^` and `$`. If the was a match, the
--- byte indices for the beginning and end of the match is returned. When
--- there is no match, `nil` is returned. As any integer is truth-y,
--- precisely, surround the regex with `^` and `$`. If there was a match, the
--- byte indices for the beginning and end of the match are returned. When
--- there is no match, `nil` is returned. Because any integer is "truthy",
--- `regex:match()` can be directly used as a condition in an if-statement.
--- @param str string
function regex:match_str(str) end

4
runtime/lua/vim/shared.lua
View File

@@ -80,7 +80,7 @@ end
---
--- @see |string.gmatch()|
--- @see |vim.split()|
--- @see |luaref-patterns|
--- @see |lua-patterns|
--- @see https://www.lua.org/pil/20.2.html
--- @see http://lua-users.org/wiki/StringLibraryTutorial
---
@@ -660,7 +660,7 @@ end
--- Trim whitespace (Lua pattern "%s") from both sides of a string.
---
---@see |luaref-patterns|
---@see |lua-patterns|
---@see https://www.lua.org/pil/20.2.html
---@param s string String to trim
---@return string String with whitespace removed from its beginning and end