clr-format

A lightweight, modular and stand-alone JavaScript implementation of a string formatting function that fully supports composite formatting, globalization and customization

• Usage
• Capabilities
• Documentation
• Development
• Roadmap

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.

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.

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.

   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 and custom numeric format strings (except for currency), as well as all standard date/time and custom date/time specifiers. For lack of a better medium (other than MSDN) please refer to the invariant test cases for a more in-depth showcase of what can be expected as input/output.

   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. Requires contextual support for the ECMAScript Intl namespace. For older browsers and cultures outside of "en-US" in NodeJS consider polyfilling with Intl.js.

   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.

   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

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 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. Overall, it doesn't seem to affect this project's build.

Planned releases

0.1 (Released)

Support for index and alignment components only; without any formatting rules specified by a provider or format string component.

0.2 (Released)

Addition of a clr-format-config.js sub-module/package which can be optionally installed to compliment the core implementation with various pre-defined configurations. See Format.Config for full documentation.

0.3 (Released)

Implementation of an invariant number formatting provider and numeric format string components.

0.4 (Released)

Addition of a clr-format-intl.js sub-module/package which can be optionally installed to provide globalization via a bridge to the ECMAScript Intl namespace.

0.5 (Released)

Complete the implementation with a date formatting provider and date/time format string components.

0.6

Cleanup, bugfixing and refinement of the existing implementation while maintaining the current API.

0.7

Add parsing support based on customized CultureInfo objects or info properties inferred from the Intl format providers.