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 &#38; Hope</a>'

Running the test suite

$ npm install
$ npm test