Introduction

This is meant to be a comprehensive list of commands in Deal which are not native to Tcl. If you want to learn Tcl, I will be providing a set of pointers later.

Text in blue is meant for Tcl afficianado - reading this text without knowledge of Tcl might confuse more than enlighten.

Text in green is meant for programmers interested in finding code definitions.

Hand commands: `north`, `east`, `south`, `west`, `hand`

Usage

east [ -void string] [ suitname ... ]
hand {hand string} [ -void string] [ suitname ... ]

south subcommand [ ... args ... ]
hand {hand string} subcommand [ ... args ... ]

These are very strange commands - they really have too much stuffed into them. That's a historical anomoly which I'm reluctant to abandon.

With no subcommands, the routine is used for formatting the hand as a string. For example, if south is:

S: AJ5432
H: KT94
D: void
C: K93

Then the results of various commands are:

south                    =>    {AJ5432 KT94 {} K93}
south spades             =>    AJ5432
south hearts clubs       =>    {KT94 K93}
south -void -            =>    {AJ5432 KT94 - K93}
south -void --- diamonds =>    ---

set h {AK4 {} A95432 JT98}
hand $h                  =>    {AK4 {} A95432 JT98}
hand $h spades           =>    AK4
hand $h hearts clubs     =>    {{} JT98}
hand $h -void -          =>    {AK4 - A95432 JT98}

The -void switch exists precisely for formatting the output.

The various subcommands will be treated in seperate sections. The hand version of this command only works with some subcommands.

For Programmers

Implementation:: C code
Location:: tcl_deal.c, function tcl_hand_cmd

Subcommand: `shape`

Usage

north shape
hand {AJTxx Axx JTxx x} shape

Summary

Returns a list of suit lengths, in standard order.

For example, the second command above would return the list:

5 3 4 1

Subcommand: `pattern`

Usage

north pattern
hand {AJ32 A5 JTxx xxx} pattern

Summary

Returns a sorted list of the suit lengths, starting with the longest. For example, the second command above would return the list:

4 4 3 2

Subcommand: `is`

Usage

south is {handstring}

Summary

This command pre-places a specific 13 cards. For voids, you can use the "-" character:

south is {AJ32 KT932 - Q876}

Calls to this subcommand must occur before dealing begins, outside the "main" command.

This subcommand calls the stack_hand command. Inside the main code, the deal is already dealt.

Subcommand: `gets`

Usage

handname gets card [card ...]

Summary

Puts a specific list of cards in the hand named. As with the "is" subcommand, this must be called before dealing starts, outside the "main" command. The card is specified in two characters, a rank character and a suit character:

AS KH JH 9D

This routine dispatches its data to the stack_cards command.

Subcommand: `has`

Usage

handname has card [card ...]
hand {string} has card [...]

Summary

This returns a count of the cards listed that occur in the hand named.

% south
AJ54 JT54 43 654
% south has SA HK HJ HT
3

Control commands

Commands: `accept` and `reject`

Usage

accept [ [ if | unless ] expr expr ...]
reject [ [ if | unless ] expr expr ...]

Summary

Without arguments, accept and reject are the same as return 1 and

return
0

, respectively.

With arguments it's a little more obscure.

accept if {$h>4}

This returns 1 if the expression matches. It is equivalent to:

if {$h>4} { return 1 }

The code:

accept if {$h>4} {$s>4}

Is logically equivalent to:

if {$h>4 || $s>4} { return 1}

That is, the values are accepted if either of the expressions evaluates as true.

The unless option does the opposite:

accept unless {$h>4} {$s>4}

This is equivalent to:

if {!($h>4) || !($s>4)} { return 1 }

The means we return with a true value unless one of the expressions is true. If one of the values is true, we simply go on to the next line.

Examples

Virtually all of the examples included in the release contain an instance of "accept" or "reject."

For Programmers

Implementation:: C code
Location:: tcl_deal.c, procedure tcl_deal_control.

This construct is borrowed from the Perl programming language. Originally, I added it to Deal 2.0 for performance reasons. Those reasons are obsolote with Tcl 8.x, but I like the mnemonic enough to keep it, and removing it might confuse old users.

For Tcl Experts

There actually is one subtle and occasionally useful distinction between accept/reject and the stated

if {...} { return ... }

version. In reality:

accept if {$h>4} {$s>4}

is equivalent to:

if {$h>4||$s>4} { 
    return 1
}
expr 0

This only matters when the command is the last command in a procedure. The two procedures:

proc A {h s} {
    if {$h>4||$s>4} {
        return 1
    }	
}

proc B {h s} {
     accept if {$h>4} {$s>4}
}

are slightly different.

A call of A 3 3 returns an empty string, while a call of B 3 3 returns 0. That can be useful, as you can see here.

Command: `main`

Usage

main {
   block of code
}

Summary

This defines the primary block of code evaluated after each deal is generated. If the code returns true, Deal will treat the deal as a "match" and call write_deal. It will also increment its count of deals found and exit if the limit is reached.

For Programmers

Implementation:: C code
Location:: tcl_deal.c, procedure tcl_deal_control.

Command: `whogets`

Usage

whogets cardname

This returns the name of the person holding the card cardname.

For Programmers

Implementation:: C code
Location:: tcl_deal.c, procedure tcl_deal_to_whom.

Command: `deal_finished`

Usage

deal_finished {
   block of code
}

This defines the code called at the completion of generating all deals. This is code you would use to dump statistics, for example.

For Programmers

Implementation:: C code
Location:: tcl_deal.c, procedure tcl_after_set.

Bridge Evaluators

Common interfaces

There are some standard interfaces to bridge evaluation functions.

Hand Procedures

Any procedure defined entirely based on the values in one hand is considered a hand procedure. These procedures can be called in one of two ways:

Weak2Bid handname

Weak2Bid hand {AKQxxx xxx xxx x}

The handname parameter can be one of north, south, east, west. Shape procedures and holding procedures fit the hand procedure calling method, along with other options.

Shape procedures

Any procedure defined on the shape of a hand can be called with one of the following methods:

balanced handname

balanced hand {AJ43 AKxx xxx K5}

balanced eval 4 3 4 2

balanced shape {4 3 4 2}

This follows the hand procedure outline with the addition of the eval option.

Holding procedures

A holding procedure is a hand procedure which is evaluated on a bridge hand by evaluating each suit holding one at a time, and then accumulate the results. There are two common ways of defining holding procedures, defvector and holdingProc.

This is an abstraction of a very common bridge evaluation technique. The most commonly used holding functions are high card points, losing trick count, controls. For example, when counting the losers in the hand AKxx Axx KQJxxx x, we find 1 loser in spades, 2 losers in hearts, 1 loser in diamonds, and one loser in clubs. We define the total losers to be the sum across all suits, and get 5 losers, total.

The interface lets you evaluate the entire hand, or only selected suits in a hand, or a specific list of holdings.

hcp handname [ suitname ...  ]

hcp hand {AKJxxx K xxx xxx} [ suitname ...  ]

hcp holding AK43 [ ... ]

In the first two cases, if no suits are named, all suits are evaluated, and the results are accumulated. In the case of the holding call, the specific holdings passed in are evaluated.

Note, I've been saying "accumulated" rather than added. In some cases, you might have an accumulation method different from addition. For example, you might return the standard opening leads from a holding:

    openingLead holding KQJ7    =>   K
    openingLead south           => {K} {7 2} {4} {J}

Each suit would create a list of proposed leads, and the result would be a list of lists of all standard leads from all holdings. Here, the accumulation is to simply make a list.

Command: `balanced` and `semibalanced`

Usage

balanced handname

balanced hand {text hand}

balanced eval s h d c

Summary

These are both shape procedures.

balanced returns true if the hand is some 4333, 4432, or 5332 without a 5-card major.

semibalanced returns true if the hand has no singletons or voids, not six-card majors, and no seven-card minors.

For Programmers

Implementation:: Tcl with shapecond
Location:: lib/features.tcl

These use to be hard-coded in the C code, but it made more sense to add them to the library code - the user can change the definitions as he likes.

Commands: `clubs`, `diamonds`, `hearts`, `spades`

Usage

     spades handname
     spades hand {AKxx Axx AJxx Kx}

These implement the hand procedure interface, and return the suit lengths for the appropriate suit.

For Programmers

Implementation:
Location:: tcl_deal.c, function tcl_suit_count

These could be shape procedures but for speed reasons, I've left them this way.

Holding Evaluators

Command: `hcp`

Usage

hcp handname
hcp handname suitname [suitname ...]
hcp hand {s h d c}
hcp hand {s h d c} suitname [suitname ...]

This procedure computes standard high card points - ace is 4, king is 3, queen is 2, jack is 1. The procedure implements the holding procedure interface.

For Programmers

Implementation:: C code
Location:: Built with additive.c, tcl_create_additive and deal.c, count_hcp

Command: `newLTC`

Usage

newLTC handname
newLTC handname suitname [suitname ...]
newLTC hand {s h d c}
newLTC hand {s h d c} suitname [suitname ...]

Rex Livingston provided this implementation of the New Losing Trick Count, from a 2003 Bridge World article.

It looks to me much like a 3-2-1 count with some adjustments, and it seems odd to me that a stiff singleton would count as 1.5 losers. Somehow, doesn't match the intuitive meaning of "loser" to me.

For Programmers

Implementation:: Tcl code
Location:: lib/features.tcl

Command: `losers`

Usage

losers handname
losers handname suitname [suitname ...]
losers hand {s h d c}
losers hand {s h d c} suitname [suitname ...]

This implements a holding procedure which computes the number of half losers. This is for historical reasons - the only holding functions allowed in past releases returned integer values, but I wanted to have some refinements over raw losing trick count.

For Programmers

Implementation:: C code
Location:: Built with additive.c, tcl_create_additive and deal.c, count_losers

It is probably better to reimplement in Tcl using holdingProc.

Bridge Logic and Utilities

Commands: `lho`, `partner`, `rho`

Usage

lho handname
rho handname
partner handname

Summary

These routines accept one hand name and return another. For example, "lho north" returns "east," and "partner east" returns "west."

For Programmers

Implementation:: C code
Location:: tcl_deal.c, function tcl_other_hand

Commands: `holding`

Usage

holding length AJxx           =>     4

holding contains AJ64 A6      =>     1 (true)
holding contains AJ64 A65     =>     0 (false)

holding encode AJ4            =>     4612  (binary: 1001000000100 )

holding decode 4612           =>     AJ4

holding matches AKxx  AK42    =>     1 (true)

holding disjoint AJ65 KT82    =>     1 (true)
holding disjoint A65  A32     =>     0 (false)

holding index AKJ4 0          =>     A
holding index AKJ4 1          =>     K
holding index AKJ4 3          =>     4
holding index AKJ4 -2         =>     J
holding index AKJ4 10         =>     ""

Summary

For Programmers

Implementation:: C code
Location:: holdings.c, function IDeal_HoldingCmd

Command: `score`

Usage

source lib/score.tcl
   ...
score contract vulnerability tricks

Summary

This routine computes the standard duplicate bridge score for a contract from the point of view of declarer, if declaring side takes the given number of tricks.

The contract is passed as a list:

2 spades

2 spades undoubled 

4 clubs doubled

6 notrump redoubled

The vulnerablity is one of the words vul or nonvul.

The tricks is the number of tricks taken by declarer.

Examples

score {2 spades} nonvul 8           =>  110
score {2 spades doubled} nonvul 8   =>  470
score {2 spades redoubled} nonvul 8 =>  640
score {2 spades doubled} vul 8      =>  670
score {2 spades} nonvul 7           =>  -50
score {2 spades doubled} nonvul 7   =>  -100
score {2 spades doubled} vul 7      =>  -200

For Programmers

Implementation:: Tcl
Location:: score.tcl

Double Dummy Solver

Starting with Deal 3.1, I've included simple access to Bo Haglund's double-dummy solver library.

Command: `deal::tricks`

Usage

deal::tricks declarer denomination

Summary

deal::tricks returns the maximum number of tricks makable by declarer in the given denomination.

declarer must be one of "north", "east", "south", or "west." By default, it is "south."

denomination must be a suit name or "notrump." The default value is "notrump."

By default, deal::tricks uses the tricks function, which calls Bo Haglund's double-dummy solver.

However, if you include "lib/gib.tcl", deal::tricks will call the GIB double dummy solver.

deal::tricks caches values, so multiple calls for the same deal with the same declarer and denomination will not result in multiple calls to the double-dummy solver.

Bo Haglund's solver has a feature which makes it faster if the next double dummy solver call is in the same denomination as the previous call. That means that if you need all double-dummy values, you would want to write your code as:

   foreach denom {clubs diamonds hearts spades notrump} {
     foreach hand {north east south west} {
       set tricks [deal::tricks $hand $denom]
       ...
     }
   }

For Programmers

Implementation:: Tcl
Location:: lib/features.tcl

Command: tricks

Usage

tricks [ declarer [ denomination [ goal ] ] ]

Summary

Unless you are using the goal parameter, you will probably want to use the deal::tricks command, since it has the advantage of caching values.

When no goal is passed, "tricks" returns the maximum number of tricks makable by declarer in the given denomination.

If a (positive) goal number of tricks is set, "tricks" returns 1 if declarer can make that many tricks, and 0 if the defense can always hold declarer to fewer tricks.

declarer must be one of "north", "east", "south", or "west." By default, it is "south."

denomination must be a suit name or "notrump." The default value is "notrump."

goal must be an integer value, either -1 for "best play" or a value from 1 to 13 equal to the goal number of tricks for declarer. Default is -1.

For Programmers

Implementation:: C, C++
Location:: dds.cpp, tcl_dds.c

Command: dds

Usage

dds [-reuse | -noreuse] [-diagram diagram] [-goal goal]  
     [-leader leader] [-trick list of cards [-trick cards ] ...] [ declarer [ denomination ] ]

Summary

The dds command gives even more refined access to Bo Haglund's double dummy engine, including the ability to solve problems with fewer than 52 cards.

The -reuse flag tells the double-dummy solver to reuse the data it generated from the last call. For example, if the hand is identical to the previous call and played in the same denomination, you'll want to reuse the data.

The -noreuse flag tells the double-dummy solver not to reuse the data. This is the default.

The -diagram flag tells the double-dummy solver to solve a specific diagram, rather than the current deal. A diagram is of the form of a Tcl list in the order north, east, south, west.

The -leader flag tells the double-dummy solver who is on lead to the current trick.

The -trick flag gives a list of cards played to the current trick.

For example, to solve George Coffin's "Avoidance" end position from his Great 88, you would write:

set diagram {
           {A987 - A -} 
           {Q5 987 - -} 
           {64 K2 2 -} 
           {K2 AQ3 - -} 
}
set tricks [dds -leader south -diagram $diagram south notrump]
...

If you wanted to see how many tricks are made if south plays a particular card, say the two of clubs, you would use the -trick flag:

set tricks [dds -leader south -diagram $diagram -trick 4S south notrump]

You can also pass full tricks, as in:

set tricks [dds -leader west -diagram $diagram -trick {4S KS 7S 5S} south notrump]

Note that the -leader option always refers to the leader to the current trick, not the leader of earlier completed tricks passed with -trick. Also, the number of tricks returned is the number of tricks after all completed tricks.

There are example tests of all the Great 88 in the file tests/great88 that is included in this release.

For Programmers

Implementation:: C, C++
Location:: dds.cpp, tcl_dds.c

Command: `parscore`

Usage

source lib/parscore.tcl
   ...
set result [parscore dealer vul]

set contract [lindex $result 0]
set declarer [lindex $result 1]
set score [lindex $result 2]
set tricks [lindex $result 3]
set auction [lindex $result 4]

Summary

This computes the double-dummy par result for the current deal.

The parscore routine returns a list of five values - the contract (in the same form that is used by the score routine above), the declarer, the score for north/south, the number of tricks taken, and a "stupid" auction to the contract suitable for putting into a PBN file.

Dealer is relevant on a few occasions. If both south and west can make 1NT, for example, and no 2-level contracts make, then "par" is 1NT by whomever gets a chance to bid it first.

For Programmers

Implementation:: Tcl
Location:: parscore.tcl

GIB-related routines

These next routines use calls to the GIB double-dummy engine. You must have a licensed version of GIB installed on your computer for these routines to work. Also, these routines only work on Windows at the moment.

Command: `gib::directory`

Usage

source lib/gib.tcl
   ...
gib::directory path

Summary

This tells the GIB-related routines where GIB is installed.

If this routine is not called, it defaults to GIB's default install directory, C:/Program Files/GIB.

Note: your path should include forward slashes '/', even on Windows.

For Programmers

Implementation:: Tcl
Location:: gib.tcl

Command: `gib::tricks`

Usage

source lib/gib.tcl
   ...
gib::tricks declarer denomination

Summary

You probably want to use the deal::tricks command, even when using GIB's double dummy solver.

Denomination can be a suit name or "notrump." Declarer can be any hand name.

This routine returns the double-dummy number of tricks available in this deal, in the given denomination by the given declarer.

If GIB is installed anywhere unusual, you will need to call gib::directory before deal::tricks is called.

For Programmers

Implementation:: Tcl
Location:: gib.tcl

Bridge Command Builders

A number of common types of bridge functions can easily be implemented to run quickly via lookup tables, including holding and shape procedures. Deal lets the user take advantage of these two sorts of lookup procedures relatively easily

Command: `defvector`

Usage

defvector vec aceVal [ kingVal ... ]

vec handname

vec hand {text hand}

vec handname suitname [ suitname ... ]

vec handname suitname [ suitname ... ]

vec hand {text hand} suitname ...

Summary

This defines a holding procedure which assigns integer values to the various cards in the hand. For example

defvector hcp6421 6 4 2 1

Defines a holding procedure which counts the ace as worth 6 points, the king as worth 4, the queen as 2, and the jack as 1.

Vectors are limited to being integer-valued. For more complicated holding procedures, use holdingProc.

For Programmers

Implementation:: C
Location:: vector.c

Vectors are slighly faster than their equivalent holdingProc. They are an old optimization which remain mostly for backwards compatibility.

Command: `holdingProc`

Usage

Temporarily, see the seperate documentation.

For Programmers

Implementation:: C
Location:: holdings.c, function IDeal_DefHoldingProc

Commands: `shapeclass`, `shapecond`, and `shapefunc`

Usage

shapeclass name {... code ...}

shapecond name {expr}

shapefunc name {... code ...}

name [ north | south | east | west ]

name eval s h d c

name shape {s h d c}

A shape class (or equivalently, a shape condition) also has the list subcommand:

name list

Summary

These commands create new procedures which fit the shape function interface.

shapeclass and shapecond define procedures which returns boolean values. shapefunc can return any type of data. shapecond is actually an alias:

shapecond name {expr}

is the equivalent of:

shapeclass name {
  if {expr} {
    return 1
  } else {
    return 0
}

The code or expr is allowed to use the variables s, h, d, or c.

More details can be found in the Advanced Guide.

The list subcommand for shape classes returns a list of shapes that are in the class.

Why are there two subcommands, "eval" and "shape" which do the roughly the same things?

Let's say you have a class named "SemiBalanced" already defined, which includes 5-card majors. You want to define a "Balanced" class which excludes the 5-card majors. You can do this with the call:

shapecond Balanced {[SemiBalanced eval $s $h $d $c] && $s<5 && $h<5}

On the other hand, if you have a shape - output by the, say, a call to [north shape] you can evaluate it as:

    SemiBalanced shape [north shape]

In fact, this is exactly equivalent to calling

    SemiBalanced north

only slightly slower.

Since these routines cache results in memory and use lookup tables, you should not use any external state or global variables inside them.

For Programmers

Implementation:: C
Location:: dist.c, functions tcl_shapeclass_define, tcl_shapecond_define, and tcl_shapefunc_define

Statistics

Command: `sdev`

Usage

sdev name

name add data [ data ... ]

name count

name average

name sdev

name rms

Summary

The "sdev" command defines a new Tcl procedure with the given name, which behaves as a data collection object. You can add data points to it, or you can retrieve the current number of data points, the average of the data points, the standard deviation of the data points, or the "root mean square" of the data points.

For Programmers

Implementation:: C code
Location:: stat.c, function tcl_sdev_define.

This was implemented in C for efficiency reasons - most real number computations really need to be done in C if they are going to be done frequently, and here, the "add" command is called quite often in normal usage.

Command: `correlation`

Usage

     correlation name

     name add xval yval [ xval yval ... ]

     name count

     name correlate

     name average [ x | y ]

     name sdev [ x | y ]

     name rms [ x | y ]

Summary

The correlation declaration defines a routine much like the sdev command, but each datapoint is a pair of values, and it computes the linear correlation between the x and y values.

You can also get individual data for the x and y values.

If there is no data, it returns an error on average, correlate, sdev and rms.

If there is only one pair entered, it will throw an error on sdev.

For Programmers

Implementation:: C code
Location:: stat.c, function tcl_correlation_define.

Utility Procedures

Command Line: -x flag

Usage

   deal -x filename

The '-x' flag tells deal to source the file and then exit.

This is useful if you want to skip the entire deal loop, and process stuff on your own. For example, the code in tests/great88 does not generate any deals, it just solves 88 5-card double-dummy problems. Before the -x flag, you had to explicitly call 'exit' from such scripts.

Command: `full_deal`

Usage

   set deal [full_deal]

This simple utility command returns the deal as a list of hands in the order of north, east, south, and west. Suitable for psassing into dds with the -diagram flag, or remembering a deal after the end of the loop.

Command: `seed_deal`

Usage

seed_deal number

Command Line: -s

$ deal -s number ...

Summary

seed_deal is used to seed the random number generator, to make sure that Deal generates the same sequence of random numbers.

Care has to be taken if you want to make sure that you are generating the same sequence of deals. For one thing, if you have a main inner loop, you should add the command "finish_deal" to the main section.

main {
   finish_deal
   ...
}

That bypasses some optimizations and forces an entire deal to be generated each time through main.

Command: `deal_deck`

Usage

deal_deck

Summary

deal_deck is called at every new deal, even when all 52 cards are specified (stacked) precisely. Imagine stacking cards as stacking them in an undealt deck, but that the cards are only distributed to the hands when deal_deck is called.

Most of the time, you won't need to call deal_deck directly, but it is useful to understand its behavior if you are going to write advanced procedures like input formats.

Stacked cards are permanently stacked until the deck is reset. In this code:

    stack_hand south {AKQ32 AJ53 K54 2}
    deal_deck
    deal_deck
    puts [south spades]

The output is "AKQ32". Use reset_deck to undo card stackings.

The deal_deck procedure does one thing rather complicated when it is called, the first thing it does is execute all code registered with the deal_reset_cmds. This allows the script writer to do one of several things before the deal is generated:

Delete metadata related to the deal. For example, the first time the user calls deal::tricks south spades it calls the double-dummy processor. Each time after that, it uses a stored value for this function call up until the next call to deal_deck.
The reset command might, instead, read the next deal from a file, stack the deck, and then re-register itself. Then when deal_deck is is called, it just deals that hand from the file. This is a crude way of allowing Deal to transparently read deals from a file (or generate deals in other ways, such as smart stacking.

For Programmers

Implementation:: C
Location:: tcl_deal.c, function tcl_deal_deck

Command: `reset_deck`

Usage

reset_deck

Summary

This forgets about all stacked cards. The deck, from Deal's point of view, plus a list of cards which must go to specific hands. The cards which are assigned to specific hands are "stacked." The cards which are not stacked can go anywhere at the next call to deal_deck.

For Programmers

Implementation:: C
Location:: tcl_deal.c, function tcl_reset_deck

Commands: `stack_hand` and `stack_cards`

Usage

stack_hand handname hand
stack_cards handname suitname holding [...]

Summary

By default, these two routines just call deck_stack_hand and deck_stack_cards, respectively - that is, they forcibly place cards in the deck.

But these routines are meant to be overridden. For example, when using one of the input formats which reads deals from a file, the format will redefine these two procedures to give errors.

% deal -I "line foo.txt" -e "stack_cards south spades AJ"
Tcl stack dump of error info:
No card stacking with input format ::line
...

A more complicated re-definition occurs in the smartstack input format, which alters its hand generation depending on what cards are stacked where.

For Programmers

Implementation:: C
Location:: hand.c, function tcl_stack_hand and tcl_stack_cards

Commands: `deck_stack_hand` and `deck_stack_cards`

Usage

deck_stack_hand handname hand
deck_stack_cards handname suitname holding [...]

Summary

These routines are the "underlying" deck-stacking routines. Any cards stacked with these routines remain stacked until the next call to reset_deck

For Programmers

Implementation:: C
Location:: hand.c, function tcl_stack_hand and tcl_stack_cards

Command: `stacked`

Usage

stacked handname

Summary

Determines what cards are stacked to this hand, returning them as a list of holdings:

south gets AS KH 3H QD JD TC 9C 8C
puts [stacked south]

writes out the list:

A K3 QJ T98

This is useful for the smartstacker, because we don't want to force the user to stack cards *after* specifying conditions.

stack_hand north {AJT KT3 KJ 75432}
deal::input smartstack south balanced hcp 20 21

The call to stack_hand occurs before smartstack is loaded, so stack_hand has not been redefined. So what smartstack does is read the cards already stacked, and use that for its initial conditions.

For Programmers

Implementation:: C
Location:: tcl_deal.c, function tcl_stacked_cards

Command: `deal::nostacking`

Usage

::deal::nostacking

Summary

This procedure redefines the stack_hand and stack_cards procedures to generate error messages, and generates an error if any cards are currently stacked.

This is used in all of the input formats which read complete deals from files, and thus are incompatible with stacking.

For Programmers

Implementation:: Tcl code
Location:: lib/features.tcl, function deal::nostacking

Command: `deal_reset_cmds`

Usage

deal_reset_cmds {...code...} [ ... ]

Summary

This adds a set of commands that are to be called before the next deal. The code is executed at the next call to the deal_deck procedure, which, unless you are doing something complicated, means it is called at the beginning of each time through the evaluation loop.

deal_reset_cmds can be used so that metadata about the previous deal, such as cached values and the like, are unset. See deal::metadata.

It is also used for defining input formats, so that deals can be read from files. For example, the "line" input format has the following routine declared:

namespace eval line {
    #....
    proc next {} {
	variable handle
	set length -1
	catch { set length [gets $handle line] }

        # ... process the line, or handle oef stuff ...
        # ...
	deal_reset_cmds {::line::next}
    }
}

The key is that when line::next is done, it re-registers itself, making sure that it is called next time through as well.

The code passed in to deal_reset_cmds is called only once, at the next request for a deal - think of it as registering a one-time trigger. Multiple triggers can be registered - they are called in the reverse order that they are added, which can seem counter-intuitive until you think of the process as an "undo" process.

For Programmers

Implementation:: C
Location:: tcl_deal.c, function add_reset_cmds

Command: `deal::metadata`

Usage

deal::metadata name {...code...}

Summary

Currently, this is just a peculiar way of caching slow evaluation routines. At the moment, the only place it is used is in deal::tricks.

When you call deal::metadata, it will check to see if there is a value associated with the name requested already. If there is, the value is returned. If it does not, it evaluates the specified code and associates the result with the name. The key is, when the next deal is being analyzed, all the cached values are pitched.

This isn't really necessary or efficient in most cases, but with evaluations which take some time, e.g. GIB calls, it improves things.

For Programmers

Implementation:: Tcl
Location:: lib/features.tcl

In later releases, metadata read from input streams (say, the fields from a PBN file) will also be stored here.

This procedure uses deal_reset_cmds. The metadata is cleared each time the deal_deck command is called.

Input formats

Command: `deal::input`

Usage

deal::input formatName args

Summary

The deal::input command is used to define an input source for deals. It works as follows:

The file input/<formatName>.tcl is loaded. This Tcl file should define a new Tcl 'namespace' with the name formatName, with member procedures named set_input and next.
Deal then calls <formatName>::set_input args, which should initialize the format reading. Usually, the argument(s) are one argument representing the source file.
The next deal, <formatName>::next is called.

For Programmers

Implementation:: Tcl code
Location:: lib/features.tcl

Input Format: `giblib`

Usage

deal::input giblib [filename]

or on the command line:

% deal -I giblib

% deal -I "giblib filename"

Summary

Specifies that deals are read from the specified file in the format of Matt Ginsberg's library.dat file. This includes double-dummy tricks data, so that later calls to deal::tricks will not entail calls to the GIB binaries.

If no filename is given, the library tries to read from a file called "library.dat" in the current directory.

The -I command-line flag is a quick alias for deal::input, passing the next argument as Tcl arguments to the deal::input command.

For Programmers

Implementation:: Tcl code
Location:: input/giblib.tcl

This procedure uses deal_reset_cmds.

Input Format: `line`

Usage

deal::input line [filename]

Summary

Specifies that deals are read from the specified file in the format written by Deal's "-l" option.

If no filename is given, the library reads from standard input. This way, you can create a single data file and then run several different queries against it:

% deal -l 100000 > sample
% deal -e "deal::input line sample" -i query1
% deal -e "deal::input line sample" -i query2

[ The -e option just evaluates the code in the next argument as Tcl code. Alternative, you can use the -I option, which is shorthand for input formats:

% deal -I "line sample" -i query1

The -I args option is exactly the same as -e "deal::input args".]

For Programmers

Implementation:: Tcl code
Location:: input/line.tcl

Input Format: `ddline`

Usage

deal::input line [filename]

Summary

Specifies that deals are read from the specified file in the format written by Deal's ddline format.

The ddline format include doubled-dummy tricks data, so when using ddline for input, calls to deal::tricks return the data read from the file.

For Programmers

Implementation:: Tcl code
Location:: input/line.tcl

Input: `smartstack`

Usage

deal::input smartstack hand shapeclass [holdproc min max]

or on the command line:

% deal -I "smartstack shapeclass ..."

Summary

This is the most complicated Deal input method in the current release. It does not read deals from a file - it is, instead, a different path to generation of deals. The purpose of this format is to allow fast generations of deals where one hand fits a very specific description. For example, if you want to find hands where south has a balanced 27-count, you could write:

deal::input smartstack south balanced hcp 27 27

On my computer, that returns the first deal in 14 seconds, and every deal after that takes a tiny fraction of a second. That's because smartstack first builds a large "factory" in memory, but once it is built, the factory spits out hands matching this condition very quickly.

By contrast, a standard "deal" script to find balanced 27-counts takes about 2.8 seconds to find each deal. That means that if you only want to find about five deals of this sort, the old style program is faster, but if you want a lot more, use smartstack. For example, if you wanted 1000 examples, smartstack takes about 15 seconds, while the old deal will take about 45 minutes.

One interesting feature of smartstack is that it is often faster if the hand type is less frequent. For example, it takes about 6 seconds to find ten deals with 9-card spade suits, and about 5 seconds to find ten deals with 10-card spade suits. Similarly, it is faster at finding hands with exactly 9 controls than it is at finding hands with 9-12 controls.

The smartstack routine only works on one hand - after it places cards in that hand, it generates the rest using the usual algorithm.

For Programmers

Implementation:: Tcl code
Location:: input/smartstack.tcl, lib/handFactory.tcl
Notes: See the two articles from the bridge developers mailing list describing the algorithm: My first stab at describing it and some corrections.

Formatting

Command: `write_deal`

Usage

write_deal

Summary

This is the the name of a procedure which is called when deals are accepted. By default, it writes the result in the format:

          S: 98632
          H: A4
          D: AJ754
          C: J
 S: K              S: AJT7
 H: J3             H: QT95
 D: T98            D: Q2
 C: AKT7532        C: 984
          S: Q54
          H: K8762
          D: K63
          C: Q6
--------------------------

New output formats are defined by redefining this routine.

For Programmers

Implementation:: Tcl
Location:: format/default

Command: `flush_deal`

Usage

flush_deal

Summary

This routine is called at the very end of a run for deal. It does nothing, by default, but some output formats may require it if data is cached.

For Programmers

Implementation:: Tcl code
Location:: format/default, function flush_deal

Output Format: `format/par`

Usage

source format/par

Summary

By including this file, you are setting the output format to write the results in PBN format, with results set to the double dummy theoretical par.

$ deal -i format/par 1
[Date "2008.05.19"]
[Board "1"]
[West "West"]
[North "North"]
[East "East"]
[South "South"]
[Dealer "N"]
[Vulnerable "None"]
[Deal "N:K.A7.QJT9865.AK7 T94.K98532.2.943 A872.QT4.AK4.862 QJ653.J6.73.QJT5"]
[Contract "6N"]
[Declarer "S"]
[Result "12"]
[Score "NS 990"]
{
          S: K
          H: A7
          D: QJT9865
          C: AK7
 S: QJ653          S: T94
 H: J6             H: K98532
 D: 73             D: 2
 C: QJT5           C: 943
          S: A872
          H: QT4
          D: AK4
          C: 862
north makes 9 tricks in clubs
north makes 12 tricks in diamonds
north makes 8 tricks in hearts
north makes 7 tricks in spades
north makes 12 tricks in notrump
east makes 3 tricks in clubs
east makes 1 tricks in diamonds
east makes 5 tricks in hearts
east makes 4 tricks in spades
east makes 1 tricks in notrump
south makes 8 tricks in clubs
south makes 12 tricks in diamonds
south makes 8 tricks in hearts
south makes 7 tricks in spades
south makes 12 tricks in notrump
west makes 3 tricks in clubs
west makes 1 tricks in diamonds
west makes 5 tricks in hearts
west makes 4 tricks in spades
west makes 1 tricks in notrump
}
[Auction "N"]
Pass   Pass   6N
[Play "W"]
*

For Programmers

Implementation:: Tcl
Location:: format/par

Output Format: `format/ddline`

Usage

source format/ddline

Summary

By including this file, you are redefining the output format to the form "ddline", which writes out the deal on a single line, as with the '-l' flag, but then adds complete double-dummy data to the deal as well. If you write the output to a file:

$ deal -i format/ddline 100 > doubledummy.txt

then you can use the ddline input format to read the file back in:

$ deal -I "ddline doubledummy.txt" -i query.tcl 100

And any call to deal::tricks in query.tcl will use the value stored doubledummy.txt.

For Programmers

Implementation:: Tcl
Location:: format/ddline

Plane Dealing graphic above created using POV-Ray.

Index

Introduction

Hand commands: north, east, south, west, hand

Usage

Subcommand: shape

Usage

Summary

Subcommand: pattern

Usage

Summary

Subcommand: is

Usage

Summary

Subcommand: gets

Usage

Summary

Subcommand: has

Usage

Summary

Control commands

Commands: accept and reject

Usage

Summary

Examples

Command: main

Usage

Summary

Command: whogets

Usage

Command: deal_finished

Usage

Bridge Evaluators

Common interfaces

Hand Procedures

Shape procedures

Holding procedures

Command: balanced and semibalanced

Usage

Summary

Commands: clubs, diamonds, hearts, spades

Usage

Holding Evaluators

Command: hcp

Usage

Command: newLTC

Usage

Command: losers

Usage

Bridge Logic and Utilities

Commands: lho, partner, rho

Usage

Summary

Commands: holding

Usage

Summary

Command: score

Usage

Summary

Examples

Double Dummy Solver

Command: deal::tricks

Usage

Summary

Command: tricks

Usage

Summary

Command: dds

Usage

Summary

Command: parscore

Usage

Summary

GIB-related routines

Command: gib::directory

Usage

Summary

Command: gib::tricks

Usage

Summary

Bridge Command Builders

Hand commands: `north`, `east`, `south`, `west`, `hand`

Subcommand: `shape`

Subcommand: `pattern`

Subcommand: `is`

Subcommand: `gets`

Subcommand: `has`

Commands: `accept` and `reject`

Command: `main`

Command: `whogets`

Command: `deal_finished`

Command: `balanced` and `semibalanced`

Commands: `clubs`, `diamonds`, `hearts`, `spades`

Command: `hcp`

Command: `newLTC`

Command: `losers`

Commands: `lho`, `partner`, `rho`

Commands: `holding`

Command: `score`

Command: `deal::tricks`

Command: `parscore`

Command: `gib::directory`

Command: `gib::tricks`

Command: `defvector`

Command: `holdingProc`

Commands: `shapeclass`, `shapecond`, and `shapefunc`

Command: `sdev`

Command: `correlation`

Command: `full_deal`

Command: `seed_deal`

Command: `deal_deck`

Command: `reset_deck`

Commands: `stack_hand` and `stack_cards`

Commands: `deck_stack_hand` and `deck_stack_cards`

Command: `stacked`

Command: `deal::nostacking`

Command: `deal_reset_cmds`

Command: `deal::metadata`

Command: `deal::input`

Input Format: `giblib`

Input Format: `line`

Input Format: `ddline`

Input: `smartstack`

Command: `write_deal`

Command: `flush_deal`