node package manager
Stop wasting time. Easily manage code sharing in your team. Create a free org »

furmat

fürmat version License

super powered printf & util.format equivalent string formatting, with locals & chainable modifiers.

Build Status Downloads Code Climate Coverage Status Dependency Status Dependencies

Install

npm install --only=production --save furmat

Usage

I recommend using an optimized build matching your Node.js environment version, otherwise, the standard require would work just fine with any version of Node >= v4.0 .

/*
 * Node 7
 */
const furmat = require('furmat/lib/node7')
 
/*
 * Node 6
 */
const furmat = require('furmat/lib/node6')
 
/*
 * Node 4 (Default)
 * Note: additional ES2015 polyfills may be required
 */
var furmat = require('furmat')

API

furmat([options])

  • options (Object, optional): configuration object
    • chalk (Boolean, optional): enable/disable Chalk modifiers Default: true
    • locals (Object, optional): locals object (key => value pairs)
    • modifers (Object, optional): modifiers object (name => function pairs)

Returns: Function The string formatting function.

const format = furmat({
  locals: {
    name: 'Ahmad'
  },
 
  modifiers: {
    capitalize: (string) => string.charAt(0).toUpperCase() + string.slice(1),
    upper: (string) => string.toUpperCase(),
    first: (string) => string.charAt(0)
  }
})
 
console.log(format('%s:capitalize %foo:upper:first', 'hello'))

the above example should output:

Hello A

The returned function behaves in an identical manner to util.format, with additional abilities to process locals & modifiers

The first argument is a string that contains zero or more placeholders. Each placeholder is replaced with the converted value from its corresponding argument. Supported placeholders are:

  • %s - String.
  • %d - Number (both integer and float).
  • %j - JSON. Replaced with the string '[Circular]' if the argument contains circular references.
  • % - single percent sign ('%'). This does not consume an argument.

If the placeholder does not have a corresponding argument, the placeholder is not replaced.

format('%s:%s:bar', 'foo') // 'foo:%s:bar' 

If there are more arguments than placeholders, the extra arguments are converted to strings with util.inspect() and these strings are concatenated, delimited by a space.

format('%s:%s', 'foo', 'bar', 'baz') // 'foo:bar baz' 

you can add predefined locals and modify placeholders & locals by attaching modifiers:

Modifiers

Modifiers are references to named functions meant to modify the placeholder,

example
const format = furmat({
  modifiers: {
    upper: (string) => string.toUpperCase(),
    lower: (string) => string.toLowerCase(),
    first: (string) => string.charAt(0)
  }
})
 
format('%s:upper | %s:lower', 'this will become upper cased', 'THIS WILL BECOME LOWER CASED')
output:
THIS WILL BECOME UPPER CASED | this will become lower cased

you can also chain modifiers:

format('%s:upper:first | %s:lower:first', 'a', 'B')
output:
A | b

Chalk Styles Modifiers

Fürmat includes Chalk Styles modifiers, which are useful for console logging. See oh-my-log.

example
const format = furmat()
 
format('%s:red', 'this text will be red in the console')

you can disable the Chalk modifiers by simply setting the chalk option to false:

const format = furmat({
  chalk: false
})
 
format('%s:red', 'plain text')

Locals

Locals are named variable references that behave in an identical manner to placeholders, but with a pre-defined value set at the time of creating the furmat function

example
const format = furmat({
  locals: {
    name: 'Slim Shady',
    action: 'please stand up?'
  }
})
 
format('Will the real %name %action')
output:
Will the real Slim Shady please stand up?

you can also attach modifiers to locals:

const format = furmat({
  modifiers: {
    upper: (value) => value.toUpperCase(),
    lower: (value) => value.toLowerCase()
  },
 
  locals: {
    name: 'Slim Shady',
    action: 'please stand up?'
  }
})
 
format('Will the real %name:lower %action:upper')
output:
Will the real slim shady PLEASE STAND UP?

©️ ahmadnassri.com  ·  License: ISC  ·  Github: @ahmadnassri  ·  Twitter: @ahmadnassri