generate documentation

Author: scurker

.eslintrc

@@ -6,6 +6,7 @@
     "es6": true
   },
   "parserOptions": {
-    "sourceType": "module"
+    "sourceType": "module",
+    "ecmaVersion": 8
   }
 }

docs/00-index.md

@@ -0,0 +1,10 @@
+<header>
+  <img src="https://user-images.githubusercontent.com/1062039/31397824-9dfa15f0-adac-11e7-9869-fb20746e90c1.png" alt="currency logo">
+  <h1>currency.js</h1>
+  <p>{{description}}</p>
+  <a class="btn" href="https://unpkg.com/currency.js/{{dist}}">Download currency.js</a>
+  <p><strong>v{{version}}</strong> <em>({{size}})</em></p>
+  <aside class="center">
+    <a class="github-button" href="https://github.com/scurker/currency.js" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star scurker/currency.js on GitHub">Star</a>
+  </aside>
+</header>

docs/01-usage.md

@@ -0,0 +1,67 @@
+## Usage
+
+*currency.js* was built to work around common floating point issues in javascript with a flexible api.
+
+When working with currencies, decimals only need to be precise up to the smallest cent value while avoiding common floating point errors when performing basic arithmetic. *currency.js* resolves this issue by working with integers behind the scenes, so you don't have to be concerned about decimal precision.
+
+For more details on why Javascript has issues with floating point numbers, there's an excellent talk by Bartek Szopka on [everything you never wanted to know about Javascript numbers](http://www.youtube.com/watch?v=MqHDDtVYJRI) explaining why Javascript and other IEEE 754 implementations have floating point issues.
+
+*currency.js* will work with a range of inputs, including `strings`, `numbers`, `decimals`, or another `currency` object.
+
+```js
+// Numbers
+currency(1); // => "1.00"
+currency(123); // => "123.00"
+
+// Decimals
+currency(1.00); // => "1.00"
+currency(1.23); // => "1.23"
+
+// Strings
+currency("1.23"); // => "1.23"
+currency("$12.30"); // => "12.23"
+currency("£1,234,567.89"); // => "1,234,567.89"
+
+// Currency
+let c1 = currency(1.23);
+let c2 = currency(4.56);
+currency(7.89).add(c1).add(c2); // => "13.68"
+```
+
+Currency values are handled transparently behind the scenes, so you don't have to worry about those pesky floating point issues!
+
+```js
+2.51 + .01;                   // => 2.5199999999999996
+currency(2.51).add(.01);      // => 2.52
+
+2.52 - .01;                   // 2.5100000000000002
+currency(2.52).subtract(.01); // 2.51
+```
+
+Since *currency.js* handles values internally as integers, there is a limit to the precision that can be stored before encountering precision errors. This should be okay for most reasonable values of currencies. As long as your currencies are less than 2<sup>52</sup>sup> (in cents) or `90,071,992,547,409.91`, you should not see any problems.
+
+*currency.js* also works with a variety of strings. This makes it easy to work into your UI without having do do string to number conversion or vice versa.
+
+```js
+var c = currency("$1,234.56").add("890.12"); // 2124.68
+c.format(); // 2,124.68
+
+// Negative values
+currency("-$5,000").add(1234.56);  // -3765.44
+currency("($5,000)").add(1234.56); // -3765.44
+```
+
+By default, currency resolves to a `string` value.
+
+```js
+// Sets the first input to the resolved currency value
+document.getElementsByTagName("input")[0].value = currency(1234.56).add(6.44); // 1241.00
+```
+
+If you need access to the raw numbers, the value is stored as both an `integer` and a `string`, which you can access with `.intValue` or `.value`;
+
+```js
+// Get the internal values
+currency(123.45).add(.1).value; // => 123.46
+currency(123.45).add(.1).intValue; // => 12346
+```

docs/02-options.md

@@ -0,0 +1,73 @@
+## Options
+
+You can customize the formatting and parsing of `currency.js` with an optional options object. These values default to US centric currency values, but they can be overridden based on your locale.
+
+### symbol *default*: `"$"`
+
+When `formatWithSymbol` is set to `true`, this currency symbol will be used when calling `currency.format()`.
+
+```js
+currency(1.23, { formatWithSymbol: true }).format(); // => "$1.23"
+```
+
+### separator *default*: `","`
+
+Separator between the number groupings when calling `currency.format()`.
+
+```js
+currency(1234.56, { symbol: ',' }).format(); // => "1,234.56"
+currency(1234.56, { symbol: ' ' }).format(); // => "1 234.56"
+```
+
+### decimal *default*: `"."`
+
+```js
+currency(1.23, { decimal: '.' }).format(); // => "1.23"
+currency(1.23, { decimal: ',' }).format(); // => "1,23"
+```
+
+### precision *default*: `2`
+
+Number of decimal places to store as cents.
+
+```js
+currency(1.234, { precision: 2 }); // => "1.23"
+currency(1.234, { precision: 3 }); // => "1.234"
+```
+
+### formatWithSymbol *default*: `false`
+
+Includes the `symbol` option when calling `currency.format()`.
+
+```js
+currency(1.23, { formatWithSymbol: true }).format(); // => "$1.23"
+currency(1.23, { formatWithSymbol: false }).format(); // => "1.23"
+```
+
+### errorOnInvalid *default*: `false`
+
+If an invalid value such as `null` or `undefined` is passed in, `currency` will throw an error.
+
+```js
+currency(undefined, { errorOnInvalid: true }); // throws an error
+```
+
+### increment *default*: `null`
+
+When implementing a currency that implements rounding, setting the `increment` value will allow you to set the closest increment to round the display value to.
+
+```js
+var currencyRounding = value => currency(value, { increment: .05 });
+currencyRounding(1.09); // => { intValue: 109, value: 1.09 }
+currencyRounding(1.09).format(); // => "1.10"
+currencyRounding(1.06); // => { intValue: 106, value: 1.06 }
+currencyRounding(1.06).format(); // => "1.05"
+```
+
+### useVedic *default*: `false`
+
+When using a currency that implements the [Indian Numbering System](https://en.wikipedia.org/wiki/Indian_numbering_system), setting `useVedic` will format values with the correct groupings, i.e. `10,00,000.00`.
+
+```js
+currency(1234567.89, { useVedic: true }).format(); // => "12,34,567.89"
+```

docs/03-api.md

@@ -0,0 +1,111 @@
+---
+toc: true
+---
+
+## Methods
+
+{{{ toc }}}
+
+### add
+
+`currency.add( value )`
+
+Adds a `string`, `number`, or `currency` value to the current currency instance.
+
+```js
+currency(123.45).add(.01); // => "123.46"
+```
+
+### subtract
+
+`currency.subtract( value )`
+
+Subtracts a `string`, `number`, or `currency` value to the current currency instance.
+
+```js
+currency(123.45).subtract(.01); // => "123.44"
+```
+
+### multiply
+
+`currency.multiply( number )`
+
+Multiplies the current currency instance by `number`.
+
+```js
+currency(123.45).multiply(2); // => "246.90"
+```
+
+### divide
+
+`currency.divide( number )`
+
+Divides the current currency instance by `number`.
+
+```js
+currency(123.45).divide(2); // => "61.73"
+```
+
+### distribute
+
+`currency.distribute( number )`
+
+Distribute takes the currency value, and tries to distribute the amount evenly. Any extra cents left over from the distribution will be stacked onto the first sets of entries.
+
+```js
+currency(12.35).distribute(3); // => [4.12, 4.12, 4.11]
+currency(12.00).distribute(3); // => [4.00, 4.00, 4.00]
+```
+
+### format
+
+`currency.format([ boolean ])`
+
+A simple formatter that returns a human friendly currency format.
+
+```js
+currency(1000.00).format(); // => "1,000.00"
+currency("1,234,567/90").add("200,000").format(); // => "1,434,567.89"
+```
+
+The default formatter can be overridden by passing in options as a second parameter.
+
+```js
+var euro = value => currency(value, { separator: ' ', decimal: ',' });
+
+// ...
+
+euro(1000.00).format(); // => "1 000,00"
+euro(1234567.89).add("200 000").format(); // => "1 434 567,89"
+```
+
+You can also include the currently set `symbol` option in a couple of different ways. By default it's always turned off, but you can turn it on for all instances of the object via options, or by passing in a boolean operator to the `format()` function.
+
+```js
+var money = value => currency(value, { formatWithSymbol: true });
+
+money(1000.00).format(); // => "$1,000.00"
+money(1000.00).format(false); // => "1,000.00"
+```
+
+### dollars
+
+`currency.dollars`
+
+Returns the dollar value of the currency.
+
+```js
+currency(123.45).dollars(); // => 123
+currency("0.99").dollars(); // => 0
+```
+
+### cents
+
+`currency.cents`
+
+Returns the cent value of the currency.
+
+```js
+currency(123.45).cents(); // => 45
+currency("0.99").cents(); // => 99
+```

docs/04-i18n.md

@@ -0,0 +1,13 @@
+## Internationalization (i18n) and Formatting
+
+*currency.js* defaults to a US locale, but is flexible enough to work with any type of format. Since each currency instance is immutable, you can create multiple instances to work with any number of different international formats.
+
+```js
+const USD = value => currency(value);
+const JPY = value => currency(value, { precision: 0, symbol: '¥' });
+const EURO = value => currency(value, { symbol: '€', decimal: ',', separator: '.' });
+
+USD(1234.567).format(true); // => "$1,234.57"
+JPY(1234.567).format(true); // => "¥1,235"
+EURO(1234.567).format(true); // => "€1.234,57"
+```

docs/05-addons.md

@@ -0,0 +1,5 @@
+## Addons
+
+### [babel-plugin-transform-currency-operators](https://github.com/scurker/babel-plugin-transform-currency-operators)
+
+An experimental babel plugin for transforming currency operators: `currency(1.23) + 4.56` to `currency(1.23).add(4.56)`.