👍 Add decode() and append() function

Additionally, make `assign()` deprecated because developers can use
`decode()` and `replace()` individually to get same result.

Author: lambdalisue

denops_std/buffer/README.md

@@ -78,6 +78,48 @@ export async function main(denops: Denops): Promise<void> {
 It may temporary change a current buffer or a current window to properly reload
 the content of the `bufnr` buffer.
 
+### decode
+
+Use `decode()` to decode raw binary content for string array for the `bufnr`
+buffer like:
+
+```typescript
+import { Denops } from "../mod.ts";
+import * as fn from "../function/mod.ts";
+import { decode, open, replace } from "../buffer/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  await open(denops, "README.md");
+  const bufnr = await fn.bufnr(denops) as number;
+  const data = await Deno.readFile("README.md");
+  const { content } = await decode(denops, bufnr, data);
+  await replace(denops, bufnr, content);
+}
+```
+
+It follows Vim's rule to find a corresponding `fileformat` and `fileencoding` to
+decode the `data` if the one is not given by `options`.
+
+### append
+
+Use `append()` to append the content of the `bufnr` buffer like:
+
+```typescript
+import { Denops } from "../mod.ts";
+import * as fn from "../function/mod.ts";
+import { append, open } from "../buffer/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  await open(denops, "README.md");
+  const bufnr = await fn.bufnr(denops) as number;
+  // Append the content under the cursor position of the `bufnr` buffer
+  await append(denops, bufnr, ["Hello", "World"]);
+}
+```
+
+It temporary change `modified`, `modifiable`, and `foldmethod` options to append
+the content of the `buffer` buffer without unmodifiable error or so on.
+
 ### replace
 
 Use `replace()` to replace the content of the `bufnr` buffer like:
@@ -100,6 +142,8 @@ replace the content of the `buffer` buffer without unmodifiable error or so on.
 
 ### assign
 
+**DEPRECATED: Use `decode()` and `replace()` individually**
+
 Use `assign()` to assign raw binary content into the `bufnr` buffer like:
 
 ```typescript

denops_std/buffer/buffer.ts

@@ -6,6 +6,7 @@ import { execute } from "../helper/mod.ts";
 import * as unknownutil from "https://deno.land/x/unknownutil@v2.0.0/mod.ts";
 import {
   assertFileFormat,
+  FileFormat,
   findFileFormat,
   isFileFormat,
   maybeFileFormat,
@@ -54,6 +55,18 @@ async function ensurePrerequisites(denops: Denops): Promise<string> {
     endtry
   endfunction
 
+  function! DenopsStdBufferAppend_${suffix}(bufnr, lnum, repl) abort
+    let modified = getbufvar(a:bufnr, '&modified')
+    let modifiable = getbufvar(a:bufnr, '&modifiable')
+    let foldmethod = getbufvar(a:bufnr, '&foldmethod')
+    call setbufvar(a:bufnr, '&modifiable', 1)
+    call setbufvar(a:bufnr, '&foldmethod', 'manual')
+    call appendbufline(a:bufnr, a:lnum, a:repl)
+    call setbufvar(a:bufnr, '&modified', modified)
+    call setbufvar(a:bufnr, '&modifiable', modifiable)
+    call setbufvar(a:bufnr, '&foldmethod', foldmethod)
+  endfunction
+
   function! DenopsStdBufferReplace_${suffix}(bufnr, repl, fileformat, fileencoding) abort
     let modified = getbufvar(a:bufnr, '&modified')
     let modifiable = getbufvar(a:bufnr, '&modifiable')
@@ -142,6 +155,82 @@ export async function reload(denops: Denops, bufnr: number): Promise<void> {
   );
 }
 
+/**
+ * Decode content for the buffer with given format and encoding.
+ */
+export async function decode(
+  denops: Denops,
+  bufnr: number,
+  data: Uint8Array,
+  options: DecodeOptions = {},
+): Promise<DecodeResult> {
+  const [fileformat, fileformatsStr, fileencodingsStr] = await batch.gather(
+    denops,
+    async (denops) => {
+      await fn.getbufvar(denops, bufnr, "&fileformat");
+      await fn.getbufvar(denops, bufnr, "&fileformats");
+      await fn.getbufvar(denops, bufnr, "&fileencodings");
+    },
+  );
+  assertFileFormat(fileformat);
+  unknownutil.assertString(fileformatsStr);
+  unknownutil.assertString(fileencodingsStr);
+  const fileformats = fileformatsStr.split(",");
+  const fileencodings = fileencodingsStr.split(",");
+  unknownutil.assertArray(fileformats, isFileFormat);
+  unknownutil.assertArray(fileencodings, unknownutil.isString);
+  let enc: string;
+  let text: string;
+  if (options.fileencoding) {
+    enc = options.fileencoding;
+    text = (new TextDecoder(enc)).decode(data);
+  } else {
+    [enc, text] = tryDecode(data, fileencodings);
+  }
+  const ff = maybeFileFormat(options.fileformat) ??
+    findFileFormat(text, fileformats) ?? fileformat;
+  return {
+    content: splitText(text, ff),
+    fileformat: ff,
+    fileencoding: enc,
+  };
+}
+
+export type DecodeOptions = {
+  fileformat?: string;
+  fileencoding?: string;
+};
+
+export type DecodeResult = {
+  content: string[];
+  fileformat: FileFormat;
+  fileencoding: string;
+};
+
+/**
+ * Append content under the current cursor position or given lnum of the buffer
+ */
+export async function append(
+  denops: Denops,
+  bufnr: number,
+  repl: string[],
+  options: AppendOptions = {},
+): Promise<void> {
+  const suffix = await ensurePrerequisites(denops);
+  const lnum = options.lnum ??
+    await ensure(denops, bufnr, () => fn.line(denops, "."));
+  await denops.call(
+    `DenopsStdBufferAppend_${suffix}`,
+    bufnr,
+    lnum,
+    repl,
+  );
+}
+
+export type AppendOptions = {
+  lnum?: number;
+};
+
 /**
  * Replace the buffer content
  */
@@ -168,49 +257,30 @@ export type ReplaceOptions = {
 
 /**
  * Assign content to the buffer with given format and encoding.
+ *
+ * @deprecated Use `decode()` and `replace()` individually instead.
  */
 export async function assign(
   denops: Denops,
   bufnr: number,
-  content: Uint8Array,
+  data: Uint8Array,
   options: AssignOptions = {},
 ): Promise<void> {
-  const [fileformat, fileformatsStr, fileencodingsStr] = await batch.gather(
+  const { content, fileformat, fileencoding } = await decode(
     denops,
-    async (denops) => {
-      await fn.getbufvar(denops, bufnr, "&fileformat");
-      await fn.getbufvar(denops, bufnr, "&fileformats");
-      await fn.getbufvar(denops, bufnr, "&fileencodings");
-    },
+    bufnr,
+    data,
+    options,
   );
-  assertFileFormat(fileformat);
-  unknownutil.assertString(fileformatsStr);
-  unknownutil.assertString(fileencodingsStr);
-  const fileformats = fileformatsStr.split(",");
-  const fileencodings = fileencodingsStr.split(",");
-  unknownutil.assertArray(fileformats, isFileFormat);
-  unknownutil.assertArray(fileencodings, unknownutil.isString);
-  let enc: string;
-  let text: string;
-  if (options.fileencoding) {
-    enc = options.fileencoding;
-    text = (new TextDecoder(enc)).decode(content);
-  } else {
-    [enc, text] = tryDecode(content, fileencodings);
-  }
-  const ff = maybeFileFormat(options.fileformat) ??
-    findFileFormat(text, fileformats) ?? fileformat;
   const preprocessor = options.preprocessor ?? ((v: string[]) => v);
-  const repl = preprocessor(splitText(text, ff));
+  const repl = preprocessor(content);
   await replace(denops, bufnr, repl, {
-    fileformat: ff,
-    fileencoding: enc,
+    fileformat,
+    fileencoding,
   });
 }
 
-export type AssignOptions = {
-  fileformat?: string;
-  fileencoding?: string;
+export type AssignOptions = DecodeOptions & {
   preprocessor?: (repl: string[]) => string[];
 };