owlbear/README.md

A simple dice notation parser.

Owlbear
=======

Parses and composes dice notation, with support for exploding dice, rerolls, discarding lowest rolls, moving along a dice chain and simple arithmetic. Doesn't actually *roll* anything.

Example
=======

```
var Owlbear = require('owlbear');

myOwlbear = new Owlbear();

myOwlbear.parse('4d6k3'); // k: keep n of x in xdykn
/* 
returns: 
[
  {
    count: 4,
    chain: 0,
    keep: 3,
    die: {
      sides: 6,
      reroll: [],
      explode: []
    }
  }
]
*/

myOwlbear.parse('1d4R! + 5'); // R: reroll lowest (1), !: explode highest (4)
/*
returns:
[
  {
    count: 1,
    chain: 0,
    keep: 1,
    die: {
      sides: 4,
      reroll: [1],
      explode: [4]
    }
  },
  {
    operator: '+'
  },
  {
    constant: 5
  }
]
*/

// or just get super goofy. 
// >: shift up dice chain, <: shift down.
// r: reroll listed, x: explode listed.
myOwlbear.parse(Math.PI + 'd10.5r6.2,6.3x10!>>>><');
/*
returns:
[
  {
    count: Math.PI,
    chain: 3,
    keep: Math.PI,
    die: {
      sides: 10.5,
      reroll: [6.2, 6.3],
      explode: [10.5, 10]
    }
  }
]
*/

// we can go backwards as well.
myOwlbear.compose([
  {
    constant: 10
  },
  {
    operator: '*'
  },
  {
    count: 1,
    chain: -1,
    keep: 1,
    die: {
      sides: 4,
      reroll: [1],
      explode: []
    }
  }
]) == '10*1d4R<';
```

Owlbear objects
===============

```
new Owlbear(options);
```

Creates a new owlbear.

**Supported options:**

- ```operators``` - Supported operators. Defaults to [ '*', '/', '+', '-' ].

parse() method
==============

```
owlbear.parse(notation);
```

Dice notation may include any of the supported operators (as above) between die specifications. Each specification may be either a numeric constant or a die. Dice are in the format:

(number of dice)d(sides on a die)R!r(comma-separated numbers)x(comma-separated numbers)k(number of dice to keep)><

- (number of dice) defaults to 1 if not present. May be floating point, must be non-negative.
- (sides on a die) May be floating point, must be non-negative.
- R indicates the lowest possible roll should be rerolled on this die.
- ! indicates the highest possible roll should 'explode' -- be rerolled and added in.
- r indicates the numbers afterward should be rerolled.
- x indicates the numbers afterward should 'explode'.
- k(number of dice to keep) indicates that only the highest n dice count.
- < and > indicate shifts along a dice chain.

parse() returns an array of objects as shown in the above examples.

compose() method
================

```
owlbear.compose(Object[])
```

Returns a string of dice notation that will parse as the object provided.