Debian Codegraph @

html/advanced.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: advanced.html 320 2010-02-16 21:17:55Z 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:[email protected] (Thomas Andrews)">
9 <link rel="stylesheet" type="text/css" href="look.css">
10
11 <title>
12 Deal - An Advanced User Guide
13 </title>
14
15
16 </head>
17
18 <body>
19 <div class="back"><a href="index.html">Back to <em>Deal Top Page</em></a></div>
20
21 <table class="toplevel">
22 <TR>
23 <td valign="middle"><img
24 style="border:0;width:225px;height:216px"
25 SRC="graphics/falling_small.jpg" ALT="Plane Dealing image"></td>
26 <td valign="middle" style="width:50%">
27 <div class="header"><h1>Deal 3.1</h1>
28 <h2>An Advanced User Guide</h2>
29 </div>
30 Covering: <UL>
31 <LI> Vector additive functions
32 <LI> Shape functions
33 <LI> Pattern functions
34 <LI> Customizable output formats
35 <LI> Statistical analysis
36 <LI> Hints for fast scripts
37 </UL>
38 </td>
39 </tr>
40 <tr><td colspan="2"><hr style="width:75%"></td></tr>
41 </table>
42
43 <div class="toplevel">
44 <h2> Prologue </h2>
45 First things first, you will need to <a href="downloading.html">download
46 Deal and build it</a>. The rest of this guide assumes you have
47 already done this.
48 <p>
49 This guide also assumes you know everything in the
50 <a href="quickstart.html">Introductory Tutorial</a>. Some sections
51 in this guide will require more <a href="ext-ref.html#tclptr">knowledge
52 of Tcl</a> than others.
53 <p>
54 <img SRC="graphics/warning.gif" ALT="**Warning**"> It takes careful
55 eyes, at least on the version of Netscape I am using, to distinguish
56 between normal parentheses, <span class="code">()</span>, and curly
57 parentheses, <span class="code">{}</span>. Almost all of the parentheses in the script
58 listings below are curly parentheses.
59 <hr>
60 <h2> Contents </h2>
61 <UL>
62 <LI><a href="#vector">Vector additive functions</a>
63 <LI><a href="#shapefunc">Shape functions</a>
64 <LI><a href="#patternfunc">Pattern functions</a>
65 <LI><a href="#formatting">Customizable output formats</a>
66 <LI><a href="#statistics">Statistical analysis</a>
67 <LI><a href="#faster">Hints for fast scripts</a>
68 </UL>
69 <h2><a name="vector">Vector additive functions</a></h2>
70
71 In the <a href="quickstart.html">Introductory Tutorial</a>, we mentioned
72 three functions which we called "additive functions." They were <span class="code">
73 hcp</span>, <span class="code">controls</span>, and <span class="code">losers</span>. We called them additive
74 because we could compute them for a single suit holding in a hand or
75 across the entire hand by summing over all the suits.
76 <p>
77 In this section, we will show how a user can create a large class
78 of fast additive functions, and show how they can be used.
79 <p>
80 The most common additive function is <span class="code">hcp</span>. How is it
81 computed? Given a suit holding, we count 4 for the ace, 3 for
82 the king, 2 for the queen, and 1 for the jack. Here is how
83 we would define this with a "vector":
84 <pre class="codesample">
85 defvector Hcp 4 3 2 1
86 </pre>
87
88 That's pretty simply. Similarly, we can define a <span class="code">Controls</span> vector:
89 <pre class="codesample">
90 defvector Controls 2 1
91 </pre>
92 <p>
93 Once these vectors are defined, we can use them as functions anywhere
94 we used <span class="code">hcp</span> and <span class="code">controls</span>.
95 <p>
96
97 Now, considering the following case: Your partner, north, opens a weak
98 two spades, and you have the agreement that partner always has a 6-card
99 suit with at least two of the top three honors. You can define a vector:
100 <pre class="codesample">
101 defvector Top3 1 1 1
102 </pre>
103 Now, to test the quality of the spade suit, you could say:
104 <pre class="codesample">
105 if {[Top3 north spades]>=2} { ... }
106 </pre>
107 Pretty simple.
108 <p>
109 So you decide to write a "weak2" procedure:
110 <pre class="codesample">
111 defvector Top3 1 1 1
112
113 proc weak2 {hand suit} {
114 if {[$suit $hand]==6 && [Top3 $hand $suit]>=2} { return 1 }
115 return 0
116 }
117 </pre>
118 You can call this by saying:
119 <pre class="codesample">
120 #...
121 main {
122 if {[weak2 north spades]} { accept }
123 }
124 </pre>
125 This will deal out hands where north has exactly six
126 spades and two of the top three spades.
127 <p>
128 This works okay (although you have forgotten to restrict the other
129 suit lengths, so you could end up with voids and side 5-card or
130 6-card suits.)
131 <p>
132 Two weeks later, you and your partner decide that you will also
133 consider a suit worth a weak 2 if it contains three of the top
134 five cards, which, specifically, really means you've now allowed
135 suits led by <span class="code">QJT</span>, <span class="code">KJT</span>, and <span class="code">AJT</span>. This is
136 not an uncommon agreement.
137 <p>
138 We could, of course, write a routine called "Top5" and check
139 both Top3 and Top5, but a little cleverness allows us to roll
140 this all up into one vector.
141 <pre class="codesample">
142 defvector weak2quality 2 2 2 1 1
143 </div>
144
145 You will see, if you think about it, that this vector evaluates
146 to 4 or more precisely when the suit has the right quality for
147 a weak two. You then rewrite the weak2 function:
148 <p>
149 <pre class="codesample">
150 defvector weak2quality 2 2 2 1 1
151
152 proc weak2 {hand suit} {
153 if {[$suit $hand]==6 && [weak2quality $hand $suit]>=4} { return 1 }
154 return 0
155 }
156 </pre>
157
158 The advantage of the vector functions is that they can be computed
159 quickly, using table lookups.
160 <p>
161 However, vectors don't compute many additive functions, like "losers"
162 and "quick tricks," or even high card points with distribution adjustments.
163 For this, you will need to use the Deal 3.1 feature,
164 <a href="holding.html">holding functions.</a> It pretty much
165 covers *all* such procedures, but still allows for a fast lookup.
166
167 <h2><a name="shapefunc">Shape functions and classes</a></h2>
168
169 In the <a href="quickstart.html">Introductory Tutorial</a>, we mentioned
170 the two functions, <span class="code">balanced</span>, and <span class="code">semi_balance</span>, and
171 called them "shape functions" because they take a hand name as an
172 argument, the return value depends only on the "shape" of the hand -
173 that is, on how many cards are in each suit.
174 <p>
175 In fact, <span class="code">balanced</span> and <span class="code">semi_balanced</span> are a special
176 sort of shape function, which we will call a "shape class." A "shape
177 class" is a shape function which returns only the values 0 and 1,
178 and therefore defines a class of shapes, namely those shapes which
179 evaluate as 1.
180 <p>
181 <strong>Deal</strong> allows for extremely fast shape class and
182 shape function computations.
183 <p>
184 <h3> A basic shape class </h3>
185 For example, lets say that we want to write a shapeclass which
186 returns 1 if our hand is right shape for a one spade opening. We would
187 do so with the following definition:
188 <pre class="codesample">
189 shapeclass spadeshape {
190 if {$s>=5 && $s>=$h && $s>=$d && $s>=$c} { return 1}
191 return 0
192 }
193 </pre>
194 This defines a routine, <span class="code">spadeshape</span>, which returns true
195 precisely when the hand has 5 or more spades and at least as
196 many spades as any other suit.
197 <p>
198 Notice, the variables <span class="code">$s</span>, <span class="code">$h</span>, <span class="code">$d</span>, and
199 <span class="code">$c</span>. Consider it this way - when you pass a hand name to
200 a shape function, it sets these variables to the suit lengths,
201 and then evaluates the code. <em> [ That is not how it works in
202 reality, because that would be too slow. ]</em>
203 <p>
204 The idiom, <span class="code">if {<em>expr</em>} {return 1} return 0
205 </span> is so common in shape classes, <strong>Deal</strong> has
206 a shorthand, <span class="code">shapecond</span>, and we could have defined <span class="code">spadeshape</span>
207 as:
208 <pre class="codesample">
209 shapecond spadeshape {$s>=5 && $s>=$h && $s>=$d && $s>=$c}
210 </pre>
211 <h3> A sample shape function </h3>
212
213 Shape functions can return any string. They can be extremely
214 powerful.
215 <p>
216 For example, we can define a function, <span class="code">opening_suit</span>:
217 <pre class="codesample">
218 shapefunc opening_suit {
219 if {$c>$s && $c>$h && $c>$d} { return clubs }
220 if {$d>$s && $d>$h && $d>$c} { return diamonds }
221 if {$s>=5 && $s>=$h} { return spades }
222 if {$h>=5} { return hearts }
223 if {$d>=5 && $d>=$c} { return diamonds }
224 if {$d>$c} { return diamonds }
225 return clubs
226 }
227 </pre>
228 This function returns the name of the suit in which you should open
229 open the hand (at least according to some people) in Standard American
230 bidding.
231
232 <p>
233 Recently, a number of people have mentioned to me Bergen's "rule of
234 20" for determining whether a hand is worth an opening bid.
235 According to the rule, add your high card points to
236 the sum of the lengths of your longest two suits. If that adds up to
237 20, open the hand. We can write this as follows:
238 <pre class="codesample">
239 shapefunc bergen::shapeval {
240 set p [lsort -integer -decreasing "$s $h $d $c"]
241 set first [lindex "$p" 0]
242 set second [lindex "$p" 1]
243 expr $first+$second
244 }
245
246 proc bergen::opening {hand} {
247 expr { [hcp $hand] + [bergen::shapeval $hand] >= 20}
248 }
249 </pre>
250 We can now use Bergen's rule in our simulations.
251 <p>
252 <h3> Calling shape functions explicitly </h3>
253
254 A shape function (or shape class) can be called with 4 numeric arguments:
255 <pre class="codesample">
256 set open3343 [openingsuit eval 3 3 4 3]
257 </pre>
258 This is most useful in defining shape classes and functions from
259 other shape classes and functions. Assume you have shape classes
260 <span class="code">spadeshape</span> and <span class="code">heartshape</span> and you want to define
261 a new shape class, <span class="code">majorshape</span>. You can do so as follows:
262 <pre class="codesample">
263 shapecond majorshape \
264 {[spadeshape eval $s $h $d $c] || [heartshape eval $s $h $d $c]}
265 </pre>
266
267 <h2><a name="patternfunc">Pattern functions and classes</a></h2>
268 <p>In <strong>Deal 3.1.8</strong>, you have access to pattern functions and
269 classes, as well as shape functions and classes.</p>
270 <p>The pattern of a hand is the lengths of the suits in the hand, sorted
271 in descending order.</p>
272 <p>You could define the pattern class, "balanced," as:
273 <pre class="codesample">
274 patterncond balanced {$l1>3 && $l2>=3 && $l3>=3 && $l4>=2}
275 </pre>
276 <p>The variables <code>l1</code>, <code>l2</code>, <code>l3</code>, and <code>l4</code> are set to the lengths of the suits, <code>l1</code> being the longest,
277 <code>l4</code> the shortest.</p> [For clarification, the first characters of each of those variables is the lowercase letter L.]
278 <p>There are similar <code>patternfunc</code> and <code>patternclass</code> functions.
279 <p>The pattern functions are implemented as shape functions. Note that this means you can call it with:
280 <pre class="codesample">
281 balanced eval 4 2 4 3
282 </pre>
283 <p>and it runs properly and returns 1 (true.)
284
285
286 <h2><a name="formatting">Customizable output formats</a></h2>
287
288 With verson 2.0 of <strong>Deal</strong>, it is finally possible to write
289 your own customizable format routines.
290 <p>
291 It is really fairly simple. When <span class="code">Deal</span> accepts a hand,
292 it calls the procedure named <span class="code">write_deal</span>. When it is finished
293 dealing the number of hands requested, it calls a procedure named
294 <span class="code">flush_deal</span>.
295 <p>
296 To change the output format, we simply redefine these procedures.
297 Tcl does not mind such redefinitions.
298 <p>
299 For example, the formatter, <span class="code">format/none</span>, is just the code:
300 <pre class="codesample">
301 proc write_deal {} {
302 # empty function
303 }
304 </pre>
305 By default, the <span class="code">flush_deal</span> procedure is already empty, so
306 we do not have to redefine it here.
307 <p>
308 Why might we need <span class="code">flush_deal</span> at all? Some formatters
309 only write to output periodically. For example, <span class="code">format/practice</span>
310 writes files <span class="code">out.north</span>, <span class="code">out.east</span>, <span class="code">out.south</span>,
311 and <span class="code">out.west</span>. The output in <span class="code">out.north</span> looks like:
312 <pre class="codesample">
313 north hands
314 ============================================================================
315 *1* *2* *3* *4*
316 S 84 S T7 S QT3 S AJ9654
317 H J8642 H Q65 H Q983 H K8
318 D Q843 D KJ42 D 865 D J
319 C 73 C T842 C AJ9 C K532
320
321 =============================================================================
322 </pre>
323 Clearly, therefore, <span class="code">write_deal</span> is buffering output
324 internally and only printing every fourth hand. What happens when
325 the user requests 10 deals? <span class="code">write_deal</span> will be called
326 on the tenth deal, but because the deal number is not a multiple
327 of four, <span class="code">write_deal</span> will not know to print the output.
328 The last two hands will be lost.
329 <p>
330 The solution is to make <strong>Deal</strong> call <span class="code">flush_deal</span>
331 on completion of dealing.
332 <h3> A most basic formatter - printing one hand </h3>
333
334 Here is a new formatter, which we will place in a file call <span class="code">NorthFmt</span>.
335 <pre class="codesample">
336 proc write_deal {} {
337 puts "S: [north -void --- spades]"
338 puts "H: [north -void --- hearts]"
339 puts "D: [north -void --- diamonds]"
340 puts "C: [north -void --- clubs]"
341 puts "============================="
342 }
343 </pre>
344 Okay, what does this expression,
345 <span class="code">[north&nbsp;-void&nbsp;---&nbsp;spades]</span>, do?
346 The expression <span class="code">[north&nbsp;spades]</span> returns the spade holding
347 of the north hand in a simple string form. If the suit is void,
348 it returns the empty string. The "<span class="code">-void ---</span>" in the
349 example above tells the formatter to use the string "<span class="code">---</span>" for
350 voids.
351 <p>
352 We could do this a little more easily:
353
354 <pre class="codesample">
355 proc write_deal {} {
356 foreach char {S H D C} suit {spades hearts diamonds clubs} {
357 puts "$char: [north -void --- $suit]"
358 }
359 puts "============================="
360 }
361 </pre>
362 This uses the interesting feature of the Tcl <span class="code">foreach</span>
363 which lets two variables move through two lists.
364 <p>
365
366 The <span class="code">north</span> routine, without arguments, returns all four suits, in
367 a Tcl list format. Here is a simple formatter for the north and south
368 hands:
369 <pre class="codesample">
370 proc write_deal {} {
371 puts "{[north]} {[south]}"
372 }
373 </pre>
374 Yielding ugly output like:
375 <pre class="codesample">
376 {{J9654} {KQT832} {} {42}} {{7} {A74} {T763} {J9865}}
377 {{KT852} {Q} {KT83} {A83}} {{96} {AK7543} {Q96} {52}}
378 </pre>
379 Not pretty, but useful if piping to another Tcl program, because
380 Tcl programs will find this fairly easy to parse.
381 <p>
382 <h3><a name="stringbox">String boxes</a></h3>
383 For more complicated formats, I have added to Tcl an invention
384 of my own for string "drawings." Tcl does not have any
385 decent formatting routines, other than the <span class="code">format</span>
386 command, which is based on the <span class="code">printf</span> class of functions
387 in C. I've always found <span class="code">printf</span> a pain, even back in Fortran.
388 <p>
389 So I invented "string boxes." A string box is a like a drawable
390 canvas, but for characters rather than pixels. For example, here
391 is a slightly simpler version of the file <span class="code">format/okb</span>:
392 <pre class="codesample">
393 stringbox okbox 14 70
394 okbox write 4 15 "West"
395 okbox write 4 50 "East"
396 okbox write 0 30 "North"
397 okbox write 10 30 "South"
398 ...
399 </pre>
400 This code creates a string box named <span class="code">okbox</span> with 14 rows of
401 70 columns of text (initially all blank), and then writes
402 the words "West", "East", "North", and "South" in different locations
403 in that box.
404 <p>
405 Next we define the sub-boxes, one for each hand:
406 <pre class="codesample">
407 ...
408 okbox subbox okbox.north 0 36 4 15
409 okbox subbox okbox.south 10 36 4 15
410 okbox subbox okbox.east 5 50 4 15
411 okbox subbox okbox.west 5 15 4 15
412 ...
413 </pre>
414
415 A "subbox" is created from a parent box, and has both a row and column
416 location, and a row and column width. In the above instance, all of
417 our sub-boxes are 4 rows and 15 columns, and placed in the location
418 where the hands will eventually be printed.
419 <p>
420 Our <span class="code">write_deal</span> procedure would look like:
421 <pre class="codesample">
422 proc write_deal {} {
423 foreach hand {west south north east} {
424 okputhand $hand
425 }
426
427 puts "[okbox]"
428 puts " -----------------------------"
429 }
430
431 proc okputhand {hand} {
432
433 okbox.$hand clear
434
435 set rowhand 0
436 foreach char {S H D C} suit {spades hearts diamonds clubs} {
437 okbox.$hand write $rowhand 0 "$char [$hand -void --- $suit]"
438 incr rowhand
439 }
440 }
441 </pre>
442
443 <span class="code">write_deal</span> just calls the routine <span class="code">okputhand</span> for each
444 hand, then writes out the contents of the entire string box, <span class="code">okbox</span>,
445 followed by the seperator string of hyphens. Note that we convert
446 a string box to a normal string just by using its name alone, without
447 arguments, as in <span class="code">[okbox]</span>. We can also convert a string with trailing
448 whitespace removed from lines, by saying <span class="code">[okbox compact]</span>.
449 In fact, we probably should have used the <span class="code">compact</span> modifier,
450 since there is so much trailing white space in this format.
451 <p>
452 The <span class="code">okputhand</span> procedure first clears the sub-box associated
453 that hand, then writes out the contents of the hand one suit at a time
454 to that same sub-box.
455 <p>
456 The output looks like:
457 <pre class="codesample">
458 North S KT6
459 H J97
460 D T8543
461 C T5
462 West East
463 S J75 S Q983
464 H T86 H A52
465 D AKJ7 D Q9
466 C AQ8 C KJ64
467
468 South S A42
469 H KQ43
470 D 62
471 C 9732
472 -----------------------------
473 </pre>
474
475 I have yet to put together complete documentation for string boxes,
476 but I intend to do so. They have some remarkable features, and perhaps
477 some surprises for the unwary.
478 <h2><a name="statistics">Statistical analysis</a></h2>
479
480 <a href="statistics.html">Go here.</a>
481
482 <h2><a name="faster">Hints for fast scripts</a></h2>
483
484 Documentation not yet written.
485 <hr>
486 <table><tr><td><a href="http://bridge.thomasoandrews.com/" class="image">
487 <img style="border:0;width:40px;height:56px" alt="Silhouette" src="graphics/StampSm.gif"></a><td>
488 Thomas Andrews
489 (<a href="mailto:deal&#64;thomasoandrews.com">deal&#64;thomasoandrews.com</a>)
490 Copyright 1996-2010. Deal is covered by the
491 <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License.</a>
492 <p>
493 <a href="graphics/falling.jpg"><em>Plane Dealing</em></a> graphic
494 above created using
495 <a href="http://www.povray.org/">POV-Ray.</a>
496 </tr></table>
497 </div>