👍 Add argument module

Author: lambdalisue

denops_std/README.md

@@ -54,15 +54,16 @@ for more details.
 
 ## Index
 
-| Name                       | Description                                                      |
-| -------------------------- | ---------------------------------------------------------------- |
-| [`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()`        |
-| [`buffer`](./buffer)       | A module to provide helper functions to manage buffers           |
-| [`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          |
-| [`option`](./option)       | A module to provide helper functions to manage options           |
-| [`variable`](./variable)   | A module to provide helper accessor functions to variables       |
+| Name                       | Description                                                            |
+| -------------------------- | ---------------------------------------------------------------------- |
+| [`anonymous`](./anonymous) | A module to provide anonymous function                                 |
+| [`argument`](./argument)   | A module to provide helper functions to manage Vim's command arguments |
+| [`autocmd`](./autocmd)     | A module to provide helper functions to manage `autocmd`               |
+| [`batch`](./batch)         | A module to provide wrapper functions of `denops.batch()`              |
+| [`buffer`](./buffer)       | A module to provide helper functions to manage buffers                 |
+| [`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                |
+| [`option`](./option)       | A module to provide helper functions to manage options                 |
+| [`variable`](./variable)   | A module to provide helper accessor functions to variables             |

denops_std/argument/README.md

@@ -0,0 +1,127 @@
+# argument
+
+`argument` is a module to handle Vim's command arguments.
+
+- [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/argument/mod.ts)
+
+## Usage
+
+### parse/parseOpts/parseFlags
+
+Use `parse()`, `parseOpts`, or `parseFlags` to parse Vim's command arguments
+like:
+
+```typescript
+import { Denops } from "../mod.ts";
+import { parse, parseFlags, parseOpts } from "../argument/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  const args = [
+    "++enc=sjis",
+    "++ff=dos",
+    "-f",
+    "--foo=foo",
+    "--bar=bar",
+    "--bar=baz",
+    "hello",
+    "world",
+  ];
+  const [opts, flags, residues] = parse(args);
+  // Or use parseOpts/parseFlags instead
+  //const [opts, residues] = parseOpts(args);
+  //const [flags, residues] = parseFlags(args);
+
+  console.log(opts);
+  // { "enc": "sjis", "ff": "dos" }
+
+  console.log(flags);
+  // { "f": "", "foo": "foo", "bar": ["bar", "baz"] }
+
+  console.log(residues);
+  // ["hello", "world"]
+}
+```
+
+### validateOpts/validateFlags
+
+Use `validateOpts` or `validateFlags` to validate if `opts` or `flags` has
+unknown attributes like:
+
+```typescript
+import { Denops } from "../mod.ts";
+import {
+  builtinOpts,
+  parse,
+  validateFlags,
+  validateOpts,
+} from "../argument/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  const args = [
+    "++enc=sjis",
+    "++ff=dos",
+    "-f",
+    "--foo=foo",
+    "--bar=bar",
+    "--bar=baz",
+    "hello",
+    "world",
+  ];
+  const [opts, flags, residues] = parse(args);
+
+  validateOpts(opts, ["enc", "ff"]);
+  // Or use `builtinOpts` to validate Vim's builtin `++opts`
+  //validateOpts(opts, builtinOpts);
+
+  validateFlags(flags, ["f", "foo", "bar"]);
+}
+```
+
+### formatOpt/formatFlag
+
+Use `formatOpt` or `formatFlag` to format `key` and `value` pair like:
+
+```typescript
+import { Denops } from "../mod.ts";
+import { formatFlag, formatOpt } from "../argument/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  console.log(formatOpt("enc", "sjis"));
+  // "++enc=sjis"
+
+  console.log(formatFlag("f", ""));
+  // "-f"
+
+  console.log(formatFlag("foo", "value"));
+  // "--foo=value"
+}
+```
+
+### formatOpts/formatFlags
+
+Use `formatOpts` or `formatFlags` to format `opts` or `flags` like:
+
+```typescript
+import { Denops } from "../mod.ts";
+import { formatFlags, formatOpts, parse } from "../argument/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  const args = [
+    "++enc=sjis",
+    "++ff=dos",
+    "-f",
+    "--foo=foo",
+    "--bar=bar",
+    "--bar=baz",
+    "hello",
+    "world",
+  ];
+  const [opts, flags, residues] = parse(args);
+
+  console.log(formatOpts(opts));
+  // "++enc=sjis ++ff=dos"
+
+  console.log(formatFlags(flags));
+  // "-f --foo=foo --bar=bar --bar=baz"
+}
+```

denops_std/argument/flags.ts

@@ -0,0 +1,82 @@
+import { parsePattern } from "./util.ts";
+
+export type Flags = Record<string, string | string[] | undefined>;
+
+const longPattern = /^--([a-zA-Z0-9-]+)(?:=(.*))?/;
+const shortPattern = /^-([a-zA-Z0-9])(.*)/;
+
+/**
+ * Parse string array to extract flags (-f/--flag).
+ */
+export function parseFlags(args: string[]): [Flags, string[]] {
+  const patterns = [longPattern, shortPattern];
+  const flags: Flags = {};
+  const residue: string[] = [];
+  loop:
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--") {
+      residue.push(...args.slice(i));
+      break;
+    }
+    for (const pattern of patterns) {
+      const r = parsePattern(arg, pattern);
+      if (r) {
+        const [k, v] = r;
+        const b = flags[k];
+        if (b != undefined) {
+          flags[k] = Array.isArray(b) ? [...b, v] : [b, v];
+        } else {
+          flags[k] = v;
+        }
+        continue loop;
+      }
+    }
+    residue.push(arg);
+  }
+  return [flags, residue];
+}
+
+/**
+ * Validate if `flags` has unknown attributes.
+ */
+export function validateFlags(flags: Flags, knownAttributes: string[]): void {
+  Object.keys(flags).forEach((v) => {
+    if (!knownAttributes.includes(v)) {
+      if (v.length === 1) {
+        throw new Error(`Unknown flag '-${v}' is specified.`);
+      } else {
+        throw new Error(`Unknown flag '--${v}' is specified.`);
+      }
+    }
+  });
+}
+
+/**
+ * Format `key` and `value` to construct string array.
+ */
+export function formatFlag(
+  key: string,
+  value: string | string[] | undefined,
+): string[] {
+  if (value == undefined) {
+    return [];
+  }
+  value = Array.isArray(value) ? value : [value];
+  if (key.length === 1) {
+    return value.map((v) => v ? `-${key}${v}` : `-${key}`);
+  } else {
+    return value.map((v) => v ? `--${key}=${v}` : `--${key}`);
+  }
+}
+
+/**
+ * Format `flags` to construct string array.
+ */
+export function formatFlags(flags: Flags, includes?: string[]): string[] {
+  let entries = Object.entries(flags);
+  if (includes != undefined) {
+    entries = entries.filter(([k, _]) => includes.includes(k));
+  }
+  return entries.map(([k, v]) => formatFlag(k, v)).flat();
+}

denops_std/argument/flags_test.ts

@@ -0,0 +1,41 @@
+import { assertEquals } from "https://deno.land/std@0.133.0/testing/asserts.ts";
+import { parseFlags } from "./flags.ts";
+
+Deno.test("parseFlags", () => {
+  const [flags, residue] = parseFlags([
+    "Gin",
+    "++buffer",
+    "status",
+    "++ff=mac",
+    "-unormal",
+    "++enc=utf-8",
+    "--ignore-submodules=all",
+    "--ignore",
+    "-v",
+    "autoload/gin.vim",
+    "--",
+    "++buffer",
+    "-v",
+    "--ignore",
+    "autoload/gin/debug.vim",
+  ]);
+  assertEquals(flags, {
+    u: "normal",
+    "ignore-submodules": "all",
+    ignore: "",
+    v: "",
+  });
+  assertEquals(residue, [
+    "Gin",
+    "++buffer",
+    "status",
+    "++ff=mac",
+    "++enc=utf-8",
+    "autoload/gin.vim",
+    "--",
+    "++buffer",
+    "-v",
+    "--ignore",
+    "autoload/gin/debug.vim",
+  ]);
+});

denops_std/argument/mod.ts

@@ -0,0 +1,11 @@
+import { Opts, parseOpts } from "./opts.ts";
+import { Flags, parseFlags } from "./flags.ts";
+
+export function parse(args: string[]): [Opts, Flags, string[]] {
+  const [opts, intermediate] = parseOpts(args);
+  const [flags, residue] = parseFlags(intermediate);
+  return [opts, flags, residue];
+}
+
+export * from "./opts.ts";
+export * from "./flags.ts";

denops_std/argument/mod_test.ts

@@ -0,0 +1,69 @@
+import { assertEquals } from "https://deno.land/std@0.133.0/testing/asserts.ts";
+import { parse } from "./mod.ts";
+
+Deno.test("parse", () => {
+  const [opts, flags, residue] = parse([
+    "Gin",
+    "++buffer",
+    "status",
+    "++ff=mac",
+    "-unormal",
+    "++enc=utf-8",
+    "--ignore-submodules=all",
+    "--ignore",
+    "-v",
+    "autoload/gin.vim",
+    "--",
+    "++buffer",
+    "-v",
+    "--ignore",
+    "autoload/gin/debug.vim",
+  ]);
+  assertEquals(opts, {
+    buffer: "",
+    ff: "mac",
+    enc: "utf-8",
+  });
+  assertEquals(flags, {
+    u: "normal",
+    "ignore-submodules": "all",
+    ignore: "",
+    v: "",
+  });
+  assertEquals(residue, [
+    "Gin",
+    "status",
+    "autoload/gin.vim",
+    "--",
+    "++buffer",
+    "-v",
+    "--ignore",
+    "autoload/gin/debug.vim",
+  ]);
+});
+
+Deno.test("parse (README)", () => {
+  const [opts, flags, residue] = parse([
+    "++enc=sjis",
+    "++ff=dos",
+    "-f",
+    "--foo=foo",
+    "--bar=bar",
+    "--bar=baz",
+    "hello",
+    "world",
+  ]);
+  assertEquals(opts, {
+    enc: "sjis",
+    ff: "dos",
+  });
+  assertEquals(flags, {
+    f: "",
+    foo: "foo",
+    bar: ["bar", "baz"],
+  });
+  assertEquals(residue, [
+    "hello",
+    "world",
+  ]);
+});