Describe the keep highest mechanic

1 files changed, 12 insertions, 4 deletions

diff --git a/README.md b/README.md
index 537872e..16ec451 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,9 @@ games are supported. You can do things like:
 * `dice +/- constant`: rolls the dice, adds/subtracts the constant.
 * `dice +/- moreDice`: sums/takes the difference of the results of rolling
   `dice` and `moreDice`.
+* `number K dice`: rolls the dice and keeps the `number` highest results. For
+  example, `1K2d20` is the "rolling with advantage" mechanic from 5th Edition
+  Dungeons and Dragons (roll two d20's, keep the highest).
 
 ### Full syntax and semantics
 
@@ -78,6 +81,7 @@ ignored):
           | Die '-' Die
           | '-' Die
           | Die 'E' Die
+          | Die 'K' Die
 
 Semantics are defined in terms of the `pool` function.
 
@@ -99,11 +103,15 @@ Semantics are defined in terms of the `pool` function.
   value rolled on `D`. The die's result is the sum of all those rolls. *Note:*
   this could lead to an infinite evaluation if `F` always rolls higher than a
   possible result of `D`.
+* `DKE` is the "keep highest" mechanic. First `D` is rolled. Now each die in the
+  dice pool generated by `E` is rolled, and the resulting dice pool is composed
+  of those dice that rolled highest, taking up to as many dice as the result of
+  rolling `D`.
 
 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)`).
+* The die operations (`d`, `E`, `K`) are right associative (`1d2d3` is
+  equivalent to `1d(2d3)`, use explicit parentheses if you need `(1d2)d3`).
+* Die operations bind stronger than the binary arithmetic operations (`1d6+1d4`
+  is equivalent to `(1d6) + (1d4)`).