improve docs

Author: forzagreen

README.md

@@ -11,14 +11,12 @@
 - - -
 Convert numbers to words - their written form.
 
-## Install with npm
-
+## Install
+With npm:
 ```bash
 npm i --save written-number
 ```
-
-## Install with bower
-
+With bower:
 ```bash
 bower install written-number
 ```
@@ -27,6 +25,10 @@ bower install written-number
 ```javascript
 var writtenNumber = require('written-number');
 writtenNumber(1234); // => 'one thousand two hundred and thirty-four'
+
+writtenNumber(1234, {lang: 'fr'}); // => 'mille deux cent trente-quatre'
+writtenNumber.defaults.lang = 'es';
+writtenNumber(4758); // => 'cuatro mil setecientos cincuenta y ocho'
 ```
 
 ## Options
@@ -36,70 +38,35 @@ writtenNumber(1234); // => 'one thousand two hundred and thirty-four'
   language to use. An i18n configuration object may be passed to support
   external language definitions.
 
-## Internationalization
 Currently supported languages are:
-- English `lang = "en"`
-- Portuguese (Brazil) `lang = "pt"`
-- Portuguese (Portugal) `lang = "ptPT"`
-- Spanish `lang = "es"`
-- French `lang = "fr"`
-- Esperanto `lang = "eo"`
-- Vietnamese `lang = "vi"`
-- Turkish `lang = "tr"`
-- English (Indian) `lang = "enIndian"`
+| Language | `lang` |
+|---------|--------|
+| English | `en` |
+| Portuguese (Brazil) | `pt` |
+| Portuguese (Portugal) | `ptPT` |
+| Spanish | `es` |
+| French | `fr` |
+| Esperanto | `eo` |
+| Vietnamese | `vi` |
+| Arabic | `ar` |
+| Turkish | `tr` |
+| English (Indian) | `enIndian` |
 
-### Spanish Example
 ```javascript
 var writtenNumber = require('written-number');
-writtenNumber(1234, { lang: 'es' }); // => 'mil doscientos treinta y cuatro'
+writtenNumber(1234, {lang: 'es'}); // => 'mil doscientos treinta y cuatro'
+writtenNumber(1234, {lang: 'pt'}); // => 'mil duzentos e trinta e quatro'
+writtenNumber(1234, {lang: 'fr'}); // => 'mille deux cent trente-quatre'
+writtenNumber(1234, {lang: 'ar'}); // => 'ألف ومائتان وأربعة وثلاثون'
+writtenNumber(1234, {lang: 'eo'}); // => 'mil ducent tridek kvar'
+writtenNumber(1234, {lang: 'vi'}); // => 'một ngàn hai trăm và ba mươi bốn'
 ```
 
-```javascript
-var writtenNumber = require('written-number');
-writtenNumber.defaults.lang = 'es';
-writtenNumber(4758); // => 'cuatro mil setecientos cincuenta y ocho'
-```
-
-### Portuguese (Brazil) Example
-```javascript
-var writtenNumber = require('written-number');
-writtenNumber(1234, { lang: 'pt' }); // => 'mil duzentos e trinta e quatro'
-```
-
-### French Example
-```javascript
-var writtenNumber = require('written-number');
-writtenNumber(1234, { lang: 'fr' }); // => 'mille deux cent trente-quatre'
-```
-
-### Esperanto Example
-```javascript
-var writtenNumber = require('written-number');
-writtenNumber(1234, { lang: 'eo' }); // => 'mil ducent tridek kvar'
-```
-
-### Vietnamese Example
-```javascript
-var writtenNumber = require('written-number');
-writtenNumber(1234, { lang: 'vi' }); // => 'một ngàn hai trăm và ba mươi bốn'
-```
-
-## Options
-Property       | Value
--------------- | -------------
-noAnd          | false
-lang           | 'en'
-
-### Configure your own language
-Each language has it's own unique grammar exceptions.  You can create your own
-language.json file in the folder "i18n" and give writtenNumber support for it. I
-don't think the current scheme and logic cover all the cases, but may be cover
-some.
+## Configure your own language
+Each language has it's own unique grammar exceptions.  You can create your own language.json file in the folder "i18n" and give writtenNumber support for it. I don't think the current scheme and logic cover all the cases, but may be cover some.
 
 ##### useLongScale:
-'Boolean' that indicates if it use [long or short
-scale](http://en.wikipedia.org/wiki/Long_and_short_scales). This differs the
-meaning of the words `billion`, `trillion` and so on.
+'Boolean' that indicates if it use [long or short scale](http://en.wikipedia.org/wiki/Long_and_short_scales). This differs the meaning of the words `billion`, `trillion` and so on.
 
 ##### baseSeparator:
 'String' that separates the base cardinal numbers.
@@ -109,148 +76,68 @@ Example: 29 -> twenty`-`eight. Spanish uses the conector " y ".
 'String' that separates the units from the last base cardinal numbers.
 Example: 1234 -> one thousand two hundred **and** thirty-four
 
+##### allSeparator:
+'String' that separates all cardinals, not only the last one.
+Example: 1125 -> ألف **و**مائة **و**خمسة **و**عشرون
+
 ##### base:
-Base cardinals numbers. Numbers that have unique names and are used to build
-others.
+Base cardinals numbers. Numbers that have unique names and are used to build others.
 
 ##### units:
 Number units.
 It can be:
 - String
-
-- Object normal flow. Give support to singular and plural units. English does
-  not need this, but spanish does.
-
+- Object normal flow. Give support to singular, dual, and plural units. English does not need this, but spanish does.
 ```json
 {
   "singular": "millón",
   "plural": "millones"
 }
 ```
-
 - Object with `useBaseInstead` exception.
-In some languages like spanish, specific units like "ciento", use the base
-cardinal number instead.
-
-With `useBaseException` you can also specify with which unit (1 to 9) you don't
-want use the base cardinal instead and use the regular behaviour.
-
+In some languages like spanish and arabic, specific units like "ciento", use the base cardinal number instead.
+- Object with `useBaseException`: You can also specify with which unit (1 to 9) you don't
+want use the base cardinal instead and use the regular behaviour:
 ```json
 {
   "singular": "ciento",
   "useBaseInstead": true,
   "useBaseException": [1]
 }
 ```
-
-- Object with `avoidPrefixException` exception.
-
+- Object with `avoidPrefixException` exception:
 In some languages like spanish, specific units like "mil" does not use the base
 cardinal number prefix for unit 1.
-
 ```json
 {
   "singular": "mil",
   "avoidPrefixException": [1]
 }
 ```
-
-
 - Object with `avoidInNumberPlural` exception.
-
 In some languages like french, specific units like "cent" does not use the plural form inside of
 numbers wioth trailing numbers other than 0, for example "deux cents" and "deux cent trois".
-
 ```json
 {
   "singular": "cent",
   "plural": "cents",
   "avoidInNumberPlural": true
 }
 ```
+- Object with `restrictedPlural` boolean:
+If plural is used only for numbers from 3 to 10 , but the singular form is used if the number is older than 11. 
 
 ##### unitExceptions:
 Sometimes grammar exceptions affect the base cardinal joined to the unit. You
 can set specific exceptions to any base cardinal number.
-
 Spanish example:
-
 ```
 Without Exception (Wrong): 1232000 -> **uno** millón doscientos treinta y dos mil
-```
-
-```
 With Exception: 1232000 -> **un** millón doscientos treinta y dos mil
 ```
 
-### English configuration example
-```json
-{
-  "useLongScale": false,
-  "baseSeparator": "-",
-  "unitSeparator": "and ",
-  "base": {
-    "0": "zero",
-    "1": "one",
-    "2": "two",
-    "3": "three",
-    ...
-    "90": "ninety"
-  },
-  "units" : [
-    "hundred",
-    "thousand",
-    "million",
-    "billion",
-    "trillion",
-    ...
-    "quindecillion"
-  ],
-  "unitExceptions": []
-}
-```
-
-### Spanish configuration example
-```json
-{
-  "useLongScale": true,
-  "baseSeparator": " y ",
-  "unitSeparator": "",
-  "base": {
-    "0": "cero",
-    "1": "uno",
-    "2": "dos",
-    "3": "tres",
-    ...
-    "1000": "mil"
-  },
-  "unitExceptions": {
-    "1": "un"
-  },
-  "units" : [
-    {
-      "singular": "ciento",
-      "useBaseInstead": true,
-      "useBaseException": [1]
-    },
-    {
-      "singular": "mil",
-      "avoidPrefixException": [1]
-    },
-    {
-      "singular": "millón",
-      "plural": "millones"
-    },
-    ...
-  ]
-}
-```
-
 ## Contributing
-Do your changes and submit a PR. If you've write access and want to bump the
-version, run `mversion [major|minor|patch] -m`. That'll bump both `bower.json`
-and `package.json`.
+Do your changes and submit a PR. If you've write access and want to bump the version, run `mversion [major|minor|patch] -m`. That'll bump both `bower.json` and `package.json`.
 
 ## License
-This code is licensed under the MIT license for Pedro Tacla Yamada. For more
-information, please refer to the [LICENSE](/LICENSE) file.
+This code is licensed under the MIT license for Pedro Tacla Yamada. For more information, please refer to the [LICENSE](/LICENSE) file.

lib/index.js

@@ -137,9 +137,11 @@ function writtenNumber(n, options) {
       str = r > 1 && unit.plural && (!unit.avoidInNumberPlural || !m)
         ? unit.plural
         : unit.singular;
+      
       // Languages with dual
       str = (r === 2 && unit.dual) ? unit.dual : str;
-      // Use plural only for <= 10
+      
+      // "restrictedPlural" : use plural only for 3 to 10
       str = (r > 10 && unit.restrictedPlural) ? unit.singular : str;
     }
 
@@ -182,7 +184,8 @@ function writtenNumber(n, options) {
       ret.slice(1)
     );
   }
-  // Languages that have separators for all. Not only base and unit
+  
+  // Languages that have separators for all cardinals.
   if (language.allSeparator) {
     for (let j = 0; j < ret.length-1; j++) {
       ret[j] = language.allSeparator + ret[j];