bs-format

Example

var format = require('format');

format.string('First: {0}, Second: {1}, Third: {2}', 'test', true, 42);
// First: test, Second: true, Third: 42

format.string('Mass: {0f:3} kg, Age: {0i} years, Hex ID: 0x{0i:32x}',
	74.21, 26, 64206);
// Mass: 74.2 kg, Age: 26 years, Hex ID: 0xface

/*
 * Optional monkey-patch:
 * Adds method to String.prototype.format which proxies to format.string
 */
format.moreConflict();

/* With moreConflict called, we can use this shorthand: */
'First: {0}, Second: {1}, Third: {2}'.format('test', true, 42);
// First: test, Second: true, Third: 42

format.string(formatStr, values...);

The formatStr string is a string which contains zero or more format specifiers.

A format specifier is contained in braces.

{spec}

Open-brace in the format string should be escaped if it is not the start of a format specifier:

not a format specifier => \{0}
is a format specifier => {0}

Remember that backslashes must also be escaped in JavaScript strings!

var format = "not a format specifier => \\{0}";

Close-brace within a format specifier must be escaped by preceeding with backslash.

{ \} }

var fmt = "true/false => \\{/}    result={0b:{:\\}}";

/* true/false => {/}    result={ */
format.string(fmt, true);

/* true/false => {/}    result=} */
format.string(fmt, false);

The specifier contains one or more fields, separated by colons:

{f1:f2:f3}

Colons within a field must be escaped by preceeding with a backslash.

{ escape close brace \} : escape colon \: }

The first field is a numerical zero-based index, specifying the index of the value to use. The first value in the value array is "{0}", the second value in the array is "{1}" and so forth.

The other fields depend on the type of value being formatted - see the formatters in the next section.

If other fields are specified, then a character after the index indicates the formatter to use:

• int
• float
• boolean
• date
• object
• array

If not specified, format.string will attempt to guess which formatter to use.

Examples:

format.string('age: {0i} years, mass: {1f:.2} kg, active: {2b:yes:no}',
	26, 74.2, true);

Produces:

age: 26 years, mass: 74.20 kg, active: yes

Syntax for individual formatters

format.array(value, formatStr)

delim : quote/escape : prefix : suffix

,:qe:[:]

• , is delimeter string to put between items.
• q char causes each item to be double-quoted.
• e char causes double-quotes in items to be escaped by backslashes.
• [ is string to put before first item.
• ] is string to put after first item.
• All fields after index are optional, e.g: The following produce the same output:
  • (blank)
  • ,::
  • ,::[
  • ,::[:]
• Other examples:
  • \n::BEGIN:END
  • , :qe:function( :)

format.int(value, formatStr)

force-sign width base

[+][width][base]

• • forces sign to be shown, even for non-negative numbers.
• width specified the minimum number of digits to show (zero-padding used).
• base is one of [bodx] for [b]inary, [o]ctal, [d]ecimal, he[x]. It can also be specified as bN where N is the base to use. N is in 2..36 as the base conversion is done by JS natively.
• All fields after index are optional, e.g: The following produce the same output:
  • (blank)
  • 0
  • 0d
  • 0b10
• Other examples:
  • 8b (eight binary digits e.g. byte bitmask)
  • 2x (two hex digits e.g. byte in dump / hex editor)
  • b36 (base-36 e.g. ???)
  • 3o (three octal digits e.g. UNIX file permissions)
  • • (always show sign)
  • +3 (always show sign, pad to at least three digits long)
  • +b10 (always show sign, base-ten i.e. decimal)

format.float(value, formatStr)

force-sign significant-figures
force-sign width.places

[+][digits]

• • forces sign to be shown, even for non-negative numbers.
• digits is either a number (0) specifying number of significant figures to show, or two numbers (0.0) specifying width of the integral part and the fractional part respectively.
• By default (no digits parameter) the value will be rounded.
• All fields after index are optional
• Examples:
  • 4 (four significant figures)
  • .3 (three decimal places)
  • 2.3 (three decimal places, pad integral part to at least two digits long)
  • 0.3 (same as .3)
  • 1.3 (same as .3)

format.bool(value, formatStr)

true-string : other-string : false-string

[true:[other:]false]

• true is string to emit for TRUE value.
• false is string to emit for FALSE value.
• other is string to emit for non-boolean value. If not specified, then values will be co-erced to boolean true/false.
• All fields after index are optional, e.g:
  • The following produce the same output:
  • (blank)
  • true:false
• Other examples:
  • true:invalid:other ("invalid" for non-boolean values)
  • yay:nay (truthy="yay", falsy="nay")
  • on:off (truthy/falsy => "on"/"off")
  • 1:-1:0 (true => "1", false => "0", other => "-1")
  • bool true:not a bool: bool false