Debian Codegraph @

html/reference.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: reference.html 313 2009-06-11 05:44:13Z thomasoa $ -->
6 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
7 <LINK REL="SHORTCUT ICON" HREF="/icon/bridge.ico">
8 <link rev="made" href="mailto:deal&#64;thomasoandrews.com (Thomas Andrews)">
9 <link rel="stylesheet" type="text/css" href="look.css">
10 <title>
11 Deal - New Features in Version 2.0
12 </title>
13
14
15 </head>
16 <body>
17 <div class="toplevel back">
18 <A href="index.html">Back to <em>Deal Top Page</em></A>.
19 </div>
20
21 <table class="toplevel">
22 <tr>
23 <td valign="middle"><img
24 style="width:225px; height:216px"
25 src="graphics/falling_small.jpg" alt="Plane Dealing image"></td>
26 <td valign="middle" width="50%"><span class="header"><h1>Deal 2.0</h1>
27 <h2>Reference Guide</h2>
28 </span>
29 Covering: <UL>
30 <LI> Command line arguments
31 <LI> Additive Functions
32 <LI> Shape Functions and Classes
33 <LI> String Boxes and formatting
34 <LI> Often used Tcl features
35 <LI> Library routines
36 </UL>
37 </td>
38 </tr></table>
39 <div class="toplevel">
40 <hr>
41
42 <h2> Command Line Options </h2>
43
44 <DL>
45 <DT> -e <var>expr</var>
46 <DD> Evaluate the Tcl expression <var>expr</var>. Not very
47 useful, but occasionally good for setting variables
48 which affect the user's script, like:
49 <pre class="codesample">
50 deal -i userscript -e "set maxnorth 10"
51 </pre>
52 <DT> -v
53 <DD> Verbose mode. Lets you know how many hands have
54 been accepted and how many hands have been tried.
55 <DT> -[NSEW] <var>hand-spec</var>
56 <DD> Specifies the cards held by the specified hand.
57 The <var>hand-spec</var> should be of the form:
58 <span classs="code">"AK8532 - KQ72 A65"</span>.
59 Voids must be represented with a '-' character.
60 <var>hand-spec</var> should be <em>one</em> argument,
61 so the string should be quoted on the command line.
62
63 <DT> -i <var>file</var>
64 <DD> Source the commands in the file named. The language
65 used is "Tcl". Read the man page for Tcl for help
66 in writing Tcl code. Additions to Tcl specific to deal are
67 listed in this manual.
68
69 <DT> -x <var>file</var>
70 <DD> Like -i, except execute this file and then exit.
71 <DT> -f
72 <DD> Instead of dealing new hands, reads hands from
73 standard input. The hands must be in the format
74 put out by "deal -l". You might deal, say, 10,000
75 hands which satisfy specific criteria, saving them
76 to a file. Then you can use that output for input
77 with deal -f to find out which hands satisfy other
78 constraints.
79
80 <DT> -t
81 <DD> Print <A href="dist.html">distribution table</A> and exit.
82 The distribution table is an ordered list
83 of all possible hand patterns for a single
84 hand.
85
86 <DT> -l
87 <DD> Write deals in a "single-line" format. In previous
88 releases this was the default format. It is useful
89 for piping to formatters written in other languages.
90 Most formatting can be defined internally, using
91 Tcl now. Still useful with the "-f" option.
92
93 </DL>
94
95 <h2> Simple Usage </h2>
96
97 The most basic usage of the program is to generate random deals
98 with no conditions:
99
100 <pre class="codesample">
101 % deal 2
102 S : QJ9
103 H : AJ
104 D : T52
105 C : AKQ84
106 S : 752 S : AK83
107 H : T85 H : Q632
108 D : AK8763 D : J4
109 C : 2 C : T96
110 S: T64
111 H: K974
112 D: Q9
113 C: J753
114 ---------------------------
115 S : QJ9
116 H : 52
117 D : AKJT9
118 C : A86
119 S : 763 S : A52
120 H : T763 H : J98
121 D : Q54 D : 876
122 C : T95 C : KQJ7
123 S: KT84
124 H: AKQ4
125 D: 32
126 C: 432
127 ---------------------------
128 </pre>
129
130 If you want a raw format, more readable by external programs,
131 use the -l flag, which prints deals in a single-line format:
132
133 <pre class="codesample">
134 % deal -l 5
135 K75 T987 AQT5 95|AQ86 2 943 QJ643|JT32 J43 KJ KT82|94 AKQ65 8762 A7
136 QJ96 KQ6 T95 K76|T5 J953 A72 AJT9|8432 A7 83 Q8432|AK7 T842 KQJ64 5
137 K52 QJT9 AKQ K63|AJ AK7542 T732 8|94 3 J965 QJT972|QT8763 86 84 A54
138 A76 A764 43 KJT2|J9 KJ53 K986 A87|K8543 T82 72 953|QT2 Q9 AQJT5 Q64
139 Q6 QJ75 3 AJ7642|AT9874 KT963 AT |K32 4 QJ2 KQ9853|J5 A82 K987654 T
140 </pre>
141
142
143
144 This output form is crude; it is meant to be post-processed. Each
145 line is of the form:
146 <blockquote>
147 &quot;<var>North</var>|<var>East</var>|<var>South</var>|<var>West</var>&quot;
148
149 </blockquote>
150 Each hand is specified by:
151 <blockquote>
152
153 &quot;<var>Spades</var> <var>Hearts</var> <var>Diamonds</var> <var>Clubs</var>&quot;
154
155 </blockquote>
156 where the space character separates each suit.
157
158 In the examples above, the east hand in the last deal is:
159 <pre class="codesample">
160 "AT9874 KT963 AT "
161 </pre>
162 which might be written more verbosely as:
163
164 <pre class="codesample">
165 S: AT9874 H: KT963 D: AT C: ---
166 </pre>
167 I've included three formatters with the package, one of which creates
168 a TeX file for the hands generated, the other two simple text files.
169 The formatters are <A href="http://www.cis.ufl.edu/perl/">Perl</a> scripts,
170 so if you don't have
171 Perl on your system they won't work. To format, you just run deal with
172 the -l flag, and pipe to the formatter:
173
174 <pre class="codesample">
175 % deal -l 5 | perl ./compactdeal
176 Deal # 1 - AKQT43 AKT65 A3
177 JT65 82 QJ32 752 AKQ82 6 94 KJ984
178 9743 J975 87 QT6
179 ------------------------
180 Deal # 2 3 QJT43 A8742 K4
181 QT4 86 T93 AJ973 AK52 2 QJ65 T862
182 J9876 AK975 K Q5
183 ------------------------
184 Deal # 3 A76 KT9 QJ84 K53
185 T952 A832 A95 Q8 J Q76 KT632 J762
186 KQ843 J54 7 AT94
187 ------------------------
188 Deal # 4 AQ752 J632 - 8652
189 6 AK74 A863 AKT9 KJ98 Q95 J752 QJ
190 T43 T8 KQT94 743
191 ------------------------
192 Deal # 5 A4 AJ72 852 AKQT
193 63 T9654 QT9 865 QJ852 Q J764 J94
194 KT97 K83 AK3 732
195 ------------------------
196 </pre>
197
198 <pre class="codesample">
199 % deal -l 2 | perl ./formatdeal
200 Deal 1 S : 75 |
201 H : Q4 |
202 D : QJ962 |
203 C : AT64 |
204 S : KQ63 S : J98 |
205 H : K732 H : T985 |
206 D : K75 D : A843 |
207 C : 83 C : J2 |
208 S : AT42 |
209 H : AJ6 |
210 D : T |
211 C : KQ975 |
212 -------------------------------------------
213 Deal 2 S : AKQJ |
214 H : J43 |
215 D : KQ4 |
216 C : 762 |
217 S : 73 S : 9865 |
218 H : QT76 H : AK82 |
219 D : J972 D : T86 |
220 C : JT4 C : A9 |
221 S : T42 |
222 H : 95 |
223 D : A53 |
224 C : KQ853 |
225 -------------------------------------------
226 </pre>
227
228
229 <h2>Putting Conditions on the Deal</h2>
230
231 There are two distinct types of conditions which can be placed on
232 a hand.
233 <p>
234 One is the rigid placement of cards, as in, `South gets the ace of
235 clubs,' or `East is "AK52 AK32 9652 6"'. Card placements are done
236 before any randomnizations.
237 <p>
238
239 Card placements are ignored when using deal with the -f option. This
240 is because `deal' is reading already built hands.
241
242 <p>
243 The other conditionals are evaluated conditionals, like "South
244 has at least 4 hearts" or "West has 11 to 15 HCP" or "North has
245 exactly one of the ace and king of clubs."
246 <p>
247
248 The flow of control is:
249 <OL>
250 <LI> Place known cards
251 <LI> Deal rest of the cards at random
252 <LI> Determine whether to accept or reject deal. If rejected,
253 go to 2.
254 </OL>
255
256 This is less than optimal in many ways. The <a href="Optimization.html">optimizing problem</a> here
257 is pretty painful, though, and, although I have some ideas for solutions,
258 I'm trying to be careful to do it right; in the meantime, this
259 method will have to do.
260
261 <p>
262 Scripts use the Tcl language, with bridge-related additions.
263 To understand these scripts, you should read the Tcl man
264 page.
265
266 <p>
267
268 An example script (ex/1.tcl from the kit):
269 <blockquote>
270 <pre>
271 ##############################################
272 # Look for deals where north has 44 in the majors, a short minor,
273 # and 11-15 HCP.
274 # To execute:
275 # deal -i ex/1.tcl [num]
276 ##############################################
277 main {
278 # Pitch deals
279 # where north does
280 # not have four spades
281 reject if {[spades north]!=4}
282
283 # Pitch deals
284 # where north does
285 # not have four hearts
286 reject if {[hearts north]!=4}
287
288 # Pitch deals
289 # where north has
290 # 2 or 3 diamonds
291 set d [diamonds north]
292 reject if {$d==2} {$d==3}
293
294 # Accept deals
295 # where north has
296 # 11-15 HCP.
297 set hcp_n [north]
298 accept if {$hcp_n>=11 && $hcp_n<=15}
299 }
300 ##############################################
301 </pre>
302 </blockquote>
303 The "main" command defines the expression which is to be evaluated
304 to ascertain whether a deal is accepted or rejected. This occurs after
305 all cards have been dealt. If the hand is never explicitly accepted,
306 the hand is rejected.
307
308 <p>
309 We can run this example as:
310 <blockquote>
311 <pre>
312 % deal -i ex/1.tcl 10
313 </pre>
314 </blockquote>
315
316 This will produce ten deals where north has a mini-Roman hand with
317 a short minor.
318 <p>
319
320 "deal" takes a "-v" flag which lets the user know about progress
321 in the hand generation; how many hands have been searched, and
322 how many have been checked.
323
324 <blockquote>
325 <pre>
326 % deal -l -v -i ex/1.tcl 5
327 KJ92 AQ42 7 K842|8 KT9763 A862 95|Q73 J JT94 QJ763|AT654 85 KQ53 AT
328 Deal 1 found after 61 tries
329 AJ62 AQ84 9 J764|K84 J2 875 KT932|QT T73 AJ643 Q85|9753 K965 KQT2 A
330 Deal 2 found after 269 tries
331 JT86 AQJ8 KQ543|9 T9432 542 A976|K7532 K6 KQJ7 T2|AQ4 75 AT9863 J8
332 Deal 3 found after 303 tries
333 A652 AT94 A985 2|3 QJ532 T63 J543|QT74 8 K7 KT9876|KJ98 K76 QJ42 AQ
334 Deal 4 found after 394 tries
335 AJ65 9743 K AJT8|T742 T6 T764 972|KQ83 AQ5 Q32 643|9 KJ82 AJ985 KQ5
336 Deal 5 found after 523 tries
337 </pre>
338 </blockquote>
339 The progress output is sent to "stderr", so you can still pipe the
340 hands to a formatter or file without trouble.
341 <p>
342 You can specify on the command line that you want South to hold a specific
343 hand:
344 <blockquote><pre>
345 % deal -v -i ex/1.tcl -S 'AK52 42 K52 7642' 10
346 </pre></blockquote>
347
348 Here are some of the procedures built in to the program which
349 have been added to Tcl for <b>Deal</b>.
350
351 <DL>
352 <DT> accept
353 <DD> Accept the current deal. Use only from "main".
354 <DT> accept if <var>expr</var> [<var>expr</var>...]
355 <DD> Accept the current deal if one of
356 the expressions is true. Use only
357 from "main". Stops evaluating
358 <var>expr</var>s when it finds a true one.
359 <DT> accept unless <var>expr</var> [<var>expr</var>...]
360 <DD> Accept the current deal unless one of
361 the expressions is true. Use only
362 from "main". Stops evaluating <var>expr</var>s
363 when it finds a true one.
364 <p>
365 <DT> reject <DD> Reject the current deal. Use only
366 from "main".
367 <DT> reject if <var>expr</var> [<var>expr</var>...]
368 <DD> Reject the current deal if one of
369 the expressions is true. Use only
370 from "main". Stops evaluating
371 <var>expr</var>s when it finds a true one.
372 <DT> reject unless <var>expr</var> [<var>expr</var>...]
373 <DD> Reject the current deal unless one of
374 the expressions is true. Use only
375 from "main". Stops evaluating
376 <var>expr</var>s when it finds a true one.
377 <p>
378 <DT> spades <var>hand</var>, hearts <var>hand</var>,
379 diamonds <var>hand</var>, clubs <var>hand</var>
380 <DD> Returns the number of cards held in the suit by hand <var>hand</var>
381 <p>
382 <DT> controls <var>hand</var> [<var>suit</var>]
383 <DD> Return the number of controls (A=2,
384 K=1) held in the suit given. If no
385 suit given, the total number of
386 controls.
387 <p>
388 <DT> <var>hand</var> is <var>hand-spec</var>
389 <DD> This places all the cards of one hand.
390 The hand spec looks like:
391 <blockquote> <code>
392 "AKQ - T642 QT9876"
393 </code></blockquote>
394 The format is pretty inflexible.
395 Example:
396
397 <blockquote> <code>
398 east is "AKQ AKQ AKQ AKQT"
399 </code></blockquote>
400
401 This is the same as saying:
402 <blockquote> <code>
403 -E 'AKQ AKQ AKQ AKQT'
404 </code></blockquote>
405 on the command line.
406 <p>
407 <DT> <var>hand</var> gets <var>card</var> [<var>card</var>...]
408 <DD> Places individual cards in to the hand.
409 Example:
410 <blockquote> <code>
411 north gets AC
412 </code></blockquote>
413 places the ace of clubs in the north hand.
414 <p>
415 <DT> <var>hand</var> has <var>card</var> [<var>card</var>...]
416 <DD> Checks to see if the hand holds
417 the specified cards, e.g.
418 <blockquote> <code>
419 if {[north has AC]} {...}
420 </code></blockquote>
421 <p>
422
423 <DT> <var>hand</var> shape
424 <DD> Returns a string of the 4 suit lengths, in the order S,H,D,C, e.g.
425 <blockquote> <code>
426 puts stderr [south shape]<br>
427 4 3 2 4
428 </code></blockquote>
429 <p>
430
431 <DT> <var>hand</var> pattern
432 <DD> Return a string of the 4 suit lengths, sorted in descending
433 order:
434 <blockquote> <code>
435 puts stderr [south pattern]<br>
436 4 4 3 2
437 </code></blockquote>
438 <p>
439 <DT> <var>hand</var>
440 <DD> Return the HCP total for the hand, e.g.
441 <blockquote> <code>
442 reject if {[north]>=16}
443 </code></blockquote>
444 <blockquote>
445 [Design note: this treatment might go away. I have serious problems
446 with making high card points so prominent, and <code>[south]</code> might
447 be better used as a method of extracting a tcl list like: <code>
448 {AK} {QJ65} {T9872} {53}
449 </code>. If I were to do this, I would add a function, <code>hcp</code>.
450 Of course, you can implement the hcp function
451 yourself with <code>defvector</code>. ]
452 </blockquote>
453 <DT> defvector <var>name</var> <var>val</var> [<var>val</var> ...]
454
455 <DD> A vector is a fast counting procedure. The "vector" for counting
456 HCP is (4,3,2,1,0,0,0,0,0,0,0,0,0). We can define
457 <blockquote><code>
458 defvector Hcp 4 3 2 1
459 </code></blockquote>
460
461 and then use "Hcp" as a procedure later:
462
463 <blockquote><code>
464 reject if {[Hcp north]>=16}
465 </code></blockquote>
466
467 Or
468 <blockquote><code>
469 defvector Top3 1 1 1
470 </code></blockquote>
471
472 creates a procedure for counting how many aces, kings, and queens are held.
473 <p>
474 One nice thing about these routines is that they are fast.
475 Clever use of vectors speeds up all sorts of evaluation routines.
476 <p>
477 <DT> <var>vector</var> <var>suit</var> [<var>suit</var> ...]
478 <DD> Counts the hand using the vector.
479 If a list of suits is given, only those
480 suits are counted. Otherwise, all suits
481 are counted. E.g.,
482 <blockquote><code>
483 defvector AKQ 3 2 1<br>
484 AKQ south hearts spades
485 </code></blockquote>
486 counts the Ace-King-Queen points held by the south hand in hearts and spades.
487 <p>
488 <DT> shapeclass <var>name</var> { <var>code</var> }
489 <DD> This, like defvector, is an optimization
490 issue. E.g.,
491
492 <blockquote><code>
493 shapeclass michaels {return [expr $h>=5 && $s>=5]}<br>
494 main { accept if {[michaels north]}}
495 </code></blockquote>
496 A shapeclass generates a lookup table
497 the first time it is called, and fast
498 shape matching occurs each time after.
499 <p>
500 <DT> shapecond <var>name</var> { <var>expression</var> }
501 <DD> This is just a shorthand for:
502 <blockquote>
503 <code>
504 shapeclass <var>name</var> {return [expr <var>expression</var>] }
505 </code>
506 </blockquote>
507
508 <DT> <var>definedclass</var> <var>hand</var>
509 <DD> Returns true if the hand is in the shape
510 class and false otherwise.
511 <p>
512 <DT> <var>definedclass</var> compile
513 <DT>
514 <DD> Returns a string of 0's, 1's and whitespaces
515 for faster shapeclass reuse. Really for my personal use,
516 but included here for completeness.
517 <p>
518
519 <DT> shapeclass.binary <var>name</var> { <var>bits</var> }
520 <DD> This is how to define the "compiled" form of the shapeclass
521 definitions, only really useful for shape
522 classes which are reused often.
523 <p>
524 <DT> balanced <var>hand</var>
525 <DD> Returns true if the hand is "balanced"
526 in the classical Goren-style: 4333s,
527 4432s, and 5332s with 5-card minor.
528 This could be implemented as a shapeclass,
529 but there still remains an internal definition
530 which is pretty fast.
531 <p>
532 <DT> losers <var>hand</var> [<var>suit</var> ...]
533 <DD> Returns the number of losing tricks for
534 the hand, or, if suits are given, the
535 number of losing tricks in those suits.
536 <p>
537 <UD>
538
539 You can, of course, create new routines with Tcl, and then call
540 them from the "main" procedure.
541
542 </DL>
543
544 There are many examples in the kit; look them over. There is also
545 a file called "library" which defines some useful procedures.
546
547 <h1>Hints</h1>
548
549 Clever use of count vectors can solve many problems efficiently.
550 For example, if you and your partner play that a weak two promises
551 2 of the top 3 <em>or</em> 3 of the top 5, you could define:
552
553 <code><blockquote>
554 defvector Weak2Quality 2 2 2 1 1
555 </blockquote></code>
556
557 This vector evaluates to 4 or greater whenever the suit has the
558 right quality, so we could check for a weak-two spade suit with:
559
560 <code><blockquote>
561 reject if {[spades north]!=6} {[Weak2Quality north spades]<4}
562 </blockquote></code>
563
564 The program doesn't do much optimization, but you can do some
565 yourself. Try not to use logical conjunctions in "require" and "accept"
566 parameters. It is better to say:
567
568 <code><blockquote>
569 accept unless {[north]<13} {[hearts north]<7}
570 </blockquote></code>
571
572 than to say:
573
574 <code><blockquote>
575 accept if {[north]>=13 && [hearts north]>=7}
576 </blockquote></code>
577
578 That's because the {[hearts north]<7} expressions doesn't get
579 evaluated if {[north]<13} evaluated as true.
580 <p>
581 It is even better to do:
582
583 <code><blockquote>
584 accept unless {[hearts north]<7} {[north]<13}
585 </blockquote></code>
586
587 Why? Because you are eliminating more hands initially. (Also,
588 the suit-length functions are faster than most since the numbers
589 are incidentally calculated at deal-time.)
590 <p>
591 Automated optimization is another area which I'm considering for
592 later versions of this program.
593
594 <h1>Who to Blame</h1>
595 Questions, comments and great thoughts are welcome. Just send me email
596 at the address at the bottom of this page.
597
598 <hr>
599 <table><tr><td><a href="http://bridge.thomasoandrews.com/" class="image">
600 <img style="border:0;width:40px;height:56px" alt="Silhouette" src="graphics/StampSm.gif"></a><td>
601 <a NAME="mysig"> Thomas Andrews</a>
602 (<a href="mailto:deal&#64;thomasoandrews.com">deal&#64;thomasoandrews.com</a>)
603 <a name="caveat"> Copyright 1996-2005.</a> Deal is covered by the
604 <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License.</a>
605 </tr></table>
606 </div>
607 </body>
608 </html>