Merge pull request #67 from vim-denops/mapping

👍  Add `mapping` module to manage mappings

Author: lambdalisue

denops_std/mapping/README.md

@@ -0,0 +1,87 @@
+# mapping
+
+`mapping` is a module to provide helper functions to manage mappings.
+
+- [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/mapping/mod.ts)
+
+## Usage
+
+### map
+
+Use `map()` to register a mapping like:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import * as mapping from "https://deno.land/x/denops_std/mapping/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  await mapping.map(denops, "<Plug>(test-denops-std)", "Hello");
+  await mapping.map(denops, "<Plug>(test-denops-std)", "Hello", {
+    mode: "i",
+  });
+}
+```
+
+### unmap
+
+Use `unmap()` to unregister a mapping like:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import * as mapping from "https://deno.land/x/denops_std/mapping/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  await mapping.map(denops, "<Plug>(test-denops-std)", "Hello");
+  await mapping.map(denops, "<Plug>(test-denops-std)", "Hello", {
+    mode: "i",
+  });
+
+  await mapping.unmap(denops, "<Plug>(test-denops-std)");
+  await mapping.unmap(denops, "<Plug>(test-denops-std)", {
+    mode: "i",
+  });
+}
+```
+
+### read
+
+Use `read()` to read a mapping like:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import * as mapping from "https://deno.land/x/denops_std/mapping/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  await denops.cmd(`map <Plug>(test-denops-std) Hello`);
+
+  console.log(await mapping.read(denops, "<Plug>(test-denops-std)"));
+  // {
+  //   mode: "",
+  //   lhs: "<Plug>(test-denops-std)",
+  //   rhs: "Hello",
+  //   // ...
+  // }
+}
+```
+
+### list
+
+Use `list()` to list mappings like:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import * as mapping from "https://deno.land/x/denops_std/mapping/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  const result = await mapping.list(denops, "<Plug>");
+  console.log(result);
+  // [
+  //   {
+  //     mode: "",
+  //     lhs: "<Plug>(...)",
+  //     // ...
+  //   },
+  //   // ...
+  // ]
+}
+```

denops_std/mapping/mod.ts

@@ -0,0 +1,111 @@
+import { Denops } from "../deps.ts";
+import * as fn from "../function/mod.ts";
+import { Mapping, Mode } from "./types.ts";
+import { parse } from "./parser.ts";
+
+export type MapOptions = {
+  mode?: Mode;
+  noremap?: boolean;
+  script?: boolean;
+  buffer?: boolean;
+  expr?: boolean;
+  nowait?: boolean;
+  silent?: boolean;
+  unique?: boolean;
+};
+
+/**
+ * Register a mapping for `lhs` to `rhs` with given options.
+ */
+export async function map(
+  denops: Denops,
+  lhs: string,
+  rhs: string,
+  options: MapOptions = {},
+): Promise<void> {
+  const mode = options.mode ?? "";
+  const prefix = options.noremap ? "nore" : "";
+  const arg = [
+    options.buffer ? "<buffer>" : "",
+    options.nowait ? "<nowait>" : "",
+    options.silent ? "<silent>" : "",
+    options.script ? "<script>" : "",
+    options.expr ? "<expr>" : "",
+    options.unique ? "<unique>" : "",
+  ].filter((v) => v).join("");
+  await denops.cmd(`${mode}${prefix}map ${arg} ${lhs} ${rhs}`);
+}
+
+export type UnmapOptions = {
+  mode?: Mode;
+};
+
+/**
+ * Remove a mapping for `lhs`.
+ */
+export async function unmap(
+  denops: Denops,
+  lhs: string,
+  options: UnmapOptions = {},
+): Promise<void> {
+  const mode = options.mode ?? "";
+  await denops.cmd(`${mode}unmap ${lhs}`);
+}
+
+export type ReadOptions = {
+  mode?: Mode;
+};
+
+/**
+ * Read a mapping and return a `Mapping` instance.
+ *
+ * Note that prior to Vim 8.2.0491 or Neovim 0.5.0, `script` is
+ * not detectable by `maparg` function internally used in this
+ * function.
+ */
+export async function read(
+  denops: Denops,
+  lhs: string,
+  options: ReadOptions = {},
+): Promise<Mapping> {
+  const info = await fn.maparg(
+    denops,
+    lhs,
+    options.mode ?? "",
+    false,
+    true,
+  ) as Record<string, unknown>;
+  if (Object.keys(info).length === 0) {
+    throw new Error(`No mapping found for '${lhs}'`);
+  }
+  return {
+    mode: (info.mode as string).trim() as Mode,
+    lhs: info.lhs as string,
+    rhs: info.rhs as string,
+    noremap: !!info.noremap,
+    script: !!info.script,
+    buffer: !!info.buffer,
+    sid: info.sid as number,
+    lnum: info.lnum as number,
+    expr: !!info.expr,
+    nowait: !!info.nowait,
+    silent: !!info.silent,
+  };
+}
+
+export type ListOptions = {
+  mode?: Mode;
+};
+
+/**
+ * List mappings which starts from `lhs`.
+ */
+export async function list(
+  denops: Denops,
+  lhs: string,
+  options: ListOptions = {},
+): Promise<Mapping[]> {
+  const mode = options.mode ?? "";
+  const result = await fn.execute(denops, `${mode}map ${lhs}`) as string;
+  return result.split(/\r?\n/).filter((v) => v).map(parse);
+}