Add unit formatting module

Gruntfile.js

@@ -377,6 +377,23 @@ module.exports = function( grunt ) {
 								}
 							}
 						},
+						{
+							name: "globalize.unit",
+							include: [ "unit" ],
+							exclude: [
+								"cldr",
+								"./core",
+								"./number",
+								"./plural"
+							],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-unit.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
 						{
 							name: "globalize-runtime",
 							include: [ "core-runtime" ],
@@ -473,6 +490,22 @@ module.exports = function( grunt ) {
 									endFile: "src/build/outro.js"
 								}
 							}
+						},
+						{
+							name: "globalize.unit-runtime",
+							include: [ "unit-runtime" ],
+							exclude: [
+								"./core-runtime",
+								"./number-runtime",
+								"./plural-runtime"
+							],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-unit-runtime.js",
+									endFile: "src/build/outro.js"
+								}
+							}
 						}
 					]
 				}
@@ -535,6 +568,7 @@ module.exports = function( grunt ) {
 					"tmp/globalize/plural.min.js": [ "dist/globalize/plural.js" ],
 					"tmp/globalize/message.min.js": [ "dist/globalize/message.js" ],
 					"tmp/globalize/relative-time.min.js": [ "dist/globalize/relative-time.js" ],
+					"tmp/globalize/unit.min.js": [ "dist/globalize/unit.js" ],
 
 					"tmp/globalize-runtime.min.js": [ "dist/globalize-runtime.js" ],
 					"tmp/globalize-runtime/currency.min.js": [
@@ -546,7 +580,8 @@ module.exports = function( grunt ) {
 					"tmp/globalize-runtime/plural.min.js": [ "dist/globalize-runtime/plural.js" ],
 					"tmp/globalize-runtime/relative-time.min.js": [
 						"dist/globalize-runtime/relative-time.js"
-					]
+					],
+					"tmp/globalize-runtime/unit.min.js": [ "dist/globalize-runtime/unit.js" ]
 				}
 			}
 		},

README.md

@@ -31,6 +31,7 @@ Node.js module.
     - [Currency module](#currency-module)
   - [Plural module](#plural-module)
   - [Relative time module](#relative-time-module)
+  - [Unit module](#unit-module)
   - more to come...
 - [Error reference](#error-reference)
 - [Development](#development)
@@ -148,6 +149,7 @@ information on its usage.
 | globalize/number.js | 3.1KB | 1.8KB | [Number module](#number-module) provides number formatting and parsing |
 | globalize/plural.js | 2.3KB | 0.4KB | [Plural module](#plural-module) provides pluralization support |
 | globalize/relative-time.js | 0.8KB | 0.6KB | [Relative time module](#relative-time-module) provides relative time formatting support |
+| globalize/unit.js | 0.9KB | 0.5KB | [Unit module](#unit-module) provides unit formatting support |
 
 ### Browser Support
 
@@ -213,8 +215,9 @@ requirements. See table below.
 | Number module | cldr/main/`locale`/numbers.json<br>cldr/supplemental/numberingSystems.json |
 | Plural module | cldr/supplemental/plurals.json (for cardinals)<br>cldr/supplemental/ordinals.json (for ordinals) |
 | Relative time module | cldr/main/`locale`/dateFields.json<br>+CLDR JSON files from number and plural modules |
+| Unit module | cldr/main/`locale`/units.json<br>+CLDR JSON files from number and plural module |
 
-As an alternative to deducing this yourself, use this [online tool](http://johnnyreilly.github.io/globalize-so-what-cha-want/). The tool allows you to select the modules you're interested in using and tells you the Globalize files *and* CLDR JSON that you need. 
+As an alternative to deducing this yourself, use this [online tool](http://johnnyreilly.github.io/globalize-so-what-cha-want/). The tool allows you to select the modules you're interested in using and tells you the Globalize files *and* CLDR JSON that you need.
 
 *(b) How am I supposed to get and load CLDR content?*
 
@@ -571,6 +574,29 @@ handle dependencies and CLDR loading manually yourself.
 
   Alias for `.relativeTimeFormatter( unit, options )( value )`.
 
+## Unit module
+
+- **`.unitFormatter( unit, options )`**
+
+  Returns a function that formats a unit according to the given unit, options, and the
+  default/instance locale.
+
+  ```javascript
+  .unitFormatter( "second", { form: "long" } )( 10 )
+  // > "10 seconds"
+
+  .unitFormatter( "second", { form: "short" } )( 10 )
+  // > "10 secs"
+
+  .unitFormatter( "second", { form: "narrow" } )( 10 )
+  // > "10s"
+  ```
+
+  [Read more...](doc/api/unit/unit-formatter.md)
+
+- **`.formatUnit( value, unit, options )`**
+
+  Alias for `.unitFormatter( unit, options )( value )`.
 
 ## Error reference
 
@@ -663,6 +689,8 @@ handle dependencies and CLDR loading manually yourself.
 │   ├── plural/ (plural source code)
 │   ├── relative-time.js (relative time module)
 │   ├── relative-time/ (relative time source code)
+│   ├── unit.js (unit module)
+│   ├── unit/ (unit source code)
 │   └── util/ (basic JavaScript helpers polyfills, eg array.map)
 └── test/ (unit and functional test files)
     ├── fixtures/ (CLDR fixture data)
@@ -727,4 +755,3 @@ dependencies (for more details, see above).
 ```bash
 grunt
 ```
-

doc/api/unit/unit-formatter.md

@@ -0,0 +1,77 @@
+## .unitFormatter( unit, options ) ➜ function( value )
+
+Returns a function that formats a unit according to the given unit, options, and the
+default/instance locale.
+
+The returned function is invoked with one argument: the number `value` to
+be formatted.
+
+### Parameters
+
+**unit**
+
+String value indicating the unit to be formatted. eg. "day", "week", "month", etc.
+Could also be a compound unit, eg. "mile-per-hour" or "mile/hour"
+
+**options**
+
+- form: [String] eg. "long", "short" or "narrow".
+
+- numberFormatter: [Object] `Globalize.numberFormatter` instance. Defaults to the
+	default numberFormatter for the current locale.
+
+**value**
+
+The number to be formatted.
+
+### Example
+
+Prior to using any unit methods, you must load `cldr/main/{locale}/units.json` and the
+CLDR content required by the plural module. Read [CLDR content][] if you need
+more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.unitFormatter()`, which uses the default
+locale.
+
+```javascript
+var customNumberFormatter, formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.unitFormatter( "month", { form: "long" } );
+
+formatter( 1 );
+// > "1 month"
+
+formatter( 3 );
+// > "3 months"
+
+formatter( 3000 );
+// > "3,000 months"
+```
+
+You can pass a custom number formatter to format the number of units.
+
+```javascript
+var customNumberFormatter, formatter;
+
+Globalize.locale( "en" );
+customNumberFormatter = Globalize.numberFormatter({ useGrouping = false })
+formatter = Globalize.unitFormatter( "mile-per-hour", {
+	form: "narrow", numberFormatter: customNumberFormatter
+} );
+
+formatter(5000)
+// > "5000mph"
+```
+
+You can use the instance method `.unitFormatter()`, which uses the instance locale.
+
+```javascript
+var globalize = new Globalize( "en" ),
+	formatter = globalize.unitFormatter( "mile-per-hour", { form: "narrow" } );
+
+formatter( 10 );
+// > "10mph"
+```

src/build/intro-unit-runtime.js

@@ -0,0 +1,40 @@
+/**
+ * Globalize Runtime v@VERSION
+ *
+ * http://github.com/jquery/globalize
+ *
+ * Copyright jQuery Foundation and other contributors
+ * Released under the MIT license
+ * http://jquery.org/license
+ *
+ * Date: @DATE
+ */
+/*!
+ * Globalize Runtime v@VERSION @DATE Released under the MIT license
+ * http://git.io/TrdQbw
+ */
+(function( root, factory ) {
+
+	// UMD returnExports
+	if ( typeof define === "function" && define.amd ) {
+
+		// AMD
+		define([
+			"../globalize-runtime",
+			"./plural"
+		], factory );
+	} else if ( typeof exports === "object" ) {
+
+		// Node, CommonJS
+		module.exports = factory(
+			require( "../globalize-runtime" ),
+			require( "./plural" )
+		);
+	} else {
+
+		// Extend global
+		factory( root.Globalize );
+	}
+}(this, function( Globalize ) {
+
+var runtimeKey = Globalize._runtimeKey;

src/build/intro-unit.js

@@ -0,0 +1,44 @@
+/**
+ * Globalize v@VERSION
+ *
+ * http://github.com/jquery/globalize
+ *
+ * Copyright 2010, 2014 jQuery Foundation, Inc. and other contributors
+ * Released under the MIT license
+ * http://jquery.org/license
+ *
+ * Date: @DATE
+ */
+/*!
+ * Globalize v@VERSION @DATE Released under the MIT license
+ * http://git.io/TrdQbw
+ */
+(function( root, factory ) {
+
+	// UMD returnExports
+	if ( typeof define === "function" && define.amd ) {
+
+		// AMD
+		define([
+			"cldr",
+			"../globalize",
+			"./number",
+			"./plural"
+		], factory );
+	} else if ( typeof exports === "object" ) {
+
+		// Node, CommonJS
+		module.exports = factory( require( "cldrjs" ), require( "globalize" ) );
+	} else {
+
+		// Extend global
+		factory( root.Cldr, root.Globalize );
+	}
+}(this, function( Cldr, Globalize ) {
+
+var formatMessage = Globalize._formatMessage,
+	runtimeBind = Globalize._runtimeBind,
+	validateParameterPresence = Globalize._validateParameterPresence,
+	validateParameterTypePlainObject = Globalize._validateParameterTypePlainObject,
+	validateParameterTypeNumber = Globalize._validateParameterTypeNumber,
+	validateParameterTypeString = Globalize._validateParameterTypeString;

src/unit-runtime.js

@@ -0,0 +1,24 @@
+define([
+	"./common/runtime-key",
+	"./core-runtime",
+	"./unit/formatter-fn",
+
+	"./number-runtime",
+	"./plural-runtime"
+], function( runtimeKey, Globalize, unitFormatterFn ) {
+
+Globalize._unitFormatterFn = unitFormatterFn;
+
+Globalize.formatUnit =
+Globalize.prototype.formatUnit = function( value, unit, options ) {
+	return this.unitFormatter( unit, options )( value );
+};
+
+Globalize.unitFormatter =
+Globalize.prototype.unitFormatter = function( unit, options ) {
+	return Globalize[ runtimeKey( "unitFormatter", this._locale, [ unit, options ] ) ];
+};
+
+return Globalize;
+
+});

src/unit.js

@@ -0,0 +1,73 @@
+define([
+	"./core",
+	"./common/runtime-bind",
+	"./common/validate/parameter-presence",
+	"./common/validate/parameter-type/number",
+	"./common/validate/parameter-type/plain-object",
+	"./common/validate/parameter-type/string",
+	"./unit/formatter-fn",
+	"./unit/properties",
+
+	"./number",
+	"./plural"
+], function( Globalize, runtimeBind, validateParameterPresence, validateParameterTypeNumber,
+	validateParameterTypePlainObject, validateParameterTypeString, unitFormatterFn,
+	unitProperties ) {
+
+/**
+ * Globalize.formatUnit( value, unit, options )
+ *
+ * @value [Number]
+ *
+ * @unit [String]: The unit (e.g "second", "day", "year")
+ *
+ * @options [Object]
+ * - form: [String] "long", "short" (default), or "narrow".
+ *
+ * Format units such as seconds, minutes, days, weeks, etc.
+ */
+Globalize.formatUnit =
+Globalize.prototype.formatUnit = function( value, unit, options ) {
+	validateParameterPresence( value, "value" );
+	validateParameterTypeNumber( value, "value" );
+
+	return this.unitFormatter( unit, options )( value );
+};
+
+/**
+ * Globalize.unitFormatter( unit, options )
+ *
+ * @unit [String]: The unit (e.g "second", "day", "year")
+ *
+ * @options [Object]
+ * - form: [String] "long", "short" (default), or "narrow".
+ *
+ * - numberFormatter: [Object] Globalize.numberFormatter object. The default value is the
+ *   default numberFormatter for the current locale.
+ */
+Globalize.unitFormatter =
+Globalize.prototype.unitFormatter = function( unit, options ) {
+	var args, form, numberFormatter, pluralGenerator, returnFn, properties;
+
+	validateParameterPresence( unit, "unit" );
+	validateParameterTypeString( unit, "unit" );
+
+	validateParameterPresence( options, "options" );
+	validateParameterTypePlainObject( options, "options" );
+
+	args = [ unit, options ];
+	form = options.form || "long";
+	properties = unitProperties( unit, form, this.cldr );
+
+	numberFormatter = options.numberFormatter || this.numberFormatter();
+	pluralGenerator = this.pluralGenerator();
+	returnFn = unitFormatterFn( properties, numberFormatter, pluralGenerator );
+
+	runtimeBind( args, this.cldr, returnFn, [ numberFormatter, pluralGenerator, properties ] );
+
+	return returnFn;
+};
+
+return Globalize;
+
+});