Fōmatto provides leightweight string interpolation and formatting for JavaScript.
The library brings with it the Formatter
factory and the FormatError
.
This repository is a fork of this repo. I decided to fork that because I needed to use the latest version 0.6 of the module via NPM.
In order to use Fōmatto it is necessary to create a format
function with the
Formatter
factory.
Formatter([formats])
format(template, arg1[, arg2, arg3, ...argN])
The format
function takes a template and either multiple arguments,
an array or array like object (an object with a length
property of type
Number
) or a standard object as its arguments.
> format('Good {} Sir {}.', 'morning', 'Lancelot')
'Good morning Sir Lancelot.'
> format('Good {0} Sir {1}.', 'morning', 'Lancelot')
'Good morning Sir Lancelot.'
> format('Good {time} Sir {name}.', 'morning', 'Lancelot')
'Good morning Sir Lancelot.'
> format('Good {0} Sir {1}.', ['morning', 'Lancelot'])
'Good morning Sir Lancelot.'
> format('Good {time} Sir {name}.', {time: 'morning', name: 'Lancelot'})
'Good morning Sir Lancelot.'
> format('Good {0} Sir {1}.', {0: 'morning', 1: 'Lancelot', length: 2})
'Good morning Sir Lancelot.'
String templates contain placeholders wrapped in {}
. There are a number of
different ways in which these placeholders can be used to insert data into a
template.
-
Auto indexes via
{}
, these automatically insert the next item from an array or a list of arguments. -
Positive
{1}
or negative{-1}
indexes, these will insert the Nth or length + Nth index of an array or a list of arguments. -
Property access via
{name}
, these will either insert the corresponding property of an object or behave like auto indexes in case of an array or a list of arguments. -
Complex property access via
{users.names[2]['first']}
, these will query an object for the specified property and throw aFormatError
in case the property could not be resolved.
By appending a semicolon at the end of a placeholder it is possible to apply a formatting function to the value before it is inserted.
> format('{0:upper}!', 'banana')
'BANANA!'
> format('Some fruits: {:join(', ')}!', ['melons', 'oranges', 'strawberries'])
'Some fruits: melons, oranges, strawberries!'
upper
will transform to UPPER case.lower
will transform to lower case.lpad(count [, padding=' '])
will pad tocount
characters on the left side.rpad(count [, padding=' '])
will pad tocount
characters on the right side.pad(count [, padding=' '])
will equally pad tocount
characters on both sides.
Note: The
pad
formats only support single characters for padding.
-
surround(left=' ' [, right=left])
will surround withleft
andright
. -
repeat(count=0)
will repeatcount
times. -
join([character=' '])
will join an array withcharacter
. -
hex([leading=false])
will convert to hexadecimal representation. If leading is true0x
will be prepended. -
bin([leading=false])
will convert to binary representation. If leading is true0b
will be prepended.
Using the Formatter
factory one can add their own formatters.
var custom = Formatter({
unicorns: function(value) {
return value + ' unicorns!';
}
});
> custom('Here come the {:unicorns}', 'five')
'Here come the five unicorns!'
It is also possible to add more formats later on by setting properties on the
formats
object of a format
function.
custom.formats.foo = function(value) {
return 'foo';
};
This will add the format :foo
.
By extending Formatter.formats
it's also possible to add more default
formats.
Formatter.formats.bonsai = function(value) {
// ...
};
The format :bonsai
will now be available to all format
functions.