👍 Add ways to silence echo and echoerr

Author: lambdalisue

denops_std/helper/README.md

@@ -25,9 +25,71 @@ export async function main(denops: Denops): Promise<void> {
 ##### Warning
 
 In order to make the behavior of Vim and Neovim consistent, `timer_start()` is
-used internally not only in Vim but also in Neovim. Note that this means that it
-is not possible to control messages by prepending `silent` to them. Developers
-must control the display of messages by not calling this function.
+used internally not only in Vim but also in Neovim. Note that this means that
+you cannot control the message by prepending `silent` when calling it from the
+Vim script. If you want to control the message, use the `setSilent` function to
+change the silent state to `'silent'` or `'silent!'` in advance, or use the
+`ensureSilent` function to fix the silent state to `'silent'` or `'silent!'`
+during execution of any function.
+
+### setSilent / getSilent
+
+By setting the silent state with `setSilent`, you can control `silent` and
+`silent!` messages as follows.
+
+```typescript
+import { Denops } from "../mod.ts";
+import { echo, echoerr, getSilent, setSilent } from "../helper/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  // Because silent is "silent!", `echo` and `echoerr` doesn't show messages.
+  setSilent(denops, "silent!");
+  await echo(denops, "Hello\nWorld!");
+  await echoerr(denops, "This is error message");
+
+  // Because silent is "silent", `echo` doesn't show messages.
+  setSilent(denops, "silent");
+  await echo(denops, "Hello\nWorld!");
+  await echoerr(denops, "This is error message");
+
+  // Because silent is "", both show messages.
+  setSilent(denops, "");
+  await echo(denops, "Hello\nWorld!");
+  await echoerr(denops, "This is error message");
+}
+```
+
+Use the `getSilent()` function to get the current silent state.
+
+### ensureSilent
+
+To control `silent` and `silent!` messages while executing a particular
+function, use `ensureSilent` as follows
+
+```typescript
+import { Denops } from "../mod.ts";
+import { echo, echoerr, ensureSilent } from "../helper/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  // Because silent is "silent!", `echo` and `echoerr` doesn't show messages.
+  await ensureSilent(denops, "silent!", async () => {
+    await echo(denops, "Hello\nWorld!");
+    await echoerr(denops, "This is error message");
+  });
+
+  // Because silent is "silent", `echo` doesn't show messages.
+  await ensureSilent(denops, "silent", async () => {
+    await echo(denops, "Hello\nWorld!");
+    await echoerr(denops, "This is error message");
+  });
+
+  // Because silent is "", both shows messages.
+  await ensureSilent(denops, "", async () => {
+    await echo(denops, "Hello\nWorld!");
+    await echoerr(denops, "This is error message");
+  });
+}
+```
 
 ### friendlyCall
 

denops_std/helper/echo.ts

@@ -4,6 +4,7 @@ import { batch } from "../batch/mod.ts";
 import { generateUniqueString } from "../util.ts";
 
 const cacheKey = Symbol("denops_std/helper/echo");
+const cacheKeySilent = Symbol("denops_std/helper/echo/silent");
 const suffix = generateUniqueString();
 
 async function ensurePrerequisites(denops: Denops): Promise<string> {
@@ -28,6 +29,39 @@ async function ensurePrerequisites(denops: Denops): Promise<string> {
   return suffix;
 }
 
+export type Silent = "" | "silent" | "silent!";
+
+/**
+ * Get global silent status
+ */
+export function getSilent(denops: Denops): Silent {
+  return (denops.context[cacheKeySilent] ?? "") as Silent;
+}
+
+/**
+ * Set global silent status
+ */
+export function setSilent(denops: Denops, silent: Silent): void {
+  denops.context[cacheKeySilent] = silent;
+}
+
+/**
+ * Ensure global silent status during given function
+ */
+export async function ensureSilent<T>(
+  denops: Denops,
+  silent: Silent,
+  executor: () => T,
+): Promise<T> {
+  const saved = denops.context[cacheKeySilent];
+  denops.context[cacheKeySilent] = silent;
+  try {
+    return await executor();
+  } finally {
+    denops.context[cacheKeySilent] = saved;
+  }
+}
+
 /**
  * Echo message as like `echo` on Vim script.
  *
@@ -40,32 +74,66 @@ async function ensurePrerequisites(denops: Denops): Promise<string> {
  * running as 'test' mode to avoid unwilling test failures.
  *
  * WARNING:
- * In order to make the behavior of Vim and Neovim consistent, `timer_start()`
- * is used internally not only in Vim but also in Neovim. Note that this
- * means that it is not possible to control messages by prepending `silent`
- * to them. Developers must control the display of messages by not calling this
- * function.
+ * In order to make the behavior of Vim and Neovim consistent,
+ * `timer_start()` is used internally not only in Vim but also in
+ * Neovim. Note that this means that you cannot control the message
+ * by prepending `silent` when calling it from the Vim script.
+ * If you want to control the message, use the `setSilent` function
+ * to change the silent state to `'silent'` or `'silent!'` in
+ * advance, or use the `ensureSilent` function to fix the silent state
+ * to `'silent'` or `'silent!'` during execution of any function.
  */
-export function echo(denops: Denops, message: string): Promise<void> {
+export function echo(
+  denops: Denops,
+  message: string,
+): Promise<void> {
+  const silent = getSilent(denops);
+  switch (silent) {
+    case "silent":
+    case "silent!":
+      return Promise.resolve();
+  }
   if (denops.meta.mode === "test") {
     return Promise.resolve();
   } else {
-    return echoVim(denops, message);
+    return echoInternal(denops, message);
   }
 }
 
 /**
  * Echo message as an error message.
  *
- * Note that this function just use ErrorMsg highlight and is not equivalent
- * to `echoerr` command in Vim/Neovim.
+ * Note that this function just use ErrorMsg highlight and is not
+ * equivalent to `echoerr` command in Vim/Neovim.
+ *
+ * WARNING:
+ * In order to make the behavior of Vim and Neovim consistent,
+ * `timer_start()` is used internally not only in Vim but also in
+ * Neovim. Note that this means that you cannot control the message
+ * by prepending `silent` when calling it from the Vim script.
+ * If you want to control the message, use the `setSilent` function
+ * to change the silent state to `'silent!'` in advance, or use the
+ * `ensureSilent` function to fix the silent state to `'silent!'`
+ * during execution of any function.
  */
-export async function echoerr(denops: Denops, message: string): Promise<void> {
-  await batch(denops, async (denops) => {
-    await denops.cmd("echohl ErrorMsg");
-    await echo(denops, message);
-    await denops.cmd("echohl None");
-  });
+export async function echoerr(
+  denops: Denops,
+  message: string,
+): Promise<void> {
+  const silent = getSilent(denops);
+  switch (silent) {
+    case "silent!":
+      return Promise.resolve();
+  }
+  if (denops.meta.mode === "test") {
+    return Promise.resolve();
+  } else {
+    await batch(denops, async (denops) => {
+      await denops.cmd("echohl ErrorMsg");
+      await echoInternal(denops, message);
+      await denops.cmd("echohl None");
+    });
+  }
 }
 
 /**
@@ -92,7 +160,7 @@ export async function friendlyCall(
   }
 }
 
-async function echoVim(denops: Denops, message: string): Promise<void> {
+async function echoInternal(denops: Denops, message: string): Promise<void> {
   const suffix = await ensurePrerequisites(denops);
   await denops.call(`DenopsStdHelperEcho_${suffix}`, message);
 }