string-format

string-format JS library on GitHub string-format JS library on npm Download string-format JS library

String formatting inspired by Python's str.format()

Version 2.0.0 License WTFPL OR MIT
string-format has no homepage
string-format JS library on GitHub
string-format JS library on npm
Download string-format JS library
Keywords
stringformattinglanguageutil
No default JS file set by the package author so the URL is guessed. You can always browse all package files to use another one.

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

  1. Install:

    $ npm install string-format
    
  2. Require:

    const format = require('string-format')
    

Browser

  1. 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:

const bobby = {firstName: 'Bobby', lastName: 'Fischer'}
const 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}:

const 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:

const sheldon = {
  firstName: 'Sheldon',
  lastName: 'Cooper',
  dob: new Date('1970-01-01'),
  fullName: function() { return this.firstName + ' ' + this.lastName },
  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.create(transformers)

This function takes an object mapping names to transformers and returns a formatting function. A transformer is applied if its name appears, prefixed with !, after a field name in a template string.

const fmt = format.create({
  escape: s => s.replace(/[&<>"'`]/g, c => '&#' + c.charCodeAt(0) + ';'),
  upper: s => s.toUpperCase(),
})

fmt('Hello, {!upper}!', 'Alice')
// => 'Hello, ALICE!'

const restaurant = {name: 'Anchor & Hope', url: 'http://anchorandhopesf.com/'}

fmt('<a href="{url!escape}">{name!escape}</a>', restaurant)
// => '<a href="http://anchorandhopesf.com/">Anchor &#38; Hope</a>'

format.extend(prototype, transformers)

This function takes a prototype (presumably String.prototype) and an object mapping names to transformers, and defines a format method on the prototype. A transformer is applied if its name appears, prefixed with !, after a field name in a template string.

format.extend(String.prototype, {
  escape: s => s.replace(/[&<>"'`]/g, c => '&#' + c.charCodeAt(0) + ';'),
  upper: s => s.toUpperCase(),
})

'Hello, {!upper}!'.format('Alice')
// => 'Hello, ALICE!'

const restaurant = {name: 'Anchor & Hope', url: 'http://anchorandhopesf.com/'}

'<a href="{url!escape}">{name!escape}</a>'.format(restaurant)
// => '<a href="http://anchorandhopesf.com/">Anchor &#38; Hope</a>'

Running the test suite

$ npm install
$ npm test