<commit_before>IOU
===

A simple JavaScript library which forces asynchronous code to give you a
promise for a value; at the very least. Really, that's not asking too much is
it?

## Installation
The most common use of IOU is to use it as a library. In that case, just
include it in your Node.js project by adding a line for IOU in your
`pacakge.json`. For more information about your `package.json` file, you should
check out the npm documentation by running `npm help json`.

Alternatively, you can quickly install IOU for use in a project by running

	npm install iou

which will install iou in your `node_modules/` folder.

## Testing
To run the tests, just do

	./manage test

You should see 'PASSED' as the only output. Any failed tests will output an
error message and halt execution. If you don't see anything, that means the
tests did not complete for some reason. You'll have to set breakpoints to
figure out where.

Copyright and License
---------------------
Copyright (c) 2013 by <NAME> <<EMAIL>> (http://www.kixx.name).

Unless otherwise indicated, all source code is licensed under the MIT license.
See LICENSE for details.
<commit_msg>Update README for API docs<commit_after>IOU
===

A simple JavaScript library used to force asynchronous calls to give you a
promise for a return value. Really, that's not asking too much is it?

## Installation
The most common use of IOU is to use it as a library. In that case, just
include it in your Node.js project by adding a line for IOU in your
`pacakge.json`. For more information about your `package.json` file, you should
check out the npm documentation by running `npm help json`.

Alternatively, you can quickly install IOU for use in a project by running

	npm install iou

which will install iou in your `node_modules/` folder.

## Examples

You can create a new promise with the constructor, passing it a block of code
in the form of a callback function. Inside that block of code is where the
asynchronous call is made, and the promise is resolved or rejected:

```JavaScript
var FS = require('fs')
  , IOU = require('iou')

var readmePromise = new IOU.Promise(function (resolve, reject) {
  FS.readFile('README.md', {encoding: 'utf8'}, function (err, text) {
    if (err) return reject(err);
    return resolve(text);
  });
})
```

Once you have a promise, you can add handlers:
```JavaScript
function printText(text) {
  console.log(text);
}

// The text String you passed into resolve() will get passed to printText().
readmePromise.then(printText);
```

Add an error handler too:
```JavaScript
// Create an error handling function.
function die(err) {
  console.error(err.stack);
  process.exit(1);
}

// The text String you passed into resolve() will get passed to printText(),
// and the Error you passed into reject() will get passed to die().
readmePromise.then(printText, die);

// We can improve this even more:

readmePromise.then(console.log, die);

// By passing console.log as the success handler, we don't even need our
// printText() function.
```

Promises become super powerful in JavaScript when we need to compose a series
of actions into a process where some of those actions involve asynchronous
operations.

```JavaScript
function printWordCount(path) {
  // Notice how obvious it is to understand what is happening here. Each of
  // these functions will be called in the order given, but only after each
  // previous one completes any asynchronous operations.
  readFile(path)
    .then(joinLines)
    .then(splitWords)
    .then(countWords)
    .then(console.log)
    .catch(die)

  // If any errors are thrown in any of the functions in the chain, or if any
  // of them rejects a promise, then `catch(die)` will catch and handle them.
}

function readFile(path) {
  var promise = new IOU.Promise(function (resolve, reject) {
    FS.readFile(path, {encoding: 'utf8'}, function (err, text) {
      if (err) return reject(err);
      return resolve(text);
    });
  })
}

function joinLines(text) {
  return text.split('\n').join(' ');
}

function splitWords(text) {
  return text.split(' ');
}

function countWords(words) {
  return words.length;
}

function die(err) {
  console.error(err.stack);
  process.exit(1);
}
```

## API Quick Reference

### Module import
Import IOU using require like this:
```JavaScript
var IOU = require('iou')
```

### Promise Constructor
Construct a Promise instance by passing in a block of code in the form of a
callback function. Your callback function will be passed a resolve function
and reject function as arguments. Use `resolve(value)` to resolve your promise
to a given value, or use `reject(err)` to reject it with an Error.
```JavaScript
// Assuming you've already imported IOU like above:

var FS = require('fs')

var promise = new IOU.Promise(function (resolve, reject) {
  FS.readFile('README.md', {encoding: 'utf8'}, function (err, text) {
    if (err) return reject(err);
    return resolve(text);
  });
})
```

### #then()
Once you have a Promise instance, you can attach resolve and reject listeners
with `then(onResolve, onReject)`. The first parameter `onResolve(value)` will
be passed the resolved value of the promise if it succeeds. The second
parameter `onReject(err)` will be passed the rejected Error of the promise if
it ends up getting rejected.

If you only care about rejections, you can pass `null` in place of
`onResolve()`, and if you want skip handling rejections then don't pass in the
`onReject()` handler at all.

The `then()` method returns the promise, so you can chain it to compose a
sequence of actions, which is really powerful.
```JavaScript
  // Assuming we're using the promise we created above:

  // Listen for both the resolved value, or rejected error:
  promise.then(console.log, console.error);

  // Listen for resolved values only:
  promise.then(console.log);

  // Listen for the rejected error only:
  promise.then(null, console.error);

  // Chain calls to `then()` like in the example code earlier:
  readFile(path)
    .then(joinLines, console.error)
    .then(splitWords, console.error)
    .then(countWords, console.error)
    .then(console.log, console.error)
```

### #catch()
This is really just an alias for `then(null, onReject)`. This is a pattern that
is good to use, since it catches any possible thrown errors or rejected promises
that have not been handled in the chain.
```JavaScript
  promise.then(console.log).catch(console.error);

  function die(err) {
    console.error(err.stack);
    process.exit(1);
  }

  // console.log() and console.error() should never throw, but if we pretend
  // that they would, then using catch() would handle thrown errors or
  // rejections from either of them.
  promise.then(console.log, console.error).catch(die);

  // catch() becomes much more useful in chaining, where errors or rejections
  // can bubble up the chain and eventually all be caught by the handler given
  // to catch() (aptly named). A good example comes from the example code from
  // earlier:
  readFile(path)
    .then(joinLines)
    .then(splitWords)
    .then(countWords)
    .then(console.log)
    .catch(die)
```

### Promise.resolve()
```JavaScript
function getDaysInYear() {
  return IOU.Promise.resolve(365);
}

getDaysInYear().then(otherThing).catch(errorHandler);
```

### Promise.reject()
```JavaScript
function catchEmptyFile(text) {
  if (!text) {
    var err = new Error("Empty file");

    // Use Promise.reject() to pass an error through the promise chain. If you
    // didn't do this, then the next success handler would be called instead of
    // the error handler.

    return IOU.Promise.reject(err);
  }
  return text;
}

function die(err) {
  console.error(err.stack);
  process.exit(1);
}

// Using Promise.reject() in catchEmptyFile() will cause an empty file error
// to be caught by catch(die), and console.log will never be called.

promise.then(catchEmptyFile).then(console.log).catch(die);
```

### Promise.all()
```JavaScript
function printAll(texts) {
  console.log.call(console, texts);
}

var promises = [readFile('./config.yaml'), readFile('/etc/config.yaml'), readFile('/home/kris/config.yaml')]
IOU.Promise.all(promises).then(printAll).catch(die);
```

## Testing
To run the tests, just do

	./manage test

A list of checkmarks followed by `OK` means the tests succeeded. Anything else
should print out a stack trace for you, indicating a test failure.

Copyright and License
---------------------
Copyright (c) 2013 by <NAME> <<EMAIL>> (http://www.kixx.name).

Unless otherwise indicated, all source code is licensed under the MIT license.
See LICENSE for details.

{'fraction_non_alphanumeric': 0.1065583284968079, 'fraction_numerical': 0.002089378990133488, 'mean_word_length': 3.8954545454545455, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, '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': '995644', 'n_tokens_mistral': 2540, 'n_tokens_neox': 2427, 'n_words': 1093}