kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-20 03:05:11 -07:00
Code Issues Packages Projects Releases Wiki Activity

doc: vim.fn, vim.call(), vim.api [ci skip]

Browse Source
This commit is contained in:
Justin M. Keyes 2019-10-27 15:05:59 -07:00
parent c66297452c
commit 9ef16a1628
11 changed files with 241 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
runtime/doc/api.txt
View File

@ -850,10 +850,10 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
{enter} Enter the window (make it the current window)
{config} Map defining the window configuration. Keys:
• `relative` : Sets the window layout to "floating", placed
at (row,col) coordinates relative to one of:
at (row,col) coordinates relative to:
• "editor" The global editor grid
• "win" Window given by the `win` field, or
current window by default.
current window.
• "cursor" Cursor position in current window.
• `win` : |window-ID| for relative="win".
@ -1476,45 +1476,66 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Line count, or 0 for unloaded buffer. |api-buffer|
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Activates buffer-update events on a channel, or as lua
Activates buffer-update events on a channel, or as Lua
callbacks.
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
{send_buffer} Set to true if the initial notification
should contain the whole buffer. If so, the
first notification will be a
`nvim_buf_lines_event` . Otherwise, the
first notification will be a
`nvim_buf_changedtick_event` . Not used for
lua callbacks.
{send_buffer} True if the initial notification should
contain the whole buffer: first
notification will be `nvim_buf_lines_event`
. Else the first notification will be
`nvim_buf_changedtick_event` . Not for Lua
callbacks.
{opts} Optional parameters.
• `on_lines` : lua callback received on
change.
• `on_changedtick` : lua callback received
on changedtick increment without text
change.
• `utf_sizes` : include UTF-32 and UTF-16
size of the replaced region. See
|api-buffer-updates-lua| for more
information
• on_lines: Lua callback invoked on change.
Return `true` to detach. Args:
• buffer handle
• b:changedtick
• first line that changed (zero-indexed)
• last line that was changed
• last line in the updated range
• byte count of previous contents
• deleted_codepoints (if `utf_sizes` is
true)
• deleted_codeunits (if `utf_sizes` is
true)
• on_changedtick: Lua callback invoked on
changedtick increment without text
change. Args:
• buffer handle
• b:changedtick
• on_detach: Lua callback invoked on
detach. Args:
• buffer handle
• utf_sizes: include UTF-32 and UTF-16 size
of the replaced region, as args to
`on_lines` .
Return: ~
False when updates couldn't be enabled because the buffer
isn't loaded or `opts` contained an invalid key; otherwise
True. TODO: LUA_API_NO_EVAL
False if attach failed (invalid parameter, or buffer isn't
loaded); otherwise True. TODO: LUA_API_NO_EVAL
See also: ~
|nvim_buf_detach()|
|api-buffer-updates-lua|
nvim_buf_detach({buffer}) *nvim_buf_detach()*
Deactivates buffer-update events on the channel.
For Lua callbacks see |api-lua-detach|.
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
Return: ~
False when updates couldn't be disabled because the buffer
isn't loaded; otherwise True.
False if detach failed (because the buffer isn't loaded);
otherwise True.
See also: ~
|nvim_buf_attach()|
|api-lua-detach| for detaching Lua callbacks
*nvim_buf_get_lines()*
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})

81
runtime/doc/develop.txt
View File

@ -143,6 +143,87 @@ DOCUMENTATION *dev-doc*
/// @param dirname The path fragment before `pend`
<
C docstrings ~
Nvim API documentation lives in the source code, as docstrings (Doxygen
comments) on the function definitions. The |api| :help is generated
from the docstrings defined in src/nvim/api/*.c.
Docstring format:
- Lines start with `///`
- Special tokens start with `@` followed by the token name:
`@note`, `@param`, `@returns`
- Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples.
Example: the help for |nvim_open_win()| is generated from a docstring defined
in src/nvim/api/vim.c like this: >
/// Opens a new window.
/// ...
///
/// Example (Lua): window-relative float
/// <pre>
/// vim.api.nvim_open_win(0, false,
/// {relative='win', row=3, col=3, width=12, height=3})
/// </pre>
///
/// @param buffer Buffer to display
/// @param enter Enter the window
/// @param config Map defining the window configuration. Keys:
/// - relative: Sets the window layout, relative to:
/// - "editor" The global editor grid.
/// - "win" Window given by the `win` field.
/// - "cursor" Cursor position in current window.
/// ...
/// @param[out] err Error details, if any
///
/// @return Window handle, or 0 on error
Lua docstrings ~
*dev-lua-doc*
Lua documentation lives in the source code, as docstrings on the function
definitions. The |lua-vim| :help is generated from the docstrings.
Docstring format:
- Lines in the main description start with `---`
- Special tokens start with `--@` followed by the token name:
`--@see`, `--@param`, `--@returns`
- Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples.
Example: the help for |vim.paste()| is generated from a docstring decorating
vim.paste in src/nvim/lua/vim.lua like this: >
--- Paste handler, invoked by |nvim_paste()| when a conforming UI
--- (such as the |TUI|) pastes text into the editor.
---
--- Example: To remove ANSI color codes when pasting:
--- <pre>
--- vim.paste = (function()
--- local overridden = vim.paste
--- ...
--- end)()
--- </pre>
---
--@see |paste|
---
--@param lines ...
--@param phase ...
--@returns false if client should cancel the paste.
LUA *dev-lua*
- Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
pseudo-OOP designs. Plugin authors just want functions to call, they don't
want to learn a big, fancy inheritance hierarchy. So we should avoid complex
objects: tables are usually better.
API *dev-api*
Use this template to name new API functions:

13
runtime/doc/eval.txt
View File

@ -1217,7 +1217,7 @@ lambda expression *expr-lambda* *lambda*
{args -> expr1} lambda expression
A lambda expression creates a new unnamed function which returns the result of
evaluating |expr1|. Lambda expressions differ from |user-functions| in
evaluating |expr1|. Lambda expressions differ from |user-function|s in
the following ways:
1. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
@ -1986,9 +1986,12 @@ v:windowid Application-specific window "handle" which may be set by any
|window-ID|.
==============================================================================
4. Builtin Functions *functions*
4. Builtin Functions *vim-function* *functions*
See |function-list| for a list grouped by what the function is used for.
The Vimscript subsystem (referred to as "eval" internally) provides the
following builtin functions. Scripts can also define |user-function|s.
See |function-list| to browse functions by topic.
(Use CTRL-] on the function name to jump to the full explanation.)
@ -3543,7 +3546,7 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is
string)
*funcname built-in function (see |functions|)
or user defined function (see
|user-functions|). Also works for a
|user-function|). Also works for a
variable that is a Funcref.
varname internal variable (see
|internal-variables|). Also works
@ -9243,7 +9246,7 @@ Don't forget that "^" will only match at the first character of the String and
"\n".
==============================================================================
5. Defining functions *user-functions*
5. Defining functions *user-function*
New functions can be defined. These can be called just like builtin
functions. The function executes a sequence of Ex commands. Normal mode

81
runtime/doc/if_lua.txt
View File

@ -285,7 +285,7 @@ Example: >
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
Additionally Lua does not have integer numbers. To distinguish between these
cases there is the following agreement:
0. Empty table is empty list.
@ -300,7 +300,7 @@ cases there is the following agreement:
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
a floating-point 1.0. Note that by default integral lua numbers are
a floating-point 1.0. Note that by default integral Lua numbers are
converted to |Number|s, non-integral are converted to |Float|s. This
variant allows integral |Float|s.
- `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty
@ -321,10 +321,10 @@ Examples: >
: endfunction
:echo Rand(1,10)
Note that currently second argument to `luaeval` undergoes VimL to lua
conversion, so changing containers in lua 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` 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.
==============================================================================
Lua standard modules *lua-stdlib*
@ -355,21 +355,11 @@ Result is something like this: >
To find documentation on e.g. the "deepcopy" function: >
:help vim.deepcopy
:help vim.deepcopy()
Note that underscore-prefixed functions (e.g. "_os_proc_children") are
internal/private and must not be used by plugins.
------------------------------------------------------------------------------
VIM.API *lua-api* *vim.api*
`vim.api` exposes the full Nvim |API| as a table of Lua functions.
Example: to use the "nvim_get_current_line()" API function, call
"vim.api.nvim_get_current_line()": >
print(tostring(vim.api.nvim_get_current_line()))
------------------------------------------------------------------------------
VIM.LOOP *lua-loop* *vim.loop*
@ -503,7 +493,7 @@ it should call `parse()` again. If the buffer wasn't edited, the same tree will
be returned again without extra work. If the buffer was parsed before,
incremental parsing will be done of the changed parts.
NB: to use the parser directly inside a |nvim_buf_attach| lua callback, you must
NB: to use the parser directly inside a |nvim_buf_attach| Lua callback, you must
call `get_parser()` before you register your callback. But preferably parsing
shouldn't be done directly in the change callback anyway as they will be very
frequent. Rather a plugin that does any kind of analysis on a tree should use
@ -578,7 +568,17 @@ tsnode:named_descendant_for_range(start_row, start_col, end_row, end_col)
range of (row, column) positions
------------------------------------------------------------------------------
VIM *lua-util*
VIM *lua-builtin*
vim.api.{func}({...}) *vim.api*
Invokes Nvim |API| function {func} with arguments {...}.
Example: call the "nvim_get_current_line()" API function: >
print(tostring(vim.api.nvim_get_current_line()))
vim.call({func}, {...}) *vim.call()*
Invokes |vim-function| or |user-function| {func} with arguments {...}.
See also |vim.fn|. Equivalent to: >
vim.fn[func]({...})
vim.in_fast_event() *vim.in_fast_event()*
Returns true if the code is executing as part of a "fast" event
@ -614,26 +614,23 @@ vim.schedule({callback}) *vim.schedule()*
Schedules {callback} to be invoked soon by the main event-loop. Useful
to avoid |textlock| or other temporary restrictions.
vim.fn.{func}({...})
Call vimL function {func} with arguments. {func} can be both builtin
functions and user functions. To call autoload functions, use the
syntax `vim.fn['some#function']({...})`
vim.fn.{func}({...}) *vim.fn*
Invokes |vim-function| or |user-function| {func} with arguments {...}.
To call autoload functions, use the syntax: >
vim.fn['some#function']({...})
<
Unlike vim.api.|nvim_call_function| this converts directly between Vim
objects and Lua objects. If the Vim function returns a float, it will
be represented directly as a Lua number. Empty lists and dictionaries
both are represented by an empty table.
Note: unlike vim.api.|nvim_call_function| this converts values directly
between vimL values and lua values. If the vimL function returns a
float, it will be representeted directly as a lua number. Both empty
lists and dictonaries will be represented by an empty table.
Note: vim.fn keys are generated on demand. So `pairs(vim.fn)`
does NOT work to enumerate all functions.
vim.call({func}, {...})
Call vim script function {func}. Equivalent to `vim.fn[func]({...})`
Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
enumerates functions that were called at least once.
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)
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.
@ -657,7 +654,7 @@ vim.types *vim.types*
`vim.types.array` and `vim.types.dictionary` fall under only two
following assumptions:
1. Value may serve both as a key and as a value in a table. Given the
properties of lua tables this basically means “value is not `nil`”.
properties of Lua tables this basically means “value is not `nil`”.
2. For each value in `vim.types` table `vim.types[vim.types[value]]`
is the same as `value`.
No other restrictions are put on types, and it is not guaranteed that
@ -679,6 +676,20 @@ paste({lines}, {phase}) *vim.paste()*
Paste handler, invoked by |nvim_paste()| when a conforming UI
(such as the |TUI|) pastes text into the editor.
Example: To remove ANSI color codes when pasting: >
vim.paste = (function()
local overridden = vim.paste
return function(lines, phase)
for i,line in ipairs(lines) do
-- Scrub ANSI color codes from paste input.
lines[i] = line:gsub('\27%[[0-9;mK]+', '')
end
overridden(lines, phase)
end
end)()
<
Parameters: ~
{lines} |readfile()|-style list of lines to paste.
|channel-lines|

2
runtime/doc/index.txt
View File

@ -1170,7 +1170,7 @@ tag command action ~
|:caddfile| :caddf[ile] add error message to current quickfix list
|:call| :cal[l] call a function
|:catch| :cat[ch] part of a :try command
|:cbelow| :cbe[low] got to error below current line
|:cbelow| :cbe[low] go to error below current line
|:cbottom| :cbo[ttom] scroll to the bottom of the quickfix window
|:cbuffer| :cb[uffer] parse error messages and jump to first error
|:cc| :cc go to specific error

16
runtime/doc/motion.txt
View File

@ -418,35 +418,35 @@ between Vi and Vim.
5. Text object motions *object-motions*
*(*
( [count] sentences backward. |exclusive| motion.
( [count] |sentence|s backward. |exclusive| motion.
*)*
) [count] sentences forward. |exclusive| motion.
) [count] |sentence|s forward. |exclusive| motion.
*{*
{ [count] paragraphs backward. |exclusive| motion.
{ [count] |paragraph|s backward. |exclusive| motion.
*}*
} [count] paragraphs forward. |exclusive| motion.
} [count] |paragraph|s forward. |exclusive| motion.
*]]*
]] [count] sections forward or to the next '{' in the
]] [count] |section|s forward or to the next '{' in the
first column. When used after an operator, then also
stops below a '}' in the first column. |exclusive|
Note that |exclusive-linewise| often applies.
*][*
][ [count] sections forward or to the next '}' in the
][ [count] |section|s forward or to the next '}' in the
first column. |exclusive|
Note that |exclusive-linewise| often applies.
*[[*
[[ [count] sections backward or to the previous '{' in
[[ [count] |section|s backward or to the previous '{' in
the first column. |exclusive|
Note that |exclusive-linewise| often applies.
*[]*
[] [count] sections backward or to the previous '}' in
[] [count] |section|s backward or to the previous '}' in
the first column. |exclusive|
Note that |exclusive-linewise| often applies.

49
src/nvim/api/buffer.c
View File

@ -101,25 +101,39 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
return rv;
}
/// Activates buffer-update events on a channel, or as lua callbacks.
/// Activates buffer-update events on a channel, or as Lua callbacks.
///
/// @see |nvim_buf_detach()|
/// @see |api-buffer-updates-lua|
///
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param send_buffer Set to true if the initial notification should contain
/// the whole buffer. If so, the first notification will be a
/// `nvim_buf_lines_event`. Otherwise, the first notification will be
/// a `nvim_buf_changedtick_event`. Not used for lua callbacks.
/// @param send_buffer True if the initial notification should contain the
/// whole buffer: first notification will be `nvim_buf_lines_event`.
/// Else the first notification will be `nvim_buf_changedtick_event`.
/// Not for Lua callbacks.
/// @param opts Optional parameters.
/// - `on_lines`: lua callback received on change.
/// - `on_changedtick`: lua callback received on changedtick
/// increment without text change.
/// - `utf_sizes`: include UTF-32 and UTF-16 size of
/// the replaced region.
/// See |api-buffer-updates-lua| for more information
/// - on_lines: Lua callback invoked on change.
/// Return `true` to detach. Args:
/// - buffer handle
/// - b:changedtick
/// - first line that changed (zero-indexed)
/// - last line that was changed
/// - last line in the updated range
/// - byte count of previous contents
/// - deleted_codepoints (if `utf_sizes` is true)
/// - deleted_codeunits (if `utf_sizes` is true)
/// - on_changedtick: Lua callback invoked on changedtick
/// increment without text change. Args:
/// - buffer handle
/// - b:changedtick
/// - on_detach: Lua callback invoked on detach. Args:
/// - buffer handle
/// - utf_sizes: include UTF-32 and UTF-16 size of the replaced
/// region, as args to `on_lines`.
/// @param[out] err Error details, if any
/// @return False when updates couldn't be enabled because the buffer isn't
/// loaded or `opts` contained an invalid key; otherwise True.
/// TODO: LUA_API_NO_EVAL
/// @return False if attach failed (invalid parameter, or buffer isn't loaded);
/// otherwise True. TODO: LUA_API_NO_EVAL
Boolean nvim_buf_attach(uint64_t channel_id,
Buffer buffer,
Boolean send_buffer,
@ -183,13 +197,14 @@ error:
/// Deactivates buffer-update events on the channel.
///
/// For Lua callbacks see |api-lua-detach|.
/// @see |nvim_buf_attach()|
/// @see |api-lua-detach| for detaching Lua callbacks
///
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any
/// @return False when updates couldn't be disabled because the buffer
/// isn't loaded; otherwise True.
/// @return False if detach failed (because the buffer isn't loaded);
/// otherwise True.
Boolean nvim_buf_detach(uint64_t channel_id,
Buffer buffer,
Error *err)

5
src/nvim/api/vim.c
View File

@ -1040,10 +1040,9 @@ fail:
/// @param enter Enter the window (make it the current window)
/// @param config Map defining the window configuration. Keys:
/// - `relative`: Sets the window layout to "floating", placed at (row,col)
/// coordinates relative to one of:
/// coordinates relative to:
/// - "editor" The global editor grid
/// - "win" Window given by the `win` field, or current window by
/// default.
/// - "win" Window given by the `win` field, or current window.
/// - "cursor" Cursor position in current window.
/// - `win`: |window-ID| for relative="win".
/// - `anchor`: Decides which corner of the float to place at (row,col):

14
src/nvim/lua/vim.lua
View File

@ -165,6 +165,20 @@ end
--- Paste handler, invoked by |nvim_paste()| when a conforming UI
--- (such as the |TUI|) pastes text into the editor.
---
--- Example: To remove ANSI color codes when pasting:
--- <pre>
--- vim.paste = (function()
--- local overridden = vim.paste
--- return function(lines, phase)
--- for i,line in ipairs(lines) do
--- -- Scrub ANSI color codes from paste input.
--- lines[i] = line:gsub('\27%[[0-9;mK]+', '')
--- end
--- overridden(lines, phase)
--- end
--- end)()
--- </pre>
---
--@see |paste|
---
--@param lines |readfile()|-style list of lines to paste. |channel-lines|

2
test/functional/lua/utility_functions_spec.lua
View File

@ -301,7 +301,7 @@ describe('lua stdlib', function()
pcall_err(exec_lua, [[return vim.pesc(2)]]))
end)
it('vim.call and vim.fn', function()
it('vim.call, vim.fn', function()
eq(true, exec_lua([[return vim.call('sin', 0.0) == 0.0 ]]))
eq(true, exec_lua([[return vim.fn.sin(0.0) == 0.0 ]]))
-- compat: nvim_call_function uses "special" value for vimL float

2
test/functional/terminal/tui_spec.lua
View File

@ -535,7 +535,7 @@ describe('TUI', function()
|
{4:~ }|
{5: }|
{8:paste: Error executing lua: vim.lua:197: Vim:E21: }|
{8:paste: Error executing lua: vim.lua:211: Vim:E21: }|
{8:Cannot make changes, 'modifiable' is off} |
{10:Press ENTER or type command to continue}{1: } |
{3:-- TERMINAL --} |