Merge pull request #98 from vim-denops/imp-bufname

💥 Improve `bufname` module (with breaking changes)

Author: lambdalisue

denops_std/bufname/README.md

@@ -1,9 +1,50 @@
 # bufname
 
-`bufname` is a module to provide manage Vim's buffer name.
+`bufname` is a module to provide functions to handle Vim's buffer name.
 
 - [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/bufname/mod.ts)
 
+The format of the buffer name assumed in this module is like
+
+```text
+{scheme}://{expr}[;{params}][#{fragment}]
+```
+
+Where
+
+- `{scheme}` is used to distinguish a buffer kind. It contains only alphabet
+  characters.
+- `{expr}` is used to identify a buffer itself. _Unusable characters_,
+  semicolons (;), and sharps (#) are replaced with percent-encoded characters.
+- `{params}` (Optional) is used to add meta information to the buffer name like
+  query parameters of URL. _Unusable characters_ and sharps (#) are replaced
+  with percent-encoded characters.
+- `{fragment}` (Optional) is used to add a suffix to the buffer name for file
+  type detection or so on. _Unusable characters_ are replaced with
+  percent-encoded characters.
+- _Unusable characters_ are `"`, `<`, `>`, `|`, `?`, or `*`. It is caused by the
+  limitations of Vim on Windows.
+
+For example,
+
+```text
+denops:///Users/John Titor/test.git
+└─┬──┘   └───────────┬────────────┘
+  scheme             expr
+
+denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2
+└─┬──┘   └───────────┬────────────┘ └───────────┬───────────┘
+  scheme             expr                       params
+
+denops:///Users/John Titor/test.git#README.md
+└─┬──┘   └───────────┬────────────┘ └───┬───┘
+  scheme             expr               fragment
+
+denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md
+└─┬──┘   └───────────┬────────────┘ └───────────┬───────────┘ └───┬───┘
+  scheme             expr                       params            fragment
+```
+
 ## Usage
 
 ### format
@@ -13,88 +54,144 @@ 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",
-  );
-}
+assertEquals(
+  format({
+    scheme: "denops",
+    expr: "/Users/John Titor/test.git",
+  }),
+  "denops:///Users/John Titor/test.git",
+);
+
+assertEquals(
+  format({
+    scheme: "denops",
+    expr: "/Users/John Titor/test.git",
+    params: {
+      foo: "foo",
+      bar: ["bar1", "bar2"],
+    },
+  }),
+  "denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2",
+);
+
+assertEquals(
+  format({
+    scheme: "denops",
+    expr: "/Users/John Titor/test.git",
+    fragment: "README.md",
+  }),
+  "denops:///Users/John Titor/test.git#README.md",
+);
+
+assertEquals(
+  format({
+    scheme: "denops",
+    expr: "/Users/John Titor/test.git",
+    params: {
+      foo: "foo",
+      bar: ["bar1", "bar2"],
+    },
+    fragment: "README.md",
+  }),
+  "denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md",
+);
 ```
 
-Note that unusable characters (`"`, `<`, `>`, `|`, `?`, `*`) are replaced with
-percent-encoded characters.
+This function does not handle path separator differences among platforms (Unix
+uses `/` but Windows uses `\`). That's why it's recommended to normalize the
+`expr` with [`toFileUrl`](https://deno.land/std/path#tofileurl) before when
+constructing a buffer name from a real path. For example
+
+```typescript
+import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+import * as path from "https://deno.land/std/path/mod.ts";
+import { format } from "https://deno.land/x/denops_std/bufname/mod.ts";
+
+// NOTE:
+// Works only on Windows (Use path.win32.toFileUrl instead on other platforms)
+assertEquals(
+  format({
+    scheme: "denops",
+    expr: path.toFileUrl("C:\\Users\John Titor\test.git").pathname,
+  }),
+  "denops:///C:/Users/John%20Titor/test.git",
+);
+```
 
 ### 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"), {
+assertEquals(
+  parse("denops:///Users/John Titor/test.git"),
+  {
     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"],
-      },
+    expr: "/Users/John Titor/test.git",
+  },
+);
+
+assertEquals(
+  parse("denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2"),
+  {
+    scheme: "denops",
+    expr: "/Users/John Titor/test.git",
+    params: {
+      foo: "foo",
+      bar: ["bar1", "bar2"],
     },
-  );
-
-  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",
+  },
+);
+
+assertEquals(
+  parse("denops:///Users/John Titor/test.git#README.md"),
+  {
+    scheme: "denops",
+    expr: "/Users/John Titor/test.git",
+    fragment: "README.md",
+  },
+);
+
+assertEquals(
+  parse(
+    "denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md",
+  ),
+  {
+    scheme: "denops",
+    expr: "/Users/John Titor/test.git",
+    params: {
+      foo: "foo",
+      bar: ["bar1", "bar2"],
     },
-  );
-}
+    fragment: "README.md",
+  },
+);
 ```
 
-Note that percent-encoded characters of unusable characters (`"`, `<`, `>`, `|`,
-`?`, `*`) are restored.
+This function does not handle path separator differences among platforms. That's
+why it's recommended to restore the `expr` with
+[`fromFileUrl`](https://deno.land/std/path#fromfileurl) after if a buffer name
+was constructed from a real path. For example
+
+```typescript
+import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+import * as path from "https://deno.land/std/path/mod.ts";
+import { parse } from "https://deno.land/x/denops_std/bufname/mod.ts";
+
+const bufname = parse("denops:///C:/Users/John%20Titor/test.git");
+assertEquals(bufname, {
+  scheme: "denops",
+  expr: "/C:/Users/John Titor/test.git",
+});
+// NOTE:
+// Works only on Windows (Use path.win32.fromFileUrl instead on other platforms)
+assertEquals(
+  path.fromFileUrl(`file://${bufname.expr}`),
+  "C:\\Users\\John Titor\\test.git",
+);
+```

denops_std/bufname/bufname.ts

@@ -5,8 +5,8 @@ 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;
+  // Expression part of a buffer name. Note that '<>|?*' are not supported in Vim on Windows.
+  expr: 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.
@@ -23,19 +23,28 @@ const schemeUnusablePattern = /[^a-zA-Z]/;
 // 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 = /^(.*?)(?:;(.*?))?(?:#(.*))?$/;
+// The expr part might contains query and/or fragment
+const exprPattern = /^(.*?)(?:;(.*?))?(?:#(.*))?$/;
 
 /**
- * Format Bufname instance to construct Vim's buffer name.
+ * Format a `Bufname` instance and return a safe string as Vim's buffer name.
+ *
+ * It throws errors when `scheme` contains unusable characters (non-alphabet characters).
+ *
+ * All unusable characters ("<>|?*) are replaced with percent-encoded characters.
+ * In addition to the above, all semicolons (;) and sharps (#) in `path` are replaced with
+ * percent-encoded characters. It's required to distinguish `params` and or `fragment`.
+ * ```
  */
-export function format({ scheme, path, params, fragment }: Bufname): string {
+export function format(
+  { scheme, expr, 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(
+  const encodedPath = encode(expr).replaceAll(";", "%3B").replaceAll(
     "#",
     "%23",
   );
@@ -47,18 +56,23 @@ export function format({ scheme, path, params, fragment }: Bufname): string {
 }
 
 /**
- * Parse Vim's buffer name to construct Bufname instance.
+ * Parse Vim's buffer name and return a `Bufname` instance.
+ *
+ * It throws errors when a given `bufname` is not valid Vim's buffer name.
+ * For example, if it contains unusable characters ("<>|?*).
  */
-export function parse(expr: string): Bufname {
-  if (bufnameUnusablePattern.test(expr)) {
+export function parse(bufname: string): Bufname {
+  if (bufnameUnusablePattern.test(bufname)) {
     throw new Error(
-      `Expression '${expr}' contains unusable characters. Vim (on Windows) does not support '<>|?*' in a buffer name.`,
+      `A buffer name '${bufname}' contains unusable characters. Vim (on Windows) does not support '<>|?*' in a buffer name.`,
     );
   }
   // Check if the bufname is remote
-  const m1 = expr.match(schemePattern);
+  const m1 = bufname.match(schemePattern);
   if (!m1) {
-    throw new Error(`Expression '${expr}' does not start from '{scheme}://'.`);
+    throw new Error(
+      `A buffer name '${bufname}' does not start from '{scheme}://'.`,
+    );
   }
   const scheme = m1[1];
   // Vim (less than 8.2.3153) only supports alphabets in scheme part
@@ -67,19 +81,19 @@ export function parse(expr: string): Bufname {
       `Scheme '${scheme}' contains unusable characters. Only alphabets are allowed.`,
     );
   }
-  const remain = decode(expr.substring(`${scheme}://`.length), [
-    "%3b", // ;
+  const remain = decode(bufname.substring(`${scheme}://`.length), [
+    "%3B", // ;
     "%23", // #
   ]);
-  const m2 = remain.match(pathPattern)!;
-  const path = decode(m2[1]);
+  const m2 = remain.match(exprPattern)!;
+  const expr = 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,
+    expr,
     ...(params ? { params } : {}),
     ...(fragment ? { fragment } : {}),
   };