Package Exports
- string-format
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (string-format) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
String::format
String::format is a small JavaScript library for formatting strings, based on
Python's str.format()
. For example:
'"{firstName} {lastName}" <{email}>'.format(user)
// => '"Jane Smith" <jsmith@example.com>'
The equivalent concatenation:
'"' + user.firstName + ' ' + user.lastName + '" <' + user.email + '>'
// => '"Jane Smith" <jsmith@example.com>'
Installation
Node
Install:
$ npm install string-format
Require:
var format = require('string-format')
Browser
Define
window.format
:<script src="path/to/string-format.js"></script>
Modes
String::format can be used in two modes: function mode and method mode.
Function mode
format('Hello, {}!', 'Alice')
// => 'Hello, Alice!'
In this mode the first argument is a template string and the remaining arguments are values to be interpolated.
Method mode
'Hello, {}!'.format('Alice')
// => 'Hello, Alice!'
In this mode values to be interpolated are supplied to the format
method
of a template string. This mode is not enabled by default. The method must
first be defined via format.extend
:
format.extend(String.prototype)
format(template, $0, $1, …, $N)
and template.format($0, $1, …, $N)
can then
be used interchangeably.
format(template, $0, $1, …, $N)
Returns the result of replacing each {…}
placeholder in the template string
with its corresponding replacement.
Placeholders may contain numbers which refer to positional arguments:
'{0}, you have {1} unread message{2}'.format('Holly', 2, 's')
// => 'Holly, you have 2 unread messages'
Unmatched placeholders produce no output:
'{0}, you have {1} unread message{2}'.format('Steve', 1)
// => 'Steve, you have 1 unread message'
A format string may reference a positional argument multiple times:
"The name's {1}. {0} {1}.".format('James', 'Bond')
// => "The name's Bond. James Bond."
Positional arguments may be referenced implicitly:
'{}, you have {} unread message{}'.format('Steve', 1)
// => 'Steve, you have 1 unread message'
A format string must not contain both implicit and explicit references:
'My name is {} {}. Do you like the name {0}?'.format('Lemony', 'Snicket')
// => ValueError: cannot switch from implicit to explicit numbering
{{
and }}
in format strings produce {
and }
:
'{{}} creates an empty {} in {}'.format('dictionary', 'Python')
// => '{} creates an empty dictionary in Python'
Dot notation may be used to reference object properties:
var bobby = {firstName: 'Bobby', lastName: 'Fischer'}
var garry = {firstName: 'Garry', lastName: 'Kasparov'}
'{0.firstName} {0.lastName} vs. {1.firstName} {1.lastName}'.format(bobby, garry)
// => 'Bobby Fischer vs. Garry Kasparov'
0.
may be omitted when referencing a property of {0}
:
var repo = {owner: 'davidchambers', slug: 'string-format'}
'https://github.com/{owner}/{slug}'.format(repo)
// => 'https://github.com/davidchambers/string-format'
If the referenced property is a method, it is invoked with no arguments to determine the replacement:
var sheldon = {
firstName: 'Sheldon',
lastName: 'Cooper',
dob: new Date('1970-01-01'),
fullName: function() { return '{firstName} {lastName}'.format(this) },
quip: function() { return 'Bazinga!' }
}
'{fullName} was born at precisely {dob.toISOString}'.format(sheldon)
// => 'Sheldon Cooper was born at precisely 1970-01-01T00:00:00.000Z'
"I've always wanted to go to a goth club. {quip.toUpperCase}".format(sheldon)
// => "I've always wanted to go to a goth club. BAZINGA!"
format.extend(prototype[, transformers])
This function defines a format
method on the provided prototype (presumably
String.prototype
). One may provide an object mapping names to transformers.
A transformer is applied if its name appears, prefixed with !
, after a field
name in a template string.
format.extend(String.prototype, {
escape: function(s) {
return s.replace(/[&<>"'`]/g, function(c) {
return '&#' + c.charCodeAt(0) + ';'
})
},
upper: function(s) { return s.toUpperCase() }
})
'Hello, {!upper}!'.format('Alice')
// => 'Hello, ALICE!'
var restaurant = {
name: 'Anchor & Hope',
url: 'http://anchorandhopesf.com/'
}
'<a href="{url!escape}">{name!escape}</a>'.format(restaurant)
// => '<a href="http://anchorandhopesf.com/">Anchor & Hope</a>'
Running the test suite
$ npm install
$ npm test