[gjs/esm/static-imports: 8/9] esm: Add builtin format module

[Philip Chimento <pchimento src gnome org>]

commit 9b41ea466ebd49b577aa360b1a2b47b878c2e9d1
Author: Evan Welsh <contact evanwelsh com>
Date:   Wed Feb 3 17:03:47 2021 -0800

    esm: Add builtin format module

 doc/ESModules.md      |  5 +++++
 doc/Modules.md        | 24 +++++++++++++++++++++---
 js.gresource.xml      |  1 +
 modules/esm/format.js | 18 ++++++++++++++++++
 4 files changed, 45 insertions(+), 3 deletions(-)
---
diff --git a/doc/ESModules.md b/doc/ESModules.md
index 4adb055f..6ec44528 100644
--- a/doc/ESModules.md
+++ b/doc/ESModules.md
@@ -165,6 +165,11 @@ import system from 'system';
 system.exit(1);
 ```
 
+```js
+import * as format from 'format';
+format.sprintf('Hi %s!', 'Bob');
+```
+
 ```js
 import { ngettext as _ } from 'gettext';
 _('Hello!');
diff --git a/doc/Modules.md b/doc/Modules.md
index c6bdac3e..808b1e82 100644
--- a/doc/Modules.md
+++ b/doc/Modules.md
@@ -92,20 +92,38 @@ drawingArea.connect("draw", (widget, cr) => {
 [cairo-const]: https://gitlab.gnome.org/GNOME/gjs/blob/master/modules/script/cairo.js
 [cairo-func]: https://gitlab.gnome.org/GNOME/gjs/blob/master/modules/cairo-context.cpp#L825
 
-## [Format](https://gitlab.gnome.org/GNOME/gjs/blob/master/modules/script/format.js)
+## [Format](https://gitlab.gnome.org/GNOME/gjs/blob/master/modules/esm/format.js)
 
-**Import with `const Format = imports.format;`**
+**Import with `import format from 'format';`**
 
-The format import is mostly obsolete, providing `vprintf()`, `printf()` and `format()`. Native [template 
literals][template-literals] should be preferred now, except in few situations like Gettext (See [Bug 
#50920][bug-50920]).
+The format module is mostly obsolete, providing only `sprintf()`.
+Native [template literals][template-literals] should be preferred now,
+except in few situations like Gettext (See [Bug #50920][bug-50920]).
+We plan to increase support for template literals in translations so
+`sprintf()` is no longer necessary.
 
 ```js
+import { sprintf } from 'format';
+
+// Using sprintf() (Output: Pi to 2 decimal points: 3.14)
+sprintf("%s to %d decimal points: %.2f", foo, bar*2, baz);
+
+// Using sprintf() with Gettext
+sprintf(_("%d:%d"), 11, 59);
+
 let foo = "Pi";
 let bar = 1;
 let baz = Math.PI;
 
 // Using native template literals (Output: Pi to 2 decimal points: 3.14)
 `${foo} to ${bar*2} decimal points: ${baz.toFixed(bar*2)}`
+```
 
+### [Deprecated Functions](https://gitlab.gnome.org/GNOME/gjs/blob/master/modules/script/format.js)
+
+**Import with `const Format = imports.format;`**
+
+```js
 // Applying format() to the string prototype
 const Format = imports.format;
 String.prototype.format = Format.format;
diff --git a/js.gresource.xml b/js.gresource.xml
index adc8edde..f1bd056c 100644
--- a/js.gresource.xml
+++ b/js.gresource.xml
@@ -11,6 +11,7 @@
 
     <!-- ESM-based modules -->
     <file>modules/esm/cairo.js</file>
+    <file>modules/esm/format.js</file>
     <file>modules/esm/gettext.js</file>
     <file>modules/esm/gi.js</file>
     <file>modules/esm/system.js</file>
diff --git a/modules/esm/format.js b/modules/esm/format.js
new file mode 100644
index 00000000..626c5932
--- /dev/null
+++ b/modules/esm/format.js
@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT OR LGPL-2.0-or-later
+// SPDX-FileCopyrightText: 2020 Evan Welsh <contact evanwelsh com>
+
+const {vprintf} = imports._format;
+
+/**
+ * @param {string} str the string to format (e.g. '%s is blue')
+ * @param {any...} args the arguments to replace placeholders with
+ */
+export function sprintf(str, ...args) {
+    return vprintf(str, args);
+}
+
+export let _ = {
+    sprintf,
+};
+
+export default _;