Update readme for new syntax

README.mkdn

@@ -1,14 +1,20 @@
 # roll.py: A dice-rolling simulator for RPGs
 
-This was a weekend hobby project inspired by
-[Critical Role](http://geekandsundry.com/shows/critical-role/) and
+This was a weekend hobby project inspired by [Critical Role][1] and
 other D&D shows and podcasts. While a dice simulator is no substitute
 for physically rolling real dice, it might be useful for anyone who's
-on the go or otherwise unable to access their dice or a flat surface
+on the go or otherwise unable to access their dice and a flat surface
 to roll them on (or for new players who want to try out RPGs without
-having to spend money on dice first). It supports pretty much
-everything under the
-["Standard Notation" section of the Wikipedia page on dice notation](https://en.wikipedia.org/wiki/Dice_notation#Standard_notation).
+having to spend money on dice first). It supports almost much
+everything under the ["Standard Notation"][2] section of the Wikipedia
+page on dice notation, as well as the syntax in this online [RPG Dice
+Roller][3] and this [Android App][4]. (One notable exception is
+non-standard Fate dice, i.e. "dF.1", which are not supported.)
+
+[1]: http://geekandsundry.com/shows/critical-role/
+[2]: https://en.wikipedia.org/wiki/Dice_notation#Standard_notation
+[3]: http://rpg.greenimp.co.uk/dice-roller/
+[4]: https://www.critdice.com/roll-advanced-dice
 
 ## Usage
 
@@ -22,69 +28,98 @@ dice rolls that led to it. Examples:
 ```bash
 # Single-roll command-line mode
 $ ./roll.py 2d4+2
-2016-03-13 14:43:16,690 INFO: Rolling 2d4+2
-2016-03-13 14:43:16,691 INFO: 2d4+2 rolled: 8
-(Individual rolls: [2, 4])
-2016-03-13 14:43:16,691 INFO: Total roll: 8
+2d4 rolled: [3,1], Total: 4
+2017-11-26 15:54:47,849 INFO: Total roll for '2d4 + 2': 6
 # Interactive mode
 $ ./roll.py
+# Advantage roll in D&D, with a modifier
 Enter roll> 2d20-L+2
-2016-03-13 15:17:24,496 INFO: Rolling 2d20-L+2
-2016-03-13 15:17:24,496 INFO: 2d20-L+2 rolled: 22 (NATURAL 20)
-(Individual rolls: [20]; Dropped low: [5]; Original rolls: [5, 20])
-2016-03-13 15:17:24,496 INFO: Total roll: 22
+2d20-L rolled: 10 (dropped 5)
+2017-11-26 15:55:37,826 INFO: Total roll for '2d20-L + 2': 12
+
 Enter roll> 6d6+6
-2016-03-13 14:43:34,468 INFO: Rolling 6d6+6
-2016-03-13 14:43:34,468 INFO: 6d6+6 rolled: 25
-(Individual rolls: [4, 1, 1, 3, 4, 6])
-2016-03-13 14:43:34,469 INFO: Total roll: 25
+6d6 rolled: [4,4,6,5,6,2], Total: 27
+2017-11-26 16:26:43,989 INFO: Total roll for '6d6 + 6': 33
+
 Enter roll> d100
-2016-03-13 14:43:41,854 INFO: Rolling d100
-2016-03-13 14:43:41,854 INFO: d100 rolled: 67
-2016-03-13 14:43:41,855 INFO: Total roll: 67
+d100 rolled: 16
+2017-11-26 16:26:51,805 INFO: Total roll for 'd100': 16
+
+# Complex arithmetic expressions and non-standard dice are allowed
 Enter roll> d4 + 2d6 + 4 - 3d8 + 6d7/2
-2016-03-13 14:49:17,237 INFO: Rolling d4 + 2d6 + 4 - 3d8 + 6d7/2
-2016-03-13 14:49:17,237 INFO: d4 rolled: 4
-2016-03-13 14:49:17,238 INFO: 2d6 rolled: 7
-(Individual rolls: [6, 1])
-2016-03-13 14:49:17,238 INFO: 3d8 rolled: 13
-(Individual rolls: [6, 5, 2])
-2016-03-13 14:49:17,238 INFO: 6d7 rolled: 19
-(Individual rolls: [2, 4, 7, 2, 1, 3])
-2016-03-13 14:49:17,238 INFO: Total roll: 11
-Enter roll> 4 + 5
-2016-03-13 14:48:13,823 INFO: Rolling 4 + 5
-2016-03-13 14:48:13,823 INFO: Total roll: 9
-Enter roll> exit
+d4 rolled: 1
+2d6 rolled: [3,6], Total: 9
+3d8 rolled: [4,5,5], Total: 14
+6d7 rolled: [1,3,4,1,4,6], Total: 19
+2017-11-26 16:27:01,238 INFO: Total roll for 'd4 + 2d6 + 4 - 3d8 + (6d7 / 2)': 9.5
+
+# Any arithmetic expression is allowd, even if it doesn't roll any dice
+Enter roll> 4 + 6^2 / 3
+2017-11-26 16:48:46,121 INFO: Total roll for '4 + ((6 ^ 2) / 3)': 16
+
+# You can save specific rolls as named variables
+Enter roll> health_potion = 2d4 + 2
+2017-11-26 16:53:56,188 INFO: Saving health_potion as '2d4 + 2'
+
+Enter roll> health_potion
+2d4 rolled: [1,3], Total: 4
+2017-11-26 16:54:44,287 INFO: Total roll for '2d4 + 2': 6
+
+# Variables can reference other variables
+Enter roll> greater_health_potion = health_potion + health_potion
+2017-11-26 16:54:12,684 INFO: Saving double_health_potion as 'health_potion + health_potion'
+
+Enter roll> greater_health_potion
+2d4 rolled: [4,4], Total: 8
+2d4 rolled: [4,3], Total: 7
+2017-11-26 16:55:30,455 INFO: Total roll for '(2d4 + 2) + (2d4 + 2)': 19
+
+# Show currently defined variables
+Enter roll> vars
+2017-11-26 16:59:15,241 INFO: Currently defined variables:
+greater_health_potion = 'health_potion + health_potion'
+health_potion = '2d4 + 2'
+
+# Delete a variable
+Enter roll> del greater_health_potion
+2017-11-26 16:59:40,713 INFO: Deleting saved value for 'greater_health_potion'.
+
+# Reroll ones once
+Enter roll> 4d4r
+4d4r rolled: [1r,2,2,3], Total: 8
+2017-11-26 17:01:41,592 INFO: Total roll for '4d4r': 8
+
+# Reroll ones indefinitely
+Enter roll> 4d4R
+4d4R rolled: [3,3,2R,4], Total: 12
+2017-11-26 17:01:53,784 INFO: Total roll for '4d4R': 12
+
+# Exploding dice
+Enter roll> 6d6!
+6d6! rolled: [1,6!,3,3,4,5,6!,5], Total: 33
+2017-11-26 16:30:43,003 INFO: Total roll for '6d6!': 33
+
+# Explode any roll greater than 3
+Enter roll> 6d6!>3
+6d6!>3 rolled: [4!,4!,6!,2,2,5!,2,1,6!,4!,1,1], Total: 38
+2017-11-26 16:32:18,204 INFO: Total roll for '6d6!>3': 38
+
+# Penetrating dice
+Enter roll> 6d6!p
+6d6!p rolled: [1,6!p,1,5,6!p,2,1,5], Total: 27
+2017-11-26 16:32:48,727 INFO: Total roll for '6d6!p': 27
+
+# Fate dice
+Enter roll> 4dF+2
+4dF rolled: [0,0,0,1], Total: 1
+2017-11-26 16:34:11,533 INFO: Total roll for '4dF + 2': 3
+
+# Enter 'help' for other non-roll commands
+Enter roll> quit
+2017-11-26 16:29:47,624 INFO: Quitting.
 ```
 
-As you can see, it not only reports the total, but all the individual
-dice rolls, so if you made a mistake on a modifier or something, you
-don't have to re-roll the entire thing, you can change the modifier
-and re-add the existing dice rolls manually. Also, as a special
-feature, it tells you when you get a natural 1 or a natural 20 on a
-singular d20 roll.
-
-Notice the last few examples that demonstrate:
-
-* arbitrarily complex arithmetic expressions involving any number and
-  kind of dice and any number of modifiers, as well as multiplication
-  and division (useful for resistances and critical hits)
-* physically impossible dice, like d7
-* simple constant expressions that don't involve any dice rolls.
-
-(This last feature is useful for re-computing a mis-typed modifier
-without re-rolling the dice.)
-
-## Rolling with advantage/disadvantage and dropping rolls
-
-Some RPGs have a concept of "advantage" or "disadvantage", which just
-means rolling two of the same die and dropping either the lower of the
-two (for advantage) or the higher (for disadvantage). You can do this
-by appending `-L` to drop the lowest roll and `-H` to drop the highest
-one. More generally, you can drop any number of low or high rolls by
-adding a number after the `H` or `L`. One of the examples above shows
-a d20 roll with a +5 modifier and advantage, which is expressed as
-"2d20-L+6". When dropping dice, all the original rolls are reported,
-as well as which ones were dropped, so you always have a full audit
-trail in case your DM asks you what your dice rolls were.
+As you can see, it not only reports the total for each roll, but all
+the individual dice rolls as well, so you can understand how it came
+up with the total. This also lets you figure out whether you rolled a
+natural 20 or natural 1 on the die.