Skip to content

Commit 75245a3

Browse files
gthelergtheler
committed
doc
1 parent 4e0cc29 commit 75245a3

17 files changed

Lines changed: 878 additions & 172 deletions

‎TODO.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,13 @@
22

33
* RSA
44
* ES10
5-
* arranged cards in shoes (i.e. decks != 0)
6-
* multiple players
5+
* multiple players (actually multiple hands for a single player)
76

87
# medium
98

109
* tests
1110
* error handler, explain what the valid choices are (i.e. unknown rules)
1211
* update docs, write a nice manual (m4 -> md -> texinfo -> pdf)
13-
- command line invocation
1412
- playing commands
1513
- configuration options
1614
* cpu and wall time in report

‎doc/blackjack.md‎

Lines changed: 76 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ a dealer (he) that knows how to deal blackjack, tells the player (her) what card
5151

5252
# Running `blackjack`
5353

54-
## Invocation
54+
## Invocation {#sec:invocation}
5555

5656
The `blackjack` program executable follows the POSIX standard. Its usage is:
5757

@@ -74,16 +74,26 @@ decks = 4
7474
no_insurance = true
7575
```
7676

77+
Proper quotation migh be needed if the value contains spaces. For example,
78+
79+
```terminal
80+
blackjack --internal --cards="TH JS 6D"
81+
```
82+
7783
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).
7884

79-
## Results
85+
## Results {#sec:results}
86+
87+
TBD
8088

8189
In YAML
8290

8391
`yq`
8492

8593
## Interactive game {#sec:interactive}
8694

95+
TBD
96+
8797
If `blackjack` is attached to an interactive TTY (i.e. neither the standard input nor outputs are redirected) and there is no `player` option in the configuration file, an interactive game is triggered. First thing the program will do is to ask for a bet:
8898

8999
```terminal
@@ -105,7 +115,7 @@ xxxxx
105115
```
106116

107117
The user can quit by either typing `quit` (or `q`) or hitting Ctrl-D.
108-
See @sec:playing for a description of all the possible commands---in both ways, from the dealer to the player and from the player to the dealer.
118+
Write `help` or see @sec:p2d for a description of all the possible commands the player can give to the dealer.
109119

110120

111121
# Playing blackjack {#sec:playing}
@@ -125,36 +135,81 @@ Here are the basic Blackjack rules:
125135
6. If the dealer has a ten or an ace showing (after offering insurance with an ace showing), then he will peek at his facedown card to see if he has a blackjack. If he does, then he will turn it over immediately.
126136
7. If the dealer does have a blackjack, then all wagers (except insurance) will lose, unless the player also has a blackjack, which will result in a push. The dealer will resolve insurance wagers at this time.
127137
8. Play begins with the player to the dealer's left. The following are the choices available to the player:
128-
- **Stand**: Player stands pat with his cards.
129-
- **Hit**: Player draws another card (and more if he wishes). If this card causes the player's total points to exceed 21 (known as "breaking" or "busting") then he loses.
130-
- **Double**: Player doubles his bet and gets one, and only one, more card.
131-
- **Split**: If the player has a pair, or any two 10-point cards, then he may double his bet and separate his cards into two individual hands. The dealer will automatically give each card a second card. Then, the player may hit, stand, or double normally. However, when splitting aces, each ace gets only one card. Sometimes doubling after splitting is not allowed. If the player gets a ten and ace after splitting, then it counts as 21 points, not a blackjack. Usually the player may keep
132-
re-splitting up to a total of four hands. Sometimes re-splitting aces is not allowed.
133-
- **Surrender**: The player forfeits half his wager, keeping the other half, and does not play out his hand. This option is only available on the initial two cards, and depending on casino rules, sometimes it is not allowed at all.
138+
139+
Stand
140+
141+
: Player stands pat with his cards.
142+
143+
Hit
144+
145+
: Player draws another card (and more if he wishes). If this card causes the player's total points to exceed 21 (known as "breaking" or "busting") then he loses.
146+
147+
Double
148+
149+
: Player doubles his bet and gets one, and only one, more card.
150+
151+
Split
152+
153+
: If the player has a pair, or any two 10-point cards, then he may double his bet and separate his cards into two individual hands. The dealer will automatically give each card a second card. Then, the player may hit, stand, or double normally. However, when splitting aces, each ace gets only one card. Sometimes doubling after splitting is not allowed. If the player gets a ten and ace after splitting, then it counts as 21 points, not a blackjack. Usually the player may keep re-splitting up to a total of four hands. Sometimes re-splitting aces is not allowed.
154+
155+
Surrender
156+
157+
: The player forfeits half his wager, keeping the other half, and does not play out his hand. This option is only available on the initial two cards, and depending on casino rules, sometimes it is not allowed at all.
158+
134159
9. After each player has had his turn, the dealer will turn over his hole card. If the dealer has 16 or less, then he will draw another card. A special situation is when the dealer has an ace and any number of cards totaling six points (known as a "soft 17"). At some tables, the dealer will also hit a soft 17.
135160
10. If the dealer goes over 21 points, then any player who didn't already bust will win.
136161
11. If the dealer does not bust, then the higher point total between the player and dealer will win.
137162
12. Winning wagers pay even money, except a winning player blackjack usually pays 3 to 2. Some casinos have been short-paying blackjacks, which is a rule strongly in the casino's favor.
138163

164+
To perform monte-carlo simulations, in Libre Blackjack the dealer (he) and the player (she) can “talk” through commands which are ASCII strings sent through an inter-process communcation (IPC) mechanism.
165+
In the most basic case, an automated player reads messages from the dealer from `blackjack`’s standard output and writes her ASCII commands into the dealer’s standard input.
166+
167+
168+
## Messages from the dealer to the player {#sec:d2p}
169+
170+
* Messages are ASCII-formatted string composed of tokens separated by spaces.
171+
* Each message starts with a single token which is either a single English word (e.g. `bet` or `play`) or more than one English words concatenated using a low hyphen `_` (e.g. `new_hand` or `player_card`). That is to say, the first token of the message is a single-token string.
172+
* The first token might or might not end with a question mark `?` (e.g. `card_player 4H` or `play? 18 4`):
173+
- Messages with tokens that do not end in a question mark `?` are informative and do not need any response from the player.
174+
- Interrogative messages strating with tokens than end in a question mark `?` need to be answered by the player. That is to say, after issuing a message as a question the dealer starts listening to the proper communication channel (see @sec:communication) for a valid command from the dealer (detailed in @sec:p2d).
175+
* A message might have extra tokens that convey information to the player, e.g. `new_hand 15141 -4587.5`, `card_player 9S`, `play? 16 10`.
176+
* All numerical values such as hand totals or bankrolls are given as decimal ASCII strings.
177+
139178

140-
In Libre Blackjack, the dealer (he) and the player (she) can “talk” through commands which are ASCII strings sent through the standard input/output. In the most basic case, a human player reads commands from the dealer from `blackjack`’s standard output and writes her commands into the dealer’s standard input. Those commands from the dealer that require a particular action from the player end with a quotation sign such as `bet?`, `insurance?` or `play?`.
179+
### Informative messages
141180

142-
All numerical values such as hand totals or bankrolls are given as decimal ASCII strings.
181+
```include
182+
commands-inf.md
183+
```
184+
185+
#### `new_hand` $n$ $b$ {#sec:new_hand}
186+
187+
The dealer states that a new hand is starting. The integer $n$ states the number of the hand (starting from 1).
188+
The decimal number $b$ states the player's bankroll before placing the bet in the starting hand.
189+
190+
191+
**Examples**
192+
193+
```
194+
new_hand 1 0.000000
195+
new_hand 22 -8.000000
196+
new_hand 24998 -7609.500000
197+
```
143198

144-
## Commands from the dealer to the player
199+
### Interrogative messages
145200

146-
xxxx
147201

148-
## Commands from the player to the dealer
202+
203+
## Commands from the player to the dealer {#sec:p2d}
204+
205+
TBD
149206

150207
The following commands are available for the player for playing her hand.
151208

152-
include(input-particular.md)
153209

154210

155211
The following are general commands in the sense that they can be sent from the player to the dealer at any moment of the game.
156212

157-
include(input-general.md)
158213

159214

160215

@@ -207,19 +262,21 @@ decks = 1 # number of decks, negative means infinite
207262

208263
## Reference
209264

210-
xxxx
265+
TBD
211266

212267

213268
# Internal players
214269

215-
270+
TBD
216271

217272
# Examples
218273

219274
The directory `players` contains a few examples of automated players, which are discussed in the following sections.
220275

221276

222-
# Communication mechanisms
277+
278+
279+
# Communication mechanisms {#sec:communication}
223280

224281
## Standard input & output
225282

‎doc/commands-inf.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
2+
* `shuffling` (@sec:shuffling)
3+
* `new_hand` (@sec:new_hand)
4+
* `bet_negative` (@sec:bet_negative)
5+
* `bet_maximum` (@sec:bet_maximum)
6+
* `bet_zero` (@sec:bet_zero)
7+
* `card_player` (@sec:card_player)
8+
9+
10+
#### `shuffling` {#sec:shuffling}
11+
12+
The dealer informs that he is shuffling the decks.
13+
This only happens when a non-zero value for the option `decks` is set.
14+
If `decks = 0` (or the command-line option `-d0` is passed), then cards
15+
are drawn randomnly from an infinite set of cards and there is no need to shuffle.
16+
17+
**Examples**
18+
19+
~~~
20+
shuffling
21+
~~~
22+
23+
#### `new_hand` $n$ $b$ {#sec:new_hand}
24+
25+
The dealer states that a new hand is starting. The integer $n$ gives
26+
the number of the hand that is about to start (first hand is $n=1$).
27+
The decimal number $b$ states the player's bankroll before placing
28+
the bet in the hand that is about to start.
29+
Even though bets have to be integers, pay offs might be non-integer
30+
such as when winning a natural (e.g. $3/2 = 1.5$ or $6/5$ = 1.2).
31+
32+
**Examples**
33+
34+
~~~
35+
new_hand 1 0
36+
new_hand 22 -8
37+
new_hand 24998 -7609.5
38+
~~~
39+
40+
#### `bet_negative` {#sec:bet_negative}
41+
42+
The dealer complains that the bet the placer placed is invalid.
43+
Only positive integer numbers are allowed.
44+
The player will receive a new `bet?` message.
45+
46+
**Examples**
47+
48+
~~~
49+
bet_negative
50+
~~~
51+
52+
#### `bet_maximum` {#sec:bet_maximum}
53+
54+
The dealer complains that the bet the placer placed is invalid.
55+
The bet is larger than the maximum wager allowed by `maximum_bet`.
56+
The player will receive a new `bet?` message.
57+
58+
**Examples**
59+
60+
~~~
61+
bet_maximum
62+
~~~
63+
64+
#### `bet_zero` {#sec:bet_zero}
65+
66+
The dealer complains that the bet the placer placed is invalid.
67+
Only positive integer numbers are allowed.
68+
The player will receive a new `bet?` message.
69+
70+
**Examples**
71+
72+
~~~
73+
bet_zero
74+
~~~
75+
76+
#### `card_player` $rs$ {#sec:card_player}
77+
78+
The dealer informs that the player has been dealt a card.
79+
The card is given as a two-character ASCII representation where
80+
the first character $r$ indicates the rank and the second
81+
character $s$ gives the suit.
82+
83+
| Character | Rank |
84+
|:---------:|------------------|
85+
| `A` | Ace |
86+
| `2` | Deuce |
87+
| `3` | Three |
88+
| `4` | Four |
89+
| `5` | Five |
90+
| `6` | Six |
91+
| `7` | Seven |
92+
| `8` | Eight |
93+
| `9` | Nine |
94+
| `T` | Ten |
95+
| `J` | Jack |
96+
| `Q` | Queen |
97+
| `J` | King |
98+
99+
| Character | Suit |
100+
|:---------:|------------------|
101+
| `C` | ♣ Clubs |
102+
| `D` | ♦ Diamonds |
103+
| `H` | ♥ Hearts |
104+
| `S` | ♠ Spades |
105+
106+
**Examples**
107+
108+
~~~
109+
card_player 9C
110+
card_player JD
111+
card_player QC
112+
card_player KS
113+
card_player TD
114+
card_player 6H
115+
~~~
116+
117+

0 commit comments

Comments
 (0)