Update README

1 files changed, 76 insertions, 0 deletions

diff --git a/README.md b/README.md
index d187bcd..82c428a 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,79 @@
 # dicebag
 
 A dice expression parser and roller.
+
+## Installation
+
+    npm install --save dicebag
+
+## Usage
+
+    const { parse, pool, roll } = require('dicebag')
+
+The API consists of three functions:
+
+* `parse(diceExpression)` parses an expression into an object understood by the
+  other two functions.
+* `pool(dice)` rolls each die in the `dice` object, returning an array of
+  results.
+* `roll(dice)` rolls the dice and returns their sum.
+
+### Examples
+
+    const d6 = parse('1d6')
+    roll(d6)   # 4
+    roll(d6)   # 5
+    pool(d6)   # [ 2 ]
+    const dice = parse('2d6 + 1d8')
+    roll(dice) # 10
+    pool(dice) # [ 1, 4, 7 ]
+
+## Dice expressions
+
+### Basics
+
+Simple expressions involving standard dice notation as used in most roleplaying
+games are supported. You can do things like:
+
+* `XdY`: rolls `X` `Y`-sided dice (`1d6` is a single 6-sided die, `2d4` is two
+  4-sided dice).
+* `dice +/- constant`: rolls the dice, adds/subtracts the constant.
+* `dice +/- moreDice`: sums/takes the difference of the results of rolling
+  `dice` and `moreDice`.
+
+### Full syntax and semantics
+
+**Note:** this is still an early version. Syntax and semantics will be expanded
+in future versions. *Backwards incompatible changes are possible.*
+
+The parser recognizes the following grammar (all whitespace between symbols is
+ignored):
+
+    Die ::= <an integer>
+          | '(' Die ')'
+          | Die 'd' Die
+          | Die '+' Die
+          | Die '-' Die
+          | '-' Die
+
+Semantics are defined in terms of the `pool` function.
+
+* `N`, where an `N` is an integer, is a die that always rolls a single value
+  equal to `N`. `pool` returns an array containing just `N`.
+* `DdE`, where `D` and `E` are dice expressions, is a die that rolls a number of
+  dice equal to the result of rolling `D`, where each die has a number of sides
+  equal to the result of rolling `E`. `pool` returns an array of `roll(D)`
+  numbers, each between 1 and `roll(E)`. *Note:* if `D` or `E` evaluates to a
+  negative number, the behavior is undefined.
+* `D+E` appends the dice pool generated by `E` to the dice pool generated by
+  `D`.
+* `-D` returns the opposites of values generated by `D`.
+* `D-E` is equivalent to `D+(-E)`.
+
+Additionally:
+
+* The binary arithmetic operations (`+`, `-`) are left associative.
+* The die operation `d` is right associative (`1d2d3` is equivalent to
+  1d(2d3)`, use explicit parentheses if you need `(1d2)d3`)
+* `d` binds stronger than the binary arithmetic operations (`1d6+1d4` is
+  equivalent to `(1d6) + (1d4)`).