/usr/share/doc/deal/html/quickstart.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
     "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<!-- $Id: quickstart.html 313 2009-06-11 05:44:13Z thomasoa $ -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<LINK REL="SHORTCUT ICON" HREF="/icon/bridge.ico">
<link rev="made" href="mailto:thomaso@centerline.com (Thomas Andrews)">
<link rel="stylesheet" type="text/css" href="look.css">

<title>
    Deal - An Introductory Tutorial
</title>


</head>
<body>

<div class="back"><A href="index.html">Back to <em>Deal Top Page</em></A></div>

<TABLE class="toplevel">

<TR>
<td valign="top"><img
style="border:0;width:225px;height:216px"
 SRC="graphics/falling_small.jpg" ALT="Plane Dealing image"></td>
<td valign="middle">
<div class="header">
<h1>Deal 3.1</h1>
<h2>An Introductory Tutorial</h2>
</div>
Covering: <UL>
<LI> Dealing hands
<LI> Stacking hands
<LI> Output formats
<LI> Basic scripting with Tcl
</UL>
</td>
</tr></table>

<div class="toplevel">
<hr>
<h2> Prologue </h2>
First things first, you will need to <a href="downloading.html">download
Deal and build it</a>.  The rest of this tutorial assumes you have
already done this.
<p>
<img SRC="graphics/warning.gif" ALT="**Warning**">  It takes careful eyes, at least on the version of Netscape I am
using, to distinguish between normal parentheses, <span class="code">()</span>, and curly
parentheses, <span class="code">{}</span>.  Almost all of the parentheses in the script
listings below are curly parentheses.
<p>Deal only works from the directory where you did your installation, because it looks there for files that Deal uses.
<h2> <a href="#basic">Basic Dealing - The Command Line </a></h2>
<UL>
<LI> <a href="#basicbasic">Dealing hands</a>
<LI> <a href="#basicstacking">Stacking a hand</a>
<LI> <a href="#basicformat">Formatting output</a>
</UL>
<h2> <a href="#scripting">Basic Dealing - Scripting </a></h2>
<UL>
<LI> <a href="#first">A first script</a>
<LI> <a href="#routines">A partial list of routines</a>
<LI> <a href="#second">A second script</a>
<LI> <a href="#accept">Revisiting <span class="code">accept</span> and <span class="code">reject</span></a>
</UL>

<h2><a name="basic">Basic Dealing</a></h2>

<h3><a name="basicbasic">Dealing hands</a></h3>
At your command prompt, you say, <span class="code">./deal</span>.  By default, this deals ten hands.
If you give <span class="code">deal</span> a numeric argument, it will deal that number of hands.
<pre class="codesample">
$ ./deal 2
          S : T6542
          H : A4
          D : A93
          C : KT2
 S : Q83            S : K97          
 H : 9873           H : K52          
 D : JT7            D : Q64          
 C : Q74            C : J863         
          S: AJ
          H: QJT6
          D: K852
          C: A95
---------------------------
          S : ---
          H : 975
          D : AT986
          C : T9753
 S : J7             S : AKT6         
 H : T32            H : KJ864        
 D : K32            D : J74          
 C : AJ842          C : 6            
          S: Q985432
          H: AQ
          D: Q5
          C: KQ
---------------------------
$
</pre>

<strong>Deal</strong> dealt two hands, as requested.
<p>
<h3><a name="basicstacking">Stacking a hand</a></h3>
Okay, let's take another example.  Say you opened 3H on the following
hand in a team game:
<pre class="codesample">
S: ---
H: KQJT62
D: T9876
C: 84
</pre>
You stumble into a six heart contract, when in fact, six diamonds has better
play opposite partner's hand.  Partner swears that opening 3H with this
hand loses more often than it wins.  You disagree.  How do you resolve
this?
<p>
<strong>Deal</strong> can help.  Just run it as:
<pre class="codesample">
$ ./deal -S "- KQJT62 T9876 84" 25
          S : KJ2
          H : 954
          D : A5
          C : AKT65
 S : T9764          S : AQ853        
 H : A              H : 873          
 D : J2             D : KQ43         
 C : QJ973          C : 2            
          S: ---
          H: KQJT62
          D: T9876
          C: 84
---------------------------
          S : KJT64
          H : 5
          D : K42
          C : AQ65
 S : 9875           S : AQ32         
 H : A93            H : 874          
 D : AJ5            D : Q3           
 C : KJ9            C : T732         
          S: ---
          H: KQJT62
          D: T9876
          C: 84
---------------------------
	.... (rest of 25 hands ellided) ...
</pre>
You inspect the 25 hands dealt, guessing how the auction would
proceed.  Sometimes, your answers will be inconclusive, but more
often one or both partners learns something from the simulation.
<p>
There are, of course, also <span class="code">-N</span>, <span class="code">-E</span>, and <span class="code">-W</span> options
for the other three seats.
<h3><a name="basicformat">Formatting output</a></h3>
Perhaps you'd like the hands to be written in some other format.
This can be arranged fairly easily.
<p>
For example, suppose you wish to deal 8 hands for practice bidding
with partner.  In that case, you would use the "practice" format:
<pre class="codesample">
$ ./deal -i format/practice 8 > out.all
$ cat out.east
                              east hands
============================================================================
     *1*                 *2*                 *3*                 *4*
  S 84                S T7                S QT3               S AJ9654
  H J8642             H Q65               H Q983              H K8
  D Q843              D KJ42              D 865               D J
  C 73                C T842              C AJ9               C K532

=============================================================================
     *5*                 *6*                 *7*                 *8*
  S J7                S 85                S AQT764            S 3
  H Q9864             H AK4               H K5                H JT4
  D 874               D A764              D 9                 D QJT86
  C J85               C Q862              C T976              C AK82

=============================================================================
</pre>

The <span class="code">-i</span> flag tells <strong>Deal</strong> to include the named file,
in this case, the file named <span class="code">format/practice</span>.  This file redefines
the output format.  At the end of this run, you should get five files:
<span class="code">out.north</span>, <span class="code">out.east</span>, <span class="code">out.south</span>,
<span class="code">out.west</span>, and <span class="code">out.all</span>. 
<p>
Now you can print out these files, pass them out amongst four people,
and practice your bidding, using <span class="code">out.all</span> at the end to make
a double dummy assessment of the auction results.
<p>
What if you only have two people, and you want to practice uninterrupted
auctions?  You could print out the north and south hands, and practice
with those, but that would be an artificial
test, because you obviously can't assume an uncontested auction for
arbitrary deals.
<p>
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
bidding.
<p>
What are the formats that come with the kit?  Well, you can simply list
the <span class="code">format</span> sub-directory to find out.  Here are the ones there
as of this writing:
<DL>
<DT> <span class="code">none</span>
<DD> This script set the formatting routine to a null routine.
	Not useful, so far, but useful, for example, when doing
	statistical analysis.
<DT> <span class="code">numeric</span> 
<DD> This formatter writes the deal as a line which looks something
	like:
<pre class="codesample">
3031333123220300123320212213021202022103101101003113
</pre>
	It's a line of 52 numbers, where 0, 1, 2, and 3 mean
	north, east, south, and west, respectively.
	The first digit tells where the ace of spades goes, the
	second digit tells where the king of spades goes, etc.
<DT>  <span class="code">okb</span>
<DD> This formatter writes the output with the same spacing as the old
OKbridge screen.
<DT> <span class="code">practice</span>
<DD> We've just seen this one - for seperating out hands for
practice bidding.
</DL>
There is one last output format, which, for historical reasons,
has its own command line switch, <span class="code">-l</span>.
<pre class="codesample">
$ ./deal -l 3
AJ9 976532 K92 A|86 A AT87 987653|Q732 JT8 543 T42|KT54 KQ4 QJ6 KQJ
K94 J93 QJ3 7653|A8 A8765 97 KQ98|JT2 Q AKT8654 T4|Q7653 KT42 2 AJ2
KJ753 T A4 KQ932|AQ94 AJ92 QT87 J|86 Q764 K9653 74|T2 K853 J2 AT865
$
</pre>
In the past, this was the only way to get alternate formats.  The
user would pipe this output to another program, usually a Perl script,
which would parse each line and format the output.
<p>
With the addition, in v2.0 of <strong>Deal</strong>, of user-configurable formatting,
this usage becomes obselete, but I'm leaving the feature because
it has one other use, which will be mentioned later.

<h2> <a name="scripting">Basic Dealing - Scripting </a></h2>
<h3><a name="first">Our First Script</a></h3>
Let's say we want a selection of deals in which north holds a one spade
opener.  For now, we will use a crude definition for an opening 1S call -
we will require north to have 5 or more spades and 12 or more points.
<p>
Here is the script we write (to a file we'll call <span class="code">onespade</span>):
<pre class="codesample">
main {
  if {[spades north]>=5 && [hcp north]>=12} { accept }
  reject
}
</pre>

<h4> Running the script</h4>
We run this code by saying:
<pre class="codesample">
$ ./deal -i onespade 2
          S : AKQT5
          H : A7
          D : 8542
          C : AT
 S : 64             S : J98          
 H : K943           H : 862          
 D : J              D : AK963        
 C : KQ8732         C : 54           
          S: 732
          H: QJT5
          D: QT7
          C: J96
---------------------------
          S : AQT73
          H : A
          D : AJ987
          C : 73
 S : K5             S : J42          
 H : JT8632         H : KQ95         
 D : Q63            D : KT4          
 C : 85             C : K92          
          S: 986
          H: 74
          D: 52
          C: AQJT64
---------------------------
</pre>
<h4>How the script works</h4>
By default, <strong>Deal</strong> accepts all hands.  With the <span class="code">main</span> code in
<span class="code">onespade</span>, we tell <strong>Deal</strong> to override that behavior.
<p>
This is similar to the way we used scripts to override <strong>Deal</strong>'s
default formatting.  Note, we even use the same flag, <span class="code">-i</span>,
to load our formatters and <span class="code">onespade</span>.
<p>
What does this <span class="code">main</span> code do?  It is run after every deal
is complete, and used to evaluate the hand.  In this case, we have only
two lines of code:
<pre class="codesample">
if {[spades north]>=5 && [hcp north]>=12} { accept }
reject
</pre>
The expression <span class="code">[spades north]</span> returns the number of spades
in the north hand.  The expression <span class="code">[hcp north]</span> returns
the number of HCP (high card points) in the north hand.  The "<span class="code">&&</span>"
is called a logical "and" operator, which returns true if the conditionals
on both sides of it are true.
<p>
If the entire expression:
<pre class="codesample">
[spades north]>=5 && [hcp north]>=12
</pre>
evaluates as true, the "accept" function is called.  This causes
<strong>Deal</strong> to exit the "main" code and format the hand.
<p>
If the expression evalutes as false, <strong>Deal</strong> goes to the next line
of code, which calls the "reject" function. This tells <strong>Deal</strong> to
discard the hand, and exit the "main" code.
<p>
<strong>Deal</strong> keeps trying until the requested number of deals is accepted.
<p>
What happens if a deal is not explicitly accepted or rejected?
If neither <span class="code">accept</span> nor <span class="code">reject</span> is called, the deal
is rejected.  That means that in our first script, the <span class="code">reject</span>
call was redundant, and we could have simply written the script as:
<pre class="codesample">
main {
  if {[spades north]>=5 && [hcp north]>=12} { accept }
}
</pre>
<h4> Monitoring Deal</h4>
You might want to try running this script with the <span class="code">-v</span> switch:
<pre class="codesample">
$ ./deal -v -i onespade
</pre>
The <span class="code">-v</span> flag tells <strong>Deal</strong> to give a progress report, which looks
like:

<pre class="codesample">
...
Deal 1 found after 2 tries
...
Deal 2 found after 21 tries
...
Deal 3 found after 31 tries
</pre>
This will give you some idea of how rare your condition is, and
also gives a good progress report when <strong>Deal</strong> is
writing to a file or running with a "silent" format, like
<span class="code">format/none</span>.  These status messages are written to "stderr",
which means that the output from <strong>Deal</strong> can be
redirected to a file without obscuring these messages.  <p>

<h4> Using formats with your script </h4>

If we wanted to use another output format with this script, we could do so 
on the command line, as follows:
<pre class="codesample">
$ ./deal -i format/practice -i onespade
</pre>
Or, alternately, we could add an explicit "source" command to our
script:
<pre class="codesample">
source format/practice

main {
        if {[spades north]>=5 && [hcp north]>=12} { accept }
}
</pre>

In fact, this second format unveils the secret of the <span class="code">-i</span> flag -
it is simply a request to "source" a file.  In fact, if you were to
write your own formatter, you would not have to put the file in
the "format" directory.
If you put it in the current directory, you could then say:
<pre class="codesample">
$ ./deal -i myformatter 100
</pre>
and it would work fine.  The "format" subdirectory is just a convenience.
You will often want to re-use a format, and placing them in one place
lets you find out which formats are available.

<h4> Stacking hands with a script </h4>

Let's say you were dealt the hand:
<pre class="codesample">
S: ---
H: 98532
D: A864
C: T962
</pre>
the previous day at a Swiss Teams event.
<p>
Your partner opened 1S, and, playing 2/1 Game Force, you chose to
pass.  This turns out well for you on this deal, because at the other
table, the opponents played in three spades, down 1.  Afterwards,
you wonder if you really made the right decision.  Your intuition
tells you that it was the right choice, but you realize there are
risks in both passing and bidding, and you know that intuition is
very bad at assessing levels of risk.
<p>
<strong>Deal</strong> can help.  Using our script, <span class="code">onespade</span>,
we can run the following simulation:
<pre class="codesample">
$ ./deal -S "- 96532 A864 T962" -i onespade
</pre>
The <span class="code">-S</span> flag stacks the south hand with the hand you held,
and the script runs exactly the same thereafter.  You can now peruse
the output to see whether it was a good idea or a bad idea to pass.
<p>
As with the formatting, we can also do our deck-stacking in our script.
<pre class="codesample">
south is "- 98532 A864 T962"

main {
  if {[spades north]>=5 && [hcp north]>=12} { accept }
}
</pre>

Notice, we do our deck-stacking outside of the evaluation loop.
Remember, the <span class="code">main</span> expression is responsible for evaluating the deals 
<em>after</em> <strong>Deal</strong> finishes dealing the hands.
We obviously want the stacking instruction to occur before
dealing occurs, so the stacking command must be outside the main
evaluation.
<p>
<h3><a name="routines">A partial list of routines</a></h3>
For evaluation routines, we have seen the <span class="code">hcp</span> and <span class="code">spades</span>
routines, as well as the "accept" and "reject" directives. 
Obviously, there are also routines called <span class="code">hearts</span>,
<span class="code"> diamonds</span>, and <span class="code">clubs</span> which count their respective
suits.  The following functions are also built-ins:
<dl>
<dt> <span class="code">controls</span> <dd>  This function computes the number of
controls held by a hand.
<dt> <span class="code">losers</span> <dd>  This function does a crude computation of
the losing trick count for a hand (it actually compute's half-losers,
so when [losers south] returns 14, that really means 7 losers.)
<dt> <span class="code">balanced</span> <dd> This function returns true (1) if the
hand name passed is balanced in the usual sense - no shortness, at most
one doubleton, and no five-card major.  It returns false (0) otherwise.
<dt> <span class="code">semibalanced</span> <dd>  Returns true (1) if the hand passed
has no shortness and no six-card or longer suit, and false (0) otherwise.
</dl>
The three functions, <span class="code">controls</span>, <span class="code">hcp</span>, and <span class="code">losers</span>, 
all have the property that we can compute them one suit at a time, and
sum the result for the entire hand.  The implementation takes advantage
of this and allows the user to request these values for specific suits:
<pre class="codesample">
main {
  if {[hcp south hearts spades]>10} {accept}
}
</pre>
This script accepts a deal if south has ten or more points in hearts
and spades.  <span class="code">controls</span> and <span class="code">losers</span> can be used similarly.
Any function of this sort we will call "additive." We will see later that
we can define a <a href="advanced.html#vector">wide class of interesting 
additive functions.</a>
<p>
The functions <span class="code">balanced</span> and <span class="code">semi_balanced</span> are entirely
dependent on the shape of the hand, and not on which cards the hand holds.  We
will call these "shape functions."  We will find out later how to
define <a href="advanced.html#shapefunc">incredibly fast shape functions.</a>

<h3><a name="second">A Second Script - defining Tcl procedures</a></h3>

Let's say we want to write a script which accepts a deal if north
has a strong notrump (15 to 17 range) and south has about invitational
values and a 5-card major.

<p>
Our script , which we will call <span class="code">jacobytest</span> might look something like:

<pre class="codesample">
# In deal 3.1, you don't need this next line, but deal 3.1 does - 
# without this line, the "balanced" routine is not defined.

main {
	if {![balanced north]} {reject}

	set hn [hcp north]
	if {$hn>17 || $hn&lt;15} {reject}

	set hs [hcp south]
	if {$hs&lt;8 || $hs>9} {reject}

	if {[spades south]==5 || [hearts south]==5} { accept }
}
</pre>

We have used one of our new functions here, <span class="code">balanced</span>, as
well as a new Tcl feature, variables.  We could, of course, not used
variables, but then we would have had to write the lines:
<pre class="codesample">
if {[hcp north]>17 || [hcp north]&lt;15} {reject}
</pre>
That is going to be slower, with one more function call.  Not appreciable
today, with a simple query, but when you might be processing a million or
more hands at a time, you learn to be frugal.
<p>
Suddenly, you realize you want to test this situation with a 12-14 notrump,
instead.  Or you realize you often want to reuse this concept.  You
can do so by defining Tcl procedures.
<p>
<pre class="codesample">
proc notrump {hand min max} {

  if {![balanced $hand]} {return 0}

  set hc [hcp $hand]
  if {$hc &lt; $min || $hc>$max} { return 0}

  return 1
}

proc jacobyinvite {hand ntmin ntmax} {
  if {[spades $hand]!=5 && [hearts $hand]!=5} {return 0}

  set hc [hcp $hand]
  if {$hc+$ntmin &lt;= 25 && $hc+$ntmax>=24} { return 1 }

  return 0
}

set NTmin 12
set NTmax 14

main {
  if {![notrump north $NTmin $NTmax]} { reject }
  if {[jacobyinvite south $NTmin $NTmax]} { accept }
}
</pre>
You are unlikely to need the <span class="code">jacobyinvite</span> function
beyond this script, but the <span class="code">notrump</span> function will be something
you will want
to use again and again.  You might even put it in a library of routines, called
<span class="code">mylibrary</span> and source that library every time you need one or more
of the routines for a script:
<pre class="codesample">
source mylibrary
</pre>
rather than rewriting the routine every time.
<p>
In fact, the <strong>Deal</strong> kit comes with a file called <span class="code">library
</span>, which is just such a library of routines the author of <strong>Deal
</strong> found himself re-using.
<hr>
<h3><a name="accept">Revisiting <span class="code">accept</span> and <span class="code">reject</span></a></h3>
The directives, <span class="code">accept</span> and <span class="code">reject</span>, can be used
in more complicated ways that are sometimes more efficient and
sometimes more readable.
<p>
Here  is the <span class="code">main</span> script from the <span class="code">notrump</span> example
using some odd constructs:
<pre class="codesample">
main {
  reject unless {[notrump north $NTmin $NTmax]}
  accept if {[jacobyinvite south $NTmin $NTmax]}
}
</pre>
Some people might find this more readable.  The first line says
we are going to reject the deal <em>unless</em> the condition
is true.  The second conditional says we are going to accept
the deal <em>if</em> the expression evaluates as true.
<p>
Multiple arguments are allowed. The following command:
<pre class="codesample">
reject unless {<em>expr1</em>} {<em>expr2</em>} ... {<em>exprn</em>}
</pre>
runs through all of the expressions until it finds one which evaluates
as "true".  If it does not find a true value, it rejects the hand.
Otherwise, deal goes on to the next line in evaluating <span class="code">main</span>.
<p>
For <span class="code">reject if</span> the deal is rejected if any one of the expressions
is true.  Similarly, <span class="code">accept if</span> accepts a deal if one of the
expressions is true.  For <span class="code">accept unless</span>, the deal is accepted
<em>unless</em> the one of the expressions is true.

<p>
<hr>
This concludes the <a href="#head">Introductory Tutorial</a>.  I hope
it inspires you to check out the <a href="advanced.html">Deal - Advanced
Guide</a> and to <a href="ext-ref.html#tclptrs">learn more about Tcl.</a>
Or check out the <a href="commands.html">index of all deal commands.</a>

<hr>
<table><tr><td><a href="http://bridge.thomasoandrews.com/" class="image">
<img style="border:0;width:40px;height:56px" alt="Silhouette" src="graphics/StampSm.gif"></a><td>
Thomas Andrews
(<a href="mailto:deal&#64;thomasoandrews.com">deal&#64;thomasoandrews.com</a>)
Copyright 1996-2010.  Deal is covered by the 
<a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License.</a>
<p>
<a href="graphics/falling.jpg"><em>Plane Dealing</em></a> graphic
above created using
<a href="http://www.povray.org/">POV-Ray.</a>
</tr></table>
</div>
</body></html>
deal 3.1.9-9 / usr / share / doc / deal / html / quickstart.html
