mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-10-26 12:27:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document breaking change for nvim_create_autocmd callback (#27484)

Browse Source 
https://github.com/neovim/neovim/pull/27428 changed the semantics of
callbacks passed to nvim_create_autocmd such that any truthy value will
delete the autocommand (rather than just the literal boolean value
`true`). Update the documentation accordingly and add an entry to
`news.txt`.

The behavior is now consistent between nvim_create_autocmd and
nvim_buf_attach.
This commit is contained in:
Gregory Anders
2024-02-15 19:56:58 -06:00
committed by GitHub
parent 04dfa2eea9
commit 55a4aa41bb
5 changed files with 24 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
runtime/doc/api.txt
View File

@@ -2099,8 +2099,9 @@ nvim_buf_attach({buffer}, {send_buffer}, {*opts}) *nvim_buf_attach()*
will be `nvim_buf_changedtick_event`. Not for Lua
callbacks.
• {opts} Optional parameters.
• on_lines: Lua callback invoked on change. Return `true` to
detach. Args:
• on_lines: Lua callback invoked on change. Return a
truthy value (not `false` or `nil`)
to detach. Args:
• the string "lines"
• buffer handle
• b:changedtick
@@ -2113,7 +2114,8 @@ nvim_buf_attach({buffer}, {send_buffer}, {*opts}) *nvim_buf_attach()*
• on_bytes: Lua callback invoked on change. This
callback receives more granular information about the
change compared to on_lines. Return `true` to
change compared to on_lines. Return a truthy value
(not `false` or `nil`) to
detach. Args:
• the string "bytes"
• buffer handle
@@ -3457,9 +3459,9 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
troubleshooting).
• callback (function|string) optional: Lua function (or
Vimscript function name, if string) called when the
event(s) is triggered. Lua callback can return true to
delete the autocommand, and receives a table argument with
these keys:
event(s) is triggered. Lua callback can return a truthy
value (not `false` or `nil`) to delete the
autocommand. Receives a table argument with these keys:
• id: (number) autocommand id
• event: (string) name of the triggered event
|autocmd-events|

3
runtime/doc/news.txt
View File

@@ -122,6 +122,9 @@ The following changes may require adaptations in user config or plugins.
• |shm-q| now fully hides macro recording message instead of only shortening it.
• Returning any truthy value from a callback passed to |nvim_create_autocmd()|
(rather than just `true`) will delete the autocommand.
==============================================================================
BREAKING CHANGES IN HEAD *news-breaking-dev*

14
runtime/lua/vim/_meta/api.lua generated
View File

@@ -155,8 +155,9 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- will be `nvim_buf_changedtick_event`. Not for Lua
--- callbacks.
--- @param opts vim.api.keyset.buf_attach Optional parameters.
--- • on_lines: Lua callback invoked on change. Return `true` to
--- detach. Args:
--- • on_lines: Lua callback invoked on change. Return a
--- truthy value (not `false` or `nil`)
--- to detach. Args:
--- • the string "lines"
--- • buffer handle
--- • b:changedtick
@@ -169,7 +170,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
---
--- • on_bytes: Lua callback invoked on change. This
--- callback receives more granular information about the
--- change compared to on_lines. Return `true` to
--- change compared to on_lines. Return a truthy value
--- (not `false` or `nil`) to
--- detach. Args:
--- • the string "bytes"
--- • buffer handle
@@ -863,9 +865,9 @@ function vim.api.nvim_create_augroup(name, opts) end
--- troubleshooting).
--- • callback (function|string) optional: Lua function (or
--- Vimscript function name, if string) called when the
--- event(s) is triggered. Lua callback can return true to
--- delete the autocommand, and receives a table argument with
--- these keys:
--- event(s) is triggered. Lua callback can return a truthy
--- value (not `false` or `nil`) to delete the
--- autocommand. Receives a table argument with these keys:
--- • id: (number) autocommand id
--- • event: (string) name of the triggered event
--- `autocmd-events`

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

@@ -378,8 +378,9 @@ cleanup:
/// |autocmd-buflocal|. Cannot be used with {pattern}.
/// - desc (string) optional: description (for documentation and troubleshooting).
/// - callback (function|string) optional: Lua function (or Vimscript function name, if
/// string) called when the event(s) is triggered. Lua callback can return true to
/// delete the autocommand, and receives a table argument with these keys:
/// string) called when the event(s) is triggered. Lua callback can return a truthy
/// value (not `false` or `nil`) to delete the autocommand. Receives a table argument
/// with these keys:
/// - id: (number) autocommand id
/// - event: (string) name of the triggered event |autocmd-events|
/// - group: (number|nil) autocommand group id, if any

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

@@ -112,7 +112,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// Not for Lua callbacks.
/// @param opts Optional parameters.
/// - on_lines: Lua callback invoked on change.
/// Return `true` to detach. Args:
/// Return a truthy value (not `false` or `nil`) to detach. Args:
/// - the string "lines"
/// - buffer handle
/// - b:changedtick
@@ -125,8 +125,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// - on_bytes: Lua callback invoked on change.
/// This callback receives more granular information about the
/// change compared to on_lines.
/// Return `true` to detach.
/// Args:
/// Return a truthy value (not `false` or `nil`) to detach. Args:
/// - the string "bytes"
/// - buffer handle
/// - b:changedtick