Convert docs to rst

docs/API.md

@@ -12,15 +12,15 @@
 
 > *Similar to `xdice.Pattern(pattern_string).roll()`*
 
-#### xdice.rolldice(faces, amount=1)
+#### xdice.rolldice(faces, amount=1, drop_lowest=0, drop_highest=0)
 
-> *Similar to `xdice.Dice(faces, amount).roll()`*
+> *Similar to `xdice.Dice(faces, amount, drop_lowest, drop_highest).roll()`*
 
 ## Dice object
 
 > Set of dice.
 
-#### Dice.__init__(sides, amount=1)
+#### Dice.__init__(sides, amount=1, drop_lowest=0, drop_highest=0)
 
 > Instantiate a set of dice.
 
@@ -30,8 +30,16 @@
 
 ####*[classmethod]* Dice.parse(cls, pattern)
 
-> Parse a pattern of the form 'AdX', where A and X are positive integers.
-> Returns the corresponding Dice object.
+> Parse a pattern of the form 'AdX', where A and X are positive integers, then return the corresponding Dice object.
+> Use 'AdX[Ln][Hn]' to drop the n lowest and/or highest dice when rolled.
+
+### Properties
+
+* `dice.sides`: number of sides of the dice
+* `dice.amount`: amount of dice to roll
+* `dice.drop_lowest`: amount of lowest scores to drop
+* `dice.drop_highest`: amount of highest scores to drop
+* `dice.name` : Decsriptive name of the Dice object
 
 ## Score object
 
@@ -51,12 +59,23 @@
         >>> list(s)
         [1,2,3]
 
-#### Score.__new__(iterable)
+#### Score.__new__(iterable, dropped=[], name="")
 
 >*`iterable` should only contain integers*
 
 > Score value will be the sum of the list's values.
 
+#### score.format(verbose=False)
+
+> A formatted string describing the detailed result.
+
+
+### Properties
+
+* score.detail: similar to list(score), return the list of the individual results
+* score.name: descriptive name of the dice rolled
+* score.dropped: list of the dropped results
+
 
 ## Pattern object
 

docs/CLI Usage.md

@@ -7,18 +7,23 @@ Run `python roll.py [options] <expr>`
 	
 	Options:
 	    -s               Numeric score only
+	    -v               Verbose result
 	
 	    -h --help        Displays help message
 	    --version        Displays current xdice version
 	    
-### Examples
 
 * Basic use
 
 	`python roll 1d6+1`
 	`>> 2       ([1]+1)`
 	
-* Numeric score only
+* Numeric score only (-s)
 
 	`python roll -s 1d6+1`
 	`>> 2`
+
+* Verbose (-v)
+
+	`python roll -v 2*(3D6L1+2D4)+R3(1d4+2)`
+	`>> (2*(3d6l1(scores:[5, 6], dropped:[3])+2d4(scores:[2, 1]))+(1d4(scores:[4])+2+1d4(scores:[1])+2+1d4(scores:[4])+2))`

docs/api.rst

@@ -0,0 +1,150 @@
+API
+===
+
+xdice.compile(pattern\_string)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    *Similar to ``xdice.Pattern(pattern_string).compile()``*
+
+    Returns a compiled Pattern object.
+
+    Pattern object can then be rolled to obtain a PatternScore object.
+
+xdice.roll(pattern\_string)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    *Similar to ``xdice.Pattern(pattern_string).roll()``*
+
+xdice.rolldice(faces, amount=1, drop\_lowest=0, drop\_highest=0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    *Similar to
+    ``xdice.Dice(faces, amount, drop_lowest, drop_highest).roll()``*
+
+Dice object
+-----------
+
+    Set of dice.
+
+Dice.\ **init**\ (sides, amount=1, drop\_lowest=0, drop\_highest=0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Instantiate a set of dice.
+
+dice.roll()
+^^^^^^^^^^^
+
+    Role the dice and return a Score object
+
+*[classmethod]* Dice.parse(cls, pattern)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Parse a pattern of the form ‘AdX’, where A and X are positive
+    integers, then return the corresponding Dice object. Use
+    ‘AdX[Ln][Hn]’ to drop the n lowest and/or highest dice when rolled.
+
+Properties
+~~~~~~~~~~
+
+-  ``dice.sides``: number of sides of the dice
+-  ``dice.amount``: amount of dice to roll
+-  ``dice.drop_lowest``: amount of lowest scores to drop
+-  ``dice.drop_highest``: amount of highest scores to drop
+-  ``dice.name`` : Decsriptive name of the Dice object
+
+Score object
+------------
+
+    Score is a subclass of integer, you can then manipulate it as you
+    would do with an integer.
+
+    | It also provides an access to the detailed score with the property
+      ‘detail’.
+    | ‘detail’ is the list of the scores obtained by each dice.
+
+    Score class can also be used as an iterable, to walk trough the
+    individual scores.
+
+::
+
+    eg:
+        >>> s = Score([1,2,3])
+        >>> print(s)
+        6
+        >>> s + 1
+        7
+        >>> list(s)
+        [1,2,3]
+
+Score.\ **new**\ (iterable, dropped=\ ``_, name=“”)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    *``iterable`` should only contain integers*
+
+    Score value will be the sum of the list’s values.
+
+score.format(verbose=False)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    A formatted string describing the detailed result.
+
+Properties
+~~~~~~~~~~
+
+-  score.detail: similar to list(score), return the list of the
+   individual results
+-  score.name: descriptive name of the dice rolled
+-  score.dropped: list of the dropped results
+
+Pattern object
+--------------
+
+    Dice notation pattern.
+
+Pattern.\ **init**\ (instr)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Instantiate a Pattern object.
+
+pattern.compile()
+^^^^^^^^^^^^^^^^^
+
+    Parse the pattern. Two properties are updated at this time:
+
+-  *pattern.format\_string*
+
+    The ready-to-be-formatted string built from the ``instr`` argument.
+
+    *Eg: ‘1d6+4+1d4’ => ‘{0}+4-{1}’*
+
+-  *pattern.dices*
+
+    The list of parsed dice.
+
+    *Eg: ‘1d6+4+1d4’ => [(Dice; sides=6;amount=1), (Dice;
+    sides=4;amount=1)]*
+
+pattern.roll()
+^^^^^^^^^^^^^^
+
+    Compile the pattern if it has not been yet, then roll the dice.
+
+    Return a PatternScore object.
+
+PatternScore object
+-------------------
+
+    PatternScore is a subclass of **integer**, you can then manipulate
+    it as you would do with an integer.
+
+    Moreover, you can get the list of the scores with the score(i) or
+    scores() methods, and retrieve a formatted result with the format()
+    method.
+
+pattern\_score.scores()
+^^^^^^^^^^^^^^^^^^^^^^^
+
+    Returns the list of Score objects extracted from the pattern and
+    rolled.
+
+.. _: #section

docs/cli.rst

@@ -0,0 +1,30 @@
+Command-Line
+------------
+
+Run ``python roll.py [options] <expr>``
+
+::
+
+    Usage:
+        roll [options] <expr>
+
+    Options:
+        -s               Numeric score only
+        -v               Verbose result
+
+        -h --help        Displays help message
+        --version        Displays current xdice version
+        
+
+-  Basic use
+
+   ``python roll 1d6+1`` ``>> 2       ([1]+1)``
+
+-  Numeric score only (-s)
+
+   ``python roll -s 1d6+1`` ``>> 2``
+
+-  Verbose (-v)
+
+   ``python roll -v 2*(3D6L1+2D4)+R3(1d4+2)``
+   ``>> (2*(3d6l1(scores:[5, 6], dropped:[3])+2d4(scores:[2, 1]))+(1d4(scores:[4])+2+1d4(scores:[1])+2+1d4(scores:[4])+2))``

docs/dice_notation.md

@@ -1,10 +1,10 @@
-# Dice Notation
+## Dice Notation
 
 *Dice notation* is nearly fully understood by pydice.
 
-## Dice
+### Dice
 
-> Following patterns can be passed to the Dice.parse() class method, and will then return the corresponding Dice object.
+> Patterns describes here can be passed to the Dice.parse() class method, and will then return the corresponding Dice object.
 
 **[See Wikipedia for a complete definition.](https://en.wikipedia.org/wiki/Dice_notation)**
 
@@ -24,22 +24,20 @@ Note: the `D%` notation is read as `D100`
 
 #### Selective results
 
-This pattern can be followed by `Ln` and/or `Hn` expressions.
-'L' and 'H' respectively stand for lowest and highest.
+The `AdX` pattern can be followed by `Ln` and/or `Hn` ('L' and 'H' respectively stand for lowest and highest).
 
 In this case, the lowest/highest n scores will be discard when the dice will be rolled.
 
-> `3D6L1` will roll three 6-sided dice, and drop the lowest, while `3D6H1` will roll three 6-sided dice, and drop the highest.
+*Eg: `3D6L1` will roll three 6-sided dice, and drop the lowest, while `3D6H1` will roll three 6-sided dice, and drop the highest.*
 
-If no number follow the 'L' or 'H', it is assumed to be a 1.
-'L' and 'H' can be combined inside a single pattern.
+Notes:
+* If no number follow the 'L' or 'H', it is assumed to be a 1.
+* 'L' and 'H' can be combined inside a single pattern.
 
 
-## Patterns
+### Patterns
 
-> Following patterns can be passed to the Pattern.parse() class method.
-
-#### Bases
+> Patterns describes here can be passed to the Pattern.parse() class method.
 
 `AdX` notations can be integrated in complex expressions.
 
@@ -55,19 +53,19 @@ Any mathematical expression is allowed:
 
 Currently, the following python functions are allowed: `abs`, `max`, `min`
 
-#### Repeat pattern
+#### Repeat
 
 The `Rn(AdX)` notation can be used to repat n times the `AdX` command.
 
 For example, the pattern `R3(2d6+2)` will roll `2d6+2` three times.
 
-## Examples
+### Examples
 
-`1d6` 					> Roll a 6-sided die
-`1d6+3` 				> Roll a 6-sided die, then add 3
-`2*(1d6+3)`			> Roll a 6-sided die, add 3, then multiply by 2
-`3d6L2`				> Roll three 6-sided dice, and drop the two lowest.
-`R2(1d6+3)`			> Similar to `1d6+3+1d6+3`
-`1d%`					> Similar to `1d100`
-`d6`					> Similar to `1d6`
-`min(1d6+10,3d6)`	> Keep the minimal score between `1d6+10` and `3d6`
+* `1d6` 					> Roll a 6-sided die
+* `1d6+3` 				> Roll a 6-sided die, then add 3
+* `2*(1d6+3)`			> Roll a 6-sided die, add 3, then multiply by 2
+* `3d6L2`				> Roll three 6-sided dice, and drop the two lowest.
+* `R2(1d6+3)`			> Similar to `1d6+3+1d6+3`
+* `1d%`					> Similar to `1d100`
+* `d6`					> Similar to `1d6`
+* `min(1d6+10,3d6)`	> Keep the minimal score between `1d6+10` and `3d6`

docs/dice_notation.rst

@@ -0,0 +1,93 @@
+Dice Notation
+-------------
+
+*Dice notation* is nearly fully understood by pydice.
+
+Dice
+~~~~
+
+    Patterns describes here can be passed to the Dice.parse() class
+    method, and will then return the corresponding Dice object.
+
+**`See Wikipedia for a complete definition.`_**
+
+Bases
+^^^^^
+
+Die rolls are given in the form AdX. A (amount) and X (sides) are
+variables, separated by the letter “d”, which stands for die or dice.
+
+-  A is the number of dice to be rolled (1 if omitted).
+-  X is the number of faces of each die.
+
+If the final number is omitted, it is assumed to be a twenty. (This can
+be changed trough the class property Dice.DEFAULT\_SIDES)
+
+    For example, if a game would call for a roll of d4 or 1d4 this would
+    mean, “roll one 4-sided die.” ``3d6`` would mean, “roll three
+    six-sided dice”
+
+Note: the ``D%`` notation is read as ``D100``
+
+Selective results
+^^^^^^^^^^^^^^^^^
+
+The ``AdX`` pattern can be followed by ``Ln`` and/or ``Hn`` (‘L’ and ‘H’
+respectively stand for lowest and highest).
+
+In this case, the lowest/highest n scores will be discard when the dice
+will be rolled.
+
+*Eg: ``3D6L1`` will roll three 6-sided dice, and drop the lowest, while
+``3D6H1`` will roll three 6-sided dice, and drop the highest.*
+
+Notes: \* If no number follow the ‘L’ or ‘H’, it is assumed to be a 1.
+\* ‘L’ and ‘H’ can be combined inside a single pattern.
+
+Patterns
+~~~~~~~~
+
+    Patterns describes here can be passed to the Pattern.parse() class
+    method.
+
+``AdX`` notations can be integrated in complex expressions.
+
+Any mathematical expression is allowed:
+
+::
+
+    >> 1d10+1d5+1
+    >> 1d20-6
+    >> 1d6*2
+    >> 2d20//4
+    >> 1d6*(1d4**2)
+
+Builtin python functions
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently, the following python functions are allowed: ``abs``, ``max``,
+``min``
+
+Repeat
+^^^^^^
+
+The ``Rn(AdX)`` notation can be used to repat n times the ``AdX``
+command.
+
+For example, the pattern ``R3(2d6+2)`` will roll ``2d6+2`` three times.
+
+Examples
+~~~~~~~~
+
+-  ``1d6`` > Roll a 6-sided die
+-  ``1d6+3`` > Roll a 6-sided die, then add 3
+-  ``2*(1d6+3)`` > Roll a 6-sided die, add 3, then multiply by 2
+-  ``3d6L2`` > Roll three 6-sided dice, and drop the two lowest.
+-  ``R2(1d6+3)`` > Similar to ``1d6+3+1d6+3``
+-  ``1d%`` > Similar to ``1d100``
+-  ``d6`` > Similar to ``1d6``
+-  ``min(1d6+10,3d6)`` > Keep the minimal score between ``1d6+10`` and
+   ``3d6``
+
+.. _See Wikipedia for a complete definition.: https://en.wikipedia.org/wiki/Dice_notation
+

docs/index.md

@@ -1,5 +1,7 @@
 # XDice
 
+## Presentation
+
 *xdice* is a lightweight python library for managing dice, scores, and dice-notation patterns.
 
 It allows to easily interpret literal expressions as rolls of dice ('1d6', '3d4+3', '12d6+1d4'...etc.), then manipulate the results.
@@ -10,31 +12,43 @@ DiceRollParser has been tested with python 3.3+
 
 ### Examples
 
-	import dice
-
-	## Roll simple dices with **rolldice()**
-	
-	score = rolldice(6, amount=2)
-	
-	# manipulates score as an integer
-	
-	print( score, score * 2, score == 11 )
-	>> 11		22		True
-	
-	
-	# Iterates over the results
-	
-	for result in score:
-		print(result)
-	>> 5
-	>> 6
-
-	# Parse patterns with **roll()**
-	
-	ps = roll("2d6+18")
-	
-	print( ps, ps.format() )
-	>> 28		'[5,6]+18'
+    import dice
+
+    # Roll dices with dice.rolldice()
+
+    score = dice.rolldice(6, amount=2)
+
+    # manipulate 'score' as an integer
+
+    print(score)
+    >> 11
+    print(score * 2)
+    >> 22
+    print(score == 11)
+    >> True
+
+    # Or iterate over the results
+
+    for result in score:
+        print(result)
+    >> 5
+    >> 6
+
+    # Parse patterns with dice.roll()
+
+    ps = dice.roll("2d6+18")
+
+    print(ps)
+    >> 28
+    print(ps.format())
+    >> '[5,6]+18'
+
+    ps = dice.roll("6D%L2")
+
+    print(ps)
+    >> 315
+    print(ps.format(verbose=True))
+    >> '6D%L2(scores:[80, 70, 76, 89], dropped:[2, 49])'
 
 
 ### Contribution

docs/introduction.rst

@@ -0,0 +1,83 @@
+XDice
+=====
+
+Presentation
+------------
+
+*xdice* is a lightweight python library for managing dice, scores, and
+dice-notation patterns.
+
+It allows to easily interpret literal expressions as rolls of dice
+(‘1d6’, ‘3d4+3’, ‘12d6+1d4’…etc.), then manipulate the results.
+
+Python Versions
+~~~~~~~~~~~~~~~
+
+DiceRollParser has been tested with python 3.3+
+
+Examples
+~~~~~~~~
+
+::
+
+    import dice
+
+    # Roll dices with dice.rolldice()
+
+    score = dice.rolldice(6, amount=2)
+
+    # manipulate 'score' as an integer
+
+    print(score)
+    >> 11
+    print(score * 2)
+    >> 22
+    print(score == 11)
+    >> True
+
+    # Or iterate over the results
+
+    for result in score:
+        print(result)
+    >> 5
+    >> 6
+
+    # Parse patterns with dice.roll()
+
+    ps = dice.roll("2d6+18")
+
+    print(ps)
+    >> 28
+    print(ps.format())
+    >> '[5,6]+18'
+
+    ps = dice.roll("6D%L2")
+
+    print(ps)
+    >> 315
+    print(ps.format(verbose=True))
+    >> '6D%L2(scores:[80, 70, 76, 89], dropped:[2, 49])'
+
+Contribution
+~~~~~~~~~~~~
+
+Any opinion / contribution is welcome, please contact us.
+
+Installation
+~~~~~~~~~~~~
+
+::
+
+    pip install xdice
+
+License
+~~~~~~~
+
+*xdice* is under GNU License
+
+Tags
+~~~~
+
+::
+
+    dice roll d20 game random parser dices role board