Plural: Create initial module

Borrow santhoshtr/CLDRPluralRuleParser.

Ref globalizejs#220

Gruntfile.js

@@ -89,7 +89,8 @@ module.exports = function( grunt ) {
 				baseUrl: ".",
 				optimize: "none",
 				paths: {
-					cldr: "../external/cldrjs/dist/cldr"
+					cldr: "../external/cldrjs/dist/cldr",
+					CLDRPluralRuleParser: "../external/CLDRPluralRuleParser/src/CLDRPluralRuleParser"
 				},
 				skipSemiColonInsertion: true,
 				skipModuleInsertion: true,
@@ -102,6 +103,15 @@ module.exports = function( grunt ) {
 				onBuildWrite: function ( id, path, contents ) {
 					var name = camelCase( id.replace(/util\//, "") );
 
+					// CLDRPluralRuleParser
+					if ( (/CLDRPluralRuleParser/).test( id ) ) {
+						return contents
+
+							// Replace UMD wrapper into var assignment.
+							.replace( /\(function\(root, factory\)[\s\S]*?}\(this, function\(\) {/, "var CLDRPluralRuleParser = (function() {" )
+							.replace( /}\)\);\s+$/, "}());" );
+					}
+
 					// 1, and 2: Remove define() wrap.
 					// 3: Remove empty define()'s.
 					contents = contents
@@ -162,6 +172,18 @@ module.exports = function( grunt ) {
 								}
 							}
 						},
+						{
+							name: "globalize.plural",
+							include: [ "plural" ],
+							exclude: [ "cldr", "./core", "./message" ],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-plural.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
 						{
 							name: "globalize.message",
 							include: [ "message" ],
@@ -222,6 +244,7 @@ module.exports = function( grunt ) {
 						"dist/globalize.min.js": [ "dist/globalize.js" ],
 						"dist/globalize/date.min.js": [ "dist/globalize/date.js" ],
 						"dist/globalize/number.min.js": [ "dist/globalize/number.js" ],
+						"dist/globalize/plural.min.js": [ "dist/globalize/plural.js" ],
 						"dist/globalize/message.min.js": [ "dist/globalize/message.js" ]
 				}
 			}

README.md

@@ -26,6 +26,7 @@ Node.js module.
   - [Date module](#date_module)
   - [Message module](#message_module)
   - [Number module](#number_module)
+  - [Plural module](#plural_module)
   - more to come...
 - [Development](#development)
   - [File structure](#file_structure)
@@ -98,6 +99,7 @@ information on its usage.
 | globalize/date.js | +9.2KB | [Date module](#date_module) provides date formatting and parsing |
 | globalize/message.js | +0.7KB | [Message module](#message_module) provides message translation |
 | globalize/number.js | +3.7KB | [Number module](#number_module) provides number formatting and parsing |
+| globalize/plural.js | +4.8KB | [Plural module](#plural_module) provides pluralization support |
 <!--- By updating this table, also update its clone in #usage -->
 
 <a name="browser_support"></a>
@@ -140,8 +142,9 @@ requirements. See table below.
 | Module | Required CLDR JSON files |
 |---|---|
 | Core module | cldr/supplemental/likelySubtags.json |
-| Number module | cldr/main/`locale`/numbers.json |
 | Date module | cldr/main/`locale`/ca-gregorian.json<br>cldr/supplemental/timeData.json<br>cldr/supplemental/weekData.json |
+| Number module | cldr/main/`locale`/numbers.json |
+| Plural module | cldr/supplemental/plurals.json |
 
 *(b) How am I supposed to get and load CLDR content?*
 
@@ -260,6 +263,16 @@ to you in different flavors):
 
  [Read more...](doc/api/number/parse.md)
 
+<a name="plural_module"></a>
+### Plural module
+
+- **`Globalize.formatPlural( value, messageData )`**
+
+ Return the appropriate message based on value's plural group: `zero`, `one`,
+ `two`, `few`, `many`, or `other`.
+
+ [Read more...](doc/api/plural/format.md)
+
 
 <a name="development"></a>
 ## Development
@@ -282,6 +295,10 @@ to you in different flavors):
 │   ├── date/ (date source code)
 │   ├── date.js (date module)
 │   ├── message.js (message module)
+│   ├── number.js (number module)
+│   ├── number/ (number source code)
+│   ├── plural.js (plural module)
+│   ├── plural/ (plural source code)
 │   └── util/ (basic JavaScript helpers polyfills, eg array.map)
 └── test/ (unit and functional test files)
     ├── fixtures/ (CLDR fixture data)
@@ -300,8 +317,8 @@ The source files are as granular as possible. When combined to generate the
 build file, all the excessive/overhead wrappers are cut off. It's following
 the same build model of jQuery and Modernizr.
 
-Core, and all modules' public APIs are located in the `src/` directory. For
-example: `core.js`, `date.js`, and `message.js`.
+Core, and all modules' public APIs are located in the `src/` directory, ie.
+`core.js`, `date.js`, `message.js`, `number.js`, and `plural.js`.
 
 <a name="build"></a>
 ### Build

bower.json

@@ -11,6 +11,7 @@
     "cldrjs": "0.3.4"
   },
   "devDependencies": {
+    "CLDRPluralRuleParser": "santhoshtr/CLDRPluralRuleParser#7450feb2de7ecdd531f3b5d13ae5b5502b5b238b",
     "jquery": "2.0.3",
     "qunit": "1.12.0",
     "requirejs": "2.1.9",

doc/api/plural/format.md

@@ -0,0 +1,53 @@
+## .formatPlural( value, messageData )
+
+It supports the creation of internationalized messages with plural inflection by
+returning the appropriate message based on value's plural group: `zero`, `one`,
+`two`, `few`, `many`, or `other`.
+
+### Parameters
+
+**value**
+
+A Number for which the plural message should be formatted for.
+
+**messageData**
+
+JSON object with message data.
+
+### Example
+
+```javascript
+var messageData = {
+  one: "You have 1 unread message",
+  other: "You have {0} unread messages"
+};
+Globalize.locale( "en" );
+Globalize.plural( 0, messageData ); // "You have {0} unread messages"
+Globalize.plural( 1, messageData ); // "You have 1 unread message"
+Globalize.plural( 2, messageData ); // "You have {0} unread messages"
+
+// FIXME
+
+messageData = {
+  zero:
+  one:
+  two:
+  few:
+  many:
+  other:
+};
+Globalize( "ar" ).plural( 0, messageData ); // "zero"
+Globalize( "ar" ).plural( 1, messageData ); // "one"
+Globalize( "ar" ).plural( 2, messageData ); // "two"
+Globalize( "ar" ).plural( 3, messageData ); // "few"
+
+messageData = {
+  few:
+  many:
+  one:
+  other:
+};
+Globalize( "ru" ).plural( 0, messageData ); // "many"
+Globalize( "ru" ).plural( 1, messageData ); // "one"
+Globalize( "ru" ).plural( 2, messageData ); // "few"
+```

src/build/allinone-node.js

@@ -15,5 +15,6 @@ module.exports = require( "./globalize" );
 
 // Extent core with the following modules
 require( "./globalize/date" );
-require( "./globalize/number" );
 require( "./globalize/message" );
+require( "./globalize/number" );
+require( "./globalize/plural" );

src/build/intro-plural.js

@@ -0,0 +1,31 @@
+/*!
+ * Globalize v@VERSION
+ *
+ * http://github.com/jquery/globalize
+ *
+ * Copyright 2005, 2013 jQuery Foundation, Inc. and other contributors
+ * Released under the MIT license
+ * http://jquery.org/license
+ *
+ * Date: @DATE
+ */
+(function( root, factory ) {
+
+	// UMD returnExports
+	if ( typeof define === "function" && define.amd ) {
+
+		// AMD
+		define([
+			"cldr",
+			"../globalize"
+		], factory );
+	} else if ( typeof exports === "object" ) {
+
+		// Node, CommonJS
+		module.exports = factory( require( "cldrjs" ), require( "globalize" ) );
+	} else {
+
+		// Global
+		factory( root.Cldr, root.Globalize );
+	}
+}(this, function( Cldr, Globalize ) {

src/plural.js

@@ -0,0 +1,36 @@
+define([
+	"./core",
+	"./plural/form",
+	"./message"
+], function( Globalize, pluralForm ) {
+
+/**
+ * Globalize.formatPlural( value, data )
+ *
+ * @value [Number]
+ *
+ * @data [JSON]
+ *
+ * FIXME
+ *
+ * Return the appropriate message based on value's plural group: zero | one | two | few | many | other.
+ */
+Globalize.formatPlural =
+Globalize.prototype.formatPlural =
+function( value, data ) {
+	var form;
+
+	if ( typeof value !== "number" ) {
+		throw new Error( "Value is not a number" );
+	}
+
+	if ( !( form = pluralForm( value, this.cldr ) ) ) {
+		throw new Error( "Plural form not found!" );
+	}
+
+	return data[ form ];
+};
+
+return Globalize;
+
+});

src/plural/form.js

@@ -0,0 +1,28 @@
+define([
+	"CLDRPluralRuleParser",
+	"./rules"
+], function( CLDRPluralRuleParser, pluralRules ) {
+
+/**
+ * pluralForm( value, cldr )
+ *
+ * @value [Number]
+ *
+ * @cldr [Cldr instance].
+ *
+ * Return the corresponding form (zero | one | two | few | many | other) of a value given locale @cldr.
+ */
+return function( value, cldr ) {
+	var form,
+		rules = pluralRules( cldr );
+
+	for( form in rules ) {
+		if( CLDRPluralRuleParser( rules[ form ], value ) ) {
+			return form.replace( /pluralRule-count-/, "" );
+		}
+	}
+
+	return null;
+};
+
+});

src/plural/rules.js

@@ -0,0 +1,14 @@
+define(function() {
+
+/**
+ * pluralRules( cldr )
+ *
+ * @cldr [Cldr instance].
+ *
+ * Return all the plural rules of a language.
+ */
+return function( cldr ) {
+	return cldr.supplemental( "plurals-type-cardinal/{language}" );
+};
+
+});