| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 |
"http://www.w3.org/TR/html4/strict.dtd"> |
| 3 |
<html> |
| 4 |
<head> |
| 5 |
<!-- $Id: commands.html 313 2009-06-11 05:44:13Z thomasoa $ --> |
| 6 |
<title>Index of Deal Commands</title> |
| 7 |
<link rel="stylesheet" type="text/css" href="commands.css"> |
| 8 |
|
| 9 |
</head> |
| 10 |
<body> |
| 11 |
<div id="indexbox" class='index'> |
| 12 |
<div><a href="index.html">Back to Deal top page</a></div> |
| 13 |
<h3>Index</h3> |
| 14 |
<ul> |
| 15 |
<li><a href='#accept' >accept</a><li><a href='#balanced' >balanced</a><li><a href='#binky' >Binky Points evaluators</a><li><a href='#binky_nt' >binky::nt</a><li><a href='#binky_suit' >binky::suit</a><li><a href='#clubs' >clubs</a><li><a href='#correlation' >correlation</a><li><a href='#deal::input' ><em>input files</em></a><li><a href='#deal::metadata' >deal::metadata</a><li><a href='#deal::nostacking' >deal::nostacking</a><li><a href='#deal::tricks' >deal::tricks</a><li><a href='#deal_deck' >deal_deck</a><li><a href='#deal_finished' >deal_finished</a><li><a href='#deal_reset_cmds' >deal_reset_cmds</a><li><a href='#deck_stack_cards' >deck_stack_cards</a><li><a href='#deck_stack_hand' >deck_stack_hand</a><li><a href='#defvector' >defvector</a><li><a href='#diamonds' >diamonds</a><li><a href='#ddline' >ddline <em>input format</em></a><li><a href='#format:ddline' >ddline <em>output format</em></a><li><a href='#dds' ><em>Double Dummy Solver, Bo Haglund's</em></a><li><a href='#ddscmd' >dds</a><li><a href='#east' >east</a><li><a href='#flush_deal' >flush_deal</a><li><a href='#full_deal' >full_deal</a><li><a href='#hand' >is <em>subcommand</em></a><li><a href='#giblib' >giblib <em>input</em></a><li><a href='#gibstuff' ><em>GIB-related routines</em></a><li><a href='#gib::directory' >gib::directory</a><li><a href='#gib::tricks' >gib::tricks</a><li><a href='#handInterface' ><em>hand procedures</em></a><li><a href='#hcp' >hcp</a><li><a href='#hearts' >hearts</a><li><a href='#holdingp' ><em>holding procedures</em></a><li><a href='#holding' >holding</a><li><a href='#holdingProc' >holdingProc</a><li><a href='#lho' >lho</a><li><a href='#library.dat' >library.dat <em>input</em></a><li><a href='#line' >line <em>input</em></a><li><a href='#losers' >losers</a><li><a href='#main' >main</a><li><a href='#newLTC' >newLTC</a><li><a href='#north' >north</a><li><a href='#format:par' >par <em>output format</em></a><li><a href='#parscore' >parscore</a><li><a href='#partner' >partner</a><li><a href='#pattern' >pattern <em>subcommand</em></a><li><a href='#patternclass' >patternclass</a><li><a href='#patterncond' >patterncond</a><li><a href='#patternfunc' >patternfunc</a><li><a href='#reject' >reject</a><li><a href='#reset_deck' >reset_deck</a><li><a href='#rho' >rho</a><li><a href='#seed_deal' >seed_deal</a><li><a href='#shape' >shape <em>subcommand</em></a><li><a href='#score' >score</a><li><a href='#sdev' >sdev</a><li><a href='#semibalanced' >semibalanced</a><li><a href='#shapeclass' >shapeclass</a><li><a href='#shapecond' >shapecond</a><li><a href='#shapefunc' >shapefunc</a><li><a href='#shapes' ><em>shape procedures</em></a><li><a href='#smartstack' >smartstack</a><li><a href='#south' >south</a><li><a href='#spades' >spades</a><li><a href='#stack_cards' >stack_cards</a><li><a href='#stack_hand' >stack_hand</a><li><a href='#stacked' >stacked</a><li><a href='#statistics' ><em>statistics</em></a><li><a href='#tricks' >tricks</a><li><a href='#west' >west</a><li><a href='#whogets' >whogets</a><li><a href='#write_deal' >write_deal</a><li><a href='#exitflag' >-x <em>flag</em></a></ul> |
| 16 |
</div> |
| 17 |
<div id="commandsbox" class='commands'> |
| 18 |
<h1>Introduction</h1> |
| 19 |
<table style="width: 100%" cellpadding=5><tr valign=top><td style="width: 65%"> |
| 20 |
This is meant to be a comprehensive list of commands in Deal which |
| 21 |
are not native to Tcl. If you want to learn Tcl, I will be providing |
| 22 |
a set of pointers later. |
| 23 |
<td style="width: 35%"> |
| 24 |
<div class='tcl'> |
| 25 |
Text in blue is meant for Tcl afficianado |
| 26 |
- reading this text without knowledge of Tcl might confuse more than |
| 27 |
enlighten. |
| 28 |
</div> |
| 29 |
<br> |
| 30 |
<div class='programmer'> |
| 31 |
Text in green is meant for programmers |
| 32 |
interested in finding code definitions. |
| 33 |
</div> |
| 34 |
</table> |
| 35 |
<hr> |
| 36 |
|
| 37 |
<a name="north"></a><a name="east"></a><a name="south"></a><a name="west"></a> |
| 38 |
<a name="hand"></a> |
| 39 |
<a name="shape"></a><a name="pattern"></a> |
| 40 |
<h1>Hand commands: <code>north</code>, <code>east</code>, <code>south</code>, <code>west</code>, <code>hand</code></h1> |
| 41 |
<table cellpadding=5 style="width: 100%"> |
| 42 |
<tr valign="top"><td style="width: 65%"> |
| 43 |
<h2>Usage</h2> |
| 44 |
<pre class='example'> |
| 45 |
east [ -void <em>string</em>] [ <em>suitname</em> ... ] |
| 46 |
hand {<em>hand string</em>} [ -void <em>string</em>] [ <em>suitname</em> ... ] |
| 47 |
|
| 48 |
south <em>subcommand</em> [ <em>... args ...</em> ] |
| 49 |
hand {<em>hand string</em>} <em>subcommand</em> [ <em>... args ...</em> ] |
| 50 |
</pre> |
| 51 |
These are very strange commands - they really have too much stuffed |
| 52 |
into them. That's a historical anomoly which I'm reluctant to abandon. |
| 53 |
<p> |
| 54 |
With no subcommands, the routine is used for formatting the hand as |
| 55 |
a string. For example, if south is: |
| 56 |
<pre class='example'> |
| 57 |
S: AJ5432 |
| 58 |
H: KT94 |
| 59 |
D: void |
| 60 |
C: K93 |
| 61 |
</pre> |
| 62 |
Then the results of various commands are: |
| 63 |
<pre class='example'> |
| 64 |
south => {AJ5432 KT94 {} K93} |
| 65 |
south spades => AJ5432 |
| 66 |
south hearts clubs => {KT94 K93} |
| 67 |
south -void - => {AJ5432 KT94 - K93} |
| 68 |
south -void --- diamonds => --- |
| 69 |
|
| 70 |
set h {AK4 {} A95432 JT98} |
| 71 |
hand $h => {AK4 {} A95432 JT98} |
| 72 |
hand $h spades => AK4 |
| 73 |
hand $h hearts clubs => {{} JT98} |
| 74 |
hand $h -void - => {AK4 - A95432 JT98} |
| 75 |
</pre> |
| 76 |
The -void switch exists precisely for formatting the output. |
| 77 |
<p> |
| 78 |
The various subcommands will be treated in seperate sections. |
| 79 |
|
| 80 |
The <code>hand</code> version of this command only works with some subcommands. |
| 81 |
</td><td style="width: 35%"> |
| 82 |
<div class='programmer'><b>For Programmers</b> |
| 83 |
<dl><dt>Implementation:</dt> |
| 84 |
<dd>C code |
| 85 |
<dt>Location:</dt> |
| 86 |
<dd><code>tcl_deal.c</code>, function <code>tcl_hand_cmd</code> |
| 87 |
</dl> |
| 88 |
</div> |
| 89 |
</td> |
| 90 |
<tr valign=top><td style="width: 65%"> |
| 91 |
<h2>Subcommand: <code>shape</code></h2> |
| 92 |
<h3>Usage</h3> |
| 93 |
<pre class='example'> |
| 94 |
north shape |
| 95 |
hand {AJTxx Axx JTxx x} shape |
| 96 |
</pre> |
| 97 |
<h3>Summary</h3> |
| 98 |
Returns a list of suit lengths, in standard order. |
| 99 |
<p> |
| 100 |
For example, the second command above would return the list: |
| 101 |
<pre class='example'> |
| 102 |
5 3 4 1 |
| 103 |
</pre> |
| 104 |
<h2>Subcommand: <code>pattern</code></h2> |
| 105 |
<h3>Usage</h3> |
| 106 |
<pre class='example'> |
| 107 |
north pattern |
| 108 |
hand {AJ32 A5 JTxx xxx} pattern |
| 109 |
</pre> |
| 110 |
<h3>Summary</h3> |
| 111 |
Returns a sorted list of the suit lengths, starting with the longest. |
| 112 |
For example, the second command above would return the list: |
| 113 |
<pre class='example'> |
| 114 |
4 4 3 2 |
| 115 |
</pre> |
| 116 |
<h2>Subcommand: <code>is</code></h2> |
| 117 |
<h3>Usage</h3> |
| 118 |
<pre class='example'> |
| 119 |
south is {<em>handstring</em>} |
| 120 |
</pre> |
| 121 |
<h3>Summary</h3> |
| 122 |
This command pre-places a specific 13 cards. For voids, you can use |
| 123 |
the "<code>-</code>" character: |
| 124 |
<pre class='example'> |
| 125 |
south is {AJ32 KT932 - Q876} |
| 126 |
</pre> |
| 127 |
Calls to this subcommand must occur before dealing begins, outside the |
| 128 |
"<code><a href="#main">main</a></code>" command. |
| 129 |
<p> |
| 130 |
This subcommand calls the <a href="#stack_hand"><code>stack_hand</code> command.</a> |
| 131 |
Inside the <code>main</code> code, the deal is already dealt. |
| 132 |
<h2>Subcommand: <code>gets</code></h2> |
| 133 |
<h3>Usage</h3> |
| 134 |
<pre class='example'> |
| 135 |
<em>handname</em> gets <em>card</em> [<em>card</em> ...] |
| 136 |
</pre> |
| 137 |
<h3>Summary</h3> |
| 138 |
Puts a specific list of cards in the hand named. As with the |
| 139 |
"<code>is</code>" subcommand, this must be called before dealing |
| 140 |
starts, outside the "<code><a href="#main">main</a></code>" command. |
| 141 |
The card is specified in two characters, a rank character and a suit |
| 142 |
character: |
| 143 |
<pre class='example'> |
| 144 |
AS KH JH 9D |
| 145 |
</pre> |
| 146 |
This routine dispatches its data to <a href="#stack_cards">the <code>stack_cards</code> command.</a> |
| 147 |
|
| 148 |
<h2>Subcommand: <code>has</code></h2> |
| 149 |
<h3>Usage</h3> |
| 150 |
<pre class='example'> |
| 151 |
<em>handname</em> has <em>card</em> [<em>card</em> ...] |
| 152 |
hand {<em>string</em>} has <em>card</em> [...] |
| 153 |
</pre> |
| 154 |
<h3>Summary</h3> |
| 155 |
This returns a count of the cards listed that occur in the hand named. |
| 156 |
<pre class='example'> |
| 157 |
% south |
| 158 |
AJ54 JT54 43 654 |
| 159 |
% south has SA HK HJ HT |
| 160 |
3 |
| 161 |
</pre> |
| 162 |
</td><td style="width: 35%"> </td></table> |
| 163 |
<hr> |
| 164 |
<h1>Control commands</h1> |
| 165 |
<a name="accept"></a><a name="reject"></a> |
| 166 |
<h2>Commands: <code>accept</code> and <code>reject</code></h2> |
| 167 |
<table style="width: 100%" cellpadding=5><tr valign=top><td style="width: 65%"> |
| 168 |
<h3>Usage</h3> |
| 169 |
<pre class='example'> |
| 170 |
accept [ [ if | unless ] <em>expr expr ...</em>] |
| 171 |
reject [ [ if | unless ] <em>expr expr ...</em>] |
| 172 |
</pre> |
| 173 |
<h3>Summary</h3> |
| 174 |
Without arguments, <code>accept</code> and <code>reject</code> are the |
| 175 |
same as <span class='nobr'><code>return 1</code></span> and <span class='nobr'><code>return |
| 176 |
0</code></span>, respectively. |
| 177 |
<p> |
| 178 |
With arguments it's a little more obscure. |
| 179 |
<pre class='example'> |
| 180 |
accept if {$h>4} |
| 181 |
</pre> |
| 182 |
This returns 1 if the expression matches. It is equivalent to: |
| 183 |
<pre class='example'> |
| 184 |
if {$h>4} { return 1 } |
| 185 |
</pre> |
| 186 |
The code: |
| 187 |
<pre class='example'> |
| 188 |
accept if {$h>4} {$s>4} |
| 189 |
</pre> |
| 190 |
Is logically equivalent to: |
| 191 |
<pre class='example'> |
| 192 |
if {$h>4 || $s>4} { return 1} |
| 193 |
</pre> |
| 194 |
That is, the values are accepted if either of the expressions |
| 195 |
evaluates as true. |
| 196 |
<p> |
| 197 |
The <code>unless</code> option does the opposite: |
| 198 |
<pre class='example'> |
| 199 |
accept unless {$h>4} {$s>4} |
| 200 |
</pre> |
| 201 |
This is equivalent to: |
| 202 |
<pre class='example'> |
| 203 |
if {!($h>4) || !($s>4)} { return 1 } |
| 204 |
</pre> |
| 205 |
<p> |
| 206 |
The means we return with a true value <em>unless</em> one of the expressions |
| 207 |
is true. If one of the values is true, we simply go on to the next line. |
| 208 |
<p> |
| 209 |
<h3>Examples</h3> |
| 210 |
Virtually all of the examples included in the release contain an |
| 211 |
instance of "accept" or "reject." |
| 212 |
|
| 213 |
<td style="width: 35%;"> |
| 214 |
<div class='programmer'> |
| 215 |
<b>For Programmers</b> |
| 216 |
<dl> |
| 217 |
<dt>Implementation:</dt> |
| 218 |
<dd>C code</dd> |
| 219 |
<dt>Location:</dt> |
| 220 |
<dd>tcl_deal.c, procedure <code>tcl_deal_control</code>.</dd> |
| 221 |
</dl> |
| 222 |
<p>This construct is borrowed from the Perl programming language. |
| 223 |
Originally, I added it to Deal 2.0 for performance reasons. Those |
| 224 |
reasons are obsolote with Tcl 8.x, but I like the mnemonic enough |
| 225 |
to keep it, and removing it might confuse old users.</p> |
| 226 |
</div> |
| 227 |
|
| 228 |
<div class='tcl'> |
| 229 |
<b>For Tcl Experts</b> |
| 230 |
<p>There actually is one subtle and occasionally useful distinction |
| 231 |
between <code>accept/reject</code> and the stated |
| 232 |
<pre class='example'>if {...} { return ... }</code></pre> |
| 233 |
<p>version. In reality:</p> |
| 234 |
<pre class='example'> |
| 235 |
accept if {$h>4} {$s>4} |
| 236 |
</pre> |
| 237 |
<p>is equivalent to:</p> |
| 238 |
<pre class='example'> |
| 239 |
if {$h>4||$s>4} { |
| 240 |
return 1 |
| 241 |
} |
| 242 |
expr 0 |
| 243 |
</pre> |
| 244 |
This only matters when the command is the last |
| 245 |
command in a procedure. The two procedures: |
| 246 |
<pre class='example'> |
| 247 |
proc A {h s} { |
| 248 |
if {$h>4||$s>4} { |
| 249 |
return 1 |
| 250 |
} |
| 251 |
} |
| 252 |
|
| 253 |
proc B {h s} { |
| 254 |
accept if {$h>4} {$s>4} |
| 255 |
} |
| 256 |
</pre> |
| 257 |
<p>are slightly different.</p> |
| 258 |
<p>A call of <code>A 3 3</code> returns an empty string, while a call |
| 259 |
of <code>B 3 3</code> returns 0. That can be useful, as you can see |
| 260 |
here.</p> |
| 261 |
</div> |
| 262 |
|
| 263 |
</table> |
| 264 |
|
| 265 |
<hr> |
| 266 |
<a name="main"></a> |
| 267 |
<h2>Command: <code>main</code></h2> |
| 268 |
<table cellspacing=5 style="width: 100%"> |
| 269 |
<tr valign=top><td style="width: 65%"> |
| 270 |
<h3>Usage</h3> |
| 271 |
<pre class='example'> |
| 272 |
main { |
| 273 |
<em>block of code</em> |
| 274 |
} |
| 275 |
</pre> |
| 276 |
|
| 277 |
<h3>Summary</h3> |
| 278 |
This defines the primary block of code evaluated after <em>each</em> |
| 279 |
deal is generated. If the code <em>returns</em> true, |
| 280 |
<b>Deal</b> will treat the deal as a "match" and call |
| 281 |
<b>write_deal</b>. It will also increment its count of deals |
| 282 |
found and exit if the limit is reached. |
| 283 |
</td><td style="width: 35%"> |
| 284 |
<div class='programmer'> |
| 285 |
<b>For Programmers</b> |
| 286 |
<dl><dt>Implementation:</dt><dd>C code</dd> |
| 287 |
<dt>Location:</dt><dd>tcl_deal.c, procedure <code>tcl_deal_control</code>. |
| 288 |
</dl> |
| 289 |
</div> |
| 290 |
</table> |
| 291 |
<hr> |
| 292 |
|
| 293 |
<a name="whogets"></a> |
| 294 |
<h2>Command: <code>whogets</code></h2> |
| 295 |
<table cellspacing=5 style="width: 100%"> |
| 296 |
<tr valign=top><td style="width:65%"> |
| 297 |
<h3>Usage</h3> |
| 298 |
<pre class='example'> |
| 299 |
whogets <em>cardname</em> |
| 300 |
</pre> |
| 301 |
This returns the name of the person holding the card <em>cardname</em>. |
| 302 |
</td><td style="width: 35%"> |
| 303 |
<div class='programmer'> |
| 304 |
<b>For Programmers</b> |
| 305 |
<dl><dt>Implementation:</dt><dd>C code</dd> |
| 306 |
<dt>Location:</dt><dd>tcl_deal.c, procedure <code>tcl_deal_to_whom</code>. |
| 307 |
</dl> |
| 308 |
</div> |
| 309 |
</table> |
| 310 |
<hr> |
| 311 |
|
| 312 |
<a name="deal_finished"></a> |
| 313 |
<h2>Command: <code>deal_finished</code></h2> |
| 314 |
<table cellspacing=5 style="width: 100%"> |
| 315 |
<tr valign=top><td style="width:65%"> |
| 316 |
<h3>Usage</h3> |
| 317 |
<pre class='example'> |
| 318 |
deal_finished { |
| 319 |
<em>block of code</em> |
| 320 |
} |
| 321 |
</pre> |
| 322 |
This defines the code called at the completion of generating all deals. |
| 323 |
This is code you would use to dump statistics, for example. |
| 324 |
</td><td style="width: 35%"> |
| 325 |
<div class='programmer'> |
| 326 |
<b>For Programmers</b> |
| 327 |
<dl><dt>Implementation:</dt><dd>C code</dd> |
| 328 |
<dt>Location:</dt><dd>tcl_deal.c, procedure <code>tcl_after_set</code>. |
| 329 |
</dl> |
| 330 |
</div> |
| 331 |
</table> |
| 332 |
<hr> |
| 333 |
|
| 334 |
<h1>Bridge Evaluators</h1> |
| 335 |
<h2>Common interfaces</h2> |
| 336 |
There are some standard interfaces to bridge evaluation functions. |
| 337 |
<a name="handInterface"></a> |
| 338 |
|
| 339 |
<h3>Hand Procedures</h3> |
| 340 |
Any procedure defined entirely based on the values in one hand is considered |
| 341 |
a <em>hand procedure</em>. These procedures can be called in one of two |
| 342 |
ways: |
| 343 |
<pre class='example'> |
| 344 |
Weak2Bid <em>handname</em> |
| 345 |
|
| 346 |
Weak2Bid hand {AKQxxx xxx xxx x} |
| 347 |
</pre> |
| 348 |
The <em>handname</em> parameter can be one of |
| 349 |
<code>north</code>, <code>south</code>, <code>east</code>, <code>west</code>. |
| 350 |
<a href="#shapes">Shape procedures</a> and <a href="#holdingp">holding |
| 351 |
procedures</a> fit the hand procedure calling method, along with other |
| 352 |
options. |
| 353 |
<hr> |
| 354 |
<a name="shapes"></a> |
| 355 |
<h3>Shape procedures</h3> |
| 356 |
Any procedure defined on the shape of a hand can be called with one of |
| 357 |
the following methods: |
| 358 |
<pre class='example'> |
| 359 |
balanced <em>handname</em> |
| 360 |
|
| 361 |
balanced hand {AJxx xxx AKxx Kx} |
| 362 |
|
| 363 |
balanced eval 4 3 4 2 |
| 364 |
|
| 365 |
balanced shape {4 3 4 2} |
| 366 |
|
| 367 |
semibalanced <em>handname</em> |
| 368 |
|
| 369 |
semibalanced hand {AJ432 AKx Kx xxx} |
| 370 |
|
| 371 |
semibalanced eval 5 3 2 3 |
| 372 |
|
| 373 |
semibalanced shape {5 3 2 3} |
| 374 |
</pre> |
| 375 |
This follows the <a href="#hand">hand procedure</a> outline with the |
| 376 |
addition of the <code>eval</code> option. |
| 377 |
<p> |
| 378 |
<hr> |
| 379 |
<a name="holdingp"></a> |
| 380 |
<h3>Holding procedures</h3> |
| 381 |
A holding procedure is a <a href="#handInterface">hand procedure</a> |
| 382 |
which is evaluated on a bridge hand by evaluating each suit holding |
| 383 |
one at a time, and then accumulate the results. There are two |
| 384 |
common ways of defining holding procedures, |
| 385 |
<a href="#defvector"><code>defvector</code></a> and |
| 386 |
<a href="#holdingProc"><code>holdingProc</code></a>. |
| 387 |
<p> This is an |
| 388 |
abstraction of a very common bridge evaluation technique. The most |
| 389 |
commonly used holding functions are <em>high card points</em>, |
| 390 |
<em>losing trick count</em>, <em>controls</em>. For example, when |
| 391 |
counting the losers in the hand <code>AKxx Axx KQJxxx x</code>, we |
| 392 |
find 1 loser in spades, 2 losers in hearts, 1 loser in diamonds, |
| 393 |
and one loser in clubs. We define the total losers to be the sum |
| 394 |
across all suits, and get 5 losers, total. <p> The interface lets |
| 395 |
you evaluate the entire hand, or only selected suits in a hand, or |
| 396 |
a specific list of holdings. |
| 397 |
|
| 398 |
<pre class='example'> |
| 399 |
hcp <em>handname</em> [ <em>suitname</em> ... ] |
| 400 |
|
| 401 |
hcp hand {AKJxxx K xxx xxx} [ <em>suitname</em> ... ] |
| 402 |
|
| 403 |
hcp holding AK43 [ ... ] |
| 404 |
</pre> |
| 405 |
In the first two cases, if no suits are named, all suits are evaluated, and |
| 406 |
the results are accumulated. In the case of the <code>holding</code> call, |
| 407 |
the specific holdings passed in are evaluated. |
| 408 |
<p> |
| 409 |
Note, I've been saying "accumulated" rather than added. In some cases, |
| 410 |
you might have an accumulation method different from addition. For example, |
| 411 |
you might return the standard opening leads from a holding: |
| 412 |
<pre class='example'> |
| 413 |
openingLead holding KQJ7 => K |
| 414 |
openingLead south => {K} {7 2} {4} {J} |
| 415 |
</pre> |
| 416 |
Each suit would create a list of proposed leads, and the result would be |
| 417 |
a list of lists of all standard leads from all holdings. Here, the |
| 418 |
accumulation is to simply make a list. |
| 419 |
<hr> |
| 420 |
|
| 421 |
<a name="balanced"></a> |
| 422 |
<a name="semibalanced"></a> |
| 423 |
<h2>Command: <code>balanced</code> and <code>semibalanced</code></h2> |
| 424 |
<table cellpadding=5 style="width: 100%"> |
| 425 |
<tr valign=top><td style="width: 65%"> |
| 426 |
<h3>Usage</h3> |
| 427 |
<pre class='example'> |
| 428 |
balanced <em>handname</em> |
| 429 |
|
| 430 |
balanced hand {<em>text hand</em>} |
| 431 |
|
| 432 |
balanced eval <em>s</em> <em>h</em> <em>d</em> <em>c</em> |
| 433 |
</pre> |
| 434 |
<h3>Summary</h3> |
| 435 |
These are both <a href="#shapes">shape procedures</a>. |
| 436 |
<p> |
| 437 |
<code>balanced</code> returns true if the hand is some 4333, 4432, or 5332 |
| 438 |
without a 5-card major. |
| 439 |
<p> |
| 440 |
<code>semibalanced</code> returns true if the hand has no singletons |
| 441 |
or voids, not six-card majors, and no seven-card minors. |
| 442 |
<td style="width: 35%"> |
| 443 |
<div class='programmer'> |
| 444 |
<b>For Programmers</b> |
| 445 |
<dl><dt>Implementation:</dt> |
| 446 |
<dd><code>Tcl</code> with <code>shapecond</code> |
| 447 |
<dt>Location:</dt> |
| 448 |
<dd><code>lib/features.tcl</code> |
| 449 |
</dl> |
| 450 |
<p>These use to be hard-coded in the C code, but it made more sense |
| 451 |
to add them to the library code - the user can change the definitions |
| 452 |
as he likes.</p> |
| 453 |
</div> |
| 454 |
</table> |
| 455 |
<hr> |
| 456 |
|
| 457 |
<a name="clubs"></a> |
| 458 |
<a name="diamonds"></a> |
| 459 |
<a name="hearts"></a> |
| 460 |
<a name="spades"></a> |
| 461 |
<h2>Commands: <code>clubs</code>, <code>diamonds</code>, <code>hearts</code>, <code>spades</code></h2> |
| 462 |
<table cellpadding=5 style="width: 100%"> |
| 463 |
<tr valign=top><td style="width: 65%"> |
| 464 |
<h3>Usage</h3> |
| 465 |
<pre class='example'> |
| 466 |
<code>spades</code> <em>handname</em> |
| 467 |
<code>spades</code> <code>hand</code> <code>{AKxx Axx AJxx Kx}</code> |
| 468 |
</pre> |
| 469 |
These implement the <a href="#hand">hand procedure</a> interface, and |
| 470 |
return the suit lengths for the appropriate suit. |
| 471 |
<td style="width: 35%"> |
| 472 |
<div class='programmer'> |
| 473 |
<b>For Programmers</b> |
| 474 |
<dl><dt>Implementation:</dt> |
| 475 |
<dd> |
| 476 |
<dt>Location:</dt> |
| 477 |
<dd><code>tcl_deal.c</code>, function <code>tcl_suit_count</code> |
| 478 |
</dl> |
| 479 |
<p>These could be <em>shape procedures</em> but for speed reasons, I've |
| 480 |
left them this way.</p> |
| 481 |
</div> |
| 482 |
</table> |
| 483 |
<hr> |
| 484 |
|
| 485 |
<h1>Holding Evaluators</h1> |
| 486 |
<a name="hcp"></a> |
| 487 |
<h2>Command: <code>hcp</code></h2> |
| 488 |
<table cellpadding=5 style="width: 100%"> |
| 489 |
<tr valign=top><td style="width: 65%"> |
| 490 |
<h3>Usage</h3> |
| 491 |
<pre class='example'> |
| 492 |
hcp <em>handname</em> |
| 493 |
hcp <em>handname</em> <em>suitname</em> [<em>suitname</em> ...] |
| 494 |
hcp hand {<em>s h d c</em>} |
| 495 |
hcp hand {<em>s h d c</em>} <em>suitname</em> [<em>suitname</em> ...] |
| 496 |
</pre> |
| 497 |
This procedure computes standard high card points - ace is 4, king |
| 498 |
is 3, queen is 2, jack is 1. The procedure implements the |
| 499 |
<a href="#holdingp">holding procedure</a> interface. |
| 500 |
<td style="width: 35%"><div class='programmer'> |
| 501 |
<b>For Programmers</b> |
| 502 |
<dl> |
| 503 |
<dt>Implementation: |
| 504 |
<dd>C code |
| 505 |
<dt>Location: |
| 506 |
<dd>Built with additive.c, <code>tcl_create_additive</code> |
| 507 |
and deal.c, <code>count_hcp</code> |
| 508 |
</dl> |
| 509 |
</div> |
| 510 |
</table> |
| 511 |
<hr> |
| 512 |
|
| 513 |
<a name="newLTC"></a> |
| 514 |
<h2>Command: <code>newLTC</code></h2> |
| 515 |
<table cellpadding=5 style="width: 100%"> |
| 516 |
<tr valign=top><td style="width: 65%"> |
| 517 |
<h3>Usage</h3> |
| 518 |
<pre class='example'> |
| 519 |
newLTC <em>handname</em> |
| 520 |
newLTC <em>handname</em> <em>suitname</em> [<em>suitname</em> ...] |
| 521 |
newLTC hand {<em>s h d c</em>} |
| 522 |
newLTC hand {<em>s h d c</em>} <em>suitname</em> [<em>suitname</em> ...] |
| 523 |
</pre> |
| 524 |
<p>Rex Livingston provided this implementation of the <a href="http://en.wikipedia.org/wiki/Losing_trick_count#New_Losing_Trick_Count_.28NLTC.29">New Losing Trick Count</a>, from a 2003 Bridge World article.</p> |
| 525 |
<p>It looks to me much like a 3-2-1 count with some adjustments, and it seems odd to me that a stiff singleton would count as 1.5 losers. Somehow, doesn't match the intuitive meaning of "loser" to me. |
| 526 |
<td style="width: 35%"> |
| 527 |
<div class='programmer'> |
| 528 |
<b>For Programmers</b> |
| 529 |
<dl><dt>Implementation:</dt> |
| 530 |
<dd>Tcl code |
| 531 |
<dt>Location:</dt> |
| 532 |
<dd>lib/features.tcl</dd> |
| 533 |
</dl> |
| 534 |
</div> |
| 535 |
</table> |
| 536 |
<hr> |
| 537 |
|
| 538 |
<a name="losers"></a> |
| 539 |
<h2>Command: <code>losers</code></h2> |
| 540 |
<table cellpadding=5 style="width: 100%"> |
| 541 |
<tr valign=top><td style="width: 65%"> |
| 542 |
<h3>Usage</h3> |
| 543 |
<pre class='example'> |
| 544 |
losers <em>handname</em> |
| 545 |
losers <em>handname</em> <em>suitname</em> [<em>suitname</em> ...] |
| 546 |
losers hand {<em>s h d c</em>} |
| 547 |
losers hand {<em>s h d c</em>} <em>suitname</em> [<em>suitname</em> ...] |
| 548 |
</pre> |
| 549 |
This implements a <a href="#holdingp">holding procedure</a> which |
| 550 |
computes the number of <em>half losers</em>. This is for historical reasons - |
| 551 |
the only holding functions allowed in past releases returned integer |
| 552 |
values, but I wanted to have some refinements over raw losing trick count. |
| 553 |
<td style="width: 35%"> |
| 554 |
<div class='programmer'> |
| 555 |
<b>For Programmers</b> |
| 556 |
<dl><dt>Implementation:</dt> |
| 557 |
<dd>C code |
| 558 |
<dt>Location:</dt> |
| 559 |
<dd>Built with additive.c, <code>tcl_create_additive</code> |
| 560 |
and deal.c, <code>count_losers</code> |
| 561 |
</dl> |
| 562 |
It is probably better to reimplement in <code>Tcl</code> using |
| 563 |
<a href="#holdingProc"><code>holdingProc</code></a>. |
| 564 |
</div> |
| 565 |
</table> |
| 566 |
<hr> |
| 567 |
|
| 568 |
<a name="binky"></a> |
| 569 |
<h1>Binky Points Evaluators</h1> |
| 570 |
<p>Binky Points are described in my <a href="http://bridge.thomasoandrews.com/valuations/">hand evaluations articles.</a></p> |
| 571 |
<p>Binky Points are designed so that sum of your partnership's Binky Point values comes as close as possible to the number of tricks that your partnership can make, double dummy.</p> |
| 572 |
<a name="binky_suit"></a> |
| 573 |
<a name="binky_nt"></a> |
| 574 |
<h2>Commands: <code>binky::suit</code> and <code>binky::nt</code></h2> |
| 575 |
<table cellpadding=5 style="width: 100%"> |
| 576 |
<tr valign=top><td style="width: 65%"> |
| 577 |
<h3>Usage</h3> |
| 578 |
<pre class='example'> |
| 579 |
source lib/binky.tcl |
| 580 |
binky::nt <em>handname</em> |
| 581 |
binky::nt hand {<em>s h d c</em>} |
| 582 |
binky::suit <em>handname</em> |
| 583 |
binky::suit hand {<em>s h d c</em>} |
| 584 |
</pre> |
| 585 |
These two functions are <a href="#handInterface">hand procedures</a> which |
| 586 |
computes the Binky Point values for a hand. |
| 587 |
<td style="width: 35%"> |
| 588 |
<div class='programmer'> |
| 589 |
<b>For Programmers</b> |
| 590 |
<dl><dt>Implementation:</dt> |
| 591 |
<dd>Tcl code |
| 592 |
<dt>Location:</dt> |
| 593 |
<dd><code>lib/binky.tcl</code> and <code>lib/binky-data.tcl</code> |
| 594 |
</dl> |
| 595 |
</div> |
| 596 |
</table> |
| 597 |
|
| 598 |
<h1>Bridge Logic and Utilities</h1> |
| 599 |
<a name="lho"></a> |
| 600 |
<a name="rho"></a> |
| 601 |
<a name="partner"></a> |
| 602 |
<h2>Commands: <code>lho</code>, <code>partner</code>, <code>rho</code></h2> |
| 603 |
<table cellpadding=5 style="width: 100%"> |
| 604 |
<tr valign="top"><td style="width: 65%"> |
| 605 |
<h3>Usage</h3> |
| 606 |
<pre class='example'> |
| 607 |
lho <em>handname</em> |
| 608 |
rho <em>handname</em> |
| 609 |
partner <em>handname</em> |
| 610 |
</pre> |
| 611 |
<h3>Summary</h3> |
| 612 |
These routines accept one hand name and return another. For example, |
| 613 |
"<code>lho north</code>" returns "<code>east</code>," and |
| 614 |
"<code>partner east</code>" |
| 615 |
returns "<code>west</code>." |
| 616 |
<td style="width: 35%"><div class='programmer'> |
| 617 |
<b>For Programmers</b> |
| 618 |
<dl><dt>Implementation:</dt> |
| 619 |
<dd>C code |
| 620 |
<dt>Location:</dt> |
| 621 |
<dd><code>tcl_deal.c</code>, function <code>tcl_other_hand</code> |
| 622 |
</dl> |
| 623 |
</div> |
| 624 |
</table> |
| 625 |
<hr> |
| 626 |
|
| 627 |
<a name="holding"></a> |
| 628 |
<h2>Commands: <code>holding</code></h2> |
| 629 |
<table cellpadding=5 style="width: 100%"> |
| 630 |
<tr valign=top><td style="width: 65%"> |
| 631 |
<h3>Usage</h3> |
| 632 |
<pre class='example'> |
| 633 |
holding length AJxx => 4 |
| 634 |
|
| 635 |
holding contains AJ64 A6 => 1 (true) |
| 636 |
holding contains AJ64 A65 => 0 (false) |
| 637 |
|
| 638 |
holding encode AJ4 => 4612 (binary: 1001000000100 ) |
| 639 |
|
| 640 |
holding decode 4612 => AJ4 |
| 641 |
|
| 642 |
holding matches AKxx AK42 => 1 (true) |
| 643 |
|
| 644 |
holding disjoint AJ65 KT82 => 1 (true) |
| 645 |
holding disjoint A65 A32 => 0 (false) |
| 646 |
|
| 647 |
holding index AKJ4 0 => A |
| 648 |
holding index AKJ4 1 => K |
| 649 |
holding index AKJ4 3 => 4 |
| 650 |
holding index AKJ4 -2 => J |
| 651 |
holding index AKJ4 10 => "" |
| 652 |
</pre> |
| 653 |
<h3>Summary</h3> |
| 654 |
<td style="width: 35%"><div class='programmer'> |
| 655 |
<b>For Programmers</b> |
| 656 |
<dl><dt>Implementation:</dt> |
| 657 |
<dd>C code |
| 658 |
<dt>Location:</dt> |
| 659 |
<dd><code>holdings.c</code>, function <code>IDeal_HoldingCmd</code> |
| 660 |
</dl> |
| 661 |
</div> |
| 662 |
</table> |
| 663 |
<hr> |
| 664 |
|
| 665 |
<a name="score"></a> |
| 666 |
<h2>Command: <code>score</code></h2> |
| 667 |
<table cellpadding=5 style="width: 100%"> |
| 668 |
<tr valign=top><td style="width: 65%"> |
| 669 |
<h3>Usage</h3> |
| 670 |
<pre class='example'> |
| 671 |
source lib/score.tcl |
| 672 |
... |
| 673 |
score <em>contract</em> <em>vulnerability</em> <em>tricks</em> |
| 674 |
</pre> |
| 675 |
<h3>Summary</h3> |
| 676 |
This routine computes the standard duplicate bridge score for a contract |
| 677 |
from the point of view of declarer, if declaring side takes the given number |
| 678 |
of tricks. |
| 679 |
<p> |
| 680 |
The <em>contract</em> is passed as a list: |
| 681 |
<pre class='example'> |
| 682 |
2 spades |
| 683 |
|
| 684 |
2 spades undoubled |
| 685 |
|
| 686 |
4 clubs doubled |
| 687 |
|
| 688 |
6 notrump redoubled |
| 689 |
</pre> |
| 690 |
The <em>vulnerablity</em> is one of the words <code>vul</code> or |
| 691 |
<code>nonvul</code>. |
| 692 |
<p> |
| 693 |
The <em>tricks</em> is the number of tricks taken by declarer. |
| 694 |
<h3>Examples</h3> |
| 695 |
<pre class='exaample'> |
| 696 |
score {2 spades} nonvul 8 => 110 |
| 697 |
score {2 spades doubled} nonvul 8 => 470 |
| 698 |
score {2 spades redoubled} nonvul 8 => 640 |
| 699 |
score {2 spades doubled} vul 8 => 670 |
| 700 |
score {2 spades} nonvul 7 => -50 |
| 701 |
score {2 spades doubled} nonvul 7 => -100 |
| 702 |
score {2 spades doubled} vul 7 => -200 |
| 703 |
</pre> |
| 704 |
|
| 705 |
<td style="width: 35%"><div class='programmer'> |
| 706 |
<b>For Programmers</b> |
| 707 |
<dl><dt>Implementation:</dt> |
| 708 |
<dd>Tcl |
| 709 |
<dt>Location:</dt> |
| 710 |
<dd><code>score.tcl</code> |
| 711 |
</dl> |
| 712 |
</div> |
| 713 |
</table> |
| 714 |
<hr> |
| 715 |
<a name="dds"></a> |
| 716 |
<h1>Double Dummy Solver</h1> |
| 717 |
<p>Starting with Deal 3.1, I've included simple access to <a href='http://web.telia.com/~u07502278/'>Bo Haglund's double-dummy solver library.</a></p> |
| 718 |
<a name="deal::tricks"></a> |
| 719 |
<h2>Command: <code>deal::tricks</code></h2> |
| 720 |
<table cellpadding=5 style="width: 100%"> |
| 721 |
<tr valign=top><td style="width: 65%"> |
| 722 |
<h3>Usage</h3> |
| 723 |
<pre class='example'> |
| 724 |
deal::tricks <em>declarer</em> <em>denomination</em> |
| 725 |
</pre> |
| 726 |
|
| 727 |
<h3>Summary</h3> |
| 728 |
<p><code>deal::tricks</code> returns the maximum number of tricks makable by <em>declarer</em> in the given <em>denomination</em>. |
| 729 |
<p><em>declarer</em> must be one of "north", "east", "south", or "west." By default, it is "south."</p> |
| 730 |
<p><em>denomination</em> must be a suit name or "notrump." The default value is "notrump."</p> |
| 731 |
<p>By default, deal::tricks uses the <a href="#tricks"><code>tricks</code></a> function, which calls Bo Haglund's double-dummy solver.</p> |
| 732 |
<p>However, if you include "lib/gib.tcl", <code>deal::tricks</code> will call the GIB double dummy solver.</p> |
| 733 |
<p><code>deal::tricks</code> caches values, so multiple calls for the same deal with the same declarer and denomination will not result in multiple calls to the |
| 734 |
double-dummy solver.</p> |
| 735 |
<p>Bo Haglund's solver has a feature which makes it faster if the next double dummy solver call is in the same denomination as the previous call. That means that |
| 736 |
if you need all double-dummy values, you would want to write your code as:</p> |
| 737 |
<pre class='example'> |
| 738 |
foreach denom {clubs diamonds hearts spades notrump} { |
| 739 |
foreach hand {north east south west} { |
| 740 |
set tricks [deal::tricks $hand $denom] |
| 741 |
... |
| 742 |
} |
| 743 |
} |
| 744 |
</pre> |
| 745 |
|
| 746 |
|
| 747 |
|
| 748 |
<td style="width: 35%"><div class='programmer'> |
| 749 |
<b>For Programmers</b> |
| 750 |
<dl><dt>Implementation:</dt> |
| 751 |
<dd>Tcl</dd> |
| 752 |
<dt>Location:</dt> |
| 753 |
<dd><code>lib/features.tcl</code> |
| 754 |
</dl> |
| 755 |
</div> |
| 756 |
</table> |
| 757 |
<hr> |
| 758 |
|
| 759 |
|
| 760 |
|
| 761 |
<a name="tricks"></a> |
| 762 |
<h2>Command: tricks</h2> |
| 763 |
<table cellpadding=5 style="width: 100%"> |
| 764 |
<tr valign=top><td style="width: 65%"> |
| 765 |
<h3>Usage</h3> |
| 766 |
<pre class='example'> |
| 767 |
tricks [ <em>declarer</em> [ <em>denomination</em> [ <em>goal</em> ] ] ] |
| 768 |
</pre> |
| 769 |
|
| 770 |
<h3>Summary</h3> |
| 771 |
<p>Unless you are using the <em>goal</em> parameter, you will probably want to use the <a href="#deal::tricks"><code>deal::tricks</code></a> command, since it has the |
| 772 |
advantage of caching values.</p> |
| 773 |
<p>When no goal is passed, "tricks" returns the maximum number of tricks makable by <em>declarer</em> in the given <em>denomination</em>. |
| 774 |
<p>If a (positive) goal number of tricks is set, "tricks" returns 1 if declarer can make that many tricks, and 0 if the defense can always hold declarer to fewer tricks. |
| 775 |
<p><em>declarer</em> must be one of "north", "east", "south", or "west." By default, it is "south."</p> |
| 776 |
<p><em>denomination</em> must be a suit name or "notrump." The default value is "notrump." |
| 777 |
<p><em>goal</em> must be an integer value, either -1 for "best play" or a value from 1 to 13 equal to the goal number of tricks for declarer. Default is -1.</p> |
| 778 |
|
| 779 |
<td style="width: 35%"><div class='programmer'> |
| 780 |
<b>For Programmers</b> |
| 781 |
<dl><dt>Implementation:</dt> |
| 782 |
<dd>C, C++</dd> |
| 783 |
<dt>Location:</dt> |
| 784 |
<dd><code>dds.cpp, tcl_dds.c</code> |
| 785 |
</dl> |
| 786 |
</div> |
| 787 |
</table> |
| 788 |
<hr> |
| 789 |
|
| 790 |
<a name="ddscmd"></a> |
| 791 |
<h2>Command: dds</h2> |
| 792 |
<table cellpadding=5 style="width: 100%"> |
| 793 |
<tr valign=top><td style="width: 65%"> |
| 794 |
<h3>Usage</h3> |
| 795 |
<pre class='example'> |
| 796 |
dds [-reuse | -noreuse] [-diagram <em>diagram</em>] [-goal <em>goal</em>] |
| 797 |
[-leader <em>leader</em>] [-trick <em>list of cards</em> [-trick <em>cards</em> ] ...] [ <em>declarer</em> [ <em>denomination</em> ] ] |
| 798 |
</pre> |
| 799 |
|
| 800 |
<h3>Summary</h3> |
| 801 |
<p>The <code>dds</code> command gives even more refined access to Bo Haglund's double dummy engine, including the ability to solve problems with fewer than 52 cards. |
| 802 |
|
| 803 |
<p>The <code>-reuse</code> flag tells the double-dummy solver to reuse the data it generated from the last call. For example, if the deal is identical to the previous call and played in the same denomination, you'll want to reuse the data. |
| 804 |
<p>The <code>-noreuse</code> flag tells the double-dummy solver not to reuse the data. This is the default. |
| 805 |
<p>The <code>-diagram</code> flag tells the double-dummy solver to solve a specific diagram, rather than the current deal. A diagram is of the form of a Tcl list in the order north, east, south, west. |
| 806 |
<p>The <code>-leader</code> flag tells the double-dummy solver who is on lead to the current trick. |
| 807 |
<p>The <code>-trick</code> flag gives a list of cards played to the current trick. |
| 808 |
<p>For example, to solve George Coffin's "Avoidance" end position from his <a href="http://www.rpbridge.net/9p01.htm">Great 88</a>, you would write: |
| 809 |
<pre class='example'> |
| 810 |
set diagram { |
| 811 |
{A987 - A -} |
| 812 |
{Q5 987 - -} |
| 813 |
{64 K2 2 -} |
| 814 |
{K2 AQ3 - -} |
| 815 |
} |
| 816 |
set tricks [dds -leader south -diagram $diagram south notrump] |
| 817 |
... |
| 818 |
</pre> |
| 819 |
<p>If you wanted to see how many tricks are made if south plays a particular card, say the two of clubs, you would use the -trick flag: |
| 820 |
<pre class='example'> |
| 821 |
set tricks [dds -leader south -diagram $diagram -trick 4S south notrump] |
| 822 |
</pre> |
| 823 |
You can also pass full tricks, as in: |
| 824 |
<pre class='example'> |
| 825 |
set tricks [dds -leader west -diagram $diagram -trick {4S KS 7S 5S} south notrump] |
| 826 |
</pre> |
| 827 |
<p>Note that the -leader option always refers to the leader to the current trick, not the leader of earlier completed tricks passed with -trick. Also, the number of tricks returned is the number of tricks after all completed tricks. |
| 828 |
<p>There are example tests of all the Great 88 in the file <code>tests/great88</code> that is included in this release. |
| 829 |
</td> |
| 830 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 831 |
<dl><dt>Implementation:</dt> |
| 832 |
<dd>C, C++</dd> |
| 833 |
<dt>Location:</dt> |
| 834 |
<dd><code>dds.cpp, tcl_dds.c</code> |
| 835 |
</dl> |
| 836 |
</div> |
| 837 |
</table> |
| 838 |
<hr> |
| 839 |
|
| 840 |
<a name="parscore"></a> |
| 841 |
<h2>Command: <code>parscore</code></h2> |
| 842 |
<table cellpadding=5 style="width: 100%"> |
| 843 |
<tr valign=top><td style="width: 65%"> |
| 844 |
<h3>Usage</h3> |
| 845 |
<pre class='example'> |
| 846 |
source lib/parscore.tcl |
| 847 |
... |
| 848 |
set result [parscore <em>dealer</em> <em>vul</em>] |
| 849 |
|
| 850 |
set contract [lindex $result 0] |
| 851 |
set declarer [lindex $result 1] |
| 852 |
set score [lindex $result 2] |
| 853 |
set tricks [lindex $result 3] |
| 854 |
set auction [lindex $result 4] |
| 855 |
</pre> |
| 856 |
<h3>Summary</h3> |
| 857 |
This computes the double-dummy par result for the current deal. |
| 858 |
<p> |
| 859 |
The parscore routine returns a list of five values - the contract (in |
| 860 |
the same form that is used by the <a href="#score"><code>score</code></a> |
| 861 |
routine above), the declarer, the score for north/south, the number of |
| 862 |
tricks taken, and a "stupid" auction to the contract suitable for putting |
| 863 |
into a PBN file. |
| 864 |
<p> |
| 865 |
Dealer is relevant on a few occasions. If both south and west can make |
| 866 |
1NT, for example, and no 2-level contracts make, then "par" is 1NT by |
| 867 |
whomever gets a chance to bid it first. |
| 868 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 869 |
<dl><dt>Implementation:</dt> |
| 870 |
<dd>Tcl |
| 871 |
<dt>Location:</dt> |
| 872 |
<dd><code>parscore.tcl</code> |
| 873 |
</dl> |
| 874 |
</div> |
| 875 |
</table> |
| 876 |
<hr> |
| 877 |
|
| 878 |
|
| 879 |
|
| 880 |
|
| 881 |
<a name="gibstuff"></a> |
| 882 |
<h1>GIB-related routines</h1> |
| 883 |
These next routines use calls to the GIB double-dummy engine. You must have |
| 884 |
a licensed version of <a href="http://www.gibware.com/">GIB</a> |
| 885 |
installed on your computer for these routines to work. Also, these |
| 886 |
routines only work on Windows at the moment. |
| 887 |
<p> |
| 888 |
<a name="gib::directory"></a> |
| 889 |
<h2>Command: <code>gib::directory</code></h2> |
| 890 |
<table cellpadding=5 style="width: 100%"> |
| 891 |
<tr valign=top><td style="width: 65%"> |
| 892 |
<h3>Usage</h3> |
| 893 |
<pre class='example'> |
| 894 |
source lib/gib.tcl |
| 895 |
... |
| 896 |
gib::directory <em>path</em> |
| 897 |
</pre> |
| 898 |
<h3>Summary</h3> |
| 899 |
This tells the GIB-related routines where GIB is installed. |
| 900 |
<p> |
| 901 |
If this routine is not called, it defaults to GIB's default install |
| 902 |
directory, <span class='nobr'><code>C:/Program Files/GIB</code>.</span> |
| 903 |
<p> |
| 904 |
<em>Note: your path should include forward slashes '<code>/</code>', |
| 905 |
even on Windows.</em> |
| 906 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 907 |
<dl><dt>Implementation:</dt> |
| 908 |
<dd>Tcl</dd> |
| 909 |
<dt>Location:</dt> |
| 910 |
<dd><code>gib.tcl</code> |
| 911 |
</dl> |
| 912 |
</div> |
| 913 |
</table> |
| 914 |
<hr> |
| 915 |
|
| 916 |
<a name="gib::tricks"></a> |
| 917 |
<h2>Command: <code>gib::tricks</code></h2> |
| 918 |
<table cellpadding=5 style="width: 100%"> |
| 919 |
<tr valign=top><td style="width: 65%"> |
| 920 |
<h3>Usage</h3> |
| 921 |
<pre class='example'> |
| 922 |
source lib/gib.tcl |
| 923 |
... |
| 924 |
gib::tricks <em>declarer</em> <em>denomination</em> |
| 925 |
</pre> |
| 926 |
<h3>Summary</h3> |
| 927 |
<p>You probably want to use the <a href="#deal::tricks"><code>deal::tricks</code></a> command, even when using GIB's double dummy solver. |
| 928 |
<p><em>Denomination</em> can be a suit name or "<code>notrump</code>." |
| 929 |
<em>Declarer</em> can be any hand name. |
| 930 |
<p> |
| 931 |
This routine returns the double-dummy number of tricks available |
| 932 |
in this deal, in the given denomination by the given declarer. |
| 933 |
<p> |
| 934 |
If GIB is installed anywhere unusual, you will need to call |
| 935 |
<a href="#gib::directory"><code>gib::directory</code></a> before |
| 936 |
<code>deal::tricks</code> is called. |
| 937 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 938 |
<dl><dt>Implementation:</dt> |
| 939 |
<dd>Tcl</dd> |
| 940 |
<dt>Location:</dt> |
| 941 |
<dd><code>gib.tcl</code> |
| 942 |
</dl> |
| 943 |
</div> |
| 944 |
</table> |
| 945 |
<hr> |
| 946 |
|
| 947 |
<h1>Bridge Command Builders</h1> |
| 948 |
|
| 949 |
<p>A number of common types of bridge functions can easily be implemented to |
| 950 |
run quickly via lookup tables, including |
| 951 |
<a href="#holdingp">holding</a> and <a href="#shape">shape</a> procedures. |
| 952 |
Deal lets the user take advantage of these two sorts of lookup procedures |
| 953 |
relatively easily</p> |
| 954 |
|
| 955 |
<a name="defvector"></a> |
| 956 |
<h2>Command: <code>defvector</code></h2> |
| 957 |
<table cellpadding=5 style="width: 100%"> |
| 958 |
<tr valign=top><td style="width: 65%"> |
| 959 |
<h3>Usage</h3> |
| 960 |
<pre class='example'> |
| 961 |
defvector <em>vec</em> <em>aceVal</em> [ <em>kingVal</em> ... ] |
| 962 |
|
| 963 |
<em>vec</em> <em>handname</em> |
| 964 |
|
| 965 |
<em>vec</em> <code>hand</code> {<em>text hand</em>} |
| 966 |
|
| 967 |
<em>vec</em> <em>handname</em> <em>suitname</em> [ <em>suitname</em> ... ] |
| 968 |
|
| 969 |
<em>vec</em> <em>handname</em> <em>suitname</em> [ <em>suitname</em> ... ] |
| 970 |
|
| 971 |
<em>vec</em> <code>hand</code> {<em>text hand</em>} <em>suitname</em> ... |
| 972 |
</pre> |
| 973 |
<h3>Summary</h3> |
| 974 |
This defines a <a href="#holdingp">holding procedure</a> which assigns |
| 975 |
integer values to the various cards in the hand. For example |
| 976 |
<pre class='example'> |
| 977 |
defvector hcp6421 6 4 2 1 |
| 978 |
</pre> |
| 979 |
Defines a holding procedure which counts the ace as worth 6 points, the |
| 980 |
king as worth 4, the queen as 2, and the jack as 1. |
| 981 |
<p> |
| 982 |
Vectors are limited to being integer-valued. For more complicated |
| 983 |
holding procedures, use <a href="#holdingProc"><code>holdingProc</code></a>.</p> |
| 984 |
<td style="width: 35%"> |
| 985 |
<div class='programmer'><b>For Programmers</b> |
| 986 |
<dl><dt>Implementation:</dt> |
| 987 |
<dd>C</dd> |
| 988 |
<dt>Location:</dt> |
| 989 |
<dd><code>vector.c</code></dd> |
| 990 |
</dl> |
| 991 |
<p>Vectors are slighly faster than their equivalent |
| 992 |
<a href="#holdingProc"><code>holdingProc</code></a>. They are an |
| 993 |
old optimization which remain mostly for backwards compatibility. |
| 994 |
</div> |
| 995 |
</table> |
| 996 |
<hr> |
| 997 |
|
| 998 |
<a name="holdingProc"></a> |
| 999 |
<h2>Command: <code>holdingProc</code></h2> |
| 1000 |
<table cellpadding=5 style="width: 100%"> |
| 1001 |
<tr valign=top><td style="width: 65%"> |
| 1002 |
<h3>Usage</h3> |
| 1003 |
<pre class='example'> |
| 1004 |
</pre> |
| 1005 |
<p> |
| 1006 |
Temporarily, see the <a href="holding.html">seperate documentation</a>. |
| 1007 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1008 |
<dl> |
| 1009 |
<dt>Implementation: <dd>C |
| 1010 |
<dt>Location: <dd><code>holdings.c</code>, function <code>IDeal_DefHoldingProc</code> |
| 1011 |
</dl> |
| 1012 |
</div> |
| 1013 |
</table> |
| 1014 |
<hr> |
| 1015 |
|
| 1016 |
<a name="shapeclass"></a> |
| 1017 |
<a name="shapecond"></a> |
| 1018 |
<a name="shapefunc"></a> |
| 1019 |
<h2>Commands: <code>shapeclass</code>, <code>shapecond</code>, and <code>shapefunc</code></h2> |
| 1020 |
<table cellpadding=5 style="width: 100%"> |
| 1021 |
<tr valign=top><td style="width: 65%"> |
| 1022 |
<h3>Usage</h3> |
| 1023 |
<pre class='example'> |
| 1024 |
shapeclass <em>name</em> {... <em>code</em> ...} |
| 1025 |
|
| 1026 |
shapecond <em>name</em> {<em>expr</em>} |
| 1027 |
|
| 1028 |
shapefunc <em>name</em> {... <em>code</em> ...} |
| 1029 |
|
| 1030 |
<em>name</em> [ north | south | east | west ] |
| 1031 |
|
| 1032 |
<em>name</em> eval <em>s</em> <em>h</em> <em>d</em> <em>c</em> |
| 1033 |
|
| 1034 |
<em>name</em> shape {<em>s</em> <em>h</em> <em>d</em> <em>c</em>} |
| 1035 |
|
| 1036 |
</pre> |
| 1037 |
A shape class (or equivalently, a shape condition) also has the list |
| 1038 |
subcommand: |
| 1039 |
<pre class='example'> |
| 1040 |
<em>name</em> list |
| 1041 |
</pre> |
| 1042 |
<h3>Summary</h3> |
| 1043 |
These commands create new procedures which fit the <a href="#shapes">shape |
| 1044 |
function</a> interface. |
| 1045 |
<p> |
| 1046 |
<code>shapeclass</code> and <code>shapecond</code> define procedures which returns boolean |
| 1047 |
values. <code>shapefunc</code> can return any type of data. |
| 1048 |
<code>shapecond</code> is actually an alias: |
| 1049 |
<pre class='example'> |
| 1050 |
shapecond <em>name</em> {<em>expr</em>} |
| 1051 |
</pre> |
| 1052 |
is the equivalent of: |
| 1053 |
<pre class='example'> |
| 1054 |
shapeclass <em>name</em> { |
| 1055 |
if {<em>expr</em>} { |
| 1056 |
return 1 |
| 1057 |
} else { |
| 1058 |
return 0 |
| 1059 |
} |
| 1060 |
</pre> |
| 1061 |
The <em>code</em> or <em>expr</em> is allowed to use the variables |
| 1062 |
<code>s</code>, <code>h</code>, <code>d</code>, or <code>c</code>. |
| 1063 |
<p> |
| 1064 |
More details can be found in the |
| 1065 |
<a href="advanced.html#shapefunc">Advanced Guide</a>. |
| 1066 |
<p> |
| 1067 |
The <code>list</code> subcommand for shape classes returns a list of |
| 1068 |
shapes that are in the class. |
| 1069 |
<p> |
| 1070 |
Why are there two subcommands, "eval" and "shape" which do the |
| 1071 |
roughly the same things? |
| 1072 |
<p> |
| 1073 |
Let's say you have a class named "SemiBalanced" already defined, |
| 1074 |
which includes 5-card majors. You want to define a "Balanced" |
| 1075 |
class which excludes the 5-card majors. You can do this with |
| 1076 |
the call: |
| 1077 |
<pre class='example'> |
| 1078 |
shapecond Balanced {[SemiBalanced eval $s $h $d $c] && $s<5 && $h<5} |
| 1079 |
</pre> |
| 1080 |
|
| 1081 |
On the other hand, if you have a shape - output by the, say, a |
| 1082 |
call to [north shape] you can evaluate it as: |
| 1083 |
<pre class='example'> |
| 1084 |
SemiBalanced shape [north shape] |
| 1085 |
</pre> |
| 1086 |
In fact, this is exactly equivalent to calling |
| 1087 |
<pre class='example'> |
| 1088 |
SemiBalanced north |
| 1089 |
</pre> |
| 1090 |
only slightly slower. |
| 1091 |
<p>Since these routines cache results in memory and use lookup |
| 1092 |
tables, you should not use any external state or global variables |
| 1093 |
inside them. |
| 1094 |
|
| 1095 |
<td style="width: 35%"> |
| 1096 |
<div class='programmer'> |
| 1097 |
<b>For Programmers</b> |
| 1098 |
<dl><dt>Implementation: <dd>C |
| 1099 |
<dt>Location: <dd><code>dist.c</code>, functions <code>tcl_shapeclass_define</code>, |
| 1100 |
<code>tcl_shapecond_define</code>, and <code>tcl_shapefunc_define</code> |
| 1101 |
</dl> |
| 1102 |
</div> |
| 1103 |
</table> |
| 1104 |
<hr> |
| 1105 |
|
| 1106 |
<a name="patternclass"></a> |
| 1107 |
<a name="patterncond"></a> |
| 1108 |
<a name="patternfunc"></a> |
| 1109 |
<h2>Commands: <code>patternclass</code>, <code>patterncond</code>, and <code>patternfunc</code></h2> |
| 1110 |
<table cellpadding=5 style="width: 100%"> |
| 1111 |
<tr valign=top><td style="width: 65%"> |
| 1112 |
<h3>Usage</h3> |
| 1113 |
<pre class='example'> |
| 1114 |
patternclass <em>name</em> {... <em>code</em> ...} |
| 1115 |
|
| 1116 |
patterncond <em>name</em> {<em>expr</em>} |
| 1117 |
|
| 1118 |
patternfunc <em>name</em> {... <em>code</em> ...} |
| 1119 |
|
| 1120 |
<em>name</em> [ north | south | east | west ] |
| 1121 |
|
| 1122 |
<em>name</em> eval <em>s</em> <em>h</em> <em>d</em> <em>c</em> |
| 1123 |
|
| 1124 |
<em>name</em> shape {<em>s</em> <em>h</em> <em>d</em> <em>c</em>} |
| 1125 |
|
| 1126 |
</pre> |
| 1127 |
A pattern class (or equivalently, a shape condition) also has the list |
| 1128 |
subcommand: |
| 1129 |
<pre class='example'> |
| 1130 |
<em>name</em> list |
| 1131 |
</pre> |
| 1132 |
<h3>Summary</h3> |
| 1133 |
These commands create new procedures which fit the <a href="#shapes">shape |
| 1134 |
function</a> interface. |
| 1135 |
<p> |
| 1136 |
<code>patternclass</code> and <code>patterncond</code> define procedures which returns boolean |
| 1137 |
values. <code>patternfunc</code> can return any type of data. |
| 1138 |
<code>patterncond</code> is actually an alias: |
| 1139 |
<pre class='example'> |
| 1140 |
patterncond <em>name</em> {<em>expr</em>} |
| 1141 |
</pre> |
| 1142 |
is the equivalent of: |
| 1143 |
<pre class='example'> |
| 1144 |
patternclass <em>name</em> { |
| 1145 |
if {<em>expr</em>} { |
| 1146 |
return 1 |
| 1147 |
} else { |
| 1148 |
return 0 |
| 1149 |
} |
| 1150 |
</pre> |
| 1151 |
The <em>code</em> or <em>expr</em> is allowed to use the variables |
| 1152 |
<code>l1</code>, <code>l2</code>, <code>l3</code>, or <code>l4</code>, the suit lengths in descending order. |
| 1153 |
<p> |
| 1154 |
The <code>list</code> subcommand for pattern classes returns a list of |
| 1155 |
shapes (not patterns) that are in the class. |
| 1156 |
<p> |
| 1157 |
Why are there two subcommands, "eval" and "shape" which do the |
| 1158 |
roughly the same things? |
| 1159 |
<p> |
| 1160 |
Let's say you have a class named "SemiBalanced" already defined, |
| 1161 |
which includes 5-card majors. You want to define a "Balanced" |
| 1162 |
class which excludes the 5-card majors. You can do this with |
| 1163 |
the call: |
| 1164 |
<pre class='example'> |
| 1165 |
shapecond Balanced {[SemiBalanced eval $s $h $d $c] && $s<5 && $h<5} |
| 1166 |
</pre> |
| 1167 |
|
| 1168 |
On the other hand, if you have a shape - output by the, say, a |
| 1169 |
call to [north shape] you can evaluate it as: |
| 1170 |
<pre class='example'> |
| 1171 |
SemiBalanced shape [north shape] |
| 1172 |
</pre> |
| 1173 |
In fact, this is exactly equivalent to calling |
| 1174 |
<pre class='example'> |
| 1175 |
SemiBalanced north |
| 1176 |
</pre> |
| 1177 |
only slightly slower. |
| 1178 |
<p>Since these routines cache results in memory and use lookup |
| 1179 |
tables, you should not use any external state or global variables |
| 1180 |
inside them. |
| 1181 |
|
| 1182 |
<td style="width: 35%"> |
| 1183 |
<div class='programmer'> |
| 1184 |
<b>For Programmers</b> |
| 1185 |
<dl><dt>Implementation: <dd>Tcl |
| 1186 |
<dt>Location: <dd><code>features.tcl</code> |
| 1187 |
</dl> |
| 1188 |
</div> |
| 1189 |
</table> |
| 1190 |
<hr> |
| 1191 |
|
| 1192 |
<a name="statistics"></a> |
| 1193 |
<h1>Statistics</h1> |
| 1194 |
<a name="sdev"></a> |
| 1195 |
<h2>Command: <code>sdev</code></h2> |
| 1196 |
<table cellpadding=5 style="width: 100%"> |
| 1197 |
<tr><td style="width: 65%"> |
| 1198 |
<h3>Usage</h3> |
| 1199 |
<pre class='example'> |
| 1200 |
sdev <em>name</em> |
| 1201 |
|
| 1202 |
<em>name</em> add <em>data</em> [ <em>data</em> ... ] |
| 1203 |
|
| 1204 |
<em>name</em> count |
| 1205 |
|
| 1206 |
<em>name</em> average |
| 1207 |
|
| 1208 |
<em>name</em> sdev |
| 1209 |
|
| 1210 |
<em>name</em> rms |
| 1211 |
</pre> |
| 1212 |
<h3>Summary</h3> |
| 1213 |
|
| 1214 |
The "sdev" command defines a new Tcl procedure with the given name, which behaves as a |
| 1215 |
data collection object. You can add data points to it, or you can retrieve |
| 1216 |
the current number of data points, the average of the data points, the |
| 1217 |
standard deviation of the data points, or the "root mean square" of the |
| 1218 |
data points. |
| 1219 |
<p> |
| 1220 |
|
| 1221 |
</td><td style="width: 35%"> |
| 1222 |
<div class='programmer'><b>For Programmers</b><br> |
| 1223 |
<dl><dt>Implementation:</dt><dd>C code</dd> |
| 1224 |
<dt>Location:</dt><dd>stat.c, function <code>tcl_sdev_define</code>. |
| 1225 |
</dl> |
| 1226 |
<p>This was implemented in C for efficiency reasons - most real number |
| 1227 |
computations really need to be done in C if they are going to be done |
| 1228 |
frequently, and here, the "add" command is called quite often in normal |
| 1229 |
usage.</p> |
| 1230 |
</div> |
| 1231 |
</table> |
| 1232 |
<hr> |
| 1233 |
|
| 1234 |
<a name="correlation"></a> |
| 1235 |
<h2>Command: <code>correlation</code></h2> |
| 1236 |
<table cellpadding=5 style="width: 100%"> |
| 1237 |
<tr valign="top"><td style="width: 65%"> |
| 1238 |
<h3>Usage</h3> |
| 1239 |
<pre class='example'> |
| 1240 |
correlation <em>name</em> |
| 1241 |
|
| 1242 |
<em>name</em> add <em>xval</em> <em>yval</em> [ <em>xval</em> <em>yval</em> ... ] |
| 1243 |
|
| 1244 |
<em>name</em> count |
| 1245 |
|
| 1246 |
<em>name</em> correlate |
| 1247 |
|
| 1248 |
<em>name</em> average [ x | y ] |
| 1249 |
|
| 1250 |
<em>name</em> sdev [ x | y ] |
| 1251 |
|
| 1252 |
<em>name</em> rms [ x | y ] |
| 1253 |
</pre> |
| 1254 |
<h3>Summary</h3> |
| 1255 |
The <code>correlation</code> declaration defines a routine much like |
| 1256 |
the <code>sdev</code> command, but each datapoint is a pair of values, |
| 1257 |
and it computes the linear correlation between the <em>x</em> and <em>y</em> |
| 1258 |
values. |
| 1259 |
<p> |
| 1260 |
You can also get individual data for the <code>x</code> and <code>y</code> |
| 1261 |
values. |
| 1262 |
<p> |
| 1263 |
If there is no data, it returns an error on <code>average</code>, |
| 1264 |
<code>correlate</code>, <code>sdev</code> and <code>rms</code>. |
| 1265 |
<p> |
| 1266 |
If there is only one pair entered, it will throw an error on |
| 1267 |
<code>sdev</code>. |
| 1268 |
<p> |
| 1269 |
</td><td style="width: 35%"> |
| 1270 |
<div class='programmer'><b>For Programmers</b> |
| 1271 |
<dl><dt>Implementation:</dt><dd>C code</dd> |
| 1272 |
<dt>Location:</dt><dd>stat.c, function <code>tcl_correlation_define</code>. |
| 1273 |
</dl> |
| 1274 |
<p>This was implemented in C for efficiency reasons - most real number |
| 1275 |
computations really need to be done in C if they are going to be done |
| 1276 |
frequently, and here, the "add" command is called quite often in normal |
| 1277 |
usage.</p> |
| 1278 |
</div> |
| 1279 |
</table> |
| 1280 |
|
| 1281 |
<h1>Utility Procedures </h1> |
| 1282 |
|
| 1283 |
<a name="exitflag"></a> |
| 1284 |
<h2>Command Line: -x flag</h2> |
| 1285 |
<table cellpadding=5 style="width: 100%"> |
| 1286 |
<tr valign=top><td style="width: 65%"> |
| 1287 |
<h3>Usage</h3> |
| 1288 |
<pre class='example'> |
| 1289 |
deal -x <em>filename</em> <arg> <arg> ... |
| 1290 |
</pre> |
| 1291 |
<p>The '-x' flag tells deal to source the file and then exit.</p> |
| 1292 |
<p>Before doing so, Deal puts remaining arguments into the variables <code>argc</code> and <code>argv</code>, and sets <code>argv0</code> to the filename of the script. |
| 1293 |
<p>This is useful if you want to skip the entire deal loop, and process stuff on your own. For example, the code in <code>tests/great88</code> does not generate any deals, it just solves 88 5-card double-dummy problems. Before the -x flag, you had to |
| 1294 |
explicitly call 'exit' from such scripts.</p> |
| 1295 |
</td> |
| 1296 |
<td></td> |
| 1297 |
</table> |
| 1298 |
|
| 1299 |
<a name="full_deal"></a> |
| 1300 |
<h2>Command: <code>full_deal</code></h2> |
| 1301 |
<table cellpadding=5 style="width: 100%"> |
| 1302 |
<tr valign=top><td style="width: 65%"> |
| 1303 |
<h3>Usage</h3> |
| 1304 |
<pre class='example'> |
| 1305 |
set deal [full_deal] |
| 1306 |
</pre> |
| 1307 |
<p>This simple utility command returns the deal as a list of hands in the order of north, east, south, and west. Suitable for psassing into <a href="#ddscmd"><code>dds</code></a> with the <code>-diagram</code> flag, or remembering a deal after the end of the loop. |
| 1308 |
</td> |
| 1309 |
<td></td> |
| 1310 |
</table> |
| 1311 |
|
| 1312 |
<a name="seed_deal"></a> |
| 1313 |
<h2>Command: <code>seed_deal</code></h2> |
| 1314 |
<table cellpadding=5 style="width: 100%"> |
| 1315 |
<tr valign=top><td style="width: 65%"> |
| 1316 |
<h3>Usage</h3> |
| 1317 |
<pre class='example'> |
| 1318 |
seed_deal <em>number</em> |
| 1319 |
</pre> |
| 1320 |
<h3>Command Line: -s</h3> |
| 1321 |
<pre class='example'> |
| 1322 |
$ deal -s <em>number</em> ... |
| 1323 |
</pre> |
| 1324 |
<h3>Summary</h3> |
| 1325 |
<p><code>seed_deal</code> is used to seed the random number generator, to make sure that Deal generates the same sequence of |
| 1326 |
random numbers. |
| 1327 |
<p>Care has to be taken if you want to make sure that you are generating the same sequence of deals. For one thing, if you have a <code>main</code> inner loop, you should add the command "finish_deal" to the <code>main</code> section. |
| 1328 |
<pre class='example'> |
| 1329 |
main { |
| 1330 |
finish_deal |
| 1331 |
... |
| 1332 |
} |
| 1333 |
</pre> |
| 1334 |
<p>That bypasses some optimizations and forces an entire deal to be generated each time through <code>main</code>. |
| 1335 |
</table> |
| 1336 |
<a name="deal_deck"></a> |
| 1337 |
<h2>Command: <code>deal_deck</code></h2> |
| 1338 |
<table cellpadding=5 style="width: 100%"> |
| 1339 |
<tr valign=top><td style="width: 65%"> |
| 1340 |
<h3>Usage</h3> |
| 1341 |
<pre class='example'> |
| 1342 |
deal_deck |
| 1343 |
</pre> |
| 1344 |
<h3>Summary</h3> |
| 1345 |
<code>deal_deck</code> is called at every new deal, |
| 1346 |
even when all 52 cards are specified (<em>stacked</em>) precisely. |
| 1347 |
Imagine stacking cards as stacking them in an undealt <em>deck</em>, |
| 1348 |
but that the cards are only distributed to the hands when |
| 1349 |
<code>deal_deck</code> is called. |
| 1350 |
<p> |
| 1351 |
Most of the time, you won't need to call deal_deck directly, but it is |
| 1352 |
useful to understand its behavior if you are going to write advanced |
| 1353 |
procedures like <a href="#deal::input">input formats.</a> |
| 1354 |
<p> |
| 1355 |
Stacked cards are permanently stacked until the deck is reset. In this code: |
| 1356 |
<pre class='example'> |
| 1357 |
stack_hand south {AKQ32 AJ53 K54 2} |
| 1358 |
deal_deck |
| 1359 |
deal_deck |
| 1360 |
puts [south spades] |
| 1361 |
</pre> |
| 1362 |
The output is "AKQ32". Use <a href="#reset_deck"><code>reset_deck</code></a> |
| 1363 |
to undo card stackings. |
| 1364 |
<p> |
| 1365 |
The <code>deal_deck</code> procedure does one thing rather complicated |
| 1366 |
when it is called, the first thing it does is execute all |
| 1367 |
code registered with the |
| 1368 |
<a href="#deal_reset_cmd"><code>deal_reset_cmds</code></a>. |
| 1369 |
This allows the script writer to do one of several things before |
| 1370 |
the deal is generated: |
| 1371 |
<ul> |
| 1372 |
<li>Delete metadata related to the deal. For example, the first time |
| 1373 |
the user calls <code>deal::tricks south spades</code> it calls the |
| 1374 |
double-dummy processor. Each time after that, it uses a stored |
| 1375 |
value for this function call up until the next call to |
| 1376 |
<code>deal_deck</code>. |
| 1377 |
<li>The reset command might, instead, read the next deal from a file, |
| 1378 |
stack the deck, and then re-register itself. Then when deal_deck is |
| 1379 |
is called, it just deals that hand from the file. This is a crude |
| 1380 |
way of allowing Deal to transparently read deals from a file (or generate |
| 1381 |
deals in other ways, such as <a href="#smartstack">smart stacking.</a> |
| 1382 |
</ul> |
| 1383 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1384 |
<dl><dt>Implementation:</dt> |
| 1385 |
<dd>C |
| 1386 |
<dt>Location:</dt> |
| 1387 |
<dd><code>tcl_deal.c</code>, function <code>tcl_deal_deck</code> |
| 1388 |
</dl> |
| 1389 |
</div> |
| 1390 |
</table> |
| 1391 |
<hr> |
| 1392 |
|
| 1393 |
<a name="reset_deck"></a> |
| 1394 |
<h2>Command: <code>reset_deck</code></h2> |
| 1395 |
<table cellpadding=5 style="width: 100%"> |
| 1396 |
<tr valign=top><td style="width: 65%"> |
| 1397 |
<h3>Usage</h3> |
| 1398 |
<pre class='example'> |
| 1399 |
reset_deck |
| 1400 |
</pre> |
| 1401 |
<h3>Summary</h3> |
| 1402 |
This forgets about all stacked cards. The <em>deck</em>, from <em>Deal</em>'s |
| 1403 |
point of view, plus a list of cards which must go to specific hands. |
| 1404 |
The cards which are assigned to specific hands are "stacked." The cards |
| 1405 |
which are not stacked can go anywhere at the next call to |
| 1406 |
<a href="#deal_deck">deal_deck</a>. |
| 1407 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1408 |
<dl><dt>Implementation:</dt> |
| 1409 |
<dd>C |
| 1410 |
<dt>Location:</dt> |
| 1411 |
<dd><code>tcl_deal.c</code>, function <code>tcl_reset_deck</code> |
| 1412 |
</dl> |
| 1413 |
</div> |
| 1414 |
</table> |
| 1415 |
<hr> |
| 1416 |
|
| 1417 |
<a name="stack_hand"></a> |
| 1418 |
<a name="stack_cards"></a> |
| 1419 |
<h2>Commands: <code>stack_hand</code> and <code>stack_cards</code></h2> |
| 1420 |
<table cellpadding=5 style="width: 100%"> |
| 1421 |
<tr valign=top><td style="width: 65%"> |
| 1422 |
<h3>Usage</h3> |
| 1423 |
<pre class='example'> |
| 1424 |
stack_hand <em>handname</em> <em>hand</em> |
| 1425 |
stack_cards <em>handname</em> <em>suitname</em> <em>holding</em> [...] |
| 1426 |
</pre> |
| 1427 |
<h3>Summary</h3> |
| 1428 |
By default, these two routines just call <a href="#deck_stack_hand"> |
| 1429 |
deck_stack_hand and deck_stack_cards,</a> |
| 1430 |
respectively - that is, they forcibly place cards in the deck. |
| 1431 |
<p> |
| 1432 |
But these routines are meant to be overridden. For example, when using |
| 1433 |
one of the <em>input formats</em> which reads deals from a file, |
| 1434 |
the format will redefine these two procedures to give errors. |
| 1435 |
<pre class='example'> |
| 1436 |
% deal -I "line foo.txt" -e "stack_cards south spades AJ" |
| 1437 |
Tcl stack dump of error info: |
| 1438 |
No card stacking with input format ::line |
| 1439 |
<em>...</em> |
| 1440 |
</pre> |
| 1441 |
A more complicated re-definition occurs in the <a name="#smartstack"> |
| 1442 |
<code>smartstack</code> input format,</a> which alters its hand |
| 1443 |
generation depending on what cards are stacked where. |
| 1444 |
|
| 1445 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1446 |
<dl> |
| 1447 |
<dt>Implementation:</dt> |
| 1448 |
<dd>C</dd> |
| 1449 |
<dt>Location:</dt> |
| 1450 |
<dd><code>hand.c</code>, function <code>tcl_stack_hand</code> and |
| 1451 |
<code>tcl_stack_cards</code> |
| 1452 |
</dl> |
| 1453 |
</div> |
| 1454 |
</table> |
| 1455 |
<hr> |
| 1456 |
|
| 1457 |
<a name="deck_stack_hand"></a> |
| 1458 |
<a name="deck_stack_cards"></a> |
| 1459 |
<h2>Commands: <code>deck_stack_hand</code> and <code>deck_stack_cards</code></h2> |
| 1460 |
<table cellpadding=5 style="width: 100%"> |
| 1461 |
<tr valign=top><td style="width: 65%"> |
| 1462 |
<h3>Usage</h3> |
| 1463 |
<pre class='example'> |
| 1464 |
deck_stack_hand <em>handname</em> <em>hand</em> |
| 1465 |
deck_stack_cards <em>handname</em> <em>suitname</em> <em>holding</em> [...] |
| 1466 |
</pre> |
| 1467 |
<h3>Summary</h3> |
| 1468 |
These routines are the "underlying" deck-stacking routines. Any cards |
| 1469 |
stacked with these routines remain stacked until the next call to |
| 1470 |
<a href="#reset_deck"><code>reset_deck</code></a> |
| 1471 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1472 |
<dl> |
| 1473 |
<dt>Implementation:</dt> |
| 1474 |
<dd>C</dd> |
| 1475 |
<dt>Location:</dt> |
| 1476 |
<dd><code>hand.c</code>, function <code>tcl_stack_hand</code> and |
| 1477 |
<code>tcl_stack_cards</code> |
| 1478 |
</dl> |
| 1479 |
</div> |
| 1480 |
</table> |
| 1481 |
<hr> |
| 1482 |
|
| 1483 |
<a name="stacked"></a> |
| 1484 |
<h2>Command: <code>stacked</code></h2> |
| 1485 |
<table cellpadding=5 style="width: 100%"> |
| 1486 |
<tr valign=top><td style="width: 65%"> |
| 1487 |
<h3>Usage</h3> |
| 1488 |
<pre class='example'> |
| 1489 |
stacked <em>handname</em> |
| 1490 |
</pre> |
| 1491 |
<h3>Summary</h3> |
| 1492 |
Determines what cards are stacked to this hand, returning them as |
| 1493 |
a list of holdings: |
| 1494 |
<pre class='example'> |
| 1495 |
south gets AS KH 3H QD JD TC 9C 8C |
| 1496 |
puts [stacked south] |
| 1497 |
</pre> |
| 1498 |
writes out the list: |
| 1499 |
<pre class='example'> |
| 1500 |
A K3 QJ T98 |
| 1501 |
</pre> |
| 1502 |
This is useful for the <a href="#smartstack">smartstacker</a>, because |
| 1503 |
we don't want to force the user to stack cards *after* specifying conditions. |
| 1504 |
<pre class='example'> |
| 1505 |
stack_hand north {AJT KT3 KJ 75432} |
| 1506 |
deal::input smartstack south balanced hcp 20 21 |
| 1507 |
</pre> |
| 1508 |
The call to <code>stack_hand</code> occurs before <code>smartstack</code> |
| 1509 |
is loaded, so <code>stack_hand</code> has not been redefined. So what |
| 1510 |
<code>smartstack</code> does is read the cards already stacked, and |
| 1511 |
use that for its initial conditions. |
| 1512 |
<p> |
| 1513 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1514 |
<dl><dt>Implementation:</dt> |
| 1515 |
<dd>C</dd> |
| 1516 |
<dt>Location:</dt> |
| 1517 |
<dd><code>tcl_deal.c</code>, function <code>tcl_stacked_cards</code> |
| 1518 |
</dl> |
| 1519 |
</div> |
| 1520 |
</table> |
| 1521 |
<hr> |
| 1522 |
|
| 1523 |
<a name="deal::nostacking"></a> |
| 1524 |
<h2>Command: <code>deal::nostacking</code></h2> |
| 1525 |
<table cellpadding=5 style="width: 100%"> |
| 1526 |
<tr valign=top><td style="width: 65%"> |
| 1527 |
<h3>Usage</h3> |
| 1528 |
<pre class='example'> |
| 1529 |
::deal::nostacking |
| 1530 |
</pre> |
| 1531 |
<h3>Summary</h3> |
| 1532 |
This procedure redefines the <a href="#stack_hand">stack_hand and |
| 1533 |
stack_cards</a> procedures to generate error messages, and |
| 1534 |
generates an error if any cards are currently stacked. |
| 1535 |
<p> |
| 1536 |
This is used in all of the input formats which read complete deals from |
| 1537 |
files, and thus are incompatible with stacking. |
| 1538 |
<td style="width: 35%"><div class='programmer'> |
| 1539 |
<b>For Programmers</b> |
| 1540 |
<dl><dt>Implementation:</dt> |
| 1541 |
<dd>Tcl code</dd> |
| 1542 |
<dt>Location:</dt> |
| 1543 |
<dd><code>lib/features.tcl</code>, function <code>deal::nostacking</code> |
| 1544 |
</dl> |
| 1545 |
</div> |
| 1546 |
</table> |
| 1547 |
<hr> |
| 1548 |
|
| 1549 |
|
| 1550 |
<a name="deal_reset_cmds"></a> |
| 1551 |
<h2>Command: <code>deal_reset_cmds</code></h2> |
| 1552 |
<table cellpadding=5 style="width: 100%"> |
| 1553 |
<tr valign=top><td style="width: 65%"> |
| 1554 |
<h3>Usage</h3> |
| 1555 |
<pre class='example'> |
| 1556 |
deal_reset_cmds {<em>...code...</em>} [ ... ] |
| 1557 |
</pre> |
| 1558 |
<h3>Summary</h3> |
| 1559 |
This adds a set of commands that are to be called before the next |
| 1560 |
deal. The code is executed at the next call to the |
| 1561 |
<a href="#deal_deck"><code>deal_deck</code></a> procedure, which, unless |
| 1562 |
you are doing something complicated, means it is called at the beginning |
| 1563 |
of each time through the evaluation loop. |
| 1564 |
<p> |
| 1565 |
<code>deal_reset_cmds</code> can be used so that metadata about the previous deal, |
| 1566 |
such as cached values and the like, are unset. See |
| 1567 |
<a href="#deal::metadata"><code>deal::metadata</code></a>. |
| 1568 |
<p> |
| 1569 |
It is also used for defining <a href="#deal::input">input formats,</a> |
| 1570 |
so that deals can be read from files. For example, the "line" input format |
| 1571 |
has the following routine declared: |
| 1572 |
<pre class='example'> |
| 1573 |
namespace eval line { |
| 1574 |
#.... |
| 1575 |
proc next {} { |
| 1576 |
variable handle |
| 1577 |
set length -1 |
| 1578 |
catch { set length [gets $handle line] } |
| 1579 |
|
| 1580 |
# ... process the line, or handle oef stuff ... |
| 1581 |
# ... |
| 1582 |
deal_reset_cmds {::line::next} |
| 1583 |
} |
| 1584 |
} |
| 1585 |
</pre> |
| 1586 |
<p> |
| 1587 |
The key is that when <code>line::next</code> is done, it re-registers itself, making |
| 1588 |
sure that it is called next time through as well. |
| 1589 |
<p> |
| 1590 |
The <em>code</em> passed in to <code>deal_reset_cmds</code> is |
| 1591 |
called only once, at the next request for a deal - think of it as |
| 1592 |
registering a one-time trigger. Multiple triggers can be registered - |
| 1593 |
they are called in the reverse order that they are added, which can seem |
| 1594 |
counter-intuitive until you think of the process as an "undo" process. |
| 1595 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1596 |
<dl><dt>Implementation:</dt> |
| 1597 |
<dd>C</dd> |
| 1598 |
<dt>Location:</dt> |
| 1599 |
<dd><code>tcl_deal.c</code>, function <code>add_reset_cmds</code> |
| 1600 |
</dl> |
| 1601 |
</div> |
| 1602 |
</table> |
| 1603 |
<hr> |
| 1604 |
|
| 1605 |
<a name="deal::metadata"></a> |
| 1606 |
<h2>Command: <code>deal::metadata</code></h2> |
| 1607 |
<table cellpadding=5 style="width: 100%"> |
| 1608 |
<tr valign=top><td style="width: 65%"> |
| 1609 |
<h3>Usage</h3> |
| 1610 |
<pre class='example'> |
| 1611 |
deal::metadata <em>name</em> {<em>...code...</em>} |
| 1612 |
</pre> |
| 1613 |
<h3>Summary</h3> |
| 1614 |
Currently, this is just a peculiar way of caching slow evaluation routines. |
| 1615 |
At the moment, the only place it is used is in |
| 1616 |
<a href="#deal::tricks"><code>deal::tricks</code></a>. |
| 1617 |
<p> |
| 1618 |
When you call <code>deal::metadata</code>, it will check to see if |
| 1619 |
there is a value associated with the <em>name</em> requested |
| 1620 |
already. If there is, the value is returned. If it does not, it evaluates the |
| 1621 |
specified code and associates the result with the <em>name</em>. The key |
| 1622 |
is, when the next deal is being analyzed, all the cached values are pitched. |
| 1623 |
<p> |
| 1624 |
This isn't really necessary or efficient in most cases, but with |
| 1625 |
evaluations which take some time, <em>e.g.</em> GIB calls, it |
| 1626 |
improves things. |
| 1627 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1628 |
<dl><dt>Implementation:</dt> |
| 1629 |
<dd><code>Tcl</code> |
| 1630 |
<dt>Location:</dt> |
| 1631 |
<dd><code>lib/features.tcl</code> |
| 1632 |
</dl> |
| 1633 |
<p>In later releases, metadata read from input streams (say, the fields |
| 1634 |
from a PBN file) will also be stored here. |
| 1635 |
<p> |
| 1636 |
This procedure uses |
| 1637 |
<a href="#deal_reset_cmds"><code>deal_reset_cmds</code></a>. |
| 1638 |
The metadata is cleared each time the <code>deal_deck</code> |
| 1639 |
command is called. |
| 1640 |
</div> |
| 1641 |
</table> |
| 1642 |
<hr> |
| 1643 |
|
| 1644 |
<h1>Input formats</h1> |
| 1645 |
<a name="deal::input"></a> |
| 1646 |
<h2>Command: <code>deal::input</code></h2> |
| 1647 |
<table cellpadding=5 style="width: 100%"> |
| 1648 |
<tr valign=top><td style="width: 65%"> |
| 1649 |
<h3>Usage</h3> |
| 1650 |
<pre class='example'> |
| 1651 |
deal::input <em>formatName</em> <em>args</em> |
| 1652 |
</pre> |
| 1653 |
<h3>Summary</h3> |
| 1654 |
The <code>deal::input</code> command is used to define an input source |
| 1655 |
for deals. It works as follows: |
| 1656 |
<ol> |
| 1657 |
<li>The file <code>input/<formatName>.tcl</code> is loaded. This |
| 1658 |
Tcl file should define a new Tcl 'namespace' with the name <em>formatName</em>, |
| 1659 |
with member procedures named <code>set_input</code> and <code>next</code>. |
| 1660 |
<li>Deal then calls |
| 1661 |
<code><formatName>::set_input <em>args</em></code>, which should |
| 1662 |
initialize the format reading. Usually, the argument(s) are one argument |
| 1663 |
representing the source file. |
| 1664 |
<li>The next deal, <code><formatName>::next</code> is called. |
| 1665 |
</ol> |
| 1666 |
</td> |
| 1667 |
<td style="width: 35%"> |
| 1668 |
<div class='programmer'><b>For Programmers</b> |
| 1669 |
<dl> |
| 1670 |
<dt>Implementation:</dt> |
| 1671 |
<dd>Tcl code</dd> |
| 1672 |
<dt>Location:</dt> |
| 1673 |
<dd>lib/features.tcl</dd> |
| 1674 |
</dl> |
| 1675 |
</div></table> |
| 1676 |
<hr> |
| 1677 |
<a name="giblib"></a><a name="library.dat"></a> |
| 1678 |
<h2>Input Format: <code>giblib</code></h2> |
| 1679 |
<table cellpadding=5 style="width: 100%"> |
| 1680 |
<tr valign=top><td style="width: 65%"> |
| 1681 |
<h3>Usage</h3> |
| 1682 |
<pre class='example'> |
| 1683 |
deal::input giblib [<em>filename</em>] |
| 1684 |
</pre> |
| 1685 |
or on the command line: |
| 1686 |
<pre class='example'> |
| 1687 |
% deal -I giblib |
| 1688 |
</pre> |
| 1689 |
or |
| 1690 |
<pre class='example'> |
| 1691 |
% deal -I "giblib <em>filename</em>" |
| 1692 |
</pre> |
| 1693 |
<h3>Summary</h3> |
| 1694 |
<p>Specifies that deals are read from the specified file in the format |
| 1695 |
of Matt Ginsberg's library.dat file. This includes double-dummy tricks |
| 1696 |
data, so that later calls to <a href="#deal::tricks"><code>deal::tricks</code></a> |
| 1697 |
will not entail calls to the GIB binaries.</p> |
| 1698 |
<p> |
| 1699 |
If no filename is given, the library tries to read from a file called |
| 1700 |
"library.dat" in the current directory. |
| 1701 |
<p> |
| 1702 |
The <code>-I</code> command-line flag is a quick alias for |
| 1703 |
<code>deal::input</code>, passing the next argument as |
| 1704 |
Tcl arguments to the <code>deal::input</code> command. |
| 1705 |
<td style="width: 35%"> |
| 1706 |
<div class='programmer'><b>For Programmers</b> |
| 1707 |
<dl> |
| 1708 |
<dt>Implementation:</dt> |
| 1709 |
<dd>Tcl code</dd> |
| 1710 |
<dt>Location:</dt> |
| 1711 |
<dd>input/giblib.tcl</dd> |
| 1712 |
</dl> |
| 1713 |
<p>This procedure uses <a href="#deal_reset_cmds">deal_reset_cmds</a>.</p> |
| 1714 |
</div> |
| 1715 |
</table> |
| 1716 |
<hr> |
| 1717 |
|
| 1718 |
<a name="line"></a> |
| 1719 |
<h2>Input Format: <code>line</code></h2> |
| 1720 |
<table cellpadding=5 style="width: 100%"> |
| 1721 |
<tr valign=top><td style="width: 65%"> |
| 1722 |
<h3>Usage</h3> |
| 1723 |
<pre class='example'> |
| 1724 |
deal::input line [<em>filename</em>] |
| 1725 |
</pre> |
| 1726 |
<h3>Summary</h3> |
| 1727 |
<p>Specifies that deals are read from the specified file in the format |
| 1728 |
written by Deal's "-l" option. |
| 1729 |
<p> |
| 1730 |
If no filename is given, the library reads from standard |
| 1731 |
input. This way, you can create a single data file and then |
| 1732 |
run several different queries against it: |
| 1733 |
<pre class='example'> |
| 1734 |
% deal -l 100000 > sample |
| 1735 |
% deal -e "deal::input line sample" -i query1 |
| 1736 |
% deal -e "deal::input line sample" -i query2 |
| 1737 |
</pre> |
| 1738 |
[ The <code>-e</code> option just evaluates the code in the next |
| 1739 |
argument as Tcl code. Alternative, you can use the <code>-I</code> |
| 1740 |
option, which is shorthand for input formats: |
| 1741 |
<pre class='example'> |
| 1742 |
% deal -I "line sample" -i query1 |
| 1743 |
</pre> |
| 1744 |
The <code>-I <em>args</em></code> option is exactly the same as -e "deal::input <em>args</em>".] |
| 1745 |
|
| 1746 |
<td style="width: 35%"> |
| 1747 |
<div class='programmer'><b>For Programmers</b> |
| 1748 |
<dl> |
| 1749 |
<dt>Implementation:</dt> |
| 1750 |
<dd>Tcl code</dd> |
| 1751 |
<dt>Location:</dt> |
| 1752 |
<dd>input/line.tcl</dd> |
| 1753 |
</dl> |
| 1754 |
</div> |
| 1755 |
</table> |
| 1756 |
<a name="ddline"></a> |
| 1757 |
<h2>Input Format: <code>ddline</code></h2> |
| 1758 |
<table cellpadding=5 style="width: 100%"> |
| 1759 |
<tr valign=top><td style="width: 65%"> |
| 1760 |
<h3>Usage</h3> |
| 1761 |
<pre class='example'> |
| 1762 |
deal::input line [<em>filename</em>] |
| 1763 |
</pre> |
| 1764 |
<h3>Summary</h3> |
| 1765 |
<p>Specifies that deals are read from the specified file in the format |
| 1766 |
written by Deal's <a href="#format:ddline"><code>ddline</code> format.</a> |
| 1767 |
<p>The ddline format include doubled-dummy tricks data, so when using <code>ddline</code> for input, calls to <a href="deal::tricks">deal::tricks</a> return the data read from the file. |
| 1768 |
<td style="width: 35%"> |
| 1769 |
<div class='programmer'><b>For Programmers</b> |
| 1770 |
<dl><dt>Implementation:</dt> |
| 1771 |
<dd>Tcl code</dd> |
| 1772 |
<dt>Location:</dt> |
| 1773 |
<dd>input/line.tcl</dd> |
| 1774 |
</dl> |
| 1775 |
</div> |
| 1776 |
</table> |
| 1777 |
<a name="smartstack"></a> |
| 1778 |
<h2>Input: <code>smartstack</code></h2> |
| 1779 |
<table cellpadding=5 style="width: 100%"> |
| 1780 |
<tr valign=top><td style="width: 65%"> |
| 1781 |
<h3>Usage</h3> |
| 1782 |
<pre class='example'> |
| 1783 |
deal::input smartstack <em>hand</em> <em>shapeclass</em> [<em>holdproc</em> <em>min</em> <em>max</em>] |
| 1784 |
</pre> |
| 1785 |
or on the command line: |
| 1786 |
<pre class='example'> |
| 1787 |
% deal -I "smartstack <em>shapeclass</em> ..." |
| 1788 |
</pre> |
| 1789 |
<h3>Summary</h3> |
| 1790 |
This is the most complicated Deal input method in the current release. |
| 1791 |
It does not read deals from a file - it is, instead, a different path to |
| 1792 |
generation of deals. The purpose of this format is to allow fast generations |
| 1793 |
of deals where one hand fits a very specific description. For example, |
| 1794 |
if you want to find hands where south has a balanced 27-count, you |
| 1795 |
could write: |
| 1796 |
<pre class='example'> |
| 1797 |
deal::input smartstack south balanced hcp 27 27 |
| 1798 |
</pre> |
| 1799 |
On my computer, that returns the first deal in 14 seconds, and every deal after |
| 1800 |
that takes a tiny fraction of a second. That's because <code>smartstack</code> |
| 1801 |
first builds a large "factory" in memory, but once it is built, the |
| 1802 |
factory spits out hands matching this condition very quickly. |
| 1803 |
<p> |
| 1804 |
By contrast, a standard "deal" script to find balanced 27-counts |
| 1805 |
takes about 2.8 seconds to find each deal. That means that if you only |
| 1806 |
want to find about five deals of this sort, the old style program |
| 1807 |
is faster, but if you want a lot more, use <code>smartstack</code>. |
| 1808 |
For example, if you wanted 1000 examples, <code>smartstack</code> |
| 1809 |
takes about 15 seconds, while the old deal will take about 45 minutes. |
| 1810 |
<p> |
| 1811 |
One interesting feature of <code>smartstack</code> is that it is often |
| 1812 |
faster if the hand type is less frequent. For example, it takes about 6 |
| 1813 |
seconds to find ten deals with 9-card spade suits, and about 5 seconds to |
| 1814 |
find ten deals with 10-card spade suits. Similarly, it is faster at |
| 1815 |
finding hands with exactly 9 controls than it is at finding hands |
| 1816 |
with 9-12 controls. |
| 1817 |
<p> |
| 1818 |
The <code>smartstack</code> routine only works on one hand - after it |
| 1819 |
places cards in that hand, it generates the rest using the usual |
| 1820 |
algorithm. |
| 1821 |
<td style="width: 35%"> |
| 1822 |
<div class='programmer'><b>For Programmers</b> |
| 1823 |
<dl> |
| 1824 |
<dt>Implementation:</dt> |
| 1825 |
<dd>Tcl code</dd> |
| 1826 |
<dt>Location:</dt> |
| 1827 |
<dd>input/smartstack.tcl, lib/handFactory.tcl</dd> |
| 1828 |
<dt>Notes</dt> |
| 1829 |
<dd>See the two articles from the bridge developers mailing list |
| 1830 |
describing the algorithm: |
| 1831 |
<a href="http://www.cirl.uoregon.edu/pipermail/developers/2001-February/000339.html">My first stab at describing it</a> and |
| 1832 |
<a href="http://www.cirl.uoregon.edu/pipermail/developers/2001-February/000342.html">some corrections.</a> |
| 1833 |
|
| 1834 |
</dl> |
| 1835 |
</div> |
| 1836 |
</table> |
| 1837 |
<hr> |
| 1838 |
<h1>Formatting</h1> |
| 1839 |
<a name="write_deal"></a> |
| 1840 |
<h2>Command: <code>write_deal</code></h2> |
| 1841 |
<table cellpadding=5 style="width: 100%"> |
| 1842 |
<tr valign=top><td style="width: 65%"> |
| 1843 |
<h3>Usage</h3> |
| 1844 |
<pre class='example'> |
| 1845 |
write_deal |
| 1846 |
</pre> |
| 1847 |
<h3>Summary</h3> |
| 1848 |
This is the the name of a procedure which is called when deals are accepted. |
| 1849 |
By default, it writes the result in the format: |
| 1850 |
<pre class='example'> |
| 1851 |
S: 98632 |
| 1852 |
H: A4 |
| 1853 |
D: AJ754 |
| 1854 |
C: J |
| 1855 |
S: K S: AJT7 |
| 1856 |
H: J3 H: QT95 |
| 1857 |
D: T98 D: Q2 |
| 1858 |
C: AKT7532 C: 984 |
| 1859 |
S: Q54 |
| 1860 |
H: K8762 |
| 1861 |
D: K63 |
| 1862 |
C: Q6 |
| 1863 |
-------------------------- |
| 1864 |
</pre> |
| 1865 |
New output formats are defined by <em>redefining this routine</em>. |
| 1866 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1867 |
<dl><dt>Implementation:</dt> |
| 1868 |
<dd>Tcl |
| 1869 |
<dt>Location:</dt> |
| 1870 |
<dd><code>format/default</code> |
| 1871 |
</dl> |
| 1872 |
</div> |
| 1873 |
</table> |
| 1874 |
<hr> |
| 1875 |
<a name="flush_deal"></a> |
| 1876 |
<h2>Command: <code>flush_deal</code></h2> |
| 1877 |
<table cellpadding=5 style="width: 100%"> |
| 1878 |
<tr valign=top><td style="width: 65%"> |
| 1879 |
<h3>Usage</h3> |
| 1880 |
<pre class='example'> |
| 1881 |
flush_deal |
| 1882 |
</pre> |
| 1883 |
<h3>Summary</h3> |
| 1884 |
This routine is called at the very end of a run for deal. It does nothing, |
| 1885 |
by default, but some output formats may require it if data is cached. |
| 1886 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1887 |
<dl> |
| 1888 |
<dt>Implementation:</dt> |
| 1889 |
<dd>Tcl code</dd> |
| 1890 |
<dt>Location:</dt> |
| 1891 |
<dd><code>format/default</code>, function <code>flush_deal</code> |
| 1892 |
</dl> |
| 1893 |
</div> |
| 1894 |
</table> |
| 1895 |
<hr> |
| 1896 |
|
| 1897 |
<a name="format:par"></a> |
| 1898 |
<h2>Output Format: <code>format/par</code></h2> |
| 1899 |
<table cellpadding=5 style="width: 100%"> |
| 1900 |
<tr valign=top><td style="width: 65%"> |
| 1901 |
<h3>Usage</h3> |
| 1902 |
<pre class='example'> |
| 1903 |
source format/par |
| 1904 |
</pre> |
| 1905 |
<h3>Summary</h3> |
| 1906 |
<p>By including this file, you are setting the output format to write the results in PBN format, with results set to the double dummy theoretical par. |
| 1907 |
<pre class='example'> |
| 1908 |
$ deal -i format/par 1 |
| 1909 |
[Date "2008.05.19"] |
| 1910 |
[Board "1"] |
| 1911 |
[West "West"] |
| 1912 |
[North "North"] |
| 1913 |
[East "East"] |
| 1914 |
[South "South"] |
| 1915 |
[Dealer "N"] |
| 1916 |
[Vulnerable "None"] |
| 1917 |
[Deal "N:K.A7.QJT9865.AK7 T94.K98532.2.943 A872.QT4.AK4.862 QJ653.J6.73.QJT5"] |
| 1918 |
[Contract "6N"] |
| 1919 |
[Declarer "S"] |
| 1920 |
[Result "12"] |
| 1921 |
[Score "NS 990"] |
| 1922 |
{ |
| 1923 |
S: K |
| 1924 |
H: A7 |
| 1925 |
D: QJT9865 |
| 1926 |
C: AK7 |
| 1927 |
S: QJ653 S: T94 |
| 1928 |
H: J6 H: K98532 |
| 1929 |
D: 73 D: 2 |
| 1930 |
C: QJT5 C: 943 |
| 1931 |
S: A872 |
| 1932 |
H: QT4 |
| 1933 |
D: AK4 |
| 1934 |
C: 862 |
| 1935 |
north makes 9 tricks in clubs |
| 1936 |
north makes 12 tricks in diamonds |
| 1937 |
north makes 8 tricks in hearts |
| 1938 |
north makes 7 tricks in spades |
| 1939 |
north makes 12 tricks in notrump |
| 1940 |
east makes 3 tricks in clubs |
| 1941 |
east makes 1 tricks in diamonds |
| 1942 |
east makes 5 tricks in hearts |
| 1943 |
east makes 4 tricks in spades |
| 1944 |
east makes 1 tricks in notrump |
| 1945 |
south makes 8 tricks in clubs |
| 1946 |
south makes 12 tricks in diamonds |
| 1947 |
south makes 8 tricks in hearts |
| 1948 |
south makes 7 tricks in spades |
| 1949 |
south makes 12 tricks in notrump |
| 1950 |
west makes 3 tricks in clubs |
| 1951 |
west makes 1 tricks in diamonds |
| 1952 |
west makes 5 tricks in hearts |
| 1953 |
west makes 4 tricks in spades |
| 1954 |
west makes 1 tricks in notrump |
| 1955 |
} |
| 1956 |
[Auction "N"] |
| 1957 |
Pass Pass 6N |
| 1958 |
[Play "W"] |
| 1959 |
* |
| 1960 |
</pre> |
| 1961 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1962 |
<dl><dt>Implementation:</dt> |
| 1963 |
<dd>Tcl</dd> |
| 1964 |
<dt>Location:</dt> |
| 1965 |
<dd><code>format/par</code></dd> |
| 1966 |
</dl> |
| 1967 |
</div> |
| 1968 |
</table> |
| 1969 |
<hr> |
| 1970 |
|
| 1971 |
<a name="format:ddline"></a> |
| 1972 |
<h2>Output Format: <code>format/ddline</code></h2> |
| 1973 |
<table cellpadding=5 style="width: 100%"> |
| 1974 |
<tr valign=top><td style="width: 65%"> |
| 1975 |
<h3>Usage</h3> |
| 1976 |
<pre class='example'> |
| 1977 |
source format/ddline |
| 1978 |
</pre> |
| 1979 |
<h3>Summary</h3> |
| 1980 |
<p>By including this file, you are redefining the output format to the form "ddline", which writes out the deal on a single line, as with the '-l' flag, but then adds complete double-dummy data to the deal as well. If you write the output to a file: |
| 1981 |
<pre class='example'> |
| 1982 |
$ deal -i format/ddline 100 > doubledummy.txt |
| 1983 |
</pre> |
| 1984 |
<p>then you can use the <a href="#ddline"><code>ddline</code> input format</a> to read the file back in: |
| 1985 |
<pre class='example'> |
| 1986 |
$ deal -I "ddline doubledummy.txt" -i query.tcl 100 |
| 1987 |
</pre> |
| 1988 |
<p>And any call to <code>deal::tricks</code> in query.tcl will use the value stored doubledummy.txt. |
| 1989 |
<td style="width: 35%"><div class='programmer'><b>For Programmers</b> |
| 1990 |
<dl><dt>Implementation:</dt> |
| 1991 |
<dd>Tcl</dd> |
| 1992 |
<dt>Location:</dt> |
| 1993 |
<dd><code>format/ddline</code></dd> |
| 1994 |
</dl> |
| 1995 |
</div> |
| 1996 |
</table> |
| 1997 |
|
| 1998 |
<hr> |
| 1999 |
<table><tr><td><a href="http://bridge.thomasoandrews.com/" class="image"> |
| 2000 |
<img style="border:0;width:40px;height:56px" alt="Silhouette" src="graphics/StampSm.gif"></a><td> |
| 2001 |
Thomas Andrews |
| 2002 |
(<a href="mailto:deal@thomasoandrews.com">deal@thomasoandrews.com</a>) |
| 2003 |
Copyright 1996-2010. Deal is covered by the |
| 2004 |
<a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License.</a> |
| 2005 |
<p> |
| 2006 |
<a href="graphics/falling.jpg"><em>Plane Dealing</em></a> graphic |
| 2007 |
above created using |
| 2008 |
<a href="http://www.povray.org/">POV-Ray.</a> |
| 2009 |
</tr></table> |
| 2010 |
</div> |
| 2011 |
</body> |
| 2012 |
</html> |