clr-format

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

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
clr-format
470.5.28 years ago8 years agoMinified + gzip package size for clr-format in KB

Readme

A lightweight, modular and stand-alone JavaScript implementation of a string formatting function that fully supports composite formattingComposite Formatting, globalization and customization Build Status Dev Dependencies Installation ------------ The following commands can be used to install the script from your favorite package manager.

NuGet

Install-Package clr-format.js

Bower

bower install clr-format

NPM

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 --------------------------- Sauce Test Status
  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]");
```
  1. 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),
as well as all standard date/timeStandard Date Time Format Specifiers and custom date/timeCustom Date Time Format String specifiers. For lack of a better medium (other than MSDN) please refer to the invariant test casesformatInvariantshould.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");
```
  1. 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 casesformatCultureshould.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");
```
  1. 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
  1. NodeJS - with the option to add node, npm, and globally (-g) installed packages to PATH
  1. 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

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.