Switch print/embed to async (#13104)

docs/plugins.md

@@ -196,8 +196,10 @@ function print(
   path: AstPath,
   options: object,
   // Recursively print a child node
-  print: (selector?: string | number | Array<string | number> | AstPath) => Doc
-): Doc;
+  print: (
+    selector?: string | number | Array<string | number> | AstPath
+  ) => Promise<Doc>
+): Promise<Doc>;
 ```
 
 The `print` function is passed the following parameters:
@@ -209,18 +211,18 @@ The `print` function is passed the following parameters:
 Here’s a simplified example to give an idea of what a typical implementation of `print` looks like:
 
 ```js
-const {
-  builders: { group, indent, join, line, softline },
-} = require("prettier").doc;
+import { doc } from "prettier";
 
-function print(path, options, print) {
+const { group, indent, join, line, softline } = doc.builders;
+
+async function print(path, options, print) {
   const node = path.getValue();
 
   switch (node.type) {
     case "list":
       return group([
         "(",
-        indent([softline, join(line, path.map(print, "elements"))]),
+        indent([softline, join(line, await path.map(print, "elements"))]),
         softline,
         ")",
       ]);
@@ -228,7 +230,13 @@ function print(path, options, print) {
     case "pair":
       return group([
         "(",
-        indent([softline, print("left"), line, ". ", print("right")]),
+        indent([
+          softline,
+          await print("left"),
+          line,
+          ". ",
+          await print("right"),
+        ]),
         softline,
         ")",
       ]);
@@ -252,13 +260,15 @@ function embed(
   // Path to the current AST node
   path: AstPath,
   // Print a node with the current printer
-  print: (selector?: string | number | Array<string | number> | AstPath) => Doc,
+  print: (
+    selector?: string | number | Array<string | number> | AstPath
+  ) => Promise<Doc>,
   // Parse and print some text using a different parser.
   // You should set `options.parser` to specify which parser to use.
-  textToDoc: (text: string, options: object) => Doc,
+  textToDoc: (text: string, options: object) => Promise<Doc>,
   // Current options
   options: object
-): Doc | null;
+): Promise<Doc | null>;
 ```
 
 The `embed` function acts like the `print` function, except that it is passed an additional `textToDoc` function, which can be used to render a doc using a different plugin. The `embed` function returns a Doc or a falsy value. If a falsy value is returned, the `print` function is called with the current `path`. If a Doc is returned, that Doc is used in printing and the `print` function is not called.
@@ -452,9 +462,10 @@ function isPreviousLineEmpty<N>(text: string, node: N, locStart: (node: N) => nu
 Since plugins can be resolved using relative paths, when working on one you can do:
 
 ```js
-const prettier = require("prettier");
+import * as prettier from "prettier";
+
 const code = "(add 1 2)";
-prettier.format(code, {
+await prettier.format(code, {
   parser: "lisp",
   plugins: ["."],
 });