A lightweight, modular and stand-alone JavaScript implementation of a string formatting function that supports composite format strings, globalization and customization
npm install clr-formatInstall-Package clr-format.js
bower install clr-format
npm install clr-format
javascript
var formatted = String.format("Value: {0:00-00}", 345.6); // formatted = "Value: 03-46"
var culture = new Format.Globalization.CultureInfo("en-US"); // or use Format.setCulture, requires the intl sub-module
formatted = String.format(culture, "Value: {0:Y}", new Date(2015, 8)); // formatted = "Value: September 2015"
`
$3
require returns the formatting method which should be assigned to String.format for clarity. The returned object also has properties that expose the config and intl sub-module implementations.
`javascript
var format = String.format = require("clr-format");
format.setCulture("en-US");
format.setCurrency("USD");
var formatted = String.format("Value: {0,-6:C}{1}", 1, "text"); // formatted = "Value: $1.00 text"
// Using the chainable configuration API
format.Config.addFormatToPrototype().addToStringOverload();
formatted = "Value:{0,10}".format("prototype"); // formatted = "Value: prototype"
formatted = new Date("T23:12:32").toString("Value\: hh:mm:ss tt"); // formatted = "Value: 11:12:32 PM"
`
Latest Version Capabilities
---------------------------
1. Core implentation of index and alignment components' replacement.
`javascript
expect(
String.format(
"Format primitives: {0}{5}, {4}, {3}, {1,-8},{2,4}",
0, { "a": 1 }, [2], "3", true, undefined))
.toBe("Format primitives: 0, true, 3, {\"a\":1} , [2]");
`
2. Core culture-invariant support for all of .NET's [standard numeric][Standard Numeric Format Specifiers] and [custom numeric][Custom Numeric Format String] format strings (except for currency),
as well as all [standard date/time][Standard Date Time Format Specifiers] and [custom date/time][Custom Date Time Format String] specifiers.
For lack of a better medium (other than MSDN) please refer to the [invariant test cases][formatInvariant_should.ts] for a more in-depth showcase of what can be expected as input/output.
`javascript
expect(String.format("{0:P1}", -0.39678)).toBe("-39.7 %");
expect(String.format("{0:#0.0E00}", 987654)).toBe("98.8E04");
expect(String.format("{0:C}", 35.23)).toThrowError(Format.Errors.FormatError);
expect(String.format("{0:F}", new Date(2015, 8, 21, 13, 4, 55)))
.toBe("Monday, 21 September 2015 13:04:55");
`
3. Optional browser globalization API contained in clr-format-intl.js that allows for culture-specific number and currency formatting via the [Format.setCulture] and [Format.setCurrency] methods.
You can find all MSDN-like examples compiled in the [culture-specific test cases][formatCulture_should.ts].
Requires contextual support for the [ECMAScript Intl namespace]. For older browsers and cultures outside of "en-US" in NodeJS consider polyfilling with [Intl.js].
`javascript
Format.setCulture("de-DE");
expect(String.format("{0:N2}", -1234.56)).toBe("-1.234,56");
expect(String.format("{0:#0.0#;(#0.0#,);-0-}", -1234.5)).toBe("(1,23)");
Format.setCurrency("EUR");
expect(String.format("{0:c}", 1230)).toBe("1.230,00 €");
expect(String.format("{0:D}", new Date(2015, 8, 21, 13, 4, 55)))
.toBe("Montag, 21. September 2015");
`
4. Optional browser configuration API contained in clr-format-config.js and defined under the [Format.Config] namespace.
`javascript
Format.Config.addFormatToPrototype();
expect("Format using the injected {0} method".format("prototype"))
.toBe("Format using the injected prototype method");
Format.Config.addToStringOverload();
expect((1234.5678).toString("#,0.00")).toBe("1,234.57");
expect(new Date().toString("dd/MM/yyyy")).toBe("16/09/2015");
`
#### Note
All optional browser APIs are included inside the NodeJS package with slightly different usage than on browsers. See the Usage section for details.
API Documentation
-----------------
The [GitHub pages documentation] is generated from the latest release's source files. It includes the jsdoc comments and signatures of public/exported members,
as well as the declarations of private ones.
Do not rely on any privates; even though for classes and some modules they are technically exported they are most likely subject to change in the future.
Development
-----------
The implementation of this string formatting function is inspired by .NET's (and other Microsoft® products') [Composite Formatting] feature.
Therefore the behaviour and method signatures match what's described in the [Getting started with the String.Format method] article as closely as possible.
The main difference is that method names in JavaScript are intrinsically camelcase therefore [String.format] is used instead.
To develop and contribute simply install NodeJS, clone the repository, install npm dependencies and run [Gulp].
#### Tools (download and install)
1. [GIT] - with the option to add git to PATH
2. [NodeJS] - with the option to add node, npm, and globally (-g) installed packages to PATH
3. [VSCode] - or any other IDE that has TypeScript language support
#### Building the project
`bash
git clone https://github.com/clr-format/clr-format.git
cd clr-format
npm install --ignore-scripts
npm install --global gulp
gulp
`
#### Notes
- The default gulp build tasks' list contains a [watch task][Gulp watch task]
which means it will block the console and continuously rebuild the project when files in the source or tests folder are changed.
- In VSCode pressing Ctrl + Shift + B or T will trigger the default build or test command respectively.
- The --ignore-scripts option is used to stop errors caused by node-gyp rebuild scripts introduced by karma`.