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.

import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
import { format } from "../bufname/mod.ts";

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",
);

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 before when constructing a buffer name from a real path. For example

import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
import * as path from "https://deno.land/std/path/mod.ts";
import { format } from "../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%2520Titor/test.git",
);