stak/README.md

# Stak [![Build Status][1]][2]

Create re-usable stacks of code to run.

## Status: beta

## Example

``` javascript
var stack = Stak.make(
    function readSelf() {
        fs.readFile(this.uri, this.next);
    },
    function capitalize(err, text) {
        this.next(err, text.toUpperCase());
    }
);

stack.handle({
    uri: __filename,
    floor: function showIt(err, newText) {
        if (err) throw err;
        console.log(newText);
    }
});
```

## Motivation

Similar to [Step][3] except you create a stack that can be re-used. This means you create the functions once and pass data in through the this context.

## Documentation

### Stak.make(...) <a name="make" href="#make"><small><sup>link</sup></small></a>

Shortcut for `Object.create(Stak).constructor(...)`

``` javascript
Stak.make(function () {
    this.next(true)
}, function (value) {
    assert(value === true);
}).handle();
```

### Stak.use(...) <a name="use" href="#use"><small><sup>link</sup></small></a>

Add extra functions to the stack

``` javascript
var s = Stak.make();

s.use(function () {
    console.log("it works");
});

s.handle(); // it works
```

### Stak.handle(context) <a name="handle" href="#handle"><small><sup>link</sup></small></a>

This starts a stack. The first function in the stack will be called and the next function will be called once the first function calls this.next. The context object is passed in as `this`.

``` javascript
var context = {};
var s = Stak.make(function () { assert(this === context); });
s.handle(context);
```

The context also has two special properties `floor` and `ceil` which form the floor and the ceiling of the stack of functions. This allows you to add a function before and after all the other functions

``` javascript
var stack = Stak.make(function (data) {
    this.next(data * this.multiplier);
});

stack.handle({
    multiplier: 3,
    ceil: function () {
        this.next(42);
    },
    floor: function (data) {
        assert(data === 42 * 3);
    }
});
```

### Stak.floor <a name="floor" href="#floor"><small><sup>link</sup></small></a>

A default floor for this instance of the stack. If no floor is passed through handle then this floor will be used

### Stak.ceil <a name="ceil" href="#ceil"><small><sup>link</sup></small></a>

A default ceiling for this instance of the stack. If no ceil is passed through handle then this ceil will be used

## Installation

`npm install stak`

## Tests

`make test`

## Contributors

 - Raynos

## MIT Licenced

  [1]: https://secure.travis-ci.org/Raynos/stak.png
  [2]: http://travis-ci.org/Raynos/stak
  [3]: https://github.com/creationix/step