Debian Codegraph @

html/quickstart.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: quickstart.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:[email protected] (Thomas Andrews)">
9 <link rel="stylesheet" type="text/css" href="look.css">
10
11 <title>
12 Deal - An Introductory Tutorial
13 </title>
14
15
16 </head>
17 <body>
18
19 <div class="back"><A href="index.html">Back to <em>Deal Top Page</em></A></div>
20
21 <TABLE class="toplevel">
22
23 <TR>
24 <td valign="top"><img
25 style="border:0;width:225px;height:216px"
26 SRC="graphics/falling_small.jpg" ALT="Plane Dealing image"></td>
27 <td valign="middle">
28 <div class="header">
29 <h1>Deal 3.1</h1>
30 <h2>An Introductory Tutorial</h2>
31 </div>
32 Covering: <UL>
33 <LI> Dealing hands
34 <LI> Stacking hands
35 <LI> Output formats
36 <LI> Basic scripting with Tcl
37 </UL>
38 </td>
39 </tr></table>
40
41 <div class="toplevel">
42 <hr>
43 <h2> Prologue </h2>
44 First things first, you will need to <a href="downloading.html">download
45 Deal and build it</a>. The rest of this tutorial assumes you have
46 already done this.
47 <p>
48 <img SRC="graphics/warning.gif" ALT="**Warning**"> It takes careful eyes, at least on the version of Netscape I am
49 using, to distinguish between normal parentheses, <span class="code">()</span>, and curly
50 parentheses, <span class="code">{}</span>. Almost all of the parentheses in the script
51 listings below are curly parentheses.
52 <p>Deal only works from the directory where you did your installation, because it looks there for files that Deal uses.
53 <h2> <a href="#basic">Basic Dealing - The Command Line </a></h2>
54 <UL>
55 <LI> <a href="#basicbasic">Dealing hands</a>
56 <LI> <a href="#basicstacking">Stacking a hand</a>
57 <LI> <a href="#basicformat">Formatting output</a>
58 </UL>
59 <h2> <a href="#scripting">Basic Dealing - Scripting </a></h2>
60 <UL>
61 <LI> <a href="#first">A first script</a>
62 <LI> <a href="#routines">A partial list of routines</a>
63 <LI> <a href="#second">A second script</a>
64 <LI> <a href="#accept">Revisiting <span class="code">accept</span> and <span class="code">reject</span></a>
65 </UL>
66
67 <h2><a name="basic">Basic Dealing</a></h2>
68
69 <h3><a name="basicbasic">Dealing hands</a></h3>
70 At your command prompt, you say, <span class="code">./deal</span>. By default, this deals ten hands.
71 If you give <span class="code">deal</span> a numeric argument, it will deal that number of hands.
72 <pre class="codesample">
73 $ ./deal 2
74 S : T6542
75 H : A4
76 D : A93
77 C : KT2
78 S : Q83 S : K97
79 H : 9873 H : K52
80 D : JT7 D : Q64
81 C : Q74 C : J863
82 S: AJ
83 H: QJT6
84 D: K852
85 C: A95
86 ---------------------------
87 S : ---
88 H : 975
89 D : AT986
90 C : T9753
91 S : J7 S : AKT6
92 H : T32 H : KJ864
93 D : K32 D : J74
94 C : AJ842 C : 6
95 S: Q985432
96 H: AQ
97 D: Q5
98 C: KQ
99 ---------------------------
100 $
101 </pre>
102
103 <strong>Deal</strong> dealt two hands, as requested.
104 <p>
105 <h3><a name="basicstacking">Stacking a hand</a></h3>
106 Okay, let's take another example. Say you opened 3H on the following
107 hand in a team game:
108 <pre class="codesample">
109 S: ---
110 H: KQJT62
111 D: T9876
112 C: 84
113 </pre>
114 You stumble into a six heart contract, when in fact, six diamonds has better
115 play opposite partner's hand. Partner swears that opening 3H with this
116 hand loses more often than it wins. You disagree. How do you resolve
117 this?
118 <p>
119 <strong>Deal</strong> can help. Just run it as:
120 <pre class="codesample">
121 $ ./deal -S "- KQJT62 T9876 84" 25
122 S : KJ2
123 H : 954
124 D : A5
125 C : AKT65
126 S : T9764 S : AQ853
127 H : A H : 873
128 D : J2 D : KQ43
129 C : QJ973 C : 2
130 S: ---
131 H: KQJT62
132 D: T9876
133 C: 84
134 ---------------------------
135 S : KJT64
136 H : 5
137 D : K42
138 C : AQ65
139 S : 9875 S : AQ32
140 H : A93 H : 874
141 D : AJ5 D : Q3
142 C : KJ9 C : T732
143 S: ---
144 H: KQJT62
145 D: T9876
146 C: 84
147 ---------------------------
148 .... (rest of 25 hands ellided) ...
149 </pre>
150 You inspect the 25 hands dealt, guessing how the auction would
151 proceed. Sometimes, your answers will be inconclusive, but more
152 often one or both partners learns something from the simulation.
153 <p>
154 There are, of course, also <span class="code">-N</span>, <span class="code">-E</span>, and <span class="code">-W</span> options
155 for the other three seats.
156 <h3><a name="basicformat">Formatting output</a></h3>
157 Perhaps you'd like the hands to be written in some other format.
158 This can be arranged fairly easily.
159 <p>
160 For example, suppose you wish to deal 8 hands for practice bidding
161 with partner. In that case, you would use the "practice" format:
162 <pre class="codesample">
163 $ ./deal -i format/practice 8 > out.all
164 $ cat out.east
165 east hands
166 ============================================================================
167 *1* *2* *3* *4*
168 S 84 S T7 S QT3 S AJ9654
169 H J8642 H Q65 H Q983 H K8
170 D Q843 D KJ42 D 865 D J
171 C 73 C T842 C AJ9 C K532
172
173 =============================================================================
174 *5* *6* *7* *8*
175 S J7 S 85 S AQT764 S 3
176 H Q9864 H AK4 H K5 H JT4
177 D 874 D A764 D 9 D QJT86
178 C J85 C Q862 C T976 C AK82
179
180 =============================================================================
181 </pre>
182
183 The <span class="code">-i</span> flag tells <strong>Deal</strong> to include the named file,
184 in this case, the file named <span class="code">format/practice</span>. This file redefines
185 the output format. At the end of this run, you should get five files:
186 <span class="code">out.north</span>, <span class="code">out.east</span>, <span class="code">out.south</span>,
187 <span class="code">out.west</span>, and <span class="code">out.all</span>.
188 <p>
189 Now you can print out these files, pass them out amongst four people,
190 and practice your bidding, using <span class="code">out.all</span> at the end to make
191 a double dummy assessment of the auction results.
192 <p>
193 What if you only have two people, and you want to practice uninterrupted
194 auctions? You could print out the north and south hands, and practice
195 with those, but that would be an artificial
196 test, because you obviously can't assume an uncontested auction for
197 arbitrary deals.
198 <p>
199 When we learn about writing scripts for <strong>Deal</strong>, we will solve with this problem by filtering out hands we think would lead to competitive
200 bidding.
201 <p>
202 What are the formats that come with the kit? Well, you can simply list
203 the <span class="code">format</span> sub-directory to find out. Here are the ones there
204 as of this writing:
205 <DL>
206 <DT> <span class="code">none</span>
207 <DD> This script set the formatting routine to a null routine.
208 Not useful, so far, but useful, for example, when doing
209 statistical analysis.
210 <DT> <span class="code">numeric</span>
211 <DD> This formatter writes the deal as a line which looks something
212 like:
213 <pre class="codesample">
214 3031333123220300123320212213021202022103101101003113
215 </pre>
216 It's a line of 52 numbers, where 0, 1, 2, and 3 mean
217 north, east, south, and west, respectively.
218 The first digit tells where the ace of spades goes, the
219 second digit tells where the king of spades goes, etc.
220 <DT> <span class="code">okb</span>
221 <DD> This formatter writes the output with the same spacing as the old
222 OKbridge screen.
223 <DT> <span class="code">practice</span>
224 <DD> We've just seen this one - for seperating out hands for
225 practice bidding.
226 </DL>
227 There is one last output format, which, for historical reasons,
228 has its own command line switch, <span class="code">-l</span>.
229 <pre class="codesample">
230 $ ./deal -l 3
231 AJ9 976532 K92 A|86 A AT87 987653|Q732 JT8 543 T42|KT54 KQ4 QJ6 KQJ
232 K94 J93 QJ3 7653|A8 A8765 97 KQ98|JT2 Q AKT8654 T4|Q7653 KT42 2 AJ2
233 KJ753 T A4 KQ932|AQ94 AJ92 QT87 J|86 Q764 K9653 74|T2 K853 J2 AT865
234 $
235 </pre>
236 In the past, this was the only way to get alternate formats. The
237 user would pipe this output to another program, usually a Perl script,
238 which would parse each line and format the output.
239 <p>
240 With the addition, in v2.0 of <strong>Deal</strong>, of user-configurable formatting,
241 this usage becomes obselete, but I'm leaving the feature because
242 it has one other use, which will be mentioned later.
243
244 <h2> <a name="scripting">Basic Dealing - Scripting </a></h2>
245 <h3><a name="first">Our First Script</a></h3>
246 Let's say we want a selection of deals in which north holds a one spade
247 opener. For now, we will use a crude definition for an opening 1S call -
248 we will require north to have 5 or more spades and 12 or more points.
249 <p>
250 Here is the script we write (to a file we'll call <span class="code">onespade</span>):
251 <pre class="codesample">
252 main {
253 if {[spades north]>=5 && [hcp north]>=12} { accept }
254 reject
255 }
256 </pre>
257
258 <h4> Running the script</h4>
259 We run this code by saying:
260 <pre class="codesample">
261 $ ./deal -i onespade 2
262 S : AKQT5
263 H : A7
264 D : 8542
265 C : AT
266 S : 64 S : J98
267 H : K943 H : 862
268 D : J D : AK963
269 C : KQ8732 C : 54
270 S: 732
271 H: QJT5
272 D: QT7
273 C: J96
274 ---------------------------
275 S : AQT73
276 H : A
277 D : AJ987
278 C : 73
279 S : K5 S : J42
280 H : JT8632 H : KQ95
281 D : Q63 D : KT4
282 C : 85 C : K92
283 S: 986
284 H: 74
285 D: 52
286 C: AQJT64
287 ---------------------------
288 </pre>
289 <h4>How the script works</h4>
290 By default, <strong>Deal</strong> accepts all hands. With the <span class="code">main</span> code in
291 <span class="code">onespade</span>, we tell <strong>Deal</strong> to override that behavior.
292 <p>
293 This is similar to the way we used scripts to override <strong>Deal</strong>'s
294 default formatting. Note, we even use the same flag, <span class="code">-i</span>,
295 to load our formatters and <span class="code">onespade</span>.
296 <p>
297 What does this <span class="code">main</span> code do? It is run after every deal
298 is complete, and used to evaluate the hand. In this case, we have only
299 two lines of code:
300 <pre class="codesample">
301 if {[spades north]>=5 && [hcp north]>=12} { accept }
302 reject
303 </pre>
304 The expression <span class="code">[spades north]</span> returns the number of spades
305 in the north hand. The expression <span class="code">[hcp north]</span> returns
306 the number of HCP (high card points) in the north hand. The "<span class="code">&&</span>"
307 is called a logical "and" operator, which returns true if the conditionals
308 on both sides of it are true.
309 <p>
310 If the entire expression:
311 <pre class="codesample">
312 [spades north]>=5 && [hcp north]>=12
313 </pre>
314 evaluates as true, the "accept" function is called. This causes
315 <strong>Deal</strong> to exit the "main" code and format the hand.
316 <p>
317 If the expression evalutes as false, <strong>Deal</strong> goes to the next line
318 of code, which calls the "reject" function. This tells <strong>Deal</strong> to
319 discard the hand, and exit the "main" code.
320 <p>
321 <strong>Deal</strong> keeps trying until the requested number of deals is accepted.
322 <p>
323 What happens if a deal is not explicitly accepted or rejected?
324 If neither <span class="code">accept</span> nor <span class="code">reject</span> is called, the deal
325 is rejected. That means that in our first script, the <span class="code">reject</span>
326 call was redundant, and we could have simply written the script as:
327 <pre class="codesample">
328 main {
329 if {[spades north]>=5 && [hcp north]>=12} { accept }
330 }
331 </pre>
332 <h4> Monitoring Deal</h4>
333 You might want to try running this script with the <span class="code">-v</span> switch:
334 <pre class="codesample">
335 $ ./deal -v -i onespade
336 </pre>
337 The <span class="code">-v</span> flag tells <strong>Deal</strong> to give a progress report, which looks
338 like:
339
340 <pre class="codesample">
341 ...
342 Deal 1 found after 2 tries
343 ...
344 Deal 2 found after 21 tries
345 ...
346 Deal 3 found after 31 tries
347 </pre>
348 This will give you some idea of how rare your condition is, and
349 also gives a good progress report when <strong>Deal</strong> is
350 writing to a file or running with a "silent" format, like
351 <span class="code">format/none</span>. These status messages are written to "stderr",
352 which means that the output from <strong>Deal</strong> can be
353 redirected to a file without obscuring these messages. <p>
354
355 <h4> Using formats with your script </h4>
356
357 If we wanted to use another output format with this script, we could do so
358 on the command line, as follows:
359 <pre class="codesample">
360 $ ./deal -i format/practice -i onespade
361 </pre>
362 Or, alternately, we could add an explicit "source" command to our
363 script:
364 <pre class="codesample">
365 source format/practice
366
367 main {
368 if {[spades north]>=5 && [hcp north]>=12} { accept }
369 }
370 </pre>
371
372 In fact, this second format unveils the secret of the <span class="code">-i</span> flag -
373 it is simply a request to "source" a file. In fact, if you were to
374 write your own formatter, you would not have to put the file in
375 the "format" directory.
376 If you put it in the current directory, you could then say:
377 <pre class="codesample">
378 $ ./deal -i myformatter 100
379 </pre>
380 and it would work fine. The "format" subdirectory is just a convenience.
381 You will often want to re-use a format, and placing them in one place
382 lets you find out which formats are available.
383
384 <h4> Stacking hands with a script </h4>
385
386 Let's say you were dealt the hand:
387 <pre class="codesample">
388 S: ---
389 H: 98532
390 D: A864
391 C: T962
392 </pre>
393 the previous day at a Swiss Teams event.
394 <p>
395 Your partner opened 1S, and, playing 2/1 Game Force, you chose to
396 pass. This turns out well for you on this deal, because at the other
397 table, the opponents played in three spades, down 1. Afterwards,
398 you wonder if you really made the right decision. Your intuition
399 tells you that it was the right choice, but you realize there are
400 risks in both passing and bidding, and you know that intuition is
401 very bad at assessing levels of risk.
402 <p>
403 <strong>Deal</strong> can help. Using our script, <span class="code">onespade</span>,
404 we can run the following simulation:
405 <pre class="codesample">
406 $ ./deal -S "- 96532 A864 T962" -i onespade
407 </pre>
408 The <span class="code">-S</span> flag stacks the south hand with the hand you held,
409 and the script runs exactly the same thereafter. You can now peruse
410 the output to see whether it was a good idea or a bad idea to pass.
411 <p>
412 As with the formatting, we can also do our deck-stacking in our script.
413 <pre class="codesample">
414 south is "- 98532 A864 T962"
415
416 main {
417 if {[spades north]>=5 && [hcp north]>=12} { accept }
418 }
419 </pre>
420
421 Notice, we do our deck-stacking outside of the evaluation loop.
422 Remember, the <span class="code">main</span> expression is responsible for evaluating the deals
423 <em>after</em> <strong>Deal</strong> finishes dealing the hands.
424 We obviously want the stacking instruction to occur before
425 dealing occurs, so the stacking command must be outside the main
426 evaluation.
427 <p>
428 <h3><a name="routines">A partial list of routines</a></h3>
429 For evaluation routines, we have seen the <span class="code">hcp</span> and <span class="code">spades</span>
430 routines, as well as the "accept" and "reject" directives.
431 Obviously, there are also routines called <span class="code">hearts</span>,
432 <span class="code"> diamonds</span>, and <span class="code">clubs</span> which count their respective
433 suits. The following functions are also built-ins:
434 <dl>
435 <dt> <span class="code">controls</span> <dd> This function computes the number of
436 controls held by a hand.
437 <dt> <span class="code">losers</span> <dd> This function does a crude computation of
438 the losing trick count for a hand (it actually compute's half-losers,
439 so when [losers south] returns 14, that really means 7 losers.)
440 <dt> <span class="code">balanced</span> <dd> This function returns true (1) if the
441 hand name passed is balanced in the usual sense - no shortness, at most
442 one doubleton, and no five-card major. It returns false (0) otherwise.
443 <dt> <span class="code">semibalanced</span> <dd> Returns true (1) if the hand passed
444 has no shortness and no six-card or longer suit, and false (0) otherwise.
445 </dl>
446 The three functions, <span class="code">controls</span>, <span class="code">hcp</span>, and <span class="code">losers</span>,
447 all have the property that we can compute them one suit at a time, and
448 sum the result for the entire hand. The implementation takes advantage
449 of this and allows the user to request these values for specific suits:
450 <pre class="codesample">
451 main {
452 if {[hcp south hearts spades]>10} {accept}
453 }
454 </pre>
455 This script accepts a deal if south has ten or more points in hearts
456 and spades. <span class="code">controls</span> and <span class="code">losers</span> can be used similarly.
457 Any function of this sort we will call "additive." We will see later that
458 we can define a <a href="advanced.html#vector">wide class of interesting
459 additive functions.</a>
460 <p>
461 The functions <span class="code">balanced</span> and <span class="code">semi_balanced</span> are entirely
462 dependent on the shape of the hand, and not on which cards the hand holds. We
463 will call these "shape functions." We will find out later how to
464 define <a href="advanced.html#shapefunc">incredibly fast shape functions.</a>
465
466 <h3><a name="second">A Second Script - defining Tcl procedures</a></h3>
467
468 Let's say we want to write a script which accepts a deal if north
469 has a strong notrump (15 to 17 range) and south has about invitational
470 values and a 5-card major.
471
472 <p>
473 Our script , which we will call <span class="code">jacobytest</span> might look something like:
474
475 <pre class="codesample">
476 # In deal 3.1, you don't need this next line, but deal 3.1 does -
477 # without this line, the "balanced" routine is not defined.
478
479 main {
480 if {![balanced north]} {reject}
481
482 set hn [hcp north]
483 if {$hn>17 || $hn&lt;15} {reject}
484
485 set hs [hcp south]
486 if {$hs&lt;8 || $hs>9} {reject}
487
488 if {[spades south]==5 || [hearts south]==5} { accept }
489 }
490 </pre>
491
492 We have used one of our new functions here, <span class="code">balanced</span>, as
493 well as a new Tcl feature, variables. We could, of course, not used
494 variables, but then we would have had to write the lines:
495 <pre class="codesample">
496 if {[hcp north]>17 || [hcp north]&lt;15} {reject}
497 </pre>
498 That is going to be slower, with one more function call. Not appreciable
499 today, with a simple query, but when you might be processing a million or
500 more hands at a time, you learn to be frugal.
501 <p>
502 Suddenly, you realize you want to test this situation with a 12-14 notrump,
503 instead. Or you realize you often want to reuse this concept. You
504 can do so by defining Tcl procedures.
505 <p>
506 <pre class="codesample">
507 proc notrump {hand min max} {
508
509 if {![balanced $hand]} {return 0}
510
511 set hc [hcp $hand]
512 if {$hc &lt; $min || $hc>$max} { return 0}
513
514 return 1
515 }
516
517 proc jacobyinvite {hand ntmin ntmax} {
518 if {[spades $hand]!=5 && [hearts $hand]!=5} {return 0}
519
520 set hc [hcp $hand]
521 if {$hc+$ntmin &lt;= 25 && $hc+$ntmax>=24} { return 1 }
522
523 return 0
524 }
525
526 set NTmin 12
527 set NTmax 14
528
529 main {
530 if {![notrump north $NTmin $NTmax]} { reject }
531 if {[jacobyinvite south $NTmin $NTmax]} { accept }
532 }
533 </pre>
534 You are unlikely to need the <span class="code">jacobyinvite</span> function
535 beyond this script, but the <span class="code">notrump</span> function will be something
536 you will want
537 to use again and again. You might even put it in a library of routines, called
538 <span class="code">mylibrary</span> and source that library every time you need one or more
539 of the routines for a script:
540 <pre class="codesample">
541 source mylibrary
542 </pre>
543 rather than rewriting the routine every time.
544 <p>
545 In fact, the <strong>Deal</strong> kit comes with a file called <span class="code">library
546 </span>, which is just such a library of routines the author of <strong>Deal
547 </strong> found himself re-using.
548 <hr>
549 <h3><a name="accept">Revisiting <span class="code">accept</span> and <span class="code">reject</span></a></h3>
550 The directives, <span class="code">accept</span> and <span class="code">reject</span>, can be used
551 in more complicated ways that are sometimes more efficient and
552 sometimes more readable.
553 <p>
554 Here is the <span class="code">main</span> script from the <span class="code">notrump</span> example
555 using some odd constructs:
556 <pre class="codesample">
557 main {
558 reject unless {[notrump north $NTmin $NTmax]}
559 accept if {[jacobyinvite south $NTmin $NTmax]}
560 }
561 </pre>
562 Some people might find this more readable. The first line says
563 we are going to reject the deal <em>unless</em> the condition
564 is true. The second conditional says we are going to accept
565 the deal <em>if</em> the expression evaluates as true.
566 <p>
567 Multiple arguments are allowed. The following command:
568 <pre class="codesample">
569 reject unless {<em>expr1</em>} {<em>expr2</em>} ... {<em>exprn</em>}
570 </pre>
571 runs through all of the expressions until it finds one which evaluates
572 as "true". If it does not find a true value, it rejects the hand.
573 Otherwise, deal goes on to the next line in evaluating <span class="code">main</span>.
574 <p>
575 For <span class="code">reject if</span> the deal is rejected if any one of the expressions
576 is true. Similarly, <span class="code">accept if</span> accepts a deal if one of the
577 expressions is true. For <span class="code">accept unless</span>, the deal is accepted
578 <em>unless</em> the one of the expressions is true.
579
580 <p>
581 <hr>
582 This concludes the <a href="#head">Introductory Tutorial</a>. I hope
583 it inspires you to check out the <a href="advanced.html">Deal - Advanced
584 Guide</a> and to <a href="ext-ref.html#tclptrs">learn more about Tcl.</a>
585 Or check out the <a href="commands.html">index of all deal commands.</a>
586
587 <hr>
588 <table><tr><td><a href="http://bridge.thomasoandrews.com/" class="image">
589 <img style="border:0;width:40px;height:56px" alt="Silhouette" src="graphics/StampSm.gif"></a><td>
590 Thomas Andrews
591 (<a href="mailto:deal&#64;thomasoandrews.com">deal&#64;thomasoandrews.com</a>)
592 Copyright 1996-2010. Deal is covered by the
593 <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License.</a>
594 <p>
595 <a href="graphics/falling.jpg"><em>Plane Dealing</em></a> graphic
596 above created using
597 <a href="http://www.povray.org/">POV-Ray.</a>
598 </tr></table>
599 </div>
600 </body></html>