readme.md

Formatter Library (NodeJS and Browser)

---

Features:

• Date Formatter
• Number Formatter
• String Formatter (format, align, pluralize)
• Static Methods
• Languages and Cultures
• MaskJS util support

Usage

NodeJS

var Formatter = require('atma-formatter');

Browser

• examples

window.Formatter

Date Formatter

Placeholder	Description
yyyy	Full Year Number
yy	Short Year Number
MM	Month Number in 2 digits, e.g. '03'
#M	Month Number in one or 2 digits
Mm	Short Month Name, e.g. 'Jan', 'Feb'
MMM	Full Month Name, e.g. 'January'
dd	Date Number in 2 digits
#d	Date Number in one or 2 digits
Dd	Short Day Name, e.g. 'Mo', 'Tu'
DD	Full Day Name, e.g. 'Monday'
HH	Hours Number in 2 digits, e.g. '03'
#H	Hours Number in one or 2 digits
hh	alias for 'HH'
#h	alias for '#H'
mm	Minutes in 2 digits
#m	Minutes in on or 2 digits
ss	Seconds in 2 digits
#s	Seconds in on or 2 digits

Standalone NodeJS example:

var format = require('atma-formatter');
var str = format(new Date, "#d MMM, yyyy (hh:mm)");
//>  1 January, 2014 (09:55)

Mask example: mask

div > 'Today - ~[format: today, "#d MMM, yyyy (hh:mm)"]'

javascript model

{ today: new Date }

Output

<div>Today - 1 January, 2014 (09:55)</div>

Javascript example:

var str = mask._.format(new Date, "#d MMM, yyyy (hh:mm)");
//>  1 January, 2014 (09:55)

Number Formatter

Pattern: e.g. ,0.0

Placeholder	Description
,	(optional) First char setts the integral part delimiter. Comma is used for default, which is defined by the current culture info.
0	Then goes the integral part of the number. More Zeros can be specified for the minimal digit output
.	(optional) Floating point. If omitted then the number is rounded to integer. When no zeros follow the point, faction will be printed as is.
0	(optional) Fraction. When defined, the fraction part of the number is rounded to the specified zeros count. When zeros in pattern are taken in parenthese, then trailing zeros will be removed from result.

Samples:

Value	Formatter	Result
1234.123	,00000.0	01,234.1
1234.123	0	1234
1.5	00.00	01.50
3.145	00.	03.145
3.4	0.(000)	3.4
3.4566	0.(000)	3.457

Standalone NodeJS example:

var format = require('atma-formatter');
var str = format(4500.3851, ",0.00");
//>  4,500.39

Mask example

div > 'Sum - ~[format: sum, ",0.00"]'

Javascript model

{ sum: 4500.3851 }

Output

<div>Sum - 4,500.39</div>

Javascript example

var str = mask._.format(4500.3851, ",0.00");
//>  4,500.39

String Formatter

{ accessor[,alignment][:pattern][;switch] }

• accessor: index or dot-notated property

   /* index */
   format('Hello {0} - {1} {0}', 'World', 'my')
   //> 'Hello World, my World'
   
   /* property */
   format('Hello {name} - {stats.qux}', {
   	name: 'Bar',
   	stats: {
   		qux: 20
   	}
   });
   //> 'Hello Bar - 20'

• alignment: minimum chars count with right/left alignment

   format('x{0,10}x', 'Q');
   //> 'x         Qx'
   format('x{0,-10}x', 'Q');
   //> 'xQ         x'
   

• pattern: Date Number format patterns. Refer to Date Formatter and Number Formatter

   format('Year: {date:yyyy}', { date: new Date(2015, 0, 1)});
   //> Year: 2015

• switch/pluralization: pattern:string;otherPattern:string; ... Choose interpolated string according to arguments value. Each string can contain nested interpolations. i18n benefits of this feature

  • Number patterns:
    • Strict and Ending patterns: 12, *12
    • Ranges: 12-16, *12-16
    • Groups: 0,1,2
    • Any: *

   format('{num; 0:Foo; 1,2:Baz {name}}', {
   	num: 2,
   	name: 'Qux'
   })
   //> 'Baz Qux'
   
   // i18n, e.g. russian has 3 plural forms. 'N day(s)' sample
   format('{days} {days; *0,*11-14,*5-9: дней; *1: день; *2-4:дня }', {
   	days: 21
   })
   //> '21 день'
   
   // It is also possible to move pluralization pattern to the cultureInfo.
   // then it would be
   format('{days} {days; день, дня, дней }', {
   	days: 21
   })
   //> '21 день'

Standalone NodeJS example:

var format = require('atma-formatter');
var str = format(
	"Name: {0}; Born: {1:dd MMM yyyy}; Salary: ${2:,0.00}",
	'John',
	new Date(1975, 0, 1),
	17000
);
//>  Name: John; Born: 01 January 1975; Salary: $17,000.00

Mask example

div > '~[format: "Name: {0}; Born: {1:dd MMM yyyy}; Salary: ${2:,0.00}", user.name, user.birth, user.salary]'

Javascript model

{ user: { name: 'John', birth: new Date(1975, 0, 1), salary: 17000 } }

Output

<div>Name: John; Born: 01 January 1975; Salary: $17,000.00</div>

Javascript example

var str = mask._.format("{0:,000}", 5.35);
//>  005

Static methods

The format method takes the formatter by the input value. You can use formatters directly. Formatters will also try to convert the input value to the desired type. For instance, when a string is passed to formatDate then we try to convert it to the Date instance.

var Formatter = require('atma-formatter');
Formatter.formatNumber(value, pattern, cultureInfo?);
Formatter.formatString(value, pattern, cultureInfo?);
Formatter.formatDate(value, pattern, cultureInfo?);

Internationalization

There are already EN and DE support.

Add culture support sample:

var formatter = require('atma-formatter');
formatter.Lang.$register('ru', {
	MONTH: ['Январь',...],
	MONTH_SHORT: ['Ян.',...],
	DAY: ['Воскресенье',...],
	DAY_SHORT: ['Bc',...],

	NUMBER: {
		// 1 000 000,00
		Delimiter: ' ',
		Point: ',',
		Default: string|number
		// When number, then for NaN input the default value will be formatted
		// When string, then it will be returned on NaN input
	}
});
formatter.Lang.$use('ru');

Build, Test

• Build

   $ npm install atma -g
   $ atma

• Test

   $ atma test

---

(c) MIT - Atma.js Project