Simplur

Simple, versatile string pluralization

Upgrading to Version 4

simplur@4 has no API changes from version 3. The only change is it is now ESM-only. (I.e. CommonJS is no longer supported.) ESM Module FAQ.

Installation

npm i simplur

import simplur from 'simplur';

Usage

simplur is an ES6 template tag that formats pluralization tokens based on the quantities injected into the string.

Simple case

Pluralization tokens have the form "[singular|plural]" and are resolved using the first expression found to the left of each token or, if no left-expression is available, the first expression to the right.

simplur`I have ${1} kitt[en|ies]`; // ⇨ 'I have 1 kitten'
simplur`I have ${3} kitt[en|ies]`; // ⇨ 'I have 3 kitties'

simplur`There [is|are] ${1} m[an|en]`; // ⇨ 'There is 1 man'
simplur`There [is|are] ${5} m[an|en]`; // ⇨ 'There are 5 men'

Multiple tokens

Multiple tokens and quantities are allowed. These follow the same rules as above.

simplur`There [is|are] ${1} fox[|es] and ${4} octop[us|i]`; // ⇨ 'There is 1 fox and 4 octopi'
simplur`There [is|are] ${4} fox[|es] and ${1} octop[us|i]`; // ⇨ 'There are 4 foxes and 1 octopus'

Custom quantities

Quantity values may be customized using value of the form, [quantity, format function]. For example:

function format(qty) {
  return qty == 1 ? 'sole' : qty == 2 ? 'twin' : qty;
}

simplur`Her ${[1, format]} br[other|ethren] left`; // ⇨ 'Her sole brother left'
simplur`Her ${[2, format]} br[other|ethren] left`; // ⇨ 'Her twin brethren left'
simplur`Her ${[3, format]} br[other|ethren] left`; // ⇨ 'Her 3 brethren left'

Hiding quantities

Quantites may be hidden by omitting the format function (i.e. just pass value in an Array), or by returning null or undefined.

Note: Whitespace immediately following a hidden quantity will be removed.

simplur`${[1]} gen[us|era]`; // ⇨ 'genus'
simplur`${[2]} gen[us|era]`; // ⇨ 'genera'

function hideSingular(qty) {
  return qty == 1 ? null : qty;
}

simplur`Delete the ${[1, hideSingular]} cact[us|i]?`; // ⇨ 'Delete the cactus?'
simplur`Delete the ${[2, hideSingular]} cact[us|i]?`; // ⇨ 'Delete the 2 cacti?'

Custom

Markdown generated from README_js.md by