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.

[!IMPORTANT]

Quantities must either be numbers (simple case) or Arrays. Other types will be ignored.

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'

Tokens as expressions

simplur inlines all string template values prior to processing, allowing you to pass pluralization tokens as values.

const pets = ['dog[|s]', 'lazy cat[|s]', 'wily fox[|es]'];

simplur`I love my ${3} ${pets[1]}`; // ⇨ 'I love my 3 lazy cats'

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

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

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