API: nvim_paste

src/nvim/api/private/helpers.c

@@ -745,6 +745,35 @@ String ga_take_string(garray_T *ga)
   return str;
 }
 
+/// Creates "readfile()-style" ArrayOf(String).
+///
+/// - NUL bytes are replaced with NL (form-feed).
+/// - If last line ends with NL an extra empty list item is added.
+Array string_to_array(const String input)
+{
+  Array ret = ARRAY_DICT_INIT;
+  for (size_t i = 0; i < input.size; i++) {
+    const char *start = input.data + i;
+    const char *end = xmemscan(start, NL, input.size - i);
+    const size_t line_len = (size_t)(end - start);
+    i += line_len;
+
+    String s = {
+      .size = line_len,
+      .data = xmemdupz(start, line_len),
+    };
+    memchrsub(s.data, NUL, NL, line_len);
+    ADD(ret, STRING_OBJ(s));
+    // If line ends at end-of-buffer, add empty final item.
+    // This is "readfile()-style", see also ":help channel-lines".
+    if (i + 1 == input.size && end[0] == NL) {
+      ADD(ret, STRING_OBJ(cchar_to_string(NUL)));
+    }
+  }
+
+  return ret;
+}
+
 /// Set, tweak, or remove a mapping in a mode. Acts as the implementation for
 /// functions like @ref nvim_buf_set_keymap.
 ///

src/nvim/api/vim.c

@@ -1206,6 +1206,42 @@ Dictionary nvim_get_namespaces(void)
   return retval;
 }
 
+/// Paste
+///
+/// Invokes the `vim.paste` handler, which handles each mode appropriately.
+/// Sets redo/undo. Faster than |nvim_input()|.
+///
+/// @param data  Multiline input. May be binary (containing NUL bytes).
+/// @param phase  Pass -1 to paste as one big buffer (i.e. without streaming).
+///               To "stream" a paste, call `nvim_paste` sequentially with
+///               these `phase` values:
+///                 - 1: starts the paste (exactly once)
+///                 - 2: continues the paste (zero or more times)
+///                 - 3: ends the paste (exactly once)
+/// @param[out] err Error details, if any
+/// @return true if paste should continue, false if paste was canceled
+Boolean nvim_paste(String data, Integer phase, Error *err)
+  FUNC_API_SINCE(6)
+{
+  if (phase < -1 || phase > 3) {
+    api_set_error(err, kErrorTypeValidation, "Invalid phase: %"PRId64, phase);
+    return false;
+  }
+  Array args = ARRAY_DICT_INIT;
+  ADD(args, ARRAY_OBJ(string_to_array(data)));
+  ADD(args, INTEGER_OBJ(phase));
+  Object rv
+    = nvim_execute_lua(STATIC_CSTR_AS_STRING("return vim._paste(...)"),
+                       args, err);
+  // Abort paste if handler does not return true.
+  bool ok = !ERROR_SET(err)
+    && (rv.type == kObjectTypeBoolean && rv.data.boolean);
+  api_free_object(rv);
+  api_free_array(args);
+
+  return ok;
+}
+
 /// Puts text at cursor.
 ///
 /// Compare |:put| and |p| which are always linewise.
@@ -1225,11 +1261,8 @@ void nvim_put(ArrayOf(String) lines, String type, Boolean after,
 {
   yankreg_T *reg = xcalloc(sizeof(yankreg_T), 1);
   if (!prepare_yankreg_from_object(reg, type, lines.size)) {
-    api_set_error(err,
-                  kErrorTypeValidation,
-                  "Invalid regtype %s",
-                  type.data);
-    return;
+    api_set_error(err, kErrorTypeValidation, "Invalid type: '%s'", type.data);
+    goto cleanup;
   }
   if (lines.size == 0) {
     goto cleanup;  // Nothing to do.
@@ -1237,9 +1270,8 @@ void nvim_put(ArrayOf(String) lines, String type, Boolean after,
 
   for (size_t i = 0; i < lines.size; i++) {
     if (lines.items[i].type != kObjectTypeString) {
-      api_set_error(err,
-                    kErrorTypeValidation,
-                    "All items in the lines array must be strings");
+      api_set_error(err, kErrorTypeValidation,
+                    "Invalid lines (expected array of strings)");
       goto cleanup;
     }
     String line = lines.items[i].data.string;