Merge pull request #16 from vim-denops/follow-latest

Update deps to latest

Author: lambdalisue

README.md

@@ -1,17 +1,49 @@
-# 🐜 denops-std-deno
+# 🐜 denops_std
 
-[![deno doc](https://doc.deno.land/badge.svg)](https://doc.deno.land/https/deno.land/x/denops_std/mod.ts)
 [![deno](https://github.com/vim-denops/denops-std-deno/workflows/deno/badge.svg)](https://github.com/vim-denops/denops-std-deno/actions?query=workflow%3Adeno)
+[![deno doc](https://doc.deno.land/badge.svg)](https://doc.deno.land/https/deno.land/x/denops_std/mod.ts)
+[![deno land](http://img.shields.io/badge/available%20on-deno.land/x-lightgrey.svg?logo=deno)](https://deno.land/x/denops_std)
 
 [Deno][deno] module for [denops.vim][denops.vim]. This module is assumed to be
 used in denops plugin and the code is assumed to be called in a worker thread
 for a plugin.
 
-Note that this module focused to provide non-primitive features. See
-[denops-deno](https://github.com/vim-denops/denops-deno) for primitives.
-
 **UNDER DEVELOPMENT**
 
+By using this module, developers can write Vim/Neovim denops plugins like:
+
+```typescript
+import { ensureString, main } from "https://deno.land/x/denops_std/mod.ts";
+
+main(async ({ vim }) => {
+  vim.register({
+    async say(where: unknown): Promise<void> {
+      ensureString(where, "where");
+      const name = await vim.call("input", "Your name: ");
+      const progname = await vim.eval("v:progname");
+      const messages = [
+        `Hello ${where}`,
+        `Your name is ${name}`,
+        `This is ${progname}`,
+      ];
+      await vim.cmd(`redraw | echomsg message`, {
+        message: messages.join(". "),
+      });
+    },
+  });
+
+  await vim.execute(`
+    command! HelloWorld call denops#notify("${vim.name}", "say", ["World"])
+    command! HelloDenops call denops#notify("${vim.name}", "say", ["Denops"])
+  `);
+
+  console.log("denops plugin has loaded");
+});
+```
+
+See [denops-helloworld.vim](https://github.com/denops-helloworld.vim) for more
+details.
+
 [deno]: https://deno.land/
 [denops.vim]: https://github.com/vim-denops/denops.vim
 

deps.ts

@@ -5,5 +5,11 @@ export * as fs from "https://deno.land/std@0.95.0/fs/mod.ts";
 export type {
   Context,
   Dispatcher,
-} from "https://deno.land/x/denops_core@v0.11.0/mod.ts";
-export { Denops } from "https://deno.land/x/denops_core@v0.11.0/mod.ts";
+} from "https://deno.land/x/denops_core@v0.13.0/mod.ts";
+export {
+  Denops,
+  ensureArray,
+  ensureNumber,
+  ensureRecord,
+  ensureString,
+} from "https://deno.land/x/denops_core@v0.13.0/mod.ts";

deps_test.ts

@@ -1 +1 @@
-export * from "https://deno.land/std@0.93.0/testing/asserts.ts";
+export * from "https://deno.land/std@0.95.0/testing/asserts.ts";

mod.ts

@@ -1,5 +1,14 @@
 export { Vim } from "./vim/mod.ts";
 export { main } from "./main.ts";
 
+// Re-export
+export {
+  Denops,
+  ensureArray,
+  ensureNumber,
+  ensureRecord,
+  ensureString,
+} from "./deps.ts";
+
 // Deprecated APIs
 export { start } from "./vim/mod.ts";

vim/execute.ts

@@ -5,19 +5,19 @@ import { Context, Denops } from "../deps.ts";
  */
 export async function execute(
   denops: Denops,
-  command: string | string[],
-  context: Context = {},
+  script: string | string[],
+  ctx: Context = {},
 ): Promise<void> {
-  if (Array.isArray(command)) {
-    context = {
-      ...context,
-      __denops_internal_command: command
+  if (Array.isArray(script)) {
+    ctx = {
+      ...ctx,
+      __denops_internal_command: script
         .map((x) => x.replace(/^\s+|\s+$/g, ""))
         .filter((x) => !!x),
     };
-    await denops.cmd("call execute(l:__denops_internal_command, '')", context);
+    await denops.cmd("call execute(l:__denops_internal_command, '')", ctx);
     return;
   }
-  command = command.replace(/\r?\n\s*\\/g, "");
-  await execute(denops, command.split(/\r?\n/g), context);
+  script = script.replace(/\r?\n\s*\\/g, "");
+  await execute(denops, script.split(/\r?\n/g), ctx);
 }

vim/vim.ts

@@ -4,6 +4,14 @@ import { autocmd, AutocmdHelper } from "./autocmd.ts";
 import { VariableHelper } from "./variable.ts";
 import { load } from "./load.ts";
 
+/**
+ * Vim is a facade instance visible from each denops plugins for
+ *
+ * 1. Communicate with other plugins
+ * 2. Communicate with the host (Vim/Neovim)
+ * 3. Register them msgpack-rpc APIs
+ *
+ */
 export class Vim {
   private static instance?: Vim;
 
@@ -24,47 +32,93 @@ export class Vim {
     this.v = new VariableHelper(denops, "v");
   }
 
+  /**
+   * Get thread-local Vim instance.
+   */
   static get(): Vim {
     if (!Vim.instance) {
       Vim.instance = new Vim(Denops.get());
     }
     return Vim.instance;
   }
 
+  /**
+   * Plugin name
+   */
   get name(): string {
     return this.#denops.name;
   }
 
+  /**
+   * Call an arbitrary function of Vim/Neovim and return the result
+   *
+   * @param fn: A function name of Vim/Neovim.
+   * @param args: Arguments of the function.
+   */
   async call(func: string, ...args: unknown[]): Promise<unknown> {
     return await this.#denops.call(func, ...args);
   }
 
-  async cmd(cmd: string, context: Context = {}): Promise<void> {
-    await this.#denops.cmd(cmd, context);
+  /**
+   * Execute an arbitrary command of Vim/Neovim under a given context.
+   *
+   * @param cmd: A command expression to be executed.
+   * @param ctx: A context object which is expanded to the local namespace (l:)
+   */
+  async cmd(cmd: string, ctx: Context = {}): Promise<void> {
+    await this.#denops.cmd(cmd, ctx);
   }
 
-  async eval(expr: string, context: Context = {}): Promise<unknown> {
-    return await this.#denops.eval(expr, context);
+  /**
+   * Evaluate an arbitrary expression of Vim/Neovim under a given context and return the result.
+   *
+   * @param expr: An expression to be evaluated.
+   * @param ctx: A context object which is expanded to the local namespace (l:)
+   */
+  async eval(expr: string, ctx: Context = {}): Promise<unknown> {
+    return await this.#denops.eval(expr, ctx);
   }
 
+  /**
+   * Execute an arbitrary Vim script under a given context.
+   *
+   * @param script: A script to be executed. Can be string or string list.
+   * @param ctx: A context object which is expanded to the local namespace (l:)
+   */
   async execute(
-    command: string | string[],
-    context: Context = {},
+    script: string | string[],
+    ctx: Context = {},
   ): Promise<void> {
-    await execute(this.#denops, command, context);
+    await execute(this.#denops, script, ctx);
   }
 
+  /**
+   * Define autocmd in autocmd group.
+   *
+   * @param group: An autocmd group name.
+   * @param main: A function which is used to define autocmds.
+   */
   async autocmd(
     group: string,
     main: (helper: AutocmdHelper) => void,
   ): Promise<void> {
     await autocmd(this.#denops, group, main);
   }
 
+  /**
+   * Load an arbitrary Vim script from local or remote.
+   *
+   * @param url: An URL to locate the target Vim script.
+   */
   async load(url: URL): Promise<void> {
     await load(this.#denops, url);
   }
 
+  /**
+   * Register plugin APIs
+   *
+   * @param dispatcher: A collection of the plugin APIs
+   */
   register(dispatcher: Dispatcher): void {
     this.#denops.extendDispatcher(dispatcher);
   }