Deal - An Introductory Tutorial

Prologue

First things first, you will need to download Deal and build it. The rest of this tutorial assumes you have already done this.

**Warning** It takes careful eyes, at least on the version of Netscape I am using, to distinguish between normal parentheses, (), and curly parentheses, {}. Almost all of the paretheses in the script listings below are curly parentheses.

Basic Dealing - Scripting

A first script
A partial list of routines
A second script
Revisiting accept and reject

Basic Dealing

Dealing hands

At your command or DOS prompt, you say, deal. By default, this deals ten hands. If you give deal a numeric argument, it will deal that number of hands you specify.

$ 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
---------------------------
$

Deal dealt two hands, as requested.

Stacking a hand

Okay, let's take another example. Say you opened 3H on the following hand in a team game:

S: ---
H: KQJT62
D: T9876
C: 84

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?

Deal can help. Just run it as:

$ 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) ...

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.

There are, of course, also -N, -E, and -W options for the other three seats.

Formatting output

Perhaps you'd like the hands to be written in some other format. This can be arranged fairly easily.

For example, suppose you wish to deal 8 hands for practice bidding with partner. In that case, you would use the "practice" format:

$ 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

=============================================================================

The -i flag tells Deal to include the named file, in this case, the file named format/practice. This file redefines the output format. At the end of this run, you should get five files: out.north, out.east, out.south, out.west, and out.all.

Now you can print out these files, pass them out amongst four people, and practice your bidding, using out.all at the end to make a double dummy assessment of the auction results.

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.

When we learn about writing scripts for Deal, we will solve with this problem by filtering out hands we think would lead to competitive bidding.

What are the formats that come with the kit? Well, you can simply list the format sub-directory to find out. Here are the ones there as of this writing:

none

This script set the formatting routine to a null routine. Not useful, so far, but useful, for example, when doing statistical analysis.

numeric

This formatter writes the deal as a line which looks something like:

3031333123220300123320212213021202022103101101003113

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.

okb

This formatter writes the output with the same spacing as the old OKbridge screen.

practice

We've just seen this one - for seperating out hands for practice bidding.

There is one last output format, which, for historical reasons, has its own command line switch, -l.

$ 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
$

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.

With the addition, in v2.0 of Deal, 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.

Basic Dealing - Scripting

Our First Script

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.

Here is the script we write (to a file we'll call onespade):

main {
  if {[spades north]>=5 && [hcp north]>=12} { accept }
  reject
}

Running the script

We run this code by saying:

$ 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
---------------------------

How the script works

By default, Deal accepts all hands. With the main code in onespade, we tell Deal to override that behavior.

This is similar to the way we used scripts to override Deal's default formatting. Note, we even use the same flag, -i, to load our formatters and onespade.

What does this main 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:

if {[spades north]>=5 && [hcp north]>=12} { accept }
reject

The expression [spades north] returns the number of spades in the north hand. The expression [hcp north] returns the number of HCP (high card points) in the north hand. The "&&" is called a logical "and" operator, which returns true if the conditionals on both sides of it are true.

If the entire expression:

[spades north]>=5 && [hcp north]>=12

evaluates as true, the "accept" function is called. This causes Deal to exit the "main" code and format the hand.

If the expression evalutes as false, Deal goes to the next line of code, which calls the "reject" function. This tells Deal to discard the hand, and exit the "main" code.

Deal keeps trying until the requested number of deals is accepted.

What happens if a deal is not explicitly accepted or rejected? If neither accept nor reject is called, the deal is rejected. That means that in our first script, the reject call was redundant, and we could have simply written the script as:

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

Monitoring Deal

You might want to try running this script with the -v switch:

$ deal -v -i onespade

The -v flag tells Deal to give a progress report, which looks like:

...
Deal 1 found after 2 tries
...
Deal 2 found after 21 tries
...
Deal 3 found after 31 tries

This will give you some idea of how rare your condition is, and also gives a good progress report when Deal is writing to a file or running with a "silent" format, like format/none. These status messages are written to "stderr", which means that the output from Deal can be redirected to a file without obscuring these messages.

Using formats with your script

If we wanted to use another output format with this script, we could do so on the command line, as follows:

$ deal -i format/practice -i onespade

Or, alternately, we could add an explicit "source" command to our script:

source format/practice

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

In fact, this second format unveils the secret of the -i 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:

$ deal -i myformatter 100

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.

Stacking hands with a script

Let's say you were dealt the hand:

S: ---
H: 98532
D: A864
C: T962

the previous day at a Swiss Teams event.

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.

Deal can help. Using our script, onespade, we can run the following simulation:

$ deal -S "- 96532 A864 T962" -i onespade

The -S 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.

As with the formatting, we can also do our deck-stacking in our script.

south is "- 98532 A864 T962"

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

Notice, we do our deck-stacking outside of the evaluation loop. Remember, the main expression is responsible for evaluating the deals after Deal 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.

A partial list of routines

For evaluation routines, we have seen the hcp and spades routines, as well as the "accept" and "reject" directives. Obviously, there are also routines called hearts, diamonds, and clubs which count their respective suits. The following functions are also built-ins:

controls: This function computes the number of controls held by a hand.
losers: 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.)
balanced: 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.
semibalanced: Returns true (1) if the hand passed has no shortness and no six-card or longer suit, and false (0) otherwise.

The three functions, controls, hcp, and losers, 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:

main {
  if {[hcp south hearts spades]>10} {accept}
}

This script accepts a deal if south has ten or more points in hearts and spades. controls and losers can be used similarly. Any function of this sort we will call "additive." We will see later that we can define a wide class of interesting additive functions.

The functions balanced and semi_balanced 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 incredibly fast shape functions.

A Second Script - defining Tcl procedures

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.

Our script , which we will call jacobytest might look something like:

# 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<15} {reject}

	set hs [hcp south]
	if {$hs<8 || $hs>9} {reject}

	if {[spades south]==5 || [hearts south]==5} { accept }
}

We have used one of our new functions here, balanced, 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:

if {[hcp north]>17 || [hcp north]<15} {reject}

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.

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.

proc notrump {hand min max} {

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

  set hc [hcp $hand]
  if {$hc < $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 <= 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 }
}

You are unlikely to need the jacobyinvite function beyond this script, but the notrump function will be something you will want to use again and again. You might even put it in a library of routines, called mylibrary and source that library every time you need one or more of the routines for a script:

source mylibrary

rather than rewriting the routine every time.

In fact, the Deal kit comes with a file called library , which is just such a library of routines the author of Deal found himself re-using.

Revisiting accept and reject

The directives, accept and reject, can be used in more complicated ways that are sometimes more efficient and sometimes more readable.

Here is the main script from the notrump example using some odd constructs:

main {
  reject unless {[notrump north $NTmin $NTmax]}
  accept if {[jacobyinvite south $NTmin $NTmax]}
}

Some people might find this more readable. The first line says we are going to reject the deal unless the condition is true. The second conditional says we are going to accept the deal if the expression evaluates as true.

Multiple arguments are allowed. The following command:

reject unless {expr1} {expr2} ... {exprn}

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 main.

For reject if the deal is rejected if any one of the expressions is true. Similarly, accept if accepts a deal if one of the expressions is true. For accept unless, the deal is accepted unless the one of the expressions is true.

This concludes the Introductory Tutorial. I hope it inspires you to check out the Deal - Advanced Guide and to learn more about Tcl. Or check out the index of all deal commands.

Plane Dealing graphic above created using POV-Ray.