Fix 220: Create plural module

Gruntfile.js

@@ -95,7 +95,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,
@@ -111,6 +112,15 @@ module.exports = function( grunt ) {
 				onBuildWrite: function( id, path, contents ) {
 					var name = camelCase( id.replace( /util\/|common\//, "" ) );
 
+					// 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
@@ -170,6 +180,18 @@ module.exports = function( grunt ) {
 								}
 							}
 						},
+						{
+							name: "globalize.plural",
+							include: [ "plural" ],
+							exclude: [ "cldr", "cldr/event", "./core" ],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-plural.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
 						{
 							name: "globalize.message",
 							include: [ "message" ],
@@ -230,6 +252,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...
 - [Error reference](#error)
 - [Development](#development)
@@ -99,6 +100,7 @@ information on its usage.
 | globalize/date.js | +3.0KB | [Date module](#date_module) provides date formatting and parsing |
 | globalize/message.js | +0.5KB | [Message module](#message_module) provides message translation |
 | globalize/number.js | +2.4KB | [Number module](#number_module) provides number formatting and parsing |
+| globalize/plural.js | +1.9KB | [Plural module](#plural_module) provides pluralization support |
 <!--- By updating this table, also update its clone in #usage -->
 
 <a name="browser_support"></a>
@@ -165,8 +167,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?*
 
@@ -285,6 +288,22 @@ to you in different flavors):
 
  [Read more...](doc/api/number/parse-number.md)
 
+<a name="plural_module"></a>
+### Plural module
+
+- **`Globalize.formatPlural( value, messageData [, formatValue ] )`**
+
+ Return the appropriate message based on value's plural group: `zero`, `one`,
+ `two`, `few`, `many`, or `other`.
+
+ [Read more...](doc/api/plural/format-plural.md)
+
+- **`Globalize.plural( value )`**
+
+ Return the value's corresponding plural group: `zero`, `one`, `two`, `few`, `many`, or `other`.
+
+ [Read more...](doc/api/plural/plural.md)
+
 
 <a name="error"></a>
 ## Error reference
@@ -371,6 +390,20 @@ Error object:
 | minimum | Minimum value of the valid range |
 | maximum | Maximum value of the valid range |
 
+<a name="E_PLURAL_FORM_NOT_FOUND"></a>
+#### `E_PLURAL_FORM_NOT_FOUND`
+
+Thrown when the plural form (also known as group) is not found for the given
+value. This error is very unlikely to occur and is related to incomplete or
+invalid CLDR data.
+
+Error object:
+
+| Attribute | Value |
+| --- | --- |
+| code | `E_PLURAL_FORM_NOT_FOUND` |
+| value | Number for which no plural form was found |
+
 
 <a name="development"></a>
 ## Development
@@ -393,6 +426,10 @@ Error object:
 │   ├── 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)
@@ -411,8 +448,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.8"
   },
   "devDependencies": {
+    "CLDRPluralRuleParser": "santhoshtr/CLDRPluralRuleParser#v1.1.3",
     "es5-shim": "3.4.0",
     "qunit": "1.12.0",
     "requirejs": "2.1.9",

doc/api/plural/format-plural.md

@@ -0,0 +1,75 @@
+## .formatPlural( value, messageData [, formatValue ] )
+
+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`.
+
+See also its sibling method [`.plural( value )`](./plural.md).
+
+### Parameters
+
+**value**
+
+A Number for which the plural message should be formatted for.
+
+**messageData**
+
+JSON object with message data.
+
+**formatValue**
+
+A Number or String to be used to replace `{0}` in the message. Defaults to
+`value`. This optional parameter may be useful when providing a formatted Number
+string.
+
+### Example
+
+Prior to using any plural method, you must load `supplemental/plurals.json`.
+Read [CLDR content](../../../README.md#2-cldr-content) if you need more
+information.
+
+You can use the static method `Globalize.formatPlural()`, which uses the default
+locale.
+
+```javascript
+var messageData = {
+  one: "You have 1 unread message",
+  other: "You have {0} unread messages"
+};
+Globalize.locale( "en" );
+
+// "You have 0 unread messages"
+Globalize.formatPlural( 0, messageData );
+
+// "You have 1 unread message"
+Globalize.formatPlural( 1, messageData );
+
+// "You have 2 unread messages"
+Globalize.formatPlural( 2, messageData );
+
+// "You have 12,345 unread messages"
+Globalize.formatPlural( 12345, messageData, Globalize.formatNumber( 12345 ) );
+```
+
+You can use the instance method `.formatPlural()`, which uses the instance
+locale.
+
+```javascript
+var en = Globalize( "en" ),
+  messageData = {
+    one: "You have 1 unread message",
+    other: "You have {0} unread messages"
+  };
+
+// "You have 0 unread messages"
+en.formatPlural( 0, messageData );
+
+// "You have 1 unread message"
+en.formatPlural( 1, messageData );
+
+// "You have 2 unread messages"
+en.formatPlural( 2, messageData );
+
+// "You have 12,345 unread messages"
+en.formatPlural( 12345, messageData, en.formatNumber( 12345 ) );
+```

doc/api/plural/plural.md

@@ -0,0 +1,53 @@
+## .plural( value )
+
+It supports the creation of internationalized messages with plural inflection by
+returning the value's plural group: `zero`, `one`, `two`, `few`, `many`, or
+`other`. For example:
+
+| | en (English) | ru (Russian) | ar (Arabic) |
+| --- | --- | --- | --- |
+| `.plural( 0 )` | `other` | `many` | `zero` |
+| `.plural( 1 )` | `one` | `one` | `one` |
+| `.plural( 2 )` | `other` | `few` | `two` |
+| `.plural( 3 )` | `other` | `few` | `few` |
+| `.plural( 5 )` | `other` | `many` | `few` |
+
+See also its sibling method [`.formatPlural( value, messageData [, formatValue ])`
+](./format-plural.md).
+
+### Parameters
+
+**value**
+
+A Number for which to return the plural group.
+
+### Example
+
+Prior to using any plural method, you must load `supplemental/plurals.json`.
+Read [CLDR content](../../../README.md#2-cldr-content) if you need more
+information.
+
+You can use the static method `Globalize.plural()`, which uses the default
+locale.
+
+```javascript
+Globalize.locale( "en" );
+
+// "other"
+Globalize.plural( 0 );
+
+// "one"
+Globalize.plural( 1 );
+
+// "other"
+Globalize.plural( 2 );
+```
+
+You can use the instance method `.plural()`, which uses the instance locale.
+
+```javascript
+var zh = Globalize( "zh" );
+
+// "other"
+zh.formatPlural( 1 );
+```

doc/hello-world/amd-bower/main.js

@@ -27,18 +27,21 @@ require([
 	"json!cldrdata/main/en/ca-gregorian.json",
 	"json!cldrdata/main/en/numbers.json",
 	"json!cldrdata/supplemental/likelySubtags.json",
+	"json!cldrdata/supplemental/plurals.json",
 	"json!cldrdata/supplemental/timeData.json",
 	"json!cldrdata/supplemental/weekData.json",
 
 	// Extend Globalize with Date and Number modules.
 	"globalize/date",
-	"globalize/number"
-], function( Globalize, enGregorian, enNumbers, likelySubtags, timeData, weekData ) {
+	"globalize/number",
+	"globalize/plural"
+], function( Globalize, enGregorian, enNumbers, likelySubtags, pluralsData, timeData, weekData ) {
 
 	// At this point, we have Globalize loaded. But, before we can use it, we need to feed it on the appropriate I18n content (Unicode CLDR). Read Requirements on Getting Started on the root's README.md for more information.
 	Globalize.load( enGregorian );
 	Globalize.load( enNumbers );
 	Globalize.load( likelySubtags );
+	Globalize.load( pluralsData );
 	Globalize.load( timeData );
 	Globalize.load( weekData );
 
@@ -51,4 +54,10 @@ require([
 	// Use Globalize to format numbers.
 	console.log( Globalize.formatNumber( 12345 ) );
 
+	// Use Globalize to format a message with plural inflection.
+	console.log( Globalize.formatPlural( 12345, {
+		one: "{0} result",
+		other: "{0} results"
+	}));
+
 });

doc/hello-world/node-npm/main.js

@@ -7,6 +7,7 @@ var Globalize = require( "globalize" );
 Globalize.load( require( "./cldr/main/en/ca-gregorian.json" ) );
 Globalize.load( require( "./cldr/main/en/numbers.json" ) );
 Globalize.load( require( "./cldr/supplemental/likelySubtags.json" ) );
+Globalize.load( require( "./cldr/supplemental/plurals.json" ) );
 Globalize.load( require( "./cldr/supplemental/timeData.json" ) );
 Globalize.load( require( "./cldr/supplemental/weekData.json" ) );
 
@@ -18,3 +19,9 @@ console.log( Globalize.formatDate( new Date(), { datetime: "medium" } ) );
 
 // Use Globalize to format numbers.
 console.log( Globalize.formatNumber( 12345 ) );
+
+// Use Globalize to format a message with plural inflection.
+console.log( Globalize.formatPlural( 12345, {
+	one: "{0} result",
+	other: "{0} results"
+}));

doc/hello-world/plain-javascript/index.html

@@ -30,6 +30,7 @@ <h2>Demo output</h2>
     <script src="../../../dist/globalize.js"></script>
     <script src="../../../dist/globalize/date.js"></script>
     <script src="../../../dist/globalize/number.js"></script>
+    <script src="../../../dist/globalize/plural.js"></script>
 
     <script>
 
@@ -113,6 +114,12 @@ <h2>Demo output</h2>
         },
         "likelySubtags": {
           "en": "en-Latn-US",
+        },
+        "plurals-type-cardinal": {
+          "en": {
+            "pluralRule-count-one": "i = 1 and v = 0 @integer 1",
+            "pluralRule-count-other": " @integer 0, 2~16, 100, 1000, 10000, 100000, 1000000, … @decimal 0.0~1.5, 10.0, 100.0, 1000.0, 10000.0, 100000.0, 1000000.0, …"
+          }
         }
       }
     });
@@ -126,6 +133,11 @@ <h2>Demo output</h2>
     // Use Globalize to format numbers.
     console.log( Globalize.formatNumber( 12345 ) );
 
+    // Use Globalize to format a message with plural inflection.
+    console.log( Globalize.formatPlural( 12345, {
+      one: "{0} result",
+      other: "{0} results"
+    }));
     </script>
 
 </body>

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" );