From db15a3b8f77a24d37e41ca53e0b032a7e35cf13a Mon Sep 17 00:00:00 2001 From: Peter Hodge Date: Fri, 26 Jan 2018 20:37:38 +0100 Subject: API: Document buffer updates Originally written by @phodge in https://github.com/neovim/neovim/pull/5269. --- runtime/doc/msgpack_rpc.txt | 188 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 01d4e10cea..ab77e08bc7 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -241,4 +241,192 @@ Even for statically compiled clients it is good practice to avoid hardcoding the type codes, because a client may be built against one Nvim version but connect to another with different type codes. +============================================================================== +6. Live Updates *live-updates* *rpc-live-updates* + +A dedicated API has been created to allow co-processes to be notified in +real-time when the user changes a buffer in any way. It is difficult and +error-prone to try and do this with autocommands such as |TextChanged|. + + *live-updates-enabling* +Setting Up~ + +If your API client is a standalone co-process, it can use the +`"nvim_buf_live_updates"`API method to activate Live Update events for a +specific buffer. For example, in python > + + import sys, neovim + nvim = neovim.attach('stdio') + bufnr = sys.argv[1] + nvim.buffers[bufnr].live_updates(True) + +After the `"nvim_buf_live_updates"` method is called, neovim will send a +series of notifications containing the entire buffer's contents and any +subsequent changes. The buffer's contents are sent via notifications because +if you were to use the other API methods to retrieve the buffer contents, the +buffer could be changed again before you turn on live updates. This can cause +a delay if your plugin activates live updates for a very large buffer, but it +is the the most efficient way to maintain a copy of the entire buffer's +contents inside your plugin. + + *live-updates-disabling* +Turning Off~ + +You can use `"nvim_buf_live_updates"` with an argument of `False` to turn off +notifications. One final notification will be sent to indicate that live +updates are no longer active for the specified buffer. Alternatively, you can +just close the channel. + + *live-updates-limitations* +Limitations~ + +Note that any of the following actions will also turn off live updates because +the buffer contents are unloaded from memory: + + - Closing all a buffer's windows (unless 'hidden' is enabled). + - Using |:edit| to reload the buffer + - reloading the buffer after it is changed from outside neovim. + + *live-updates-events* +Handling Events~ + +The co-process will start receiving the notification events which will be +equivilent to the following |rpcnotify()| calls: + +1. rpcnotify({channel}, "LiveUpdateStart", *LiveUpdateStart* + [{buf}, {changedtick}, {linedata}, {more}]) + + Neovim will send at least one of these notifications to provide you + with the original buffer contents. If the buffer is very large, neovim + will send the contents through in multiple events to avoid loading the + entire buffer's contents into memory at once. + + {buf} is an API handle for the buffer. + + {changedtick} is the value of |b:changedtick| for the buffer. If you + send an API command back to neovim you can check the value of + |b:changedtick| as part of your request to ensure that no other + changes have been made. See |live-update-race-conditions| for more + information. + + {linedata} is a list of strings containing the buffer's contents. If + this list contains 100 strings, then they represent lines 1-100 of the + buffer. Newline characters are not included in the strings, so empty + lines will be given as empty strings. If you receive another + `"LiveUpdateStart"` notification with another {linedata} list, then + these lines represent the next N lines of the buffer. I.e., a second + notification with another list of 100 strings will represent lines + 101-200 of the buffer. + + {linedata} will always have at least 1 item, but the maximum length is + determined by neovim and not guaranteed to be any particular size. + Also the number of {linedata} items may vary between notifications, so + your plugin must be prepared to receive the line data in whatever size + lists neovim decides to split it into. + + {more} is a boolean which tells you whether or not to expect more + `"LiveUpdateStart"` notifications. When {more} is false, you can + be certain that you now have the entire buffer's contents. + +2. rpcnotify({channel}, "LiveUpdate", *LiveUpdate* + [{buf}, {changedtick}, {firstline}, {numreplaced}, {linedata}]) + + Indicates that {numreplaced} lines starting at line {firstline} have + been replaced with the new line data contained in the {linedata} list. + All buffer changes (even adding single characters) will be transmitted + as whole-line changes. + + {buf} is an API handle for the buffer. + + {changedtick} is the value of |b:changedtick| for the buffer. If you + send an API command back to neovim you can check the value of + |b:changedtick| as part of your request to ensure that no other + changes have been made. + + {firstline} is the integer line number of the first line that was + replaced. Note that {firstline} is zero-indexed, so if line `1` was + replaced then {firstline} will be `0` instead of `1`. {firstline} is + guaranteed to always be less than or equal to the number of lines that + were in the buffer before the lines were replaced. + + {numreplaced} is a positive integer indicating how many lines were + replaced. It will be `0` if new lines were added to the buffer but + none were replaced. If {numreplaced} is `0` then the new lines were + added + before the zero-indexed line number in {firstline}. + + {linedata} is a list of strings containing the contents of the new + buffer lines. Newline characters are not included in the strings, so + empty lines will be given as empty strings. If {numreplaced} is `1` or + more, then {linedata} may be an empty list (indicating that lines were + deleted from the buffer). But if {numreplaced} is `0` (indicating that + lines were added to the buffer) then {linedata} is guaranteed to + contain at least 1 item. + + Note: sometimes {changedtick} will be |v:null|, which means that the + buffer text *looks* like it has changed, but actually hasn't. In this + case the lines in {linedata} contain the modified text that is shown + to the user, but doesn't reflect the actual buffer contents. Currently + this behaviour is only used for the 'inccommand' option. + +3. rpcnotify({channel}, "LiveUpdateTick", *LiveUpdateTick* + [{buf}, {changedtick}]) + + Indicates that |b:changedtick| was incremented for the buffer {buf}, + but no text was changed. This is currently only used by undo/redo. + + {buf} is an API handle for the buffer. + + {changedtick} is the new value of |b:changedtick| for that buffer. + +4. rpcnotify({channel}, "LiveUpdateEnd", [{buf}]) *LiveUpdateEnd* + + {buf} is an API handle for the buffer. + + Indicates that live updates for the nominated buffer have been + disabled, either by calling the api function `"nvim_buf_live_updates"` + with argument `false`, or because the buffer was unloaded (see + |live-updates-disabling| and |live-updates-limitations| for more + information). + + *live-updates-examples* +Example Events~ + +If live updates are activated a new empty buffer, the following +|LiveUpdateStart| event will be sent: > + + rpcnotify({channel}, "LiveUpdateStart", [{buf}, [""], v:false]) + +If the user adds 2 new lines to the start of a buffer, the following event +would be generated: > + + rpcnotify({channel}, "LiveUpdate", [{buf}, 0, 0, ["line1", "line2"]]) + +If the puts the cursor on a line containing the text `"Hello world"` and adds +a `!` character to the end using insert mode, the following event would be +generated: > + + rpcnotify({channel}, "LiveUpdate", + [{buf}, {linenr}, 1, ["Hello world!"]]) + +If the user moves their cursor to line 3 of a buffer and deletes 20 lines +using `20dd`, the following event will be generated: > + + rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 20, []]) + +If the user selects lines 3-5 of a buffer using |linewise-visual| mode and +then presses `p` to paste in a new block of 6 lines, then the following event +would be sent to the co-process: > + + rpcnotify({channel}, "LiveUpdate", + [{buf}, 2, 3, ['pasted line 1', 'pasted line 2', + 'pasted line 3', 'pasted line 4', + 'pasted line 5', 'pasted line 6']]) + +If the user uses :edit to reload a buffer then the following event would be +generated: > + + rpcnotify({channel}, "LiveUpdateEnd", [{buf}]) + + vim:tw=78:ts=8:ft=help:norl: -- cgit From 8bcc01195968b84d1a74ecb82598bdf538004404 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Fri, 26 Jan 2018 17:42:51 +0100 Subject: Make separate functions to start/stop live updates --- runtime/doc/msgpack_rpc.txt | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index ab77e08bc7..6d5ac25b27 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -258,24 +258,24 @@ specific buffer. For example, in python > import sys, neovim nvim = neovim.attach('stdio') bufnr = sys.argv[1] - nvim.buffers[bufnr].live_updates(True) + nvim.buffers[bufnr].live_updates_start(True) -After the `"nvim_buf_live_updates"` method is called, neovim will send a -series of notifications containing the entire buffer's contents and any -subsequent changes. The buffer's contents are sent via notifications because -if you were to use the other API methods to retrieve the buffer contents, the -buffer could be changed again before you turn on live updates. This can cause -a delay if your plugin activates live updates for a very large buffer, but it -is the the most efficient way to maintain a copy of the entire buffer's -contents inside your plugin. +After the `"nvim_buf_live_updates_start"` method is called with Argument `"True"`, +neovim will send a series of notifications containing the entire buffer's +contents and any subsequent changes. The buffer's contents are sent via +notifications because if you were to use the other API methods to retrieve the +buffer contents, the buffer could be changed again before you turn on live +updates. This can cause a delay if your plugin activates live updates for a +very large buffer, but it is the the most efficient way to maintain a copy of +the entire buffer's contents inside your plugin. *live-updates-disabling* Turning Off~ -You can use `"nvim_buf_live_updates"` with an argument of `False` to turn off -notifications. One final notification will be sent to indicate that live -updates are no longer active for the specified buffer. Alternatively, you can -just close the channel. +You can use `"nvim_buf_live_updates_stop"` to turn off notifications. One +final notification will be sent to indicate that live updates are no longer +active for the specified buffer. Alternatively, you can just close the +channel. *live-updates-limitations* Limitations~ -- cgit From 0476e0aef3a82879961acd515b8587fc1b941597 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Sat, 27 Jan 2018 14:49:16 +0100 Subject: Make LiveUpdate return lastline instead of numreplaced In analogy to `nvim_buf_set_lines`. --- runtime/doc/msgpack_rpc.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 6d5ac25b27..e7c80236f8 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -329,12 +329,12 @@ equivilent to the following |rpcnotify()| calls: be certain that you now have the entire buffer's contents. 2. rpcnotify({channel}, "LiveUpdate", *LiveUpdate* - [{buf}, {changedtick}, {firstline}, {numreplaced}, {linedata}]) + [{buf}, {changedtick}, {firstline}, {lastline}, {linedata}]) - Indicates that {numreplaced} lines starting at line {firstline} have - been replaced with the new line data contained in the {linedata} list. - All buffer changes (even adding single characters) will be transmitted - as whole-line changes. + Indicates that the lines between {firstline} and {lastline} (end-exclusive, + zero-indexed) have been replaced with the new line data contained in the + {linedata} list. All buffer changes (even adding single characters) will be + transmitted as whole-line changes. {buf} is an API handle for the buffer. @@ -349,11 +349,11 @@ equivilent to the following |rpcnotify()| calls: guaranteed to always be less than or equal to the number of lines that were in the buffer before the lines were replaced. - {numreplaced} is a positive integer indicating how many lines were - replaced. It will be `0` if new lines were added to the buffer but - none were replaced. If {numreplaced} is `0` then the new lines were - added - before the zero-indexed line number in {firstline}. + {lastline} is the integer line number of the first line that was not + replaced. Note that {lastline} is zero-indexed, so if line numbers 2 to 5 + were replaced, this will be `5` instead of `6`. {lastline} is guaranteed to + always be less than or equal to the number of lines that were in the buffer + before the lines were replaced. {linedata} is a list of strings containing the contents of the new buffer lines. Newline characters are not included in the strings, so -- cgit From a1d831a49c9428fcbd55d4b06bacca9cb2e9320c Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Fri, 26 Jan 2018 16:19:55 +0100 Subject: Doc --- runtime/doc/msgpack_rpc.txt | 208 ++++++++++++++++++++------------------------ 1 file changed, 94 insertions(+), 114 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index e7c80236f8..8781c4589c 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -244,79 +244,59 @@ connect to another with different type codes. ============================================================================== 6. Live Updates *live-updates* *rpc-live-updates* -A dedicated API has been created to allow co-processes to be notified in -real-time when the user changes a buffer in any way. It is difficult and -error-prone to try and do this with autocommands such as |TextChanged|. - - *live-updates-enabling* -Setting Up~ - -If your API client is a standalone co-process, it can use the -`"nvim_buf_live_updates"`API method to activate Live Update events for a -specific buffer. For example, in python > - - import sys, neovim - nvim = neovim.attach('stdio') - bufnr = sys.argv[1] - nvim.buffers[bufnr].live_updates_start(True) - -After the `"nvim_buf_live_updates_start"` method is called with Argument `"True"`, -neovim will send a series of notifications containing the entire buffer's -contents and any subsequent changes. The buffer's contents are sent via -notifications because if you were to use the other API methods to retrieve the -buffer contents, the buffer could be changed again before you turn on live -updates. This can cause a delay if your plugin activates live updates for a -very large buffer, but it is the the most efficient way to maintain a copy of -the entire buffer's contents inside your plugin. - - *live-updates-disabling* -Turning Off~ - -You can use `"nvim_buf_live_updates_stop"` to turn off notifications. One -final notification will be sent to indicate that live updates are no longer -active for the specified buffer. Alternatively, you can just close the -channel. - - *live-updates-limitations* -Limitations~ +A dedicated API has been created to allow co-processes to be notified when a +buffer is changed in any way. It is difficult and error-prone to try and do +this with autocommands such as |TextChanged|. -Note that any of the following actions will also turn off live updates because -the buffer contents are unloaded from memory: + *live-updates-api* +LiveUpdate Functions~ - - Closing all a buffer's windows (unless 'hidden' is enabled). - - Using |:edit| to reload the buffer - - reloading the buffer after it is changed from outside neovim. +nvim_buf_live_updates_start({send_buffer}) *nvim_buf_live_updates_start()* + Register a plugin to receive notifications on buffer changes. An + initial |LiveUpdateStart| notification will be sent as a + confirmation. After that, |LiveUpdate| notifications will be + sent for buffer updates, and |LiveUpdateTick| notifications for + a new changedtick without buffer change. + + Parameters:~ + {send_buffer} Bool. If `"True"`, the initial + |LiveUpdateStart| notification will also send the full + buffer's content. If `"False"`, the notification will + contain an empty list instead. - *live-updates-events* -Handling Events~ +nvim_buf_live_updates_stop() *nvim_buf_live_updates_stop()* + Unregister a plugin from buffer change notifications. A final + |LiveUpdateEnd| notification will be sent as confirmation. -The co-process will start receiving the notification events which will be -equivilent to the following |rpcnotify()| calls: + *live-updates-events* +LiveUpdate Events~ -1. rpcnotify({channel}, "LiveUpdateStart", *LiveUpdateStart* - [{buf}, {changedtick}, {linedata}, {more}]) +The co-process will start receiving the following notification events: - Neovim will send at least one of these notifications to provide you - with the original buffer contents. If the buffer is very large, neovim - will send the contents through in multiple events to avoid loading the - entire buffer's contents into memory at once. +LiveUpdateStart[{buf}, {changedtick}, {linedata}, {more}] *LiveUpdateStart* + + Neovim will send at least one of these notifications to confirm that + liveupdates are registered for this plugin, and possibly send the buffer's + contents. If the buffer is very large, neovim might send the contents through + in multiple events to avoid loading the entire buffer's contents into memory + at once. {buf} is an API handle for the buffer. {changedtick} is the value of |b:changedtick| for the buffer. If you send an API command back to neovim you can check the value of |b:changedtick| as part of your request to ensure that no other - changes have been made. See |live-update-race-conditions| for more - information. + changes have been made. {linedata} is a list of strings containing the buffer's contents. If this list contains 100 strings, then they represent lines 1-100 of the buffer. Newline characters are not included in the strings, so empty lines will be given as empty strings. If you receive another - `"LiveUpdateStart"` notification with another {linedata} list, then + |LiveUpdateStart| notification with another {linedata} list, then these lines represent the next N lines of the buffer. I.e., a second - notification with another list of 100 strings will represent lines - 101-200 of the buffer. + notification with another list of 100 strings will represent lines 101-200 + of the buffer. If you send the |nvim_buf_live_updates_start| request with + its argument set to `"False"`, this will be empty. {linedata} will always have at least 1 item, but the maximum length is determined by neovim and not guaranteed to be any particular size. @@ -324,12 +304,11 @@ equivilent to the following |rpcnotify()| calls: your plugin must be prepared to receive the line data in whatever size lists neovim decides to split it into. - {more} is a boolean which tells you whether or not to expect more - `"LiveUpdateStart"` notifications. When {more} is false, you can - be certain that you now have the entire buffer's contents. + {more} is a boolean which tells you whether or not to expect more + |LiveUpdateStart| notifications. When {more} is false, you can be certain + that you now have the entire buffer's contents. -2. rpcnotify({channel}, "LiveUpdate", *LiveUpdate* - [{buf}, {changedtick}, {firstline}, {lastline}, {linedata}]) +LiveUpdate[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *LiveUpdate* Indicates that the lines between {firstline} and {lastline} (end-exclusive, zero-indexed) have been replaced with the new line data contained in the @@ -338,95 +317,96 @@ equivilent to the following |rpcnotify()| calls: {buf} is an API handle for the buffer. - {changedtick} is the value of |b:changedtick| for the buffer. If you - send an API command back to neovim you can check the value of - |b:changedtick| as part of your request to ensure that no other - changes have been made. + {changedtick} is the value of |b:changedtick| for the buffer. If you send an + API command back to neovim you can check the value of |b:changedtick| as + part of your request to ensure that no other changes have been made. - {firstline} is the integer line number of the first line that was - replaced. Note that {firstline} is zero-indexed, so if line `1` was - replaced then {firstline} will be `0` instead of `1`. {firstline} is - guaranteed to always be less than or equal to the number of lines that - were in the buffer before the lines were replaced. + {firstline} is the integer line number of the first line that was replaced. + Note that {firstline} is zero-indexed, so if line `1` was replaced then + {firstline} will be `0` instead of `1`. {firstline} is guaranteed to always + be less than or equal to the number of lines that were in the buffer before + the lines were replaced. {lastline} is the integer line number of the first line that was not - replaced. Note that {lastline} is zero-indexed, so if line numbers 2 to 5 - were replaced, this will be `5` instead of `6`. {lastline} is guaranteed to - always be less than or equal to the number of lines that were in the buffer - before the lines were replaced. - - {linedata} is a list of strings containing the contents of the new - buffer lines. Newline characters are not included in the strings, so - empty lines will be given as empty strings. If {numreplaced} is `1` or - more, then {linedata} may be an empty list (indicating that lines were - deleted from the buffer). But if {numreplaced} is `0` (indicating that - lines were added to the buffer) then {linedata} is guaranteed to - contain at least 1 item. - - Note: sometimes {changedtick} will be |v:null|, which means that the - buffer text *looks* like it has changed, but actually hasn't. In this - case the lines in {linedata} contain the modified text that is shown - to the user, but doesn't reflect the actual buffer contents. Currently - this behaviour is only used for the 'inccommand' option. - -3. rpcnotify({channel}, "LiveUpdateTick", *LiveUpdateTick* - [{buf}, {changedtick}]) - - Indicates that |b:changedtick| was incremented for the buffer {buf}, - but no text was changed. This is currently only used by undo/redo. + replaced (i.e. the range {firstline}, {lastline} is end-exclusive). Note + that {lastline} is zero-indexed, so if line numbers 2 to 5 were replaced, + this will be `5` instead of `6`. {lastline} is guaranteed to always be less + than or equal to the number of lines that were in the buffer before the + lines were replaced. - {buf} is an API handle for the buffer. + {linedata} is a list of strings containing the contents of the new buffer + lines. Newline characters are not included in the strings, so empty lines + will be given as empty strings. - {changedtick} is the new value of |b:changedtick| for that buffer. + Note: sometimes {changedtick} will be |v:null|, which means that the buffer + text *looks* like it has changed, but actually hasn't. In this case the + lines in {linedata} contain the modified text that is shown to the user, but + doesn't reflect the actual buffer contents. Currently this behaviour is only + used for the 'inccommand' option. -4. rpcnotify({channel}, "LiveUpdateEnd", [{buf}]) *LiveUpdateEnd* +LiveUpdateTick[{buf}, {changedtick}] *LiveUpdateTick* - {buf} is an API handle for the buffer. + Indicates that |b:changedtick| was incremented for the buffer {buf}, but no + text was changed. This is currently only used by undo/redo. + + {buf} is an API handle for the buffer. - Indicates that live updates for the nominated buffer have been - disabled, either by calling the api function `"nvim_buf_live_updates"` - with argument `false`, or because the buffer was unloaded (see - |live-updates-disabling| and |live-updates-limitations| for more - information). + {changedtick} is the new value of |b:changedtick| for that buffer. - *live-updates-examples* +LiveUpdateEnd[{buf}] *LiveUpdateEnd* + + {buf} is an API handle for the buffer. + + Indicates that live updates for the nominated buffer have been disabled, + either by calling |nvim_buf_live_updates_stop| or because the buffer was + unloaded (see |live-updates-limitations| for more information). + + *live-updates-limitations* +Limitations~ + +Note that any of the following actions will also turn off live updates because +the buffer contents are unloaded from memory: + + - Closing all a buffer's windows (unless 'hidden' is enabled). + - Using |:edit| to reload the buffer + - reloading the buffer after it is changed from outside neovim. + + *live-updates-examples* Example Events~ If live updates are activated a new empty buffer, the following |LiveUpdateStart| event will be sent: > - rpcnotify({channel}, "LiveUpdateStart", [{buf}, [""], v:false]) + rpcnotify({channel}, "LiveUpdateStart", [{buf}, [""], v:false]) If the user adds 2 new lines to the start of a buffer, the following event would be generated: > - rpcnotify({channel}, "LiveUpdate", [{buf}, 0, 0, ["line1", "line2"]]) + rpcnotify({channel}, "LiveUpdate", [{buf}, 0, 0, ["line1", "line2"]]) If the puts the cursor on a line containing the text `"Hello world"` and adds a `!` character to the end using insert mode, the following event would be generated: > - rpcnotify({channel}, "LiveUpdate", - [{buf}, {linenr}, 1, ["Hello world!"]]) + rpcnotify({channel}, "LiveUpdate", [{buf}, {linenr}, {linenr} + 1, ["Hello + world!"]]) If the user moves their cursor to line 3 of a buffer and deletes 20 lines using `20dd`, the following event will be generated: > - rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 20, []]) + rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 20, []]) If the user selects lines 3-5 of a buffer using |linewise-visual| mode and then presses `p` to paste in a new block of 6 lines, then the following event would be sent to the co-process: > - rpcnotify({channel}, "LiveUpdate", - [{buf}, 2, 3, ['pasted line 1', 'pasted line 2', - 'pasted line 3', 'pasted line 4', - 'pasted line 5', 'pasted line 6']]) + rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 5, ['pasted line 1', 'pasted + line 2', 'pasted line 3', 'pasted line 4', 'pasted line 5', 'pasted line + 6']]) If the user uses :edit to reload a buffer then the following event would be generated: > - rpcnotify({channel}, "LiveUpdateEnd", [{buf}]) - + rpcnotify({channel}, "LiveUpdateEnd", [{buf}]) vim:tw=78:ts=8:ft=help:norl: -- cgit From 6bdcbef2f5acfd9815599c751bd8dcbe3204281f Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Sun, 11 Feb 2018 22:51:29 +0100 Subject: The grand renaming --- runtime/doc/msgpack_rpc.txt | 124 ++++++++++++++++++++++---------------------- 1 file changed, 62 insertions(+), 62 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 8781c4589c..bf7c63710f 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -242,44 +242,44 @@ the type codes, because a client may be built against one Nvim version but connect to another with different type codes. ============================================================================== -6. Live Updates *live-updates* *rpc-live-updates* +6. Buffer Updates *buffer-updates* *rpc-buffer-updates* A dedicated API has been created to allow co-processes to be notified when a buffer is changed in any way. It is difficult and error-prone to try and do this with autocommands such as |TextChanged|. - *live-updates-api* -LiveUpdate Functions~ + *buffer-updates-api* +BufferUpdates Functions~ -nvim_buf_live_updates_start({send_buffer}) *nvim_buf_live_updates_start()* +nvim_buf_attach({send_buffer}) *nvim_buf_attach()* Register a plugin to receive notifications on buffer changes. An - initial |LiveUpdateStart| notification will be sent as a - confirmation. After that, |LiveUpdate| notifications will be - sent for buffer updates, and |LiveUpdateTick| notifications for - a new changedtick without buffer change. + initial |nvim_buf_updates_start| notification will be sent as a + confirmation. After that, |nvim_buf_update| notifications will be + sent for buffer updates, and |nvim_buf_update_tick| notifications + for a new changedtick without buffer change. Parameters:~ {send_buffer} Bool. If `"True"`, the initial - |LiveUpdateStart| notification will also send the full - buffer's content. If `"False"`, the notification will - contain an empty list instead. + |nvim_buf_updates_start| notification will also send the full + buffer's content. If `"False"`, the notification will contain + an empty list instead. -nvim_buf_live_updates_stop() *nvim_buf_live_updates_stop()* +nvim_buf_detach() *nvim_buf_detach()* Unregister a plugin from buffer change notifications. A final - |LiveUpdateEnd| notification will be sent as confirmation. + |nvim_buf_updates_end| notification will be sent as confirmation. - *live-updates-events* -LiveUpdate Events~ + *buffer-updates-events* +BufferUpdates Events~ The co-process will start receiving the following notification events: -LiveUpdateStart[{buf}, {changedtick}, {linedata}, {more}] *LiveUpdateStart* +nvim_buf_updates_start[{buf}, {changedtick}, {linedata}, {more}] *nvim_buf_updates_start* Neovim will send at least one of these notifications to confirm that - liveupdates are registered for this plugin, and possibly send the buffer's + buffer updates are registered for this plugin, and possibly send the buffer's contents. If the buffer is very large, neovim might send the contents through - in multiple events to avoid loading the entire buffer's contents into memory - at once. + in multiple events to avoid loading the entire buffer's contents into + memory at once. {buf} is an API handle for the buffer. @@ -288,27 +288,27 @@ LiveUpdateStart[{buf}, {changedtick}, {linedata}, {more}] *LiveUpdateStart* |b:changedtick| as part of your request to ensure that no other changes have been made. - {linedata} is a list of strings containing the buffer's contents. If - this list contains 100 strings, then they represent lines 1-100 of the - buffer. Newline characters are not included in the strings, so empty - lines will be given as empty strings. If you receive another - |LiveUpdateStart| notification with another {linedata} list, then - these lines represent the next N lines of the buffer. I.e., a second - notification with another list of 100 strings will represent lines 101-200 - of the buffer. If you send the |nvim_buf_live_updates_start| request with - its argument set to `"False"`, this will be empty. - - {linedata} will always have at least 1 item, but the maximum length is - determined by neovim and not guaranteed to be any particular size. - Also the number of {linedata} items may vary between notifications, so - your plugin must be prepared to receive the line data in whatever size - lists neovim decides to split it into. + {linedata} is a list of strings containing the buffer's contents. If this + list contains 100 strings, then they represent lines 1-100 of the buffer. + Newline characters are not included in the strings, so empty lines will be + given as empty strings. If you receive another |nvim_buf_updates_start| + notification with another {linedata} list, then these lines represent the + next N lines of the buffer. I.e., a second notification with another list of + 100 strings will represent lines 101-200 of the buffer. If you send the + |nvim_buf_updates_start| request with its argument set to `"False"`, this + will be empty. + + {linedata} will always have at least 1 item, but the maximum length is + determined by neovim and not guaranteed to be any particular size. Also the + number of {linedata} items may vary between notifications, so your plugin + must be prepared to receive the line data in whatever size lists neovim + decides to split it into. {more} is a boolean which tells you whether or not to expect more - |LiveUpdateStart| notifications. When {more} is false, you can be certain + |nvim_buf_updates_start| notifications. When {more} is false, you can be certain that you now have the entire buffer's contents. -LiveUpdate[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *LiveUpdate* +nvim_buf_update[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *nvim_buf_update* Indicates that the lines between {firstline} and {lastline} (end-exclusive, zero-indexed) have been replaced with the new line data contained in the @@ -327,24 +327,24 @@ LiveUpdate[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *LiveUpdat be less than or equal to the number of lines that were in the buffer before the lines were replaced. - {lastline} is the integer line number of the first line that was not - replaced (i.e. the range {firstline}, {lastline} is end-exclusive). Note - that {lastline} is zero-indexed, so if line numbers 2 to 5 were replaced, - this will be `5` instead of `6`. {lastline} is guaranteed to always be less - than or equal to the number of lines that were in the buffer before the - lines were replaced. + {lastline} is the integer line number of the first line that was not replaced + (i.e. the range {firstline}, {lastline} is end-exclusive). Note that + {lastline} is zero-indexed, so if line numbers 2 to 5 were replaced, this + will be `5` instead of `6`. {lastline} is guaranteed to always be less than + or equal to the number of lines that were in the buffer before the lines were + replaced. {linedata} is a list of strings containing the contents of the new buffer lines. Newline characters are not included in the strings, so empty lines will be given as empty strings. Note: sometimes {changedtick} will be |v:null|, which means that the buffer - text *looks* like it has changed, but actually hasn't. In this case the - lines in {linedata} contain the modified text that is shown to the user, but - doesn't reflect the actual buffer contents. Currently this behaviour is only - used for the 'inccommand' option. + text *looks* like it has changed, but actually hasn't. In this case the lines + in {linedata} contain the modified text that is shown to the user, but + doesn't reflect the actual buffer contents. Currently this behaviour is + only used for the 'inccommand' option. -LiveUpdateTick[{buf}, {changedtick}] *LiveUpdateTick* +nvim_buf_update_tick[{buf}, {changedtick}] *nvim_buf_update_tick* Indicates that |b:changedtick| was incremented for the buffer {buf}, but no text was changed. This is currently only used by undo/redo. @@ -353,60 +353,60 @@ LiveUpdateTick[{buf}, {changedtick}] *LiveUpdateTick* {changedtick} is the new value of |b:changedtick| for that buffer. -LiveUpdateEnd[{buf}] *LiveUpdateEnd* +nvim_buf_updates_end[{buf}] *nvim_buf_updates_end* {buf} is an API handle for the buffer. - Indicates that live updates for the nominated buffer have been disabled, - either by calling |nvim_buf_live_updates_stop| or because the buffer was - unloaded (see |live-updates-limitations| for more information). + Indicates that buffer updates for the nominated buffer have been disabled, + either by calling |nvim_buf_detach| or because the buffer was unloaded + (see |buffer-updates-limitations| for more information). - *live-updates-limitations* + *buffer-updates-limitations* Limitations~ -Note that any of the following actions will also turn off live updates because +Note that any of the following actions will also turn off buffer updates because the buffer contents are unloaded from memory: - Closing all a buffer's windows (unless 'hidden' is enabled). - Using |:edit| to reload the buffer - reloading the buffer after it is changed from outside neovim. - *live-updates-examples* + *buffer-updates-examples* Example Events~ -If live updates are activated a new empty buffer, the following -|LiveUpdateStart| event will be sent: > +If buffer updates are activated a new empty buffer, the following +|nvim_buf_updates_start| event will be sent: > - rpcnotify({channel}, "LiveUpdateStart", [{buf}, [""], v:false]) + rpcnotify({channel}, "nvim_buf_updates_start", [{buf}, [""], v:false]) If the user adds 2 new lines to the start of a buffer, the following event would be generated: > - rpcnotify({channel}, "LiveUpdate", [{buf}, 0, 0, ["line1", "line2"]]) + rpcnotify({channel}, "nvim_buf_update", [{buf}, 0, 0, ["line1", "line2"]]) If the puts the cursor on a line containing the text `"Hello world"` and adds a `!` character to the end using insert mode, the following event would be generated: > - rpcnotify({channel}, "LiveUpdate", [{buf}, {linenr}, {linenr} + 1, ["Hello + rpcnotify({channel}, "nvim_buf_update", [{buf}, {linenr}, {linenr} + 1, ["Hello world!"]]) If the user moves their cursor to line 3 of a buffer and deletes 20 lines using `20dd`, the following event will be generated: > - rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 20, []]) + rpcnotify({channel}, "nvim_buf_update", [{buf}, 2, 20, []]) If the user selects lines 3-5 of a buffer using |linewise-visual| mode and then presses `p` to paste in a new block of 6 lines, then the following event would be sent to the co-process: > - rpcnotify({channel}, "LiveUpdate", [{buf}, 2, 5, ['pasted line 1', 'pasted + rpcnotify({channel}, "nvim_buf_update", [{buf}, 2, 5, ['pasted line 1', 'pasted line 2', 'pasted line 3', 'pasted line 4', 'pasted line 5', 'pasted line 6']]) If the user uses :edit to reload a buffer then the following event would be generated: > - rpcnotify({channel}, "LiveUpdateEnd", [{buf}]) + rpcnotify({channel}, "nvim_buf_updates_end", [{buf}]) vim:tw=78:ts=8:ft=help:norl: -- cgit From de5d1e863c71c8da87422bdb94dc91749d4a8b61 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Mon, 12 Feb 2018 22:49:35 +0100 Subject: Try fixing that test on travis --- runtime/doc/msgpack_rpc.txt | 42 +++++++++++------------------------------- 1 file changed, 11 insertions(+), 31 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index bf7c63710f..0b0e774d33 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -242,32 +242,12 @@ the type codes, because a client may be built against one Nvim version but connect to another with different type codes. ============================================================================== -6. Buffer Updates *buffer-updates* *rpc-buffer-updates* +6. Buffer Updates *buffer-updates* *rpc-buffer-updates* A dedicated API has been created to allow co-processes to be notified when a buffer is changed in any way. It is difficult and error-prone to try and do this with autocommands such as |TextChanged|. - *buffer-updates-api* -BufferUpdates Functions~ - -nvim_buf_attach({send_buffer}) *nvim_buf_attach()* - Register a plugin to receive notifications on buffer changes. An - initial |nvim_buf_updates_start| notification will be sent as a - confirmation. After that, |nvim_buf_update| notifications will be - sent for buffer updates, and |nvim_buf_update_tick| notifications - for a new changedtick without buffer change. - - Parameters:~ - {send_buffer} Bool. If `"True"`, the initial - |nvim_buf_updates_start| notification will also send the full - buffer's content. If `"False"`, the notification will contain - an empty list instead. - -nvim_buf_detach() *nvim_buf_detach()* - Unregister a plugin from buffer change notifications. A final - |nvim_buf_updates_end| notification will be sent as confirmation. - *buffer-updates-events* BufferUpdates Events~ @@ -372,41 +352,41 @@ the buffer contents are unloaded from memory: - reloading the buffer after it is changed from outside neovim. *buffer-updates-examples* -Example Events~ +Examples~ -If buffer updates are activated a new empty buffer, the following +If buffer updates are activated a new empty buffer (and sending the buffer's +content on the initial notification has been requested), the following |nvim_buf_updates_start| event will be sent: > - rpcnotify({channel}, "nvim_buf_updates_start", [{buf}, [""], v:false]) + nvim_buf_updates_start[{buf}, [""], v:false] If the user adds 2 new lines to the start of a buffer, the following event would be generated: > - rpcnotify({channel}, "nvim_buf_update", [{buf}, 0, 0, ["line1", "line2"]]) + nvim_buf_update[{buf}, 0, 0, ["line1", "line2"]] If the puts the cursor on a line containing the text `"Hello world"` and adds a `!` character to the end using insert mode, the following event would be generated: > - rpcnotify({channel}, "nvim_buf_update", [{buf}, {linenr}, {linenr} + 1, ["Hello - world!"]]) + nvim_buf_update[{buf}, {linenr}, {linenr} + 1, ["Hello world!"]] If the user moves their cursor to line 3 of a buffer and deletes 20 lines using `20dd`, the following event will be generated: > - rpcnotify({channel}, "nvim_buf_update", [{buf}, 2, 20, []]) + nvim_buf_update[{buf}, 2, 20, []] If the user selects lines 3-5 of a buffer using |linewise-visual| mode and then presses `p` to paste in a new block of 6 lines, then the following event would be sent to the co-process: > - rpcnotify({channel}, "nvim_buf_update", [{buf}, 2, 5, ['pasted line 1', 'pasted + nvim_buf_update[{buf}, 2, 5, ['pasted line 1', 'pasted line 2', 'pasted line 3', 'pasted line 4', 'pasted line 5', 'pasted line - 6']]) + 6']] If the user uses :edit to reload a buffer then the following event would be generated: > - rpcnotify({channel}, "nvim_buf_updates_end", [{buf}]) + nvim_buf_updates_end[{buf}] vim:tw=78:ts=8:ft=help:norl: -- cgit From e7451f8a91e0a9452fc3c3627ac60dc80288252c Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Tue, 24 Apr 2018 20:38:00 +0200 Subject: Some renamings and doc changes --- runtime/doc/msgpack_rpc.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 0b0e774d33..9ebebb8d61 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -255,16 +255,16 @@ The co-process will start receiving the following notification events: nvim_buf_updates_start[{buf}, {changedtick}, {linedata}, {more}] *nvim_buf_updates_start* - Neovim will send at least one of these notifications to confirm that - buffer updates are registered for this plugin, and possibly send the buffer's - contents. If the buffer is very large, neovim might send the contents through - in multiple events to avoid loading the entire buffer's contents into - memory at once. + Nvim will send at least one of these notifications to confirm that buffer + updates are registered for this plugin, and possibly send the buffer's + contents. If the buffer is very large, nvim might send the contents + through in multiple events to avoid loading the entire buffer's contents + into memory at once. {buf} is an API handle for the buffer. {changedtick} is the value of |b:changedtick| for the buffer. If you - send an API command back to neovim you can check the value of + send an API command back to nvim you can check the value of |b:changedtick| as part of your request to ensure that no other changes have been made. @@ -279,9 +279,9 @@ nvim_buf_updates_start[{buf}, {changedtick}, {linedata}, {more}] *nvim_buf_upda will be empty. {linedata} will always have at least 1 item, but the maximum length is - determined by neovim and not guaranteed to be any particular size. Also the + determined by nvim and not guaranteed to be any particular size. Also the number of {linedata} items may vary between notifications, so your plugin - must be prepared to receive the line data in whatever size lists neovim + must be prepared to receive the line data in whatever size lists nvim decides to split it into. {more} is a boolean which tells you whether or not to expect more @@ -298,7 +298,7 @@ nvim_buf_update[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *nvim {buf} is an API handle for the buffer. {changedtick} is the value of |b:changedtick| for the buffer. If you send an - API command back to neovim you can check the value of |b:changedtick| as + API command back to nvim you can check the value of |b:changedtick| as part of your request to ensure that no other changes have been made. {firstline} is the integer line number of the first line that was replaced. @@ -324,7 +324,7 @@ nvim_buf_update[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *nvim doesn't reflect the actual buffer contents. Currently this behaviour is only used for the 'inccommand' option. -nvim_buf_update_tick[{buf}, {changedtick}] *nvim_buf_update_tick* +nvim_buf_changedtick[{buf}, {changedtick}] *nvim_buf_changedtick* Indicates that |b:changedtick| was incremented for the buffer {buf}, but no text was changed. This is currently only used by undo/redo. @@ -349,7 +349,7 @@ the buffer contents are unloaded from memory: - Closing all a buffer's windows (unless 'hidden' is enabled). - Using |:edit| to reload the buffer - - reloading the buffer after it is changed from outside neovim. + - reloading the buffer after it is changed from outside nvim. *buffer-updates-examples* Examples~ -- cgit From ad151847f179e51d70cbde9440e765c2a451a7f6 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Thu, 10 May 2018 15:47:00 +0200 Subject: Unify updates_start and updates to lines_event Also rename changedtick -> changedtick_event --- runtime/doc/msgpack_rpc.txt | 94 ++++++++++++++++----------------------------- 1 file changed, 33 insertions(+), 61 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 9ebebb8d61..571a08930c 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -242,7 +242,7 @@ the type codes, because a client may be built against one Nvim version but connect to another with different type codes. ============================================================================== -6. Buffer Updates *buffer-updates* *rpc-buffer-updates* +6. Buffer Updates *buffer-updates* *rpc-buffer-updates* A dedicated API has been created to allow co-processes to be notified when a buffer is changed in any way. It is difficult and error-prone to try and do @@ -253,94 +253,66 @@ BufferUpdates Events~ The co-process will start receiving the following notification events: -nvim_buf_updates_start[{buf}, {changedtick}, {linedata}, {more}] *nvim_buf_updates_start* - - Nvim will send at least one of these notifications to confirm that buffer - updates are registered for this plugin, and possibly send the buffer's - contents. If the buffer is very large, nvim might send the contents - through in multiple events to avoid loading the entire buffer's contents - into memory at once. - - {buf} is an API handle for the buffer. - - {changedtick} is the value of |b:changedtick| for the buffer. If you - send an API command back to nvim you can check the value of - |b:changedtick| as part of your request to ensure that no other - changes have been made. - - {linedata} is a list of strings containing the buffer's contents. If this - list contains 100 strings, then they represent lines 1-100 of the buffer. - Newline characters are not included in the strings, so empty lines will be - given as empty strings. If you receive another |nvim_buf_updates_start| - notification with another {linedata} list, then these lines represent the - next N lines of the buffer. I.e., a second notification with another list of - 100 strings will represent lines 101-200 of the buffer. If you send the - |nvim_buf_updates_start| request with its argument set to `"False"`, this - will be empty. - - {linedata} will always have at least 1 item, but the maximum length is - determined by nvim and not guaranteed to be any particular size. Also the - number of {linedata} items may vary between notifications, so your plugin - must be prepared to receive the line data in whatever size lists nvim - decides to split it into. - - {more} is a boolean which tells you whether or not to expect more - |nvim_buf_updates_start| notifications. When {more} is false, you can be certain - that you now have the entire buffer's contents. - -nvim_buf_update[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}] *nvim_buf_update* + *nvim_buf_lines_event* +nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, {more}] Indicates that the lines between {firstline} and {lastline} (end-exclusive, zero-indexed) have been replaced with the new line data contained in the {linedata} list. All buffer changes (even adding single characters) will be transmitted as whole-line changes. - {buf} is an API handle for the buffer. + {buf} is an API handle for the buffer. + + {changedtick} is the value of |b:changedtick| for the buffer. If you send an + API command back to nvim you can check the value of |b:changedtick| as + part of your request to ensure that no other changes have been made. - {changedtick} is the value of |b:changedtick| for the buffer. If you send an - API command back to nvim you can check the value of |b:changedtick| as - part of your request to ensure that no other changes have been made. + {firstline} is the integer line number of the first line that was replaced. + Note that {firstline} is zero-indexed, so if line `1` was replaced then + {firstline} will be `0` instead of `1`. {firstline} is guaranteed to always + be less than or equal to the number of lines that were in the buffer before + the lines were replaced. - {firstline} is the integer line number of the first line that was replaced. - Note that {firstline} is zero-indexed, so if line `1` was replaced then - {firstline} will be `0` instead of `1`. {firstline} is guaranteed to always - be less than or equal to the number of lines that were in the buffer before - the lines were replaced. + {lastline} is the integer line number of the first line that was not replaced + (i.e. the range {firstline}, {lastline} is end-exclusive). Note that + {lastline} is zero-indexed, so if line numbers 2 to 5 were replaced, this + will be `5` instead of `6`. {lastline} is guaranteed to always be less than + or equal to the number of lines that were in the buffer before the lines were + replaced. {lastline} will be `-1` if the event is part of the initial + sending of the buffer. - {lastline} is the integer line number of the first line that was not replaced - (i.e. the range {firstline}, {lastline} is end-exclusive). Note that - {lastline} is zero-indexed, so if line numbers 2 to 5 were replaced, this - will be `5` instead of `6`. {lastline} is guaranteed to always be less than - or equal to the number of lines that were in the buffer before the lines were - replaced. + {linedata} is a list of strings containing the contents of the new buffer + lines. Newline characters are not included in the strings, so empty lines + will be given as empty strings. - {linedata} is a list of strings containing the contents of the new buffer - lines. Newline characters are not included in the strings, so empty lines - will be given as empty strings. + {more} is a boolean which tells you whether or not to expect more + |nvim_buf_updates| notifications for a single buffer change (i.e. Nvim has + chunked up one event into several). Not yet used. Note: sometimes {changedtick} will be |v:null|, which means that the buffer text *looks* like it has changed, but actually hasn't. In this case the lines in {linedata} contain the modified text that is shown to the user, but doesn't reflect the actual buffer contents. Currently this behaviour is - only used for the 'inccommand' option. + only used for the |inccommand| option. -nvim_buf_changedtick[{buf}, {changedtick}] *nvim_buf_changedtick* +nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick* Indicates that |b:changedtick| was incremented for the buffer {buf}, but no text was changed. This is currently only used by undo/redo. - {buf} is an API handle for the buffer. + {buf} is an API handle for the buffer. - {changedtick} is the new value of |b:changedtick| for that buffer. + {changedtick} is the new value of |b:changedtick| for that buffer. nvim_buf_updates_end[{buf}] *nvim_buf_updates_end* - {buf} is an API handle for the buffer. - Indicates that buffer updates for the nominated buffer have been disabled, either by calling |nvim_buf_detach| or because the buffer was unloaded (see |buffer-updates-limitations| for more information). + {buf} is an API handle for the buffer. + + *buffer-updates-limitations* Limitations~ -- cgit From 65e7f6f0b97b02e323488e06bf0f5df93bbcbf93 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Fri, 18 May 2018 10:09:11 +0200 Subject: Rename some more, fixe borked renaming --- runtime/doc/msgpack_rpc.txt | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) (limited to 'runtime') diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 571a08930c..b99b876722 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -286,7 +286,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, will be given as empty strings. {more} is a boolean which tells you whether or not to expect more - |nvim_buf_updates| notifications for a single buffer change (i.e. Nvim has + |nvim_buf_lines_event| notifications for a single buffer change (i.e. Nvim has chunked up one event into several). Not yet used. Note: sometimes {changedtick} will be |v:null|, which means that the buffer @@ -295,7 +295,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, doesn't reflect the actual buffer contents. Currently this behaviour is only used for the |inccommand| option. -nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick* +nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick_event* Indicates that |b:changedtick| was incremented for the buffer {buf}, but no text was changed. This is currently only used by undo/redo. @@ -304,7 +304,7 @@ nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick* {changedtick} is the new value of |b:changedtick| for that buffer. -nvim_buf_updates_end[{buf}] *nvim_buf_updates_end* +nvim_buf_detach_event[{buf}] *nvim_buf_detach_event* Indicates that buffer updates for the nominated buffer have been disabled, either by calling |nvim_buf_detach| or because the buffer was unloaded @@ -326,39 +326,45 @@ the buffer contents are unloaded from memory: *buffer-updates-examples* Examples~ -If buffer updates are activated a new empty buffer (and sending the buffer's +If buffer updates are activated on an empty buffer (and sending the buffer's content on the initial notification has been requested), the following -|nvim_buf_updates_start| event will be sent: > +|nvim_buf_lines_event| event will be sent: > - nvim_buf_updates_start[{buf}, [""], v:false] + nvim_buf_lines_event[{buf}, {changedtick}, 0, 0, [""], v:false] If the user adds 2 new lines to the start of a buffer, the following event would be generated: > - nvim_buf_update[{buf}, 0, 0, ["line1", "line2"]] + nvim_buf_lines_event[{buf}, {changedtick}, 0, 0, ["line1", "line2"], v:false] If the puts the cursor on a line containing the text `"Hello world"` and adds a `!` character to the end using insert mode, the following event would be generated: > - nvim_buf_update[{buf}, {linenr}, {linenr} + 1, ["Hello world!"]] + nvim_buf_lines_event[ + {buf}, {changedtick}, {linenr}, {linenr} + 1, + ["Hello world!"], v:false + ] If the user moves their cursor to line 3 of a buffer and deletes 20 lines using `20dd`, the following event will be generated: > - nvim_buf_update[{buf}, 2, 20, []] + nvim_buf_lines_event[{buf}, {changedtick}, 2, 22, [], v:false] If the user selects lines 3-5 of a buffer using |linewise-visual| mode and then presses `p` to paste in a new block of 6 lines, then the following event would be sent to the co-process: > - nvim_buf_update[{buf}, 2, 5, ['pasted line 1', 'pasted - line 2', 'pasted line 3', 'pasted line 4', 'pasted line 5', 'pasted line - 6']] + nvim_buf_lines_event[ + {buf}, {changedtick}, 2, 5, + ['pasted line 1', 'pasted line 2', 'pasted line 3', 'pasted line 4', + 'pasted line 5', 'pasted line 6'], + v:false + ] If the user uses :edit to reload a buffer then the following event would be generated: > - nvim_buf_updates_end[{buf}] + nvim_buf_detach_event[{buf}] vim:tw=78:ts=8:ft=help:norl: -- cgit