resplit, 0deck-s17

Author: gtheler

doc/blackjack.md

@@ -86,15 +86,93 @@ Proper quotation migh be needed if the value contains spaces. For example,
 blackjack --internal --cards="TH JS 6D"
 ```
 
-With no command-line options and no configuration file, `blackjack` starts in interactive mode and it is ready to start a blackjack game (see @sec:interactive for details).
+With no command-line options and no configuration file, `blackjack` starts in interactive mode and it is ready to start an ASCII blackjack game (see @sec:interactive).
 
 ## Results {#sec:results}
 
-TBD
+Before exiting, the program prints a summary of the results in YAML format:
+
+```terminal
+---
+result: "(-0.8 ± 0.3)"
+rules: "ahc h17 das doa 3rsp 0decks"
+mean: -0.008237
+error: 0.00348378
+hands: 1e+06
+bankroll: -8237
+busts_player: 0.139315
+busts_dealer: 0.239251
+wins: 0.447443
+pushes: 0.086111
+losses: 0.495896
+total_money_waged: 1.13708e+06
+blackjacks_player: 0.047392
+blackjacks_dealer: 0.047318
+variance: 1.34853
+deviation: 1.16126
+...
+```
+
+By default, the results are written in the standard error, as the standard output is typically used to send dealer's messages to the player.
+Therefore, if you are not using stdout (e.g. because you used the internal player `-i`) and want to use the results with Unix pipes, you have to redirect the standard error to the standard output:
+
+```terminal
+$ blackjack -i 2>&1 | yq .
+{
+  "result": "(-0.8 ± 0.3)",
+  "rules": "ahc h17 das doa 3rsp 0decks",
+  "mean": -0.007579,
+  "error": 0.00348416,
+  "hands": 1000000.0,
+  "bankroll": -7579,
+  "busts_player": 0.139308,
+  "busts_dealer": 0.239262,
+  "wins": 0.447834,
+  "pushes": 0.085761,
+  "losses": 0.495561,
+  "total_money_waged": 1136900.0,
+  "blackjacks_player": 0.047427,
+  "blackjacks_dealer": 0.047433,
+  "variance": 1.34882,
+  "deviation": 1.16139
+}
+```
 
-In YAML
+The YAML results can be written to a file by setting the variable `report` in the configuration file, where `stdout` is a valid file name.
+So the redirection above can be also performed as
 
-`yq`
+```terminal
+$ blackjack -i --report=stdout | yq .
+{
+  "result": "(-0.9 ± 0.3)",
+  "rules": "ahc h17 das doa 3rsp 0decks",
+  "mean": -0.00889,
+  "error": 0.00348549,
+  "hands": 1000000.0,
+  "bankroll": -8890,
+  "busts_player": 0.139248,
+  "busts_dealer": 0.239346,
+  "wins": 0.447292,
+  "pushes": 0.085985,
+  "losses": 0.495988,
+  "total_money_waged": 1136880.0,
+  "blackjacks_player": 0.047253,
+  "blackjacks_dealer": 0.047674,
+  "variance": 1.34985,
+  "deviation": 1.16183
+}
+```
+
+## Progress
+
+If the number of played hands exceeds a couple dozen million, one might want to track the progress.
+In that case, pass the option `-p` (or `--progress`) to get an ASCII progress bar in the standard error (remember standard output is used to play blackack).
+
+
+```terminal
+$ blackjack -i --progress
+[==================>                               ] 36 %
+```
 
 ## Interactive game {#sec:interactive}
 

doc/commands-inf.md

@@ -135,7 +135,7 @@ character $s$ gives the suit.
 |    `S`    | ♠ Spades         |
 : Suit (second) character of a card {#tbl:suit}
 
-The optional argument $h$ indicates the id of the player's hand
+The optional argument $h$ indicates the id of the player's hand
 being dealt. If it not present, that means the base hand.
 When performing a splitting on the base hand, the original hand
 has id equal to zero and the new hand has id equal to one.

doc/conf.md

@@ -15,6 +15,7 @@
 * `penetration_sigma` (@sec:penetration_sigma)
 * `player` (@sec:player)
 * `quit_when_arranged_cards_run_out` (@sec:quit_when_arranged_cards_run_out)
+* `resplits` (@sec:resplits)
 * `rng_seed` (@sec:rng_seed)
 * `rules` (@sec:rules)
 * `shuffle_every_hand` (@sec:shuffle_every_hand)
@@ -337,6 +338,21 @@ quit_when_arranged_cards_run_out = false
 quit_when_arranged_cards_run_out = true
 ~~~
 
+# `resplits = ` $n$ {#sec:resplits}
+
+Sets the maximum number of re-split hands.
+Default is three, meaning the dealer allows the player to play up to four hands.
+
+**Default**
+$3$
+
+**Examples**
+
+~~~
+resplits = 1
+resplits = 8
+~~~
+
 # `rng_seed = ` $n$ {#sec:rng_seed}
 
 This option sets the seed of the random number generator used by the dealer to draw cards.

doc/help-extra.txt

@@ -1,5 +1,3 @@
 If no configuration file is given, a file named blackjack.conf in the
-current directory is used, provided it exists.
-
-See the full documentation for the available options and the default
-values.
+current directory is used, provided it exists. See the full
+documentation for the available options and the default values.

doc/help-options-base.txt

@@ -2,7 +2,8 @@
   -n<n> or --hands=n         Specify the number of hands to play. Corresponds to the hands variable in the configuration file.
   -d<n> or --decks=n         Specify the number of decks to use in the shoe. Corresponds to the decks variable in the configuration file.
   -f or --flatbet            Do not ask for the amount to bet before starting a new hand and use a flat unit bet. Corresponds to the flat_bet variable in the configuration file.
-  -i or --internal -p or --progressUse the internal player to play against the dealer. See the manual for details and instructions to define the rules and optionally, the playing strategy and/or arranged shoes. Show a progress bar.
+  -i or --internal           Use the internal player to play against the dealer. See the manual for details and instructions to define the rules and optionally, the playing strategy and/or arranged shoes.
+  -p or --progress           Show a progress bar when playing a fixed number of hands.
   -h or --help               Print this informative help message into standard output and exit successfully.
   -v or --version            Print the version number and licensing information into standard output and then exit successfully.
   --configuration_variable[=value]Any configuration variable from the configuration file can be set from the command line. For example, passing --no_insurance is like setting no_insurance = 1 in the configuration file. Command-line options override setting in the configuration file.

doc/help.md

@@ -24,11 +24,14 @@ Corresponds to the `flat_bet` variable in the configuration file.
 
 
 `-i` or `--internal`
-`-p` or `--progress`
 
 :    Use the internal player to play against the dealer. See the manual for details
 and instructions to define the rules and optionally, the playing strategy and/or arranged shoes.
-Show a progress bar.
+
+
+`-p` or `--progress`
+
+:    Show a progress bar when playing a fixed number of hands.
 
 
 `-h` or `--help`
@@ -50,6 +53,5 @@ Command-line options override setting in the configuration file.
 
 If no configuration file is given, a file named `blackjack.conf`
 in the current directory is used, provided it exists.
-
 See the full documentation for the available options and the default values.
 

doc/help.txt

@@ -21,11 +21,15 @@
     a flat unit bet. Corresponds to the flat_bet variable in the
     configuration file.
 
--i or --internal -p or --progress
+-i or --internal
 
-: Use the internal player to play against the dealer. See the manual for
-details and instructions to define the rules and optionally, the playing
-strategy and/or arranged shoes. Show a progress bar.
+    Use the internal player to play against the dealer. See the manual
+    for details and instructions to define the rules and optionally, the
+    playing strategy and/or arranged shoes.
+
+-p or --progress
+
+    Show a progress bar when playing a fixed number of hands.
 
 -h or --help
 
@@ -45,7 +49,5 @@ strategy and/or arranged shoes. Show a progress bar.
     options override setting in the configuration file.
 
 If no configuration file is given, a file named blackjack.conf in the
-current directory is used, provided it exists.
-
-See the full documentation for the available options and the default
-values.
+current directory is used, provided it exists. See the full
+documentation for the available options and the default values.