Debian Codegraph @

html/commands.html

raw
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%">&nbsp;</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/&lt;formatName&gt;.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>&lt;formatName&gt;::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>&lt;formatName&gt;::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&#64;thomasoandrews.com">deal&#64;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>