# fomatto

> Lightweight JavaScript String Interpolation.

Latest version **0.5.0** (published 2011-03-04) · 0 weekly downloads

## Install

```sh
npm install fomatto
pnpm add fomatto
yarn add fomatto
bun add fomatto
```

## Health

**Score 10/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; low quality score; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2011-03-04 |
| First published | 2011-03-04 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.1.5 |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 49 |
| Author | Ivo Wetzel |
| Keywords | string, interpolation, formatting |

## Links

- npm: https://www.npmjs.com/package/fomatto
- Repository: https://github.com/BonsaiDen/fomatto
- Issues: http://github.com/BonsaiDen/fomatto/issues
- npm.io page: https://npm.io/package/fomatto

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.5.0 (latest) — 2011-03-04

## README

Fōmatto - Japanese for Format
=============================

Fōmatto provides leightweight string interpolation and formatting for
JavaScript.

The library brings with it the `Formatter` factory and the `FormatError`.

# Usage
    
In order to use Fōmatto it is necessary to create a `format` function with the 
`Formatter` factory.

    Formatter([formats])

### The `format` function

    format(template, arg1[, arg2, arg3, ...argN])

The `format` function takes a **template** and either  **multiple arguments**, 
an **array** or **array like object** (an object with a `length` property of type
`Number`) or a standard **object** as its arguments. 

    > format('Good {} Sir {}.', 'morning', 'Lancelot')
    'Good morning Sir Lancelot.'

    > format('Good {0} Sir {1}.', 'morning', 'Lancelot')
    'Good morning Sir Lancelot.'

    > format('Good {time} Sir {name}.', 'morning', 'Lancelot')
    'Good morning Sir Lancelot.'

    > format('Good {0} Sir {1}.', ['morning', 'Lancelot'])
    'Good morning Sir Lancelot.'

    > format('Good {time} Sir {name}.', {time: 'morning', name: 'Lancelot'})
    'Good morning Sir Lancelot.'

    > format('Good {0} Sir {1}.', {0: 'morning', 1: 'Lancelot', length: 2})
    'Good morning Sir Lancelot.'

### Templates

String templates contain placeholders wrapped in `{}`. There are a number of
different ways in which these placeholders can be used to insert data into a
template.

 - Auto indexes via `{}`, these automatically insert the **next item** from an 
   array or a list of arguments.

 - Positive `{1}` or negative `{-1}` indexes, these will insert the **Nth** or 
   **length + Nth** index of an array or a list of arguments.

 - Property access via `{name}`, these will either insert the corresponding
   **property of an object** or behave like auto indexes in case of an array or 
   a list of arguments.

 - Complex property access via `{users.names[2]['first']}`, these will query an
   **object** for the specified property and throw a `FormatError` in case the 
   property could not be resolved.

# Formats

By appending a semicolon at the end of a placeholder it is possible to apply a
formatting function to the value before it is inserted.

    > format('{0:upper}!', 'banana')
    'BANANA!'

    > format('Some fruits: {:join(', ')}!', ['melons', 'oranges', 'strawberries'])
    'Some fruits: melons, oranges, strawberries!'

### Standard formats
    
- `upper` will transform to UPPER case.
- `lower` will transform to lower case.
- `lpad(count [, padding=' '])` will pad to `count` characters on the left side.
- `rpad(count [, padding=' '])` will pad to `count` characters on the right side.
- `pad(count [, padding=' '])` will equally pad to `count` characters on both sides.

> **Note:** The `pad` formats only support single characters for padding.

- `surround(left=' ' [, right=left])` will surround with `left` and `right`.
- `repeat(count=0)` will repeat `count` times.
- `join([character=' '])` will join an array with `character`.
- `hex([leading=false])` will convert to hexadecimal representation. If leading
  is true `0x` will be prepended.

- `bin([leading=false])` will convert to binary representation. If leading
  is true `0b` will be prepended.                                     

### Custom formats

Using the `Formatter` factory one can add their own formatters.

    var custom = Formatter({
        unicorns: function(value) {
            return value + ' unicorns!';
        }
    });

    > custom('Here come the {:unicorns}', 'five')
    'Here come the five unicorns!'

It is also possible to add more formats later on by setting properties on the
`formats` object of a `format` function.

    custom.formats.foo = function(value) {
        return 'foo';
    };

This will add the format `:foo`.

### Adding default formats

By extending `Formatter.formats` it's also possible to add more default
formats.

    Formatter.formats.bonsai = function(value) {
        // ...   
    };

The format `:bonsai` will now be available to all `format` functions.

---
_Source: https://npm.io/package/fomatto · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._