The Format
module is a mostly deprecated module that implements printf()
style formatting for GJS.
In most cases, native template literals should be preferred now, except in few situations like Gettext (See Bug #60027).
const foo = 'Pi';
const bar = 1;
const baz = Math.PI;
// expected result: "Pi to 2 decimal points: 3.14"
// Native template literals
const str1 = `${foo} to ${bar*2} decimal points: ${baz.toFixed(bar*2)}`
// Format.vprintf()
const str2 = Format.vprintf('%s to %d decimal points: %.2f', [foo, bar*2, baz]);
Attention: This module is not available as an ECMAScript Module
The Format
module is available on the global imports
object:
const Format = imports.format;
Deprecated: Use
Format.vprintf()
instead
Type:
- Prototype Function
Parameters:
- args (
Any
) — Formatting substitutions
Returns:
- (
String
) — A new formatted string
This function was intended to extend the String
object and provide a
String.format
API for string formatting.
Example usage:
const Format = imports.format;
// Applying format() to the string prototype.
//
// This is highly discouraged, especially in GNOME Shell extensions where other
// extensions might overwrite it. Use Format.vprintf() directly instead.
String.prototype.format = Format.format;
// Usage with String.prototype.format()
// expected result: "A formatted string"
const str = 'A %s %s'.format('formatted', 'string');
Deprecated: Use template literals with
print()
instead
Type:
- Static
Parameters:
- fmt (
String
) — A format template - args (
Any
) — Formatting substitutions
Substitute the specifiers in fmt
with args
and print the result to stdout
.
Example usage:
// expected output: A formatted string
Format.printf('A %s %s', 'formatted', 'string');
Deprecated: Prefer template literals when possible
Type:
- Static
Parameters:
- fmt (
String
) — A format template - args (
Array(Any)
) — Formatting substitutions
Returns:
- (
String
) — A new formatted string
Substitute the specifiers in fmt
with args
and return a new string. It
supports the %s
, %d
, %x
and %f
specifiers.
For %f
it also supports precisions like vprintf('%.2f', [1.526])
. All
specifiers can be prefixed with a minimum field width (e.g.
vprintf('%5s', ['foo'])
). Unless the width is prefixed with '0'
, the
formatted string will be padded with spaces.
Example usage:
// expected result: "A formatted string"
const str = Format.vprintf('A %s %s', ['formatted', 'string']);
// Usage with Gettext
Format.vprintf(_('%d:%d'), [11, 59]);
Format.vprintf(
Gettext.ngettext('I have %d apple', 'I have %d apples', num), [num]);