<commit_before># cash.js
modules for processing, parsing, computing and exchange-rate-swapping money strings. Works as a templating module, also hooks into the DOM.

## Under construction - do not use in production!

* [What this does](#what-this-does)
* [How this serves users and developers](#how-this-serves-users-and-developers)
* [Currency support](#currency-support)
* [Configurations](#configurations)
* [Instantiate](#instantiate)
* [Settings](#settings)
* [Core Methods](#core-methods)
* [Client-Side Methods](#client-side-methods)
* [Contributing](#contributing)

## What this does
cash.js is a money-finder.  Give it a string or a DOM node, and its regular expression engine will find anything that looks like it's talking about a money amount and wrap it in a `span` tag with a `cash-node` class and a unique alphanumeric `id` tag which is also persisted in memory.  It also exposes a few useful methods for updating those strings post-render, including an elegant way to pass in exchange rates and dynamically update the DOM with new money information.  This makes localization a snap.

## How this serves users and developers
When delivering content, it's very easy to be currency-biased.  If your backend or API doesn't support displaying money figures in local currencies, you may be alienating your users who may not know the Ruble - Peso exchange rate (for instance).  Since cash.js is lightweight and can be deployed on the server via node, used pre-template on the client side, or applied directly to the DOM after rendering (or any combination thereof), there's no excuse for not internationalizing your money values.

## Currency support
cash.js comes with [support for a handful of major currencies](https://github.com/bignimbus/cash.js/blob/master/src/settings.js) out of the box, but is infinitely extensible.  In addition to traditional currencies, you can set, swap and display exchange rates for cryptocurrencies, virtual currencies, stock prices, toothbrush prices, whatever!  If you have the data, cash.js will make sure that the user can see it in a performant way.

## Configurations
Cash currently has two distributions: `cash-lite`, which houses the regex engine and templating utility; and `cash`, which is dependent on jQuery and houses the DOM manipulation library and other client-side features.  I intend to make `cash-lite` into an [npm](!https://www.npmjs.com/) module in the near future.

## Instantiate

```js
var cash = new Cash(options);
```

The `Cash` object is a constructor so more than one instance can be loaded (use this pattern with caution).

## Settings
`cash`'s power comes from its ability to be modified and extended.  On instantiation, `cash`'s [settings](https://github.com/bignimbus/cash.js/blob/master/src/settings.js) (affectionately called the "register") hash is extended by the passed `options` hash using Object.assign (not a deep copy).  The [settings](https://github.com/bignimbus/cash.js/blob/master/src/settings.js) source annotates the configurable parameters.  If you are adding a currency, consider forking this repo and submitting a pull request with the new configurations.  You can never have too much `cash`!

## Core methods
These methods are supported in `cash-lite` and `cash`.

### tag(string)
Given a string, finds all substrings that represent a money figure, wraps them in span tags, parses their values, and stores them in memory.  Notice that there are no data-attributes or any other persistence layer in the DOM itself, just a class and a unique id.  All values are stored in the `cash.register` (lol) object in memory.  `cash` is pretty smart out of the box and understands that if your default currency is GBP, 'five quid' (for example) means £5.00.  This behavior is configurable.

```js
var demand = 'I want one million dollars in cash.';
cash.tag(demand);

// output:
'I want <span id="abcd1234" class="cash-node">one million dollars</span> in cash.'
```

### addFilters(function, [function, ...])
cash.js has a very broad regex engine that will catch lots of different permutations of money strings, including natural language (e.g. 'five bucks' is understood to be $5.00).  If you want your cash instance to be more selective, pass a callback or callbacks that return a boolean, similar to [Array.prototype.every](!https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every).  The one key difference is that `addFilters` allows you to pass in an arbitrary number of callbacks.

```js
var sample = 'I got five bucks the other day.  That\'s five dollars, or $5.00!',
    noBucks = function (str) {
        return !/bucks?/i.test(str);
    },
    noDollars = function (str) {
        return !/dollars?/i.test(str);
    };

cash.tag(sample);

// output:
'I got <span id="asdf3456" class="cash-node">five bucks</span> the other day.  That\'s <span id="3457gby3" class="cash-node">five dollars</span>, or <span id="urmng731" class="cash-node">$5.00</span>!'

cash.addFilters(noBucks, noDollars)
    .tag(sample);

// output with filters:
'I got five bucks the other day.  That\'s five dollars, or <span id="efgh5678" class="cash-node">$5.00</span>!'
```

### setValues(object)
Pass this method a hash of exchange rates and it will update these values in memory.  This will not trigger a DOM update in `cash`, nor will it affect the templating engine in any way.  It is important to maintain even ratios - `cash` assumes you know what you're doing with the data you're providing.  It is recommended that your default currency always be set to `1`.  Trust me, it'll make your life easier.

```js
cash.setValues({
    "USD": 1,
    "EUR": 0.9,
    "JPY": 100
});
```

## Client-side methods
These methods are supported in `cash.js` and are designed for client-side use only.

### lookFor(string[, string, ...])
Tells `cash` what currencies you expect to be rendered in the DOM.  This helps make sure `cash` isn't confused by currencies that share symbols (like Japanese Yen and Chinese Yuan).  For example, try not to tell `cash` to look for USD and CAD on the same page.  You're gonna have a bad time because they share the `$` symbol.

```js
cash.lookFor('USD', 'GBP', 'MXN', 'RUB');
```

### wrap(string OR [string, string...])
Like [tag](#tag-string-), but instead of passing a string, just pass a jQuery selector or array of jQuery selectors.  `cash.js` will crawl the DOM and wrap all money strings in those elements.  This method is often chained with `lookFor`.

```html
<!-- index.html, before -->
<h1 class="hodor">HODOR hodor hodor HODOR $3.50 hodor HODOR</h1><commit_msg>fix documentation error<commit_after># cash.js
modules for processing, parsing, computing and exchange-rate-swapping money strings. Works as a templating module, also hooks into the DOM.

## Under construction - do not use in production!

* [What this does](#what-this-does)
* [How this serves users and developers](#how-this-serves-users-and-developers)
* [Currency support](#currency-support)
* [Configurations](#configurations)
* [Instantiate](#instantiate)
* [Settings](#settings)
* [Core Methods](#core-methods)
* [Client-Side Methods](#client-side-methods)
* [Contributing](#contributing)

## What this does
cash.js is a money-finder.  Give it a string or a DOM node, and its regular expression engine will find anything that looks like it's talking about a money amount and wrap it in a `span` tag with a `cash-node` class and a unique alphanumeric `id` tag which is also persisted in memory.  It also exposes a few useful methods for updating those strings post-render, including an elegant way to pass in exchange rates and dynamically update the DOM with new money information.  This makes localization a snap.

## How this serves users and developers
When delivering content, it's very easy to be currency-biased.  If your backend or API doesn't support displaying money figures in local currencies, you may be alienating your users who may not know the Ruble - Peso exchange rate (for instance).  Since cash.js is lightweight and can be deployed on the server via node, used pre-template on the client side, or applied directly to the DOM after rendering (or any combination thereof), there's no excuse for not internationalizing your money values.

## Currency support
cash.js comes with [support for a handful of major currencies](https://github.com/bignimbus/cash.js/blob/master/src/settings.js) out of the box, but is infinitely extensible.  In addition to traditional currencies, you can set, swap and display exchange rates for cryptocurrencies, virtual currencies, stock prices, toothbrush prices, whatever!  If you have the data, cash.js will make sure that the user can see it in a performant way.

## Configurations
Cash currently has two distributions: `cash-lite`, which houses the regex engine and templating utility; and `cash`, which is dependent on jQuery and houses the DOM manipulation library and other client-side features.  I intend to make `cash-lite` into an [npm](!https://www.npmjs.com/) module in the near future.

## Instantiate

```js
var cash = new Cash(options);
```

The `Cash` object is a constructor so more than one instance can be loaded (use this pattern with caution).

## Settings
`cash`'s power comes from its ability to be modified and extended.  On instantiation, `cash`'s [settings](https://github.com/bignimbus/cash.js/blob/master/src/settings.js) (affectionately called the "register") hash is extended by the passed `options` hash using Object.assign (not a deep copy).  The [settings](https://github.com/bignimbus/cash.js/blob/master/src/settings.js) source annotates the configurable parameters.  If you are adding a currency, consider forking this repo and submitting a pull request with the new configurations.  You can never have too much `cash`!

## Core methods
These methods are supported in `cash-lite` and `cash`.

### lookFor(string[, string, ...])
Tells `cash` what currencies you expect to be rendered in the DOM.  This helps make sure `cash` isn't confused by currencies that share symbols (like Japanese Yen and Chinese Yuan).  For example, try not to tell `cash` to look for USD and CAD on the same page.  You're gonna have a bad time because they share the `$` symbol.

```js
cash.lookFor('USD', 'GBP', 'MXN', 'RUB');
```

### tag(string)
Given a string, finds all substrings that represent a money figure, wraps them in span tags, parses their values, and stores them in memory.  Notice that there are no data-attributes or any other persistence layer in the DOM itself, just a class and a unique id.  All values are stored in the `cash.register` (lol) object in memory.  `cash` is pretty smart out of the box and understands that if you have 'GBP' in your `lookFor` method, 'five quid' (for example) means £5.00.  This behavior is configurable.

```js
var demand = 'I want one million dollars in cash.';
cash.lookFor('USD').tag(demand);

// output:
'I want <span id="abcd1234" class="cash-node">one million dollars</span> in cash.'
```

### addFilters(function, [function, ...])
cash.js has a very broad regex engine that will catch lots of different permutations of money strings, including natural language (e.g. 'five bucks' is understood to be $5.00).  If you want your cash instance to be more selective, pass a callback or callbacks that return a boolean, similar to [Array.prototype.every](!https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every).  The one key difference is that `addFilters` allows you to pass in an arbitrary number of callbacks.

```js
var sample = 'I got five bucks the other day.  That\'s five dollars, or $5.00!',
    noBucks = function (str) {
        return !/bucks?/i.test(str);
    },
    noDollars = function (str) {
        return !/dollars?/i.test(str);
    };

cash.tag(sample);

// output:
'I got <span id="asdf3456" class="cash-node">five bucks</span> the other day.  That\'s <span id="3457gby3" class="cash-node">five dollars</span>, or <span id="urmng731" class="cash-node">$5.00</span>!'

cash.addFilters(noBucks, noDollars)
    .tag(sample);

// output with filters:
'I got five bucks the other day.  That\'s five dollars, or <span id="efgh5678" class="cash-node">$5.00</span>!'
```

### setValues(object)
Pass this method a hash of exchange rates and it will update these values in memory.  This will not trigger a DOM update in `cash`, nor will it affect the templating engine in any way.  It is important to maintain even ratios - `cash` assumes you know what you're doing with the data you're providing.  It is recommended that your default currency always be set to `1`.  Trust me, it'll make your life easier.

```js
cash.setValues({
    "USD": 1,
    "EUR": 0.9,
    "JPY": 100
});
```

## Client-side methods
These methods are supported in `cash.js` and are designed for client-side use only.

### wrap(string OR [string, string...])
Like [tag](#tag-string-), but instead of passing a string, just pass a jQuery selector or array of jQuery selectors.  `cash.js` will crawl the DOM and wrap all money strings in those elements.  This method is often chained with `lookFor`.

```html
<!-- index.html, before -->
<h1 class="hodor">HODOR hodor hodor HODOR $3.50 hodor HODOR</h1>
{'fraction_non_alphanumeric': 0.1004983388704319, 'fraction_numerical': 0.007097553609181516, 'mean_word_length': 4.362348178137652, 'pattern_counts': {'":': 6, '<': 29, '<?xml version=': 0, '>': 29, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3883471', 'n_tokens_mistral': 3921, 'n_tokens_neox': 3635, 'n_words': 1775}