Merge pull request #95 from vim-denops/add-bufname

👍 Add `bufname` module

Author: lambdalisue

denops_std/README.md

@@ -59,6 +59,7 @@ for more details.
 | [`anonymous`](./anonymous) | A module to provide anonymous function                           |
 | [`autocmd`](./autocmd)     | A module to provide helper functions to manage `autocmd`         |
 | [`batch`](./batch)         | A module to provide wrapper functions of `denops.batch()`        |
+| [`bufname`](./bufname)     | A module to provide helper functions to manage Vim's buffer name |
 | [`function`](./function)   | A module to provide functions of Vim and Neovim native functions |
 | [`helper`](./helper)       | A module to provide helper functions                             |
 | [`mapping`](./mapping)     | A module to provide helper functions to manage mappings          |

denops_std/bufname/README.md

@@ -0,0 +1,100 @@
+# bufname
+
+`bufname` is a module to provide manage Vim's buffer name.
+
+- [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/bufname/mod.ts)
+
+## Usage
+
+### format
+
+Use `format()` to format a Vim's buffer name in a safe way from `Bufname`
+instance like:
+
+```typescript
+import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import { format } from "https://deno.land/x/denops_std/bufname/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  assertEquals(
+    format({ scheme: "denops", path: "/Users/johntitor/.vimrc" }),
+    "denops:///Users/johntitor/.vimrc",
+  );
+
+  assertEquals(
+    format({
+      scheme: "denops",
+      path: "/Users/johntitor/.vimrc",
+      params: {
+        foo: "foo",
+        bar: ["bar", "bar"],
+        hoge: undefined,
+      },
+    }),
+    "denops:///Users/johntitor/.vimrc;foo=foo&bar=bar&bar=bar",
+  );
+
+  assertEquals(
+    format({
+      scheme: "denops",
+      path: "/Users/johntitor/.vimrc",
+      params: {
+        foo: "foo",
+        bar: ["bar", "bar"],
+        hoge: undefined,
+      },
+      fragment: "README.md",
+    }),
+    "denops:///Users/johntitor/.vimrc;foo=foo&bar=bar&bar=bar#README.md",
+  );
+}
+```
+
+Note that unusable characters (`"`, `<`, `>`, `|`, `?`, `*`) are replaced with
+percent-encoded characters.
+
+### parse
+
+Use `parse()` to parse Vim's buffer name and get a `Bufname` instance like
+
+```typescript
+import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import { parse } from "https://deno.land/x/denops_std/bufname/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  assertEquals(parse("denops:///Users/johntitor/.vimrc"), {
+    scheme: "denops",
+    path: "/Users/johntitor/.vimrc",
+  });
+
+  assertEquals(
+    parse("denops:///Users/johntitor/.vimrc;foo=foo&bar=bar&bar=bar"),
+    {
+      scheme: "denops",
+      path: "/Users/johntitor/.vimrc",
+      params: {
+        foo: "foo",
+        bar: ["bar", "bar"],
+      },
+    },
+  );
+
+  assertEquals(
+    parse("denops:///Users/johntitor/.vimrc;foo=foo&bar=bar&bar=bar#README.md"),
+    {
+      scheme: "denops",
+      path: "/Users/johntitor/.vimrc",
+      params: {
+        foo: "foo",
+        bar: ["bar", "bar"],
+      },
+      fragment: "README.md",
+    },
+  );
+}
+```
+
+Note that percent-encoded characters of unusable characters (`"`, `<`, `>`, `|`,
+`?`, `*`) are restored.

denops_std/bufname/bufname.ts

@@ -0,0 +1,119 @@
+import { bufnameUnusablePattern, decode, encode } from "./utils.ts";
+
+export type BufnameParams = Record<string, string | string[] | undefined>;
+
+export type Bufname = {
+  // Scheme part of a buffer name. Note that Vim supports only alphabets in scheme part.
+  scheme: string;
+  // Path part of a buffer name. Note that '<>|?*' are not supported in Vim on Windows.
+  path: string;
+  // Params part of a buffer name. While '?' is not supported, the params part are splitted by ';' instead.
+  params?: BufnameParams;
+  // Fragment part of a buffer name. This is mainly used to regulate the suffix of the buffer name.
+  fragment?: string;
+};
+
+// Vim only supports alphabet characters in the scheme part of a buffer name.
+// That behavior has slightly improved from Vim 8.2.3153 but we suppor Vim 8.2.0662
+// thus we need to stack old behavior
+// https://github.com/vim/vim/pull/8299
+const schemeUnusablePattern = /[^a-zA-Z]/;
+
+// Vim assumes a bufname is URL when it starts with "name://"
+// https://github.com/vim/vim/blob/36698e34aacee4186e6f5f87f431626752fcb337/src/misc1.c#L2567-L2580
+const schemePattern = /^(\S+):\/\//;
+
+// The path part might contains query and/or fragment
+const pathPattern = /^(.*?)(?:;(.*?))?(?:#(.*))?$/;
+
+/**
+ * Format Bufname instance to construct Vim's buffer name.
+ */
+export function format({ scheme, path, params, fragment }: Bufname): string {
+  if (schemeUnusablePattern.test(scheme)) {
+    throw new Error(
+      `Scheme '${scheme}' contains unusable characters. Only alphabets are allowed.`,
+    );
+  }
+  const encodedPath = encode(path).replaceAll(";", "%3b").replaceAll(
+    "#",
+    "%23",
+  );
+  const suffix1 = params
+    ? `;${encode(toURLSearchParams(params).toString())}`
+    : "";
+  const suffix2 = fragment ? `#${encode(fragment)}` : "";
+  return `${scheme}://${encodedPath}${suffix1}${suffix2}`;
+}
+
+/**
+ * Parse Vim's buffer name to construct Bufname instance.
+ */
+export function parse(expr: string): Bufname {
+  if (bufnameUnusablePattern.test(expr)) {
+    throw new Error(
+      `Expression '${expr}' contains unusable characters. Vim (on Windows) does not support '<>|?*' in a buffer name.`,
+    );
+  }
+  // Check if the bufname is remote
+  const m1 = expr.match(schemePattern);
+  if (!m1) {
+    throw new Error(`Expression '${expr}' does not start from '{scheme}://'.`);
+  }
+  const scheme = m1[1];
+  // Vim (less than 8.2.3153) only supports alphabets in scheme part
+  if (schemeUnusablePattern.test(scheme)) {
+    throw new Error(
+      `Scheme '${scheme}' contains unusable characters. Only alphabets are allowed.`,
+    );
+  }
+  const remain = decode(expr.substring(`${scheme}://`.length), [
+    "%3b", // ;
+    "%23", // #
+  ]);
+  const m2 = remain.match(pathPattern)!;
+  const path = decode(m2[1]);
+  const params = m2[2]
+    ? fromURLSearchParams(new URLSearchParams(decode(m2[2])))
+    : undefined;
+  const fragment = m2[3] ? decode(m2[3]) : undefined;
+  return {
+    scheme,
+    path,
+    ...(params ? { params } : {}),
+    ...(fragment ? { fragment } : {}),
+  };
+}
+
+function toURLSearchParams(params: BufnameParams): URLSearchParams {
+  const cs = Object.entries(params).flatMap(
+    ([key, value]): [string, string][] => {
+      if (value == undefined) {
+        return [];
+      } else if (Array.isArray(value)) {
+        return value.map((v) => [key, v]);
+      } else {
+        return [[key, value]];
+      }
+    },
+  );
+  return new URLSearchParams(cs);
+}
+
+function fromURLSearchParams(search: URLSearchParams): BufnameParams {
+  const params: BufnameParams = {};
+  search.forEach((value, key) => {
+    if (Object.prototype.hasOwnProperty.call(params, key)) {
+      const previous = params[key];
+      if (Array.isArray(previous)) {
+        previous.push(value);
+        return;
+      } else if (previous != undefined) {
+        params[key] = [previous, value];
+        return;
+      }
+    }
+    params[key] = value;
+  });
+  return params;
+}