Merge #7917 'API: buffer updates'

18 files changed, 1337 insertions, 74 deletions

diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 01d4e10cea..b99b876722 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -241,4 +241,130 @@ 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. 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-events*
+BufferUpdates Events~
+
+The co-process will start receiving the following notification events:
+
+                                                                   *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.
+
+    {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.
+
+    {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.
+
+    {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_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
+  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.
+
+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.
+
+    {buf} is an API handle for the buffer.
+
+    {changedtick} is the new value of |b:changedtick| for that buffer.
+
+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
+  (see |buffer-updates-limitations| for more information).
+
+    {buf} is an API handle for the buffer.
+
+
+                                                      *buffer-updates-limitations*
+Limitations~
+
+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 nvim.
+
+                                                       *buffer-updates-examples*
+Examples~
+
+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_lines_event| event will be sent: >
+
+  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_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_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_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_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_detach_event[{buf}]
+
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index fa4ad27e60..215859a499 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -25,6 +25,7 @@
 #include "nvim/window.h"
 #include "nvim/undo.h"
 #include "nvim/ex_docmd.h"
+#include "nvim/buffer_updates.h"
 
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "api/buffer.c.generated.h"
@@ -75,6 +76,59 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
   return rv;
 }
 
+/// Activate updates from this buffer to the current channel.
+///
+/// @param buffer The buffer handle
+/// @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`
+/// @param  opts  Optional parameters. Currently not used.
+/// @param[out] err Details of an error that may have occurred
+/// @return False when updates couldn't be enabled because the buffer isn't
+///         loaded or `opts` contained an invalid key; otherwise True.
+Boolean nvim_buf_attach(uint64_t channel_id,
+                        Buffer buffer,
+                        Boolean send_buffer,
+                        Dictionary opts,
+                        Error *err)
+  FUNC_API_SINCE(4) FUNC_API_REMOTE_ONLY
+{
+  if (opts.size > 0) {
+      api_set_error(err, kErrorTypeValidation, "dict isn't empty");
+      return false;
+  }
+
+  buf_T *buf = find_buffer_by_handle(buffer, err);
+
+  if (!buf) {
+    return false;
+  }
+
+  return buf_updates_register(buf, channel_id, send_buffer);
+}
+//
+/// Deactivate updates from this buffer to the current channel.
+///
+/// @param buffer The buffer handle
+/// @param[out] err Details of an error that may have occurred
+/// @return False when updates couldn't be disabled because the buffer
+///         isn't loaded; otherwise True.
+Boolean nvim_buf_detach(uint64_t channel_id,
+                        Buffer buffer,
+                        Error *err)
+  FUNC_API_SINCE(4) FUNC_API_REMOTE_ONLY
+{
+  buf_T *buf = find_buffer_by_handle(buffer, err);
+
+  if (!buf) {
+    return false;
+  }
+
+  buf_updates_unregister(buf, channel_id);
+  return true;
+}
+
 /// Sets a buffer line
 ///
 /// @deprecated use nvim_buf_set_lines instead.
@@ -407,7 +461,7 @@ void nvim_buf_set_lines(uint64_t channel_id,
                 false);
   }
 
-  changed_lines((linenr_T)start, 0, (linenr_T)end, (long)extra);
+  changed_lines((linenr_T)start, 0, (linenr_T)end, (long)extra, true);
 
   if (save_curbuf.br_buf == NULL) {
     fix_cursor((linenr_T)start, (linenr_T)end, (linenr_T)extra);
diff --git a/src/nvim/buffer.c b/src/nvim/buffer.c
index ba63822837..838f267dcd 100644
--- a/src/nvim/buffer.c
+++ b/src/nvim/buffer.c
@@ -73,6 +73,7 @@
 #include "nvim/os/os.h"
 #include "nvim/os/time.h"
 #include "nvim/os/input.h"
+#include "nvim/buffer_updates.h"
 
 typedef enum {
   kBLSUnchanged = 0,
@@ -574,6 +575,9 @@ void close_buffer(win_T *win, buf_T *buf, int action, int abort_if_last)
   /* Change directories when the 'acd' option is set. */
   do_autochdir();
 
+  // disable buffer updates for the current buffer
+  buf_updates_unregister_all(buf);
+
   /*
    * Remove the buffer from the list.
    */
@@ -784,6 +788,8 @@ free_buffer_stuff (
   map_clear_int(buf, MAP_ALL_MODES, true, true);     // clear local abbrevs
   xfree(buf->b_start_fenc);
   buf->b_start_fenc = NULL;
+
+  buf_updates_unregister_all(buf);
 }
 
 /*
@@ -1732,9 +1738,11 @@ buf_T * buflist_new(char_u *ffname, char_u *sfname, linenr_T lnum, int flags)
   if (flags & BLN_DUMMY)
     buf->b_flags |= BF_DUMMY;
   buf_clear_file(buf);
-  clrallmarks(buf);                     /* clear marks */
-  fmarks_check_names(buf);              /* check file marks for this file */
-  buf->b_p_bl = (flags & BLN_LISTED) ? TRUE : FALSE;    /* init 'buflisted' */
+  clrallmarks(buf);                     // clear marks
+  fmarks_check_names(buf);              // check file marks for this file
+  buf->b_p_bl = (flags & BLN_LISTED) ? true : false;    // init 'buflisted'
+  kv_destroy(buf->update_channels);
+  kv_init(buf->update_channels);
   if (!(flags & BLN_DUMMY)) {
     // Tricky: these autocommands may change the buffer list.  They could also
     // split the window with re-using the one empty buffer. This may result in
diff --git a/src/nvim/buffer_defs.h b/src/nvim/buffer_defs.h
index 807baf02c1..50d8c822c1 100644
--- a/src/nvim/buffer_defs.h
+++ b/src/nvim/buffer_defs.h
@@ -38,6 +38,8 @@ typedef struct {
 #include "nvim/api/private/defs.h"
 // for Map(K, V)
 #include "nvim/map.h"
+// for kvec
+#include "nvim/lib/kvec.h"
 
 #define MODIFIABLE(buf) (buf->b_p_ma)
 
@@ -771,6 +773,10 @@ struct file_buffer {
   BufhlInfo b_bufhl_info;       // buffer stored highlights
 
   kvec_t(BufhlLine *) b_bufhl_move_space;  // temporary space for highlights
+
+  // array of channelids which have asked to receive updates for this
+  // buffer.
+  kvec_t(uint64_t) update_channels;
 };
 
 /*
diff --git a/src/nvim/buffer_updates.c b/src/nvim/buffer_updates.c
new file mode 100644
index 0000000000..157f80e55a
--- /dev/null
+++ b/src/nvim/buffer_updates.c
@@ -0,0 +1,233 @@
+// This is an open source non-commercial project. Dear PVS-Studio, please check
+// it. PVS-Studio Static Code Analyzer for C, C++ and C#: http://www.viva64.com
+
+#include "nvim/buffer_updates.h"
+#include "nvim/memline.h"
+#include "nvim/api/private/helpers.h"
+#include "nvim/msgpack_rpc/channel.h"
+#include "nvim/assert.h"
+
+// Register a channel. Return True if the channel was added, or already added.
+// Return False if the channel couldn't be added because the buffer is
+// unloaded.
+bool buf_updates_register(buf_T *buf, uint64_t channel_id, bool send_buffer)
+{
+  // must fail if the buffer isn't loaded
+  if (buf->b_ml.ml_mfp == NULL) {
+    return false;
+  }
+
+  // count how many channels are currently watching the buffer
+  size_t size = kv_size(buf->update_channels);
+  if (size) {
+    for (size_t i = 0; i < size; i++) {
+      if (kv_A(buf->update_channels, i) == channel_id) {
+        // buffer is already registered ... nothing to do
+        return true;
+      }
+    }
+  }
+
+  // append the channelid to the list
+  kv_push(buf->update_channels, channel_id);
+
+  if (send_buffer) {
+    Array args = ARRAY_DICT_INIT;
+    args.size = 6;
+    args.items = xcalloc(sizeof(Object), args.size);
+
+    // the first argument is always the buffer handle
+    args.items[0] = BUFFER_OBJ(buf->handle);
+    args.items[1] = INTEGER_OBJ(buf->b_changedtick);
+    // the first line that changed (zero-indexed)
+    args.items[2] = INTEGER_OBJ(0);
+    // the last line that was changed
+    args.items[3] = INTEGER_OBJ(-1);
+    Array linedata = ARRAY_DICT_INIT;
+
+    // collect buffer contents
+
+    // True now, but a compile time reminder for future systems we support
+    STATIC_ASSERT(SIZE_MAX >= MAXLNUM, "size_t to small to hold the number of"
+                  " lines in a buffer");
+    size_t line_count = (size_t)buf->b_ml.ml_line_count;
+
+    if (line_count >= 1) {
+      linedata.size = line_count;
+      linedata.items = xcalloc(sizeof(Object), line_count);
+      for (size_t i = 0; i < line_count; i++) {
+        linenr_T lnum = 1 + (linenr_T)i;
+
+        const char *bufstr = (char *)ml_get_buf(buf, lnum, false);
+        Object str = STRING_OBJ(cstr_to_string(bufstr));
+
+        // Vim represents NULs as NLs, but this may confuse clients.
+        strchrsub(str.data.string.data, '\n', '\0');
+
+        linedata.items[i] = str;
+      }
+    }
+
+    args.items[4] = ARRAY_OBJ(linedata);
+    args.items[5] = BOOLEAN_OBJ(false);
+
+    rpc_send_event(channel_id, "nvim_buf_lines_event", args);
+  } else {
+    buf_updates_changedtick_single(buf, channel_id);
+  }
+
+  return true;
+}
+
+void buf_updates_send_end(buf_T *buf, uint64_t channelid)
+{
+    Array args = ARRAY_DICT_INIT;
+    args.size = 1;
+    args.items = xcalloc(sizeof(Object), args.size);
+    args.items[0] = BUFFER_OBJ(buf->handle);
+    rpc_send_event(channelid, "nvim_buf_detach_event", args);
+}
+
+void buf_updates_unregister(buf_T *buf, uint64_t channelid)
+{
+  size_t size = kv_size(buf->update_channels);
+  if (!size) {
+    return;
+  }
+
+  // go through list backwards and remove the channel id each time it appears
+  // (it should never appear more than once)
+  size_t j = 0;
+  size_t found = 0;
+  for (size_t i = 0; i < size; i++) {
+    if (kv_A(buf->update_channels, i) == channelid) {
+      found++;
+    } else {
+      // copy item backwards into prior slot if needed
+      if (i != j) {
+        kv_A(buf->update_channels, j) = kv_A(buf->update_channels, i);
+      }
+      j++;
+    }
+  }
+
+  if (found) {
+    // remove X items from the end of the array
+    buf->update_channels.size -= found;
+
+    // make a new copy of the active array without the channelid in it
+    buf_updates_send_end(buf, channelid);
+
+    if (found == size) {
+      kv_destroy(buf->update_channels);
+      kv_init(buf->update_channels);
+    }
+  }
+}
+
+void buf_updates_unregister_all(buf_T *buf)
+{
+  size_t size = kv_size(buf->update_channels);
+  if (size) {
+    for (size_t i = 0; i < size; i++) {
+      buf_updates_send_end(buf, kv_A(buf->update_channels, i));
+    }
+    kv_destroy(buf->update_channels);
+    kv_init(buf->update_channels);
+  }
+}
+
+void buf_updates_send_changes(buf_T *buf,
+                              linenr_T firstline,
+                              int64_t num_added,
+                              int64_t num_removed,
+                              bool send_tick)
+{
+  // if one the channels doesn't work, put its ID here so we can remove it later
+  uint64_t badchannelid = 0;
+
+  // notify each of the active channels
+  for (size_t i = 0; i < kv_size(buf->update_channels); i++) {
+    uint64_t channelid = kv_A(buf->update_channels, i);
+
+    // send through the changes now channel contents now
+    Array args = ARRAY_DICT_INIT;
+    args.size = 6;
+    args.items = xcalloc(sizeof(Object), args.size);
+
+    // the first argument is always the buffer handle
+    args.items[0] = BUFFER_OBJ(buf->handle);
+
+    // next argument is b:changedtick
+    args.items[1] = send_tick ? INTEGER_OBJ(buf->b_changedtick) : NIL;
+
+    // the first line that changed (zero-indexed)
+    args.items[2] = INTEGER_OBJ(firstline - 1);
+
+    // the last line that was changed
+    args.items[3] = INTEGER_OBJ(firstline - 1 + num_removed);
+
+    // linedata of lines being swapped in
+    Array linedata = ARRAY_DICT_INIT;
+    if (num_added > 0) {
+        // True now, but a compile time reminder for future systems we support
+        // Note that `num_added` is a `int64_t`, but still must be lower than
+        // `MAX_LNUM`
+        STATIC_ASSERT(SIZE_MAX >= MAXLNUM, "size_t to small to hold the number "
+                      "of lines in a buffer");
+        linedata.size = (size_t)num_added;
+        linedata.items = xcalloc(sizeof(Object), (size_t)num_added);
+        for (int64_t i = 0; i < num_added; i++) {
+          int64_t lnum = firstline + i;
+          const char *bufstr = (char *)ml_get_buf(buf, (linenr_T)lnum, false);
+          Object str = STRING_OBJ(cstr_to_string(bufstr));
+
+          // Vim represents NULs as NLs, but this may confuse clients.
+          strchrsub(str.data.string.data, '\n', '\0');
+
+          linedata.items[i] = str;
+        }
+    }
+    args.items[4] = ARRAY_OBJ(linedata);
+    args.items[5] = BOOLEAN_OBJ(false);
+    if (!rpc_send_event(channelid, "nvim_buf_lines_event", args)) {
+      // We can't unregister the channel while we're iterating over the
+      // update_channels array, so we remember its ID to unregister it at
+      // the end.
+      badchannelid = channelid;
+    }
+  }
+
+  // We can only ever remove one dead channel at a time. This is OK because the
+  // change notifications are so frequent that many dead channels will be
+  // cleared up quickly.
+  if (badchannelid != 0) {
+    ELOG("Disabling buffer updates for dead channel %llu", badchannelid);
+    buf_updates_unregister(buf, badchannelid);
+  }
+}
+
+void buf_updates_changedtick(buf_T *buf)
+{
+  // notify each of the active channels
+  for (size_t i = 0; i < kv_size(buf->update_channels); i++) {
+    uint64_t channel_id = kv_A(buf->update_channels, i);
+    buf_updates_changedtick_single(buf, channel_id);
+  }
+}
+
+void buf_updates_changedtick_single(buf_T *buf, uint64_t channel_id)
+{
+    Array args = ARRAY_DICT_INIT;
+    args.size = 2;
+    args.items = xcalloc(sizeof(Object), args.size);
+
+    // the first argument is always the buffer handle
+    args.items[0] = BUFFER_OBJ(buf->handle);
+
+    // next argument is b:changedtick
+    args.items[1] = INTEGER_OBJ(buf->b_changedtick);
+
+    // don't try and clean up dead channels here
+    rpc_send_event(channel_id, "nvim_buf_changedtick_event", args);
+}
diff --git a/src/nvim/buffer_updates.h b/src/nvim/buffer_updates.h
new file mode 100644
index 0000000000..b2d0a62270
--- /dev/null
+++ b/src/nvim/buffer_updates.h
@@ -0,0 +1,10 @@
+#ifndef NVIM_BUFFER_UPDATES_H
+#define NVIM_BUFFER_UPDATES_H
+
+#include "nvim/buffer_defs.h"
+
+#ifdef INCLUDE_GENERATED_DECLARATIONS
+# include "buffer_updates.h.generated.h"
+#endif
+
+#endif  // NVIM_BUFFER_UPDATES_H
diff --git a/src/nvim/diff.c b/src/nvim/diff.c
index f9e40ed06f..61e0b76558 100644
--- a/src/nvim/diff.c
+++ b/src/nvim/diff.c
@@ -2344,7 +2344,7 @@ void ex_diffgetput(exarg_T *eap)
           }
         }
       }
-      changed_lines(lnum, 0, lnum + count, (long)added);
+      changed_lines(lnum, 0, lnum + count, (long)added, true);
 
       if (dfree != NULL) {
         // Diff is deleted, update folds in other windows.
diff --git a/src/nvim/event/wstream.c b/src/nvim/event/wstream.c
index d2fb52243c..2baa667e7d 100644
--- a/src/nvim/event/wstream.c
+++ b/src/nvim/event/wstream.c
@@ -14,7 +14,7 @@
 #include "nvim/vim.h"
 #include "nvim/memory.h"
 
-#define DEFAULT_MAXMEM 1024 * 1024 * 10
+#define DEFAULT_MAXMEM 1024 * 1024 * 2000
 
 typedef struct {
   Stream *stream;
diff --git a/src/nvim/ex_cmds.c b/src/nvim/ex_cmds.c
index f575d58f05..1d98f171b4 100644
--- a/src/nvim/ex_cmds.c
+++ b/src/nvim/ex_cmds.c
@@ -35,6 +35,7 @@
 #include "nvim/fold.h"
 #include "nvim/getchar.h"
 #include "nvim/indent.h"
+#include "nvim/buffer_updates.h"
 #include "nvim/main.h"
 #include "nvim/mark.h"
 #include "nvim/mbyte.h"
@@ -279,7 +280,7 @@ void ex_align(exarg_T *eap)
       new_indent = 0;
     (void)set_indent(new_indent, 0);                    /* set indent */
   }
-  changed_lines(eap->line1, 0, eap->line2 + 1, 0L);
+  changed_lines(eap->line1, 0, eap->line2 + 1, 0L, true);
   curwin->w_cursor = save_curpos;
   beginline(BL_WHITE | BL_FIX);
 }
@@ -612,7 +613,7 @@ void ex_sort(exarg_T *eap)
   } else if (deleted < 0) {
     mark_adjust(eap->line2, MAXLNUM, -deleted, 0L, false);
   }
-  changed_lines(eap->line1, 0, eap->line2 + 1, -deleted);
+  changed_lines(eap->line1, 0, eap->line2 + 1, -deleted, true);
 
   curwin->w_cursor.lnum = eap->line1;
   beginline(BL_WHITE | BL_FIX);
@@ -744,8 +745,9 @@ void ex_retab(exarg_T *eap)
 
   if (curbuf->b_p_ts != new_ts)
     redraw_curbuf_later(NOT_VALID);
-  if (first_line != 0)
-    changed_lines(first_line, 0, last_line + 1, 0L);
+  if (first_line != 0) {
+    changed_lines(first_line, 0, last_line + 1, 0L, true);
+  }
 
   curwin->w_p_list = save_list;         /* restore 'list' */
 
@@ -806,6 +808,7 @@ int do_move(linenr_T line1, linenr_T line2, linenr_T dest)
    */
   last_line = curbuf->b_ml.ml_line_count;
   mark_adjust_nofold(line1, line2, last_line - line2, 0L, true);
+  changed_lines(last_line - num_lines + 1, 0, last_line + 1, num_lines, false);
   if (dest >= line2) {
     mark_adjust_nofold(line2 + 1, dest, -num_lines, 0L, false);
     FOR_ALL_TAB_WINDOWS(tab, win) {
@@ -828,6 +831,12 @@ int do_move(linenr_T line1, linenr_T line2, linenr_T dest)
   curbuf->b_op_start.col = curbuf->b_op_end.col = 0;
   mark_adjust_nofold(last_line - num_lines + 1, last_line,
                      -(last_line - dest - extra), 0L, true);
+  changed_lines(last_line - num_lines + 1, 0, last_line + 1, -extra, false);
+
+  // send update regarding the new lines that were added
+  if (kv_size(curbuf->update_channels)) {
+    buf_updates_send_changes(curbuf, dest + 1, num_lines, 0, true);
+  }
 
   /*
    * Now we delete the original text -- webb
@@ -858,9 +867,14 @@ int do_move(linenr_T line1, linenr_T line2, linenr_T dest)
     last_line = curbuf->b_ml.ml_line_count;
     if (dest > last_line + 1)
       dest = last_line + 1;
-    changed_lines(line1, 0, dest, 0L);
+    changed_lines(line1, 0, dest, 0L, false);
   } else {
-    changed_lines(dest + 1, 0, line1 + num_lines, 0L);
+    changed_lines(dest + 1, 0, line1 + num_lines, 0L, false);
+  }
+
+  // send nvim_buf_lines_event regarding lines that were deleted
+  if (kv_size(curbuf->update_channels)) {
+    buf_updates_send_changes(curbuf, line1 + extra, 0, num_lines, true);
   }
 
   return OK;
@@ -2428,6 +2442,7 @@ int do_ecmd(
         goto theend;
       }
       u_unchanged(curbuf);
+      buf_updates_unregister_all(curbuf);
       buf_freeall(curbuf, BFA_KEEP_UNDO);
 
       // Tell readfile() not to clear or reload undo info.
@@ -3153,8 +3168,10 @@ static char_u *sub_parse_flags(char_u *cmd, subflags_T *subflags,
 ///
 /// The usual escapes are supported as described in the regexp docs.
 ///
+/// @param do_buf_event If `true`, send buffer updates.
 /// @return buffer used for 'inccommand' preview
-static buf_T *do_sub(exarg_T *eap, proftime_T timeout)
+static buf_T *do_sub(exarg_T *eap, proftime_T timeout,
+                     bool do_buf_event)
 {
   long i = 0;
   regmmatch_T regmatch;
@@ -4000,7 +4017,14 @@ skip:
      * the line number before the change (same as adding the number of
      * deleted lines). */
     i = curbuf->b_ml.ml_line_count - old_line_count;
-    changed_lines(first_line, 0, last_line - i, i);
+    changed_lines(first_line, 0, last_line - i, i, false);
+
+    if (kv_size(curbuf->update_channels)) {
+      int64_t num_added = last_line - first_line;
+      int64_t num_removed = num_added - i;
+      buf_updates_send_changes(curbuf, first_line, num_added, num_removed,
+                               do_buf_event);
+    }
   }
 
   xfree(sub_firstline);   /* may have to free allocated copy of the line */
@@ -6246,7 +6270,7 @@ void ex_substitute(exarg_T *eap)
 {
   bool preview = (State & CMDPREVIEW);
   if (*p_icm == NUL || !preview) {  // 'inccommand' is disabled
-    (void)do_sub(eap, profile_zero());
+    (void)do_sub(eap, profile_zero(), true);
     return;
   }
 
@@ -6270,7 +6294,7 @@ void ex_substitute(exarg_T *eap)
   // Don't show search highlighting during live substitution
   bool save_hls = p_hls;
   p_hls = false;
-  buf_T *preview_buf = do_sub(eap, profile_setlimit(p_rdt));
+  buf_T *preview_buf = do_sub(eap, profile_setlimit(p_rdt), false);
   p_hls = save_hls;
 
   if (save_changedtick != curbuf->b_changedtick) {
diff --git a/src/nvim/fold.c b/src/nvim/fold.c
index 316fbef47c..52ed2fe3dc 100644
--- a/src/nvim/fold.c
+++ b/src/nvim/fold.c
@@ -20,6 +20,7 @@
 #include "nvim/ex_docmd.h"
 #include "nvim/func_attr.h"
 #include "nvim/indent.h"
+#include "nvim/buffer_updates.h"
 #include "nvim/mark.h"
 #include "nvim/memline.h"
 #include "nvim/memory.h"
@@ -742,8 +743,20 @@ deleteFold (
     /* Deleting markers may make cursor column invalid. */
     check_cursor_col();
 
-  if (last_lnum > 0)
-    changed_lines(first_lnum, (colnr_T)0, last_lnum, 0L);
+  if (last_lnum > 0) {
+    changed_lines(first_lnum, (colnr_T)0, last_lnum, 0L, false);
+
+    // send one nvim_buf_lines_event at the end
+    if (kv_size(curbuf->update_channels)) {
+      // last_lnum is the line *after* the last line of the outermost fold
+      // that was modified. Note also that deleting a fold might only require
+      // the modification of the *first* line of the fold, but we send through a
+      // notification that includes every line that was part of the fold
+      int64_t num_changed = last_lnum - first_lnum;
+      buf_updates_send_changes(curbuf, first_lnum, num_changed,
+                               num_changed, true);
+    }
+  }
 }
 
 /* clearFolding() {{{2 */
@@ -1590,7 +1603,15 @@ static void foldCreateMarkers(linenr_T start, linenr_T end)
 
   /* Update both changes here, to avoid all folds after the start are
    * changed when the start marker is inserted and the end isn't. */
-  changed_lines(start, (colnr_T)0, end, 0L);
+  changed_lines(start, (colnr_T)0, end, 0L, false);
+
+  if (kv_size(curbuf->update_channels)) {
+    // Note: foldAddMarker() may not actually change start and/or end if
+    // u_save() is unable to save the buffer line, but we send the
+    // nvim_buf_lines_event anyway since it won't do any harm.
+    int64_t num_changed = 1 + end - start;
+    buf_updates_send_changes(curbuf, start, num_changed, num_changed, true);
+  }
 }
 
 /* foldAddMarker() {{{2 */
diff --git a/src/nvim/generators/gen_api_dispatch.lua b/src/nvim/generators/gen_api_dispatch.lua
index 2ee1e5d4c5..15fcafb584 100644
--- a/src/nvim/generators/gen_api_dispatch.lua
+++ b/src/nvim/generators/gen_api_dispatch.lua
@@ -223,6 +223,11 @@ for i = 1, #functions do
           output:write('\n  } else if (args.items['..(j - 1)..'].type == kObjectTypeInteger && args.items['..(j - 1)..'].data.integer >= 0) {')
           output:write('\n    '..converted..' = (handle_T)args.items['..(j - 1)..'].data.integer;')
         end
+        -- accept empty lua tables as empty dictionarys
+        if rt:match('^Dictionary') then
+          output:write('\n  } else if (args.items['..(j - 1)..'].type == kObjectTypeArray && args.items['..(j - 1)..'].data.array.size == 0) {')
+          output:write('\n    '..converted..' = (Dictionary)ARRAY_DICT_INIT;')
+        end
         output:write('\n  } else {')
         output:write('\n    api_set_error(error, kErrorTypeException, "Wrong type for argument '..j..', expecting '..param[1]..'");')
         output:write('\n    goto cleanup;')
diff --git a/src/nvim/misc1.c b/src/nvim/misc1.c
index dc59aa1281..70733e5564 100644
--- a/src/nvim/misc1.c
+++ b/src/nvim/misc1.c
@@ -28,6 +28,7 @@
 #include "nvim/getchar.h"
 #include "nvim/indent.h"
 #include "nvim/indent_c.h"
+#include "nvim/buffer_updates.h"
 #include "nvim/main.h"
 #include "nvim/mark.h"
 #include "nvim/mbyte.h"
@@ -836,8 +837,8 @@ open_line (
       saved_line = NULL;
       if (did_append) {
         changed_lines(curwin->w_cursor.lnum, curwin->w_cursor.col,
-            curwin->w_cursor.lnum + 1, 1L);
-        did_append = FALSE;
+                      curwin->w_cursor.lnum + 1, 1L, true);
+        did_append = false;
 
         /* Move marks after the line break to the new line. */
         if (flags & OPENLINE_MARKFIX)
@@ -854,8 +855,9 @@ open_line (
      */
     curwin->w_cursor.lnum = old_cursor.lnum + 1;
   }
-  if (did_append)
-    changed_lines(curwin->w_cursor.lnum, 0, curwin->w_cursor.lnum, 1L);
+  if (did_append) {
+    changed_lines(curwin->w_cursor.lnum, 0, curwin->w_cursor.lnum, 1L, true);
+  }
 
   curwin->w_cursor.col = newcol;
   curwin->w_cursor.coladd = 0;
@@ -1820,6 +1822,10 @@ void changed_bytes(linenr_T lnum, colnr_T col)
 {
   changedOneline(curbuf, lnum);
   changed_common(lnum, col, lnum + 1, 0L);
+  // notify any channels that are watching
+  if (kv_size(curbuf->update_channels)) {
+    buf_updates_send_changes(curbuf, lnum, 1, 1, true);
+  }
 
   /* Diff highlighting in other diff windows may need to be updated too. */
   if (curwin->w_p_diff) {
@@ -1860,7 +1866,7 @@ static void changedOneline(buf_T *buf, linenr_T lnum)
  */
 void appended_lines(linenr_T lnum, long count)
 {
-  changed_lines(lnum + 1, 0, lnum + 1, count);
+  changed_lines(lnum + 1, 0, lnum + 1, count, true);
 }
 
 /*
@@ -1873,7 +1879,7 @@ void appended_lines_mark(linenr_T lnum, long count)
   if (lnum + count < curbuf->b_ml.ml_line_count || curwin->w_p_diff) {
     mark_adjust(lnum + 1, (linenr_T)MAXLNUM, count, 0L, false);
   }
-  changed_lines(lnum + 1, 0, lnum + 1, count);
+  changed_lines(lnum + 1, 0, lnum + 1, count, true);
 }
 
 /*
@@ -1883,7 +1889,7 @@ void appended_lines_mark(linenr_T lnum, long count)
  */
 void deleted_lines(linenr_T lnum, long count)
 {
-  changed_lines(lnum, 0, lnum + count, -count);
+  changed_lines(lnum, 0, lnum + count, -count, true);
 }
 
 /*
@@ -1894,7 +1900,7 @@ void deleted_lines(linenr_T lnum, long count)
 void deleted_lines_mark(linenr_T lnum, long count)
 {
   mark_adjust(lnum, (linenr_T)(lnum + count - 1), (long)MAXLNUM, -count, false);
-  changed_lines(lnum, 0, lnum + count, -count);
+  changed_lines(lnum, 0, lnum + count, -count, true);
 }
 
 /*
@@ -1909,12 +1915,16 @@ void deleted_lines_mark(linenr_T lnum, long count)
  * Takes care of calling changed() and updating b_mod_*.
  * Careful: may trigger autocommands that reload the buffer.
  */
-void 
-changed_lines (
-    linenr_T lnum,              /* first line with change */
-    colnr_T col,                /* column in first line with change */
-    linenr_T lnume,             /* line below last changed line */
-    long xtra                  /* number of extra lines (negative when deleting) */
+void
+changed_lines(
+    linenr_T lnum,        // first line with change
+    colnr_T col,          // column in first line with change
+    linenr_T lnume,       // line below last changed line
+    long xtra,            // number of extra lines (negative when deleting)
+    bool do_buf_event  // some callers like undo/redo call changed_lines()
+                       // and then increment b_changedtick *again*. This flag
+                       // allows these callers to send the nvim_buf_lines_event
+                       // events after they're done modifying b_changedtick.
 )
 {
   changed_lines_buf(curbuf, lnum, lnume, xtra);
@@ -1938,6 +1948,12 @@ changed_lines (
   }
 
   changed_common(lnum, col, lnume, xtra);
+
+  if (do_buf_event && kv_size(curbuf->update_channels)) {
+    int64_t num_added = (int64_t)(lnume + xtra - lnum);
+    int64_t num_removed = lnume - lnum;
+    buf_updates_send_changes(curbuf, lnum, num_added, num_removed, true);
+  }
 }
 
 /// Mark line range in buffer as changed.
diff --git a/src/nvim/normal.c b/src/nvim/normal.c
index a2aaf8f9af..a995535da2 100644
--- a/src/nvim/normal.c
+++ b/src/nvim/normal.c
@@ -6140,7 +6140,7 @@ static void n_swapchar(cmdarg_T *cap)
   curwin->w_set_curswant = true;
   if (did_change) {
     changed_lines(startpos.lnum, startpos.col, curwin->w_cursor.lnum + 1,
-        0L);
+                  0L, true);
     curbuf->b_op_start = startpos;
     curbuf->b_op_end = curwin->w_cursor;
     if (curbuf->b_op_end.col > 0)
diff --git a/src/nvim/ops.c b/src/nvim/ops.c
index d874768dfc..c9e8344ac1 100644
--- a/src/nvim/ops.c
+++ b/src/nvim/ops.c
@@ -214,7 +214,7 @@ void op_shift(oparg_T *oap, int curs_top, int amount)
     ++curwin->w_cursor.lnum;
   }
 
-  changed_lines(oap->start.lnum, 0, oap->end.lnum + 1, 0L);
+  changed_lines(oap->start.lnum, 0, oap->end.lnum + 1, 0L, true);
 
   if (oap->motion_type == kMTBlockWise) {
     curwin->w_cursor.lnum = oap->start.lnum;
@@ -570,7 +570,7 @@ static void block_insert(oparg_T *oap, char_u *s, int b_insert, struct block_def
     }
   }   /* for all lnum */
 
-  changed_lines(oap->start.lnum + 1, 0, oap->end.lnum + 1, 0L);
+  changed_lines(oap->start.lnum + 1, 0, oap->end.lnum + 1, 0L, true);
 
   State = oldstate;
 }
@@ -632,12 +632,13 @@ void op_reindent(oparg_T *oap, Indenter how)
   /* Mark changed lines so that they will be redrawn.  When Visual
    * highlighting was present, need to continue until the last line.  When
    * there is no change still need to remove the Visual highlighting. */
-  if (last_changed != 0)
+  if (last_changed != 0) {
     changed_lines(first_changed, 0,
-        oap->is_VIsual ? start_lnum + oap->line_count :
-        last_changed + 1, 0L);
-  else if (oap->is_VIsual)
+                  oap->is_VIsual ? start_lnum + oap->line_count :
+                  last_changed + 1, 0L, true);
+  } else if (oap->is_VIsual) {
     redraw_curbuf_later(INVERTED);
+  }
 
   if (oap->line_count > p_report) {
     i = oap->line_count - (i + 1);
@@ -1455,7 +1456,7 @@ int op_delete(oparg_T *oap)
 
     check_cursor_col();
     changed_lines(curwin->w_cursor.lnum, curwin->w_cursor.col,
-                  oap->end.lnum + 1, 0L);
+                  oap->end.lnum + 1, 0L, true);
     oap->line_count = 0;  // no lines deleted
   } else if (oap->motion_type == kMTLineWise) {
     if (oap->op_type == OP_CHANGE) {
@@ -1822,7 +1823,7 @@ int op_replace(oparg_T *oap, int c)
 
   curwin->w_cursor = oap->start;
   check_cursor();
-  changed_lines(oap->start.lnum, oap->start.col, oap->end.lnum + 1, 0L);
+  changed_lines(oap->start.lnum, oap->start.col, oap->end.lnum + 1, 0L, true);
 
   /* Set "'[" and "']" marks. */
   curbuf->b_op_start = oap->start;
@@ -1856,8 +1857,9 @@ void op_tilde(oparg_T *oap)
       did_change |= one_change;
 
     }
-    if (did_change)
-      changed_lines(oap->start.lnum, 0, oap->end.lnum + 1, 0L);
+    if (did_change) {
+      changed_lines(oap->start.lnum, 0, oap->end.lnum + 1, 0L, true);
+    }
   } else {  // not block mode
     if (oap->motion_type == kMTLineWise) {
       oap->start.col = 0;
@@ -1881,7 +1883,7 @@ void op_tilde(oparg_T *oap)
       }
     if (did_change) {
       changed_lines(oap->start.lnum, oap->start.col, oap->end.lnum + 1,
-          0L);
+                    0L, true);
     }
   }
 
@@ -2264,7 +2266,7 @@ int op_change(oparg_T *oap)
         }
       }
       check_cursor();
-      changed_lines(oap->start.lnum + 1, 0, oap->end.lnum + 1, 0L);
+      changed_lines(oap->start.lnum + 1, 0, oap->end.lnum + 1, 0L, true);
       xfree(ins_text);
     }
   }
@@ -3033,7 +3035,7 @@ void do_put(int regname, yankreg_T *reg, int dir, long count, int flags)
         curwin->w_cursor.col += bd.startspaces;
     }
 
-    changed_lines(lnum, 0, curwin->w_cursor.lnum, nr_lines);
+    changed_lines(lnum, 0, curwin->w_cursor.lnum, nr_lines, true);
 
     /* Set '[ mark. */
     curbuf->b_op_start = curwin->w_cursor;
@@ -3210,10 +3212,10 @@ error:
       // note changed text for displaying and folding
       if (y_type == kMTCharWise) {
         changed_lines(curwin->w_cursor.lnum, col,
-                      curwin->w_cursor.lnum + 1, nr_lines);
+                      curwin->w_cursor.lnum + 1, nr_lines, true);
       } else {
         changed_lines(curbuf->b_op_start.lnum, 0,
-                      curbuf->b_op_start.lnum, nr_lines);
+                      curbuf->b_op_start.lnum, nr_lines, true);
       }
 
       /* put '] mark at last inserted character */
@@ -3693,7 +3695,7 @@ int do_join(size_t count,
   /* Only report the change in the first line here, del_lines() will report
    * the deleted line. */
   changed_lines(curwin->w_cursor.lnum, currsize,
-      curwin->w_cursor.lnum + 1, 0L);
+                curwin->w_cursor.lnum + 1, 0L, true);
 
   /*
    * Delete following lines. To do this we move the cursor there
@@ -4363,7 +4365,7 @@ void op_addsub(oparg_T *oap, linenr_T Prenum1, bool g_cmd)
     }
     change_cnt = do_addsub(oap->op_type, &pos, 0, amount);
     if (change_cnt) {
-      changed_lines(pos.lnum, 0, pos.lnum + 1, 0L);
+      changed_lines(pos.lnum, 0, pos.lnum + 1, 0L, true);
     }
   } else {
     int one_change;
@@ -4419,7 +4421,7 @@ void op_addsub(oparg_T *oap, linenr_T Prenum1, bool g_cmd)
       }
     }
     if (change_cnt) {
-      changed_lines(oap->start.lnum, 0, oap->end.lnum + 1, 0L);
+      changed_lines(oap->start.lnum, 0, oap->end.lnum + 1, 0L, true);
     }
 
     if (!change_cnt && oap->is_VIsual) {
diff --git a/src/nvim/terminal.c b/src/nvim/terminal.c
index 7f1bff75b4..c2370de0f8 100644
--- a/src/nvim/terminal.c
+++ b/src/nvim/terminal.c
@@ -1239,7 +1239,9 @@ static void refresh_screen(Terminal *term, buf_T *buf)
 
   int change_start = row_to_linenr(term, term->invalid_start);
   int change_end = change_start + changed;
-  changed_lines(change_start, 0, change_end, added);
+  changed_lines(change_start, 0, change_end, added,
+                // Don't send nvim_buf_lines_event for :terminal buffer.
+                false);
   term->invalid_start = INT_MAX;
   term->invalid_end = -1;
 }
diff --git a/src/nvim/undo.c b/src/nvim/undo.c
index e1ae4b4cc0..8b290edd1f 100644
--- a/src/nvim/undo.c
+++ b/src/nvim/undo.c
@@ -92,6 +92,7 @@
 #include "nvim/eval.h"
 #include "nvim/fileio.h"
 #include "nvim/fold.h"
+#include "nvim/buffer_updates.h"
 #include "nvim/mark.h"
 #include "nvim/memline.h"
 #include "nvim/message.h"
@@ -1672,7 +1673,7 @@ void u_undo(int count)
     undo_undoes = TRUE;
   else
     undo_undoes = !undo_undoes;
-  u_doit(count, false);
+  u_doit(count, false, true);
 }
 
 /*
@@ -1685,7 +1686,7 @@ void u_redo(int count)
     undo_undoes = false;
   }
 
-  u_doit(count, false);
+  u_doit(count, false, true);
 }
 
 /// Undo and remove the branch from the undo tree.
@@ -1697,7 +1698,9 @@ bool u_undo_and_forget(int count)
     count = 1;
   }
   undo_undoes = true;
-  u_doit(count, true);
+  u_doit(count, true,
+         // Don't send nvim_buf_lines_event for u_undo_and_forget().
+         false);
 
   if (curbuf->b_u_curhead == NULL) {
     // nothing was undone.
@@ -1732,7 +1735,11 @@ bool u_undo_and_forget(int count)
 }
 
 /// Undo or redo, depending on `undo_undoes`, `count` times.
-static void u_doit(int startcount, bool quiet)
+///
+/// @param startcount How often to undo or redo
+/// @param quiet If `true`, don't show messages
+/// @param do_buf_event If `true`, send the changedtick with the buffer updates
+static void u_doit(int startcount, bool quiet, bool do_buf_event)
 {
   int count = startcount;
 
@@ -1768,7 +1775,7 @@ static void u_doit(int startcount, bool quiet)
         break;
       }
 
-      u_undoredo(true);
+      u_undoredo(true, do_buf_event);
     } else {
       if (curbuf->b_u_curhead == NULL || get_undolevel() <= 0) {
         beep_flush();           /* nothing to redo */
@@ -1779,7 +1786,7 @@ static void u_doit(int startcount, bool quiet)
         break;
       }
 
-      u_undoredo(FALSE);
+      u_undoredo(false, do_buf_event);
 
       /* Advance for next redo.  Set "newhead" when at the end of the
        * redoable changes. */
@@ -2026,8 +2033,8 @@ void undo_time(long step, int sec, int file, int absolute)
           || (uhp->uh_seq == target && !above))
         break;
       curbuf->b_u_curhead = uhp;
-      u_undoredo(TRUE);
-      uhp->uh_walk = nomark;            /* don't go back down here */
+      u_undoredo(true, true);
+      uhp->uh_walk = nomark;            // don't go back down here
     }
 
     /*
@@ -2082,7 +2089,7 @@ void undo_time(long step, int sec, int file, int absolute)
         break;
       }
 
-      u_undoredo(FALSE);
+      u_undoredo(false, true);
 
       /* Advance "curhead" to below the header we last used.  If it
       * becomes NULL then we need to set "newhead" to this leaf. */
@@ -2105,16 +2112,15 @@ void undo_time(long step, int sec, int file, int absolute)
   u_undo_end(did_undo, absolute, false);
 }
 
-/*
- * u_undoredo: common code for undo and redo
- *
- * The lines in the file are replaced by the lines in the entry list at
- * curbuf->b_u_curhead. The replaced lines in the file are saved in the entry
- * list for the next undo/redo.
- *
- * When "undo" is TRUE we go up in the tree, when FALSE we go down.
- */
-static void u_undoredo(int undo)
+/// u_undoredo: common code for undo and redo
+///
+/// The lines in the file are replaced by the lines in the entry list at
+/// curbuf->b_u_curhead. The replaced lines in the file are saved in the entry
+/// list for the next undo/redo.
+///
+/// @param undo If `true`, go up the tree. Down if `false`.
+/// @param do_buf_event If `true`, send buffer updates.
+static void u_undoredo(int undo, bool do_buf_event)
 {
   char_u      **newarray = NULL;
   linenr_T oldsize;
@@ -2242,7 +2248,7 @@ static void u_undoredo(int undo)
       }
     }
 
-    changed_lines(top + 1, 0, bot, newsize - oldsize);
+    changed_lines(top + 1, 0, bot, newsize - oldsize, do_buf_event);
 
     /* set '[ and '] mark */
     if (top + 1 < curbuf->b_op_start.lnum)
@@ -2277,6 +2283,13 @@ static void u_undoredo(int undo)
     unchanged(curbuf, FALSE);
   }
 
+  // because the calls to changed()/unchanged() above will bump b_changedtick
+  // again, we need to send a nvim_buf_lines_event with just the new value of
+  // b:changedtick
+  if (do_buf_event && kv_size(curbuf->update_channels)) {
+    buf_updates_changedtick(curbuf);
+  }
+
   /*
    * restore marks from before undo/redo
    */
diff --git a/test/functional/api/buffer_updates_spec.lua b/test/functional/api/buffer_updates_spec.lua
new file mode 100644
index 0000000000..6da790b871
--- /dev/null
+++ b/test/functional/api/buffer_updates_spec.lua
@@ -0,0 +1,743 @@
+local helpers = require('test.functional.helpers')(after_each)
+local eq, ok = helpers.eq, helpers.ok
+local buffer, command, eval, nvim, next_msg = helpers.buffer,
+  helpers.command, helpers.eval, helpers.nvim, helpers.next_msg
+local expect_err = helpers.expect_err
+local write_file = helpers.write_file
+
+local origlines = {"original line 1",
+                   "original line 2",
+                   "original line 3",
+                   "original line 4",
+                   "original line 5",
+                   "original line 6"}
+
+local function expectn(name, args)
+  -- expect the next message to be the specified notification event
+  eq({'notification', name, args}, next_msg())
+end
+
+local function sendkeys(keys)
+  nvim('input', keys)
+  -- give nvim some time to process msgpack requests before possibly sending
+  -- more key presses - otherwise they all pile up in the queue and get
+  -- processed at once
+  local ntime = os.clock() + 0.1
+  repeat until os.clock() > ntime
+end
+
+local function open(activate, lines)
+  local filename = helpers.tmpname()
+  write_file(filename, table.concat(lines, "\n").."\n", true)
+  command('edit ' .. filename)
+  local b = nvim('get_current_buf')
+  -- what is the value of b:changedtick?
+  local tick = eval('b:changedtick')
+
+  -- Enable buffer events, ensure that the nvim_buf_lines_event messages
+  -- arrive as expected
+  if activate then
+    local firstline = 0
+    ok(buffer('attach', b, true, {}))
+    expectn('nvim_buf_lines_event', {b, tick, firstline, -1, lines, false})
+  end
+
+  return b, tick, filename
+end
+
+local function editoriginal(activate, lines)
+  if not lines then
+    lines = origlines
+  end
+  -- load up the file with the correct contents
+  helpers.clear()
+  return open(activate, lines)
+end
+
+local function reopen(buf, expectedlines)
+  ok(buffer('detach', buf))
+  expectn('nvim_buf_detach_event', {buf})
+  -- for some reason the :edit! increments tick by 2
+  command('edit!')
+  local tick = eval('b:changedtick')
+  ok(buffer('attach', buf, true, {}))
+  local firstline = 0
+  expectn('nvim_buf_lines_event', {buf, tick, firstline, -1, expectedlines, false})
+  command('normal! gg')
+  return tick
+end
+
+local function reopenwithfolds(b)
+  -- discard any changes to the buffer
+  local tick = reopen(b, origlines)
+
+  -- use markers for folds, make all folds open by default
+  command('setlocal foldmethod=marker foldlevel=20')
+
+  -- add a fold
+  command('2,4fold')
+  tick = tick + 1
+  expectn('nvim_buf_lines_event', {b, tick, 1, 4, {'original line 2/*{{{*/',
+                                          'original line 3',
+                                          'original line 4/*}}}*/'}, false})
+  -- make a new fold that wraps lines 1-6
+  command('1,6fold')
+  tick = tick + 1
+  expectn('nvim_buf_lines_event', {b, tick, 0, 6, {'original line 1/*{{{*/',
+                                          'original line 2/*{{{*/',
+                                          'original line 3',
+                                          'original line 4/*}}}*/',
+                                          'original line 5',
+                                          'original line 6/*}}}*/'}, false})
+  return tick
+end
+
+describe('API: buffer events:', function()
+  it('when lines are added', function()
+    local b, tick = editoriginal(true)
+
+    -- add a new line at the start of the buffer
+    command('normal! GyyggP')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 0, {'original line 6'}, false})
+
+    -- add multiple lines at the start of the file
+    command('normal! GkkyGggP')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 0, {'original line 4',
+                                           'original line 5',
+                                           'original line 6'}, false})
+
+    -- add one line to the middle of the file, several times
+    command('normal! ggYjjp')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 3, {'original line 4'}, false})
+    command('normal! p')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 4, 4, {'original line 4'}, false})
+    command('normal! p')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 5, 5, {'original line 4'}, false})
+
+    -- add multiple lines to the middle of the file
+    command('normal! gg4Yjjp')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 3, {'original line 4',
+                                           'original line 5',
+                                           'original line 6',
+                                           'original line 4'}, false})
+
+    -- add one line to the end of the file
+    command('normal! ggYGp')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 17, 17, {'original line 4'}, false})
+
+    -- add one line to the end of the file, several times
+    command('normal! ggYGppp')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 18, 18, {'original line 4'}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 19, 19, {'original line 4'}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 20, 20, {'original line 4'}, false})
+
+    -- add several lines to the end of the file, several times
+    command('normal! gg4YGp')
+    command('normal! Gp')
+    command('normal! Gp')
+    local firstfour = {'original line 4',
+                 'original line 5',
+                 'original line 6',
+                 'original line 4'}
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 21, 21, firstfour, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 25, 25, firstfour, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 29, 29, firstfour, false})
+
+    -- create a new empty buffer and wipe out the old one ... this will
+    -- turn off buffer events
+    command('enew!')
+    expectn('nvim_buf_detach_event', {b})
+
+    -- add a line at the start of an empty file
+    command('enew')
+    tick = eval('b:changedtick')
+    local b2 = nvim('get_current_buf')
+    ok(buffer('attach', b2, true, {}))
+    expectn('nvim_buf_lines_event', {b2, tick, 0, -1, {""}, false})
+    eval('append(0, ["new line 1"])')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b2, tick, 0, 0, {'new line 1'}, false})
+
+    -- turn off buffer events manually
+    buffer('detach', b2)
+    expectn('nvim_buf_detach_event', {b2})
+
+    -- add multiple lines to a blank file
+    command('enew!')
+    local b3 = nvim('get_current_buf')
+    ok(buffer('attach', b3, true, {}))
+    tick = eval('b:changedtick')
+    expectn('nvim_buf_lines_event', {b3, tick, 0, -1, {""}, false})
+    eval('append(0, ["new line 1", "new line 2", "new line 3"])')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b3, tick, 0, 0, {'new line 1',
+                                            'new line 2',
+                                            'new line 3'}, false})
+
+    -- use the API itself to add a line to the start of the buffer
+    buffer('set_lines', b3, 0, 0, true, {'New First Line'})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b3, tick, 0, 0, {"New First Line"}, false})
+  end)
+
+  it('when lines are removed', function()
+    local b, tick = editoriginal(true)
+
+    -- remove one line from start of file
+    command('normal! dd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {}, false})
+
+    -- remove multiple lines from the start of the file
+    command('normal! 4dd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 4, {}, false})
+
+    -- remove multiple lines from middle of file
+    tick = reopen(b, origlines)
+    command('normal! jj3dd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 2, 5, {}, false})
+
+    -- remove one line from the end of the file
+    tick = reopen(b, origlines)
+    command('normal! Gdd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 5, 6, {}, false})
+
+    -- remove multiple lines from the end of the file
+    tick = reopen(b, origlines)
+    command('normal! 4G3dd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 6, {}, false})
+
+    -- pretend to remove heaps lines from the end of the file but really
+    -- just remove two
+    tick = reopen(b, origlines)
+    command('normal! Gk5dd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 4, 6, {}, false})
+  end)
+
+  it('when text is changed', function()
+    local b, tick = editoriginal(true)
+
+    -- some normal text editing
+    command('normal! A555')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {'original line 1555'}, false})
+    command('normal! jj8X')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 2, 3, {'origin3'}, false})
+
+    -- modify multiple lines at once using visual block mode
+    tick = reopen(b, origlines)
+    command('normal! jjw')
+    sendkeys('<C-v>jjllx')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event',
+            {b, tick, 2, 5, {'original e 3', 'original e 4', 'original e 5'}, false})
+
+    -- replace part of a line line using :s
+    tick = reopen(b, origlines)
+    command('3s/line 3/foo/')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 2, 3, {'original foo'}, false})
+
+    -- replace parts of several lines line using :s
+    tick = reopen(b, origlines)
+    command('%s/line [35]/foo/')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 2, 5, {'original foo',
+                                           'original line 4',
+                                           'original foo'}, false})
+
+    -- type text into the first line of a blank file, one character at a time
+    command('enew!')
+    tick = 2
+    expectn('nvim_buf_detach_event', {b})
+    local bnew = nvim('get_current_buf')
+    ok(buffer('attach', bnew, true, {}))
+    expectn('nvim_buf_lines_event', {bnew, tick, 0, -1, {''}, false})
+    sendkeys('i')
+    sendkeys('h')
+    sendkeys('e')
+    sendkeys('l')
+    sendkeys('l')
+    sendkeys('o\nworld')
+    expectn('nvim_buf_lines_event', {bnew, tick + 1, 0, 1, {'h'}, false})
+    expectn('nvim_buf_lines_event', {bnew, tick + 2, 0, 1, {'he'}, false})
+    expectn('nvim_buf_lines_event', {bnew, tick + 3, 0, 1, {'hel'}, false})
+    expectn('nvim_buf_lines_event', {bnew, tick + 4, 0, 1, {'hell'}, false})
+    expectn('nvim_buf_lines_event', {bnew, tick + 5, 0, 1, {'hello'}, false})
+    expectn('nvim_buf_lines_event', {bnew, tick + 6, 0, 1, {'hello', ''}, false})
+    expectn('nvim_buf_lines_event', {bnew, tick + 7, 1, 2, {'world'}, false})
+  end)
+
+  it('when lines are replaced', function()
+    local b, tick = editoriginal(true)
+
+    -- blast away parts of some lines with visual mode
+    command('normal! jjwvjjllx')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 2, 3, {'original '}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 4, {}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 4, {'e 5'}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 2, 3, {'original e 5'}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 4, {}, false})
+
+    -- blast away a few lines using :g
+    tick = reopen(b, origlines)
+    command('global/line [35]/delete')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 2, 3, {}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 4, {}, false})
+  end)
+
+  it('when lines are filtered', function()
+    -- Test filtering lines with !cat
+    local b, tick = editoriginal(true, {"A", "C", "E", "B", "D", "F"})
+
+    command('silent 2,5!cat')
+    -- the change comes through as two changes:
+    -- 1) addition of the new lines after the filtered lines
+    -- 2) removal of the original lines
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 5, 5, {"C", "E", "B", "D"}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 5, {}, false})
+  end)
+
+  it('when you use "o"', function()
+    local b, tick = editoriginal(true, {'AAA', 'BBB'})
+    command('set noautoindent nosmartindent')
+
+    -- use 'o' to start a new line from a line with no indent
+    command('normal! o')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 1, {""}, false})
+
+    -- undo the change, indent line 1 a bit, and try again
+    command('undo')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 2, {}, false})
+    tick = tick + 1
+    expectn('nvim_buf_changedtick_event', {b, tick})
+    command('set autoindent')
+    command('normal! >>')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {"\tAAA"}, false})
+    command('normal! ommm')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 1, {"\t"}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 2, {"\tmmm"}, false})
+
+    -- undo the change, and try again with 'O'
+    command('undo')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 2, {'\t'}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 2, {}, false})
+    tick = tick + 1
+    expectn('nvim_buf_changedtick_event', {b, tick})
+    command('normal! ggOmmm')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 0, {"\t"}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {"\tmmm"}, false})
+  end)
+
+  it('deactivates if the buffer is changed externally', function()
+    -- Test changing file from outside vim and reloading using :edit
+    local lines = {"Line 1", "Line 2"};
+    local b, tick, filename = editoriginal(true, lines)
+
+    command('normal! x')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {'ine 1'}, false})
+    command('undo')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {'Line 1'}, false})
+    tick = tick + 1
+    expectn('nvim_buf_changedtick_event', {b, tick})
+
+    -- change the file directly
+    write_file(filename, "another line\n", true, true)
+
+    -- reopen the file and watch buffer events shut down
+    command('edit')
+    expectn('nvim_buf_detach_event', {b})
+  end)
+
+  it('channel can watch many buffers at once', function()
+    -- edit 3 buffers, make sure they all have windows visible so that when we
+    -- move between buffers, none of them are unloaded
+    local b1, tick1 = editoriginal(true, {'A1', 'A2'})
+    local b1nr = eval('bufnr("")')
+    command('split')
+    local b2, tick2 = open(true, {'B1', 'B2'})
+    local b2nr = eval('bufnr("")')
+    command('split')
+    local b3, tick3 = open(true, {'C1', 'C2'})
+    local b3nr = eval('bufnr("")')
+
+    -- make a new window for moving between buffers
+    command('split')
+
+    command('b'..b1nr)
+    command('normal! x')
+    tick1 = tick1 + 1
+    expectn('nvim_buf_lines_event', {b1, tick1, 0, 1, {'1'}, false})
+    command('undo')
+    tick1 = tick1 + 1
+    expectn('nvim_buf_lines_event', {b1, tick1, 0, 1, {'A1'}, false})
+    tick1 = tick1 + 1
+    expectn('nvim_buf_changedtick_event', {b1, tick1})
+
+    command('b'..b2nr)
+    command('normal! x')
+    tick2 = tick2 + 1
+    expectn('nvim_buf_lines_event', {b2, tick2, 0, 1, {'1'}, false})
+    command('undo')
+    tick2 = tick2 + 1
+    expectn('nvim_buf_lines_event', {b2, tick2, 0, 1, {'B1'}, false})
+    tick2 = tick2 + 1
+    expectn('nvim_buf_changedtick_event', {b2, tick2})
+
+    command('b'..b3nr)
+    command('normal! x')
+    tick3 = tick3 + 1
+    expectn('nvim_buf_lines_event', {b3, tick3, 0, 1, {'1'}, false})
+    command('undo')
+    tick3 = tick3 + 1
+    expectn('nvim_buf_lines_event', {b3, tick3, 0, 1, {'C1'}, false})
+    tick3 = tick3 + 1
+    expectn('nvim_buf_changedtick_event', {b3, tick3})
+  end)
+
+  it('does not get confused if enabled/disabled many times',
+     function()
+    local channel = nvim('get_api_info')[1]
+    local b, tick = editoriginal(false)
+
+    -- Enable buffer events many times.
+    ok(buffer('attach', b, true, {}))
+    ok(buffer('attach', b, true, {}))
+    ok(buffer('attach', b, true, {}))
+    ok(buffer('attach', b, true, {}))
+    ok(buffer('attach', b, true, {}))
+    expectn('nvim_buf_lines_event', {b, tick, 0, -1, origlines, false})
+    eval('rpcnotify('..channel..', "Hello There")')
+    expectn('Hello There', {})
+
+    -- Disable buffer events many times.
+    ok(buffer('detach', b))
+    ok(buffer('detach', b))
+    ok(buffer('detach', b))
+    ok(buffer('detach', b))
+    ok(buffer('detach', b))
+    expectn('nvim_buf_detach_event', {b})
+    eval('rpcnotify('..channel..', "Hello Again")')
+    expectn('Hello Again', {})
+  end)
+
+  it('can notify several channels at once', function()
+    helpers.clear()
+
+    -- create several new sessions, in addition to our main API
+    local sessions = {}
+    local pipe = helpers.new_pipename()
+    eval("serverstart('"..pipe.."')")
+    sessions[1] = helpers.connect(pipe)
+    sessions[2] = helpers.connect(pipe)
+    sessions[3] = helpers.connect(pipe)
+
+    local function request(sessionnr, method, ...)
+      local status, rv = sessions[sessionnr]:request(method, ...)
+      if not status then
+        error(rv[2])
+      end
+      return rv
+    end
+
+    local function wantn(sessionid, name, args)
+      local session = sessions[sessionid]
+      eq({'notification', name, args}, session:next_message())
+    end
+
+    -- Edit a new file, but don't enable buffer events.
+    local lines = {'AAA', 'BBB'}
+    local b, tick = open(false, lines)
+
+    -- Enable buffer events for sessions 1, 2 and 3.
+    ok(request(1, 'nvim_buf_attach', b, true, {}))
+    ok(request(2, 'nvim_buf_attach', b, true, {}))
+    ok(request(3, 'nvim_buf_attach', b, true, {}))
+    wantn(1, 'nvim_buf_lines_event', {b, tick, 0, -1, lines, false})
+    wantn(2, 'nvim_buf_lines_event', {b, tick, 0, -1, lines, false})
+    wantn(3, 'nvim_buf_lines_event', {b, tick, 0, -1, lines, false})
+
+    -- Change the buffer.
+    command('normal! x')
+    tick = tick + 1
+    wantn(1, 'nvim_buf_lines_event', {b, tick, 0, 1, {'AA'}, false})
+    wantn(2, 'nvim_buf_lines_event', {b, tick, 0, 1, {'AA'}, false})
+    wantn(3, 'nvim_buf_lines_event', {b, tick, 0, 1, {'AA'}, false})
+
+    -- Stop watching on channel 1.
+    ok(request(1, 'nvim_buf_detach', b))
+    wantn(1, 'nvim_buf_detach_event', {b})
+
+    -- Undo the change to buffer 1.
+    command('undo')
+    tick = tick + 1
+    wantn(2, 'nvim_buf_lines_event', {b, tick, 0, 1, {'AAA'}, false})
+    wantn(3, 'nvim_buf_lines_event', {b, tick, 0, 1, {'AAA'}, false})
+    tick = tick + 1
+    wantn(2, 'nvim_buf_changedtick_event', {b, tick})
+    wantn(3, 'nvim_buf_changedtick_event', {b, tick})
+
+    -- make sure there are no other pending nvim_buf_lines_event messages going to
+    -- channel 1
+    local channel1 = request(1, 'nvim_get_api_info')[1]
+    eval('rpcnotify('..channel1..', "Hello")')
+    wantn(1, 'Hello', {})
+
+    -- close the buffer and channels 2 and 3 should get a nvim_buf_detach_event
+    -- notification
+    command('edit')
+    wantn(2, 'nvim_buf_detach_event', {b})
+    wantn(3, 'nvim_buf_detach_event', {b})
+
+    -- make sure there are no other pending nvim_buf_lines_event messages going to
+    -- channel 1
+    channel1 = request(1, 'nvim_get_api_info')[1]
+    eval('rpcnotify('..channel1..', "Hello Again")')
+    wantn(1, 'Hello Again', {})
+  end)
+
+  it('works with :diffput and :diffget', function()
+    if os.getenv("APPVEYOR") then
+      pending("Fails on appveyor for some reason.", function() end)
+    end
+
+    local b1, tick1 = editoriginal(true, {"AAA", "BBB"})
+    local channel = nvim('get_api_info')[1]
+    command('diffthis')
+    command('rightbelow vsplit')
+    local b2, tick2 = open(true, {"BBB", "CCC"})
+    command('diffthis')
+    -- go back to first buffer, and push the 'AAA' line to the second buffer
+    command('1wincmd w')
+    command('normal! gg')
+    command('diffput')
+    tick2 = tick2 + 1
+    expectn('nvim_buf_lines_event', {b2, tick2, 0, 0, {"AAA"}, false})
+
+    -- use :diffget to grab the other change from buffer 2
+    command('normal! G')
+    command('diffget')
+    tick1 = tick1 + 1
+    expectn('nvim_buf_lines_event', {b1, tick1, 2, 2, {"CCC"}, false})
+
+    eval('rpcnotify('..channel..', "Goodbye")')
+    expectn('Goodbye', {})
+  end)
+
+  it('works with :sort', function()
+    -- test for :sort
+    local b, tick = editoriginal(true, {"B", "D", "C", "A", "E"})
+    command('%sort')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 5, {"A", "B", "C", "D", "E"}, false})
+  end)
+
+  it('works with :left', function()
+    local b, tick = editoriginal(true, {" A", "  B", "B", "\tB", "\t\tC"})
+    command('2,4left')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 4, {"B", "B", "B"}, false})
+  end)
+
+  it('works with :right', function()
+    local b, tick = editoriginal(true, {" A",
+                                        "\t  B",
+                                        "\t  \tBB",
+                                        " \tB",
+                                        "\t\tC"})
+    command('set ts=2 et')
+    command('2,4retab')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 4, {"    B", "      BB", "  B"}, false})
+  end)
+
+  it('works with :move', function()
+    local b, tick = editoriginal(true, origlines)
+    -- move text down towards the end of the file
+    command('2,3move 4')
+    tick = tick + 2
+    expectn('nvim_buf_lines_event', {b, tick, 4, 4, {"original line 2",
+                                           "original line 3"}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 3, {}, false})
+
+    -- move text up towards the start of the file
+    tick = reopen(b, origlines)
+    command('4,5move 2')
+    tick = tick + 2
+    expectn('nvim_buf_lines_event', {b, tick, 2, 2, {"original line 4",
+                                           "original line 5"}, false})
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 5, 7, {}, false})
+  end)
+
+  it('when you manually add/remove folds', function()
+    local b = editoriginal(true)
+    local tick = reopenwithfolds(b)
+
+    -- delete the inner fold
+    command('normal! zR3Gzd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 1, 4, {'original line 2',
+                                           'original line 3',
+                                           'original line 4'}, false})
+    -- delete the outer fold
+    command('normal! zd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 6, origlines, false})
+
+    -- discard changes and put the folds back
+    tick = reopenwithfolds(b)
+
+    -- remove both folds at once
+    command('normal! ggzczD')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 6, origlines, false})
+
+    -- discard changes and put the folds back
+    tick = reopenwithfolds(b)
+
+    -- now delete all folds at once
+    command('normal! zE')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 6, origlines, false})
+
+    -- create a fold from line 4 to the end of the file
+    command('normal! 4GA/*{{{*/')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 4, {'original line 4/*{{{*/'}, false})
+
+    -- delete the fold which only has one marker
+    command('normal! Gzd')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 3, 6, {'original line 4',
+                                           'original line 5',
+                                           'original line 6'}, false})
+  end)
+
+  it('detaches if the buffer is closed', function()
+    local b, tick = editoriginal(true, {'AAA'})
+    local channel = nvim('get_api_info')[1]
+
+    -- Test that buffer events are working.
+    command('normal! x')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {'AA'}, false})
+    command('undo')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {'AAA'}, false})
+    tick = tick + 1
+    expectn('nvim_buf_changedtick_event', {b, tick})
+
+    -- close our buffer by creating a new one
+    command('enew')
+    expectn('nvim_buf_detach_event', {b})
+
+    -- Reopen the original buffer, make sure there are no buffer events sent.
+    command('b1')
+    command('normal! x')
+
+    eval('rpcnotify('..channel..', "Hello There")')
+    expectn('Hello There', {})
+  end)
+
+  it('stays attached if the buffer is hidden', function()
+    local b, tick = editoriginal(true, {'AAA'})
+    local channel = nvim('get_api_info')[1]
+
+    -- Test that buffer events are working.
+    command('normal! x')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {'AA'}, false})
+    command('undo')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {'AAA'}, false})
+    tick = tick + 1
+    expectn('nvim_buf_changedtick_event', {b, tick})
+
+    -- Close our buffer by creating a new one.
+    command('set hidden')
+    command('enew')
+
+    -- Assert that no nvim_buf_detach_event is sent.
+    eval('rpcnotify('..channel..', "Hello There")')
+    expectn('Hello There', {})
+
+    -- Reopen the original buffer, assert that buffer events are still active.
+    command('b1')
+    command('normal! x')
+    tick = tick + 1
+    expectn('nvim_buf_lines_event', {b, tick, 0, 1, {'AA'}, false})
+  end)
+
+  it('detaches if the buffer is unloaded/deleted/wiped',
+     function()
+    -- start with a blank nvim
+    helpers.clear()
+    -- need to make a new window with a buffer because :bunload doesn't let you
+    -- unload the last buffer
+    for _, cmd in ipairs({'bunload', 'bdelete', 'bwipeout'}) do
+      command('new')
+      -- open a brand spanking new file
+      local b = open(true, {'AAA'})
+
+      -- call :bunload or whatever the command is, and then check that we
+      -- receive a nvim_buf_detach_event
+      command(cmd)
+      expectn('nvim_buf_detach_event', {b})
+    end
+  end)
+
+  it('does not send the buffer content if not requested', function()
+    helpers.clear()
+    local b, tick = editoriginal(false)
+    ok(buffer('attach', b, false, {}))
+    expectn('nvim_buf_changedtick_event', {b, tick})
+  end)
+
+  it('returns a proper error on nonempty options dict', function()
+    helpers.clear()
+    local b = editoriginal(false)
+    expect_err("dict isn't empty", buffer, 'attach', b, false, {builtin="asfd"})
+  end)
+
+end)
diff --git a/test/functional/api/highlight_spec.lua b/test/functional/api/highlight_spec.lua
index fed53a3dfd..76bf338d97 100644
--- a/test/functional/api/highlight_spec.lua
+++ b/test/functional/api/highlight_spec.lua
@@ -5,7 +5,7 @@ local eq, eval = helpers.eq, helpers.eval
 local command = helpers.command
 local meths = helpers.meths
 
-describe('highlight api',function()
+describe('API: highlight',function()
   local expected_rgb = {
     background = Screen.colors.Yellow,
     foreground = Screen.colors.Red,