A lightweight, modular and stand-alone JavaScript implementation of a string formatting function that fully supports composite formattingComposite Formatting, globalization and customization
Installation
------------
The following commands can be used to install the script from your favorite package manager.
Install-Package clr-format.js
bower install clr-format
npm install clr-format
Usage
-----
As a browser script
Include the clr-format.js script (and optionally the config and/or intl sub-modules). Only the Format namesace will ever be added as a global object and, of course, the declaration for the String.format method. ```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" ```As a module
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
---------------------------
- 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]");
```
- Core culture-invariant support for all of .NET's standard numericStandard Numeric Format Specifiers and custom numericCustom Numeric Format String format strings (except for currency),
```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");
```
- 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.
"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");
```
- 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)
- GIT - with the option to add
git
to PATH
- NodeJS - with the option to add
node
,npm
, and globally (-g
) installed packages to PATH
- 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 taskGulp watch task
- 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 bynode-gyp
rebuild scripts introduced bykarma
.