1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<!-- $Id: commands.html 313 2009-06-11 05:44:13Z thomasoa $ -->
<title>Index of Deal Commands</title>
<link rel="stylesheet" type="text/css" href="commands.css">
</head>
<body>
<div id="indexbox" class='index'>
<div><a href="index.html">Back to Deal top page</a></div>
<h3>Index</h3>
<ul>
<li><a href='#accept' >accept</a><li><a href='#balanced' >balanced</a><li><a href='#binky' >Binky Points evaluators</a><li><a href='#binky_nt' >binky::nt</a><li><a href='#binky_suit' >binky::suit</a><li><a href='#clubs' >clubs</a><li><a href='#correlation' >correlation</a><li><a href='#deal::input' ><em>input files</em></a><li><a href='#deal::metadata' >deal::metadata</a><li><a href='#deal::nostacking' >deal::nostacking</a><li><a href='#deal::tricks' >deal::tricks</a><li><a href='#deal_deck' >deal_deck</a><li><a href='#deal_finished' >deal_finished</a><li><a href='#deal_reset_cmds' >deal_reset_cmds</a><li><a href='#deck_stack_cards' >deck_stack_cards</a><li><a href='#deck_stack_hand' >deck_stack_hand</a><li><a href='#defvector' >defvector</a><li><a href='#diamonds' >diamonds</a><li><a href='#ddline' >ddline <em>input format</em></a><li><a href='#format:ddline' >ddline <em>output format</em></a><li><a href='#dds' ><em>Double Dummy Solver, Bo Haglund's</em></a><li><a href='#ddscmd' >dds</a><li><a href='#east' >east</a><li><a href='#flush_deal' >flush_deal</a><li><a href='#full_deal' >full_deal</a><li><a href='#hand' >is <em>subcommand</em></a><li><a href='#giblib' >giblib <em>input</em></a><li><a href='#gibstuff' ><em>GIB-related routines</em></a><li><a href='#gib::directory' >gib::directory</a><li><a href='#gib::tricks' >gib::tricks</a><li><a href='#handInterface' ><em>hand procedures</em></a><li><a href='#hcp' >hcp</a><li><a href='#hearts' >hearts</a><li><a href='#holdingp' ><em>holding procedures</em></a><li><a href='#holding' >holding</a><li><a href='#holdingProc' >holdingProc</a><li><a href='#lho' >lho</a><li><a href='#library.dat' >library.dat <em>input</em></a><li><a href='#line' >line <em>input</em></a><li><a href='#losers' >losers</a><li><a href='#main' >main</a><li><a href='#newLTC' >newLTC</a><li><a href='#north' >north</a><li><a href='#format:par' >par <em>output format</em></a><li><a href='#parscore' >parscore</a><li><a href='#partner' >partner</a><li><a href='#pattern' >pattern <em>subcommand</em></a><li><a href='#patternclass' >patternclass</a><li><a href='#patterncond' >patterncond</a><li><a href='#patternfunc' >patternfunc</a><li><a href='#reject' >reject</a><li><a href='#reset_deck' >reset_deck</a><li><a href='#rho' >rho</a><li><a href='#seed_deal' >seed_deal</a><li><a href='#shape' >shape <em>subcommand</em></a><li><a href='#score' >score</a><li><a href='#sdev' >sdev</a><li><a href='#semibalanced' >semibalanced</a><li><a href='#shapeclass' >shapeclass</a><li><a href='#shapecond' >shapecond</a><li><a href='#shapefunc' >shapefunc</a><li><a href='#shapes' ><em>shape procedures</em></a><li><a href='#smartstack' >smartstack</a><li><a href='#south' >south</a><li><a href='#spades' >spades</a><li><a href='#stack_cards' >stack_cards</a><li><a href='#stack_hand' >stack_hand</a><li><a href='#stacked' >stacked</a><li><a href='#statistics' ><em>statistics</em></a><li><a href='#tricks' >tricks</a><li><a href='#west' >west</a><li><a href='#whogets' >whogets</a><li><a href='#write_deal' >write_deal</a><li><a href='#exitflag' >-x <em>flag</em></a></ul>
</div>
<div id="commandsbox" class='commands'>
<h1>Introduction</h1>
<table style="width: 100%" cellpadding=5><tr valign=top><td style="width: 65%">
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.
<td style="width: 35%">
<div class='tcl'>
Text in blue is meant for Tcl afficianado
- reading this text without knowledge of Tcl might confuse more than
enlighten.
</div>
<br>
<div class='programmer'>
Text in green is meant for programmers
interested in finding code definitions.
</div>
</table>
<hr>
<a name="north"></a><a name="east"></a><a name="south"></a><a name="west"></a>
<a name="hand"></a>
<a name="shape"></a><a name="pattern"></a>
<h1>Hand commands: <code>north</code>, <code>east</code>, <code>south</code>, <code>west</code>, <code>hand</code></h1>
<table cellpadding=5 style="width: 100%">
<tr valign="top"><td style="width: 65%">
<h2>Usage</h2>
<pre class='example'>
east [ -void <em>string</em>] [ <em>suitname</em> ... ]
hand {<em>hand string</em>} [ -void <em>string</em>] [ <em>suitname</em> ... ]
south <em>subcommand</em> [ <em>... args ...</em> ]
hand {<em>hand string</em>} <em>subcommand</em> [ <em>... args ...</em> ]
</pre>
These are very strange commands - they really have too much stuffed
into them. That's a historical anomoly which I'm reluctant to abandon.
<p>
With no subcommands, the routine is used for formatting the hand as
a string. For example, if south is:
<pre class='example'>
S: AJ5432
H: KT94
D: void
C: K93
</pre>
Then the results of various commands are:
<pre class='example'>
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}
</pre>
The -void switch exists precisely for formatting the output.
<p>
The various subcommands will be treated in seperate sections.
The <code>hand</code> version of this command only works with some subcommands.
</td><td style="width: 35%">
<div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C code
<dt>Location:</dt>
<dd><code>tcl_deal.c</code>, function <code>tcl_hand_cmd</code>
</dl>
</div>
</td>
<tr valign=top><td style="width: 65%">
<h2>Subcommand: <code>shape</code></h2>
<h3>Usage</h3>
<pre class='example'>
north shape
hand {AJTxx Axx JTxx x} shape
</pre>
<h3>Summary</h3>
Returns a list of suit lengths, in standard order.
<p>
For example, the second command above would return the list:
<pre class='example'>
5 3 4 1
</pre>
<h2>Subcommand: <code>pattern</code></h2>
<h3>Usage</h3>
<pre class='example'>
north pattern
hand {AJ32 A5 JTxx xxx} pattern
</pre>
<h3>Summary</h3>
Returns a sorted list of the suit lengths, starting with the longest.
For example, the second command above would return the list:
<pre class='example'>
4 4 3 2
</pre>
<h2>Subcommand: <code>is</code></h2>
<h3>Usage</h3>
<pre class='example'>
south is {<em>handstring</em>}
</pre>
<h3>Summary</h3>
This command pre-places a specific 13 cards. For voids, you can use
the "<code>-</code>" character:
<pre class='example'>
south is {AJ32 KT932 - Q876}
</pre>
Calls to this subcommand must occur before dealing begins, outside the
"<code><a href="#main">main</a></code>" command.
<p>
This subcommand calls the <a href="#stack_hand"><code>stack_hand</code> command.</a>
Inside the <code>main</code> code, the deal is already dealt.
<h2>Subcommand: <code>gets</code></h2>
<h3>Usage</h3>
<pre class='example'>
<em>handname</em> gets <em>card</em> [<em>card</em> ...]
</pre>
<h3>Summary</h3>
Puts a specific list of cards in the hand named. As with the
"<code>is</code>" subcommand, this must be called before dealing
starts, outside the "<code><a href="#main">main</a></code>" command.
The card is specified in two characters, a rank character and a suit
character:
<pre class='example'>
AS KH JH 9D
</pre>
This routine dispatches its data to <a href="#stack_cards">the <code>stack_cards</code> command.</a>
<h2>Subcommand: <code>has</code></h2>
<h3>Usage</h3>
<pre class='example'>
<em>handname</em> has <em>card</em> [<em>card</em> ...]
hand {<em>string</em>} has <em>card</em> [...]
</pre>
<h3>Summary</h3>
This returns a count of the cards listed that occur in the hand named.
<pre class='example'>
% south
AJ54 JT54 43 654
% south has SA HK HJ HT
3
</pre>
</td><td style="width: 35%"> </td></table>
<hr>
<h1>Control commands</h1>
<a name="accept"></a><a name="reject"></a>
<h2>Commands: <code>accept</code> and <code>reject</code></h2>
<table style="width: 100%" cellpadding=5><tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
accept [ [ if | unless ] <em>expr expr ...</em>]
reject [ [ if | unless ] <em>expr expr ...</em>]
</pre>
<h3>Summary</h3>
Without arguments, <code>accept</code> and <code>reject</code> are the
same as <span class='nobr'><code>return 1</code></span> and <span class='nobr'><code>return
0</code></span>, respectively.
<p>
With arguments it's a little more obscure.
<pre class='example'>
accept if {$h>4}
</pre>
This returns 1 if the expression matches. It is equivalent to:
<pre class='example'>
if {$h>4} { return 1 }
</pre>
The code:
<pre class='example'>
accept if {$h>4} {$s>4}
</pre>
Is logically equivalent to:
<pre class='example'>
if {$h>4 || $s>4} { return 1}
</pre>
That is, the values are accepted if either of the expressions
evaluates as true.
<p>
The <code>unless</code> option does the opposite:
<pre class='example'>
accept unless {$h>4} {$s>4}
</pre>
This is equivalent to:
<pre class='example'>
if {!($h>4) || !($s>4)} { return 1 }
</pre>
<p>
The means we return with a true value <em>unless</em> one of the expressions
is true. If one of the values is true, we simply go on to the next line.
<p>
<h3>Examples</h3>
Virtually all of the examples included in the release contain an
instance of "accept" or "reject."
<td style="width: 35%;">
<div class='programmer'>
<b>For Programmers</b>
<dl>
<dt>Implementation:</dt>
<dd>C code</dd>
<dt>Location:</dt>
<dd>tcl_deal.c, procedure <code>tcl_deal_control</code>.</dd>
</dl>
<p>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.</p>
</div>
<div class='tcl'>
<b>For Tcl Experts</b>
<p>There actually is one subtle and occasionally useful distinction
between <code>accept/reject</code> and the stated
<pre class='example'>if {...} { return ... }</code></pre>
<p>version. In reality:</p>
<pre class='example'>
accept if {$h>4} {$s>4}
</pre>
<p>is equivalent to:</p>
<pre class='example'>
if {$h>4||$s>4} {
return 1
}
expr 0
</pre>
This only matters when the command is the last
command in a procedure. The two procedures:
<pre class='example'>
proc A {h s} {
if {$h>4||$s>4} {
return 1
}
}
proc B {h s} {
accept if {$h>4} {$s>4}
}
</pre>
<p>are slightly different.</p>
<p>A call of <code>A 3 3</code> returns an empty string, while a call
of <code>B 3 3</code> returns 0. That can be useful, as you can see
here.</p>
</div>
</table>
<hr>
<a name="main"></a>
<h2>Command: <code>main</code></h2>
<table cellspacing=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
main {
<em>block of code</em>
}
</pre>
<h3>Summary</h3>
This defines the primary block of code evaluated after <em>each</em>
deal is generated. If the code <em>returns</em> true,
<b>Deal</b> will treat the deal as a "match" and call
<b>write_deal</b>. It will also increment its count of deals
found and exit if the limit is reached.
</td><td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt><dd>C code</dd>
<dt>Location:</dt><dd>tcl_deal.c, procedure <code>tcl_deal_control</code>.
</dl>
</div>
</table>
<hr>
<a name="whogets"></a>
<h2>Command: <code>whogets</code></h2>
<table cellspacing=5 style="width: 100%">
<tr valign=top><td style="width:65%">
<h3>Usage</h3>
<pre class='example'>
whogets <em>cardname</em>
</pre>
This returns the name of the person holding the card <em>cardname</em>.
</td><td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt><dd>C code</dd>
<dt>Location:</dt><dd>tcl_deal.c, procedure <code>tcl_deal_to_whom</code>.
</dl>
</div>
</table>
<hr>
<a name="deal_finished"></a>
<h2>Command: <code>deal_finished</code></h2>
<table cellspacing=5 style="width: 100%">
<tr valign=top><td style="width:65%">
<h3>Usage</h3>
<pre class='example'>
deal_finished {
<em>block of code</em>
}
</pre>
This defines the code called at the completion of generating all deals.
This is code you would use to dump statistics, for example.
</td><td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt><dd>C code</dd>
<dt>Location:</dt><dd>tcl_deal.c, procedure <code>tcl_after_set</code>.
</dl>
</div>
</table>
<hr>
<h1>Bridge Evaluators</h1>
<h2>Common interfaces</h2>
There are some standard interfaces to bridge evaluation functions.
<a name="handInterface"></a>
<h3>Hand Procedures</h3>
Any procedure defined entirely based on the values in one hand is considered
a <em>hand procedure</em>. These procedures can be called in one of two
ways:
<pre class='example'>
Weak2Bid <em>handname</em>
Weak2Bid hand {AKQxxx xxx xxx x}
</pre>
The <em>handname</em> parameter can be one of
<code>north</code>, <code>south</code>, <code>east</code>, <code>west</code>.
<a href="#shapes">Shape procedures</a> and <a href="#holdingp">holding
procedures</a> fit the hand procedure calling method, along with other
options.
<hr>
<a name="shapes"></a>
<h3>Shape procedures</h3>
Any procedure defined on the shape of a hand can be called with one of
the following methods:
<pre class='example'>
balanced <em>handname</em>
balanced hand {AJxx xxx AKxx Kx}
balanced eval 4 3 4 2
balanced shape {4 3 4 2}
semibalanced <em>handname</em>
semibalanced hand {AJ432 AKx Kx xxx}
semibalanced eval 5 3 2 3
semibalanced shape {5 3 2 3}
</pre>
This follows the <a href="#hand">hand procedure</a> outline with the
addition of the <code>eval</code> option.
<p>
<hr>
<a name="holdingp"></a>
<h3>Holding procedures</h3>
A holding procedure is a <a href="#handInterface">hand procedure</a>
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,
<a href="#defvector"><code>defvector</code></a> and
<a href="#holdingProc"><code>holdingProc</code></a>.
<p> This is an
abstraction of a very common bridge evaluation technique. The most
commonly used holding functions are <em>high card points</em>,
<em>losing trick count</em>, <em>controls</em>. For example, when
counting the losers in the hand <code>AKxx Axx KQJxxx x</code>, 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. <p> The interface lets
you evaluate the entire hand, or only selected suits in a hand, or
a specific list of holdings.
<pre class='example'>
hcp <em>handname</em> [ <em>suitname</em> ... ]
hcp hand {AKJxxx K xxx xxx} [ <em>suitname</em> ... ]
hcp holding AK43 [ ... ]
</pre>
In the first two cases, if no suits are named, all suits are evaluated, and
the results are accumulated. In the case of the <code>holding</code> call,
the specific holdings passed in are evaluated.
<p>
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:
<pre class='example'>
openingLead holding KQJ7 => K
openingLead south => {K} {7 2} {4} {J}
</pre>
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.
<hr>
<a name="balanced"></a>
<a name="semibalanced"></a>
<h2>Command: <code>balanced</code> and <code>semibalanced</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
balanced <em>handname</em>
balanced hand {<em>text hand</em>}
balanced eval <em>s</em> <em>h</em> <em>d</em> <em>c</em>
</pre>
<h3>Summary</h3>
These are both <a href="#shapes">shape procedures</a>.
<p>
<code>balanced</code> returns true if the hand is some 4333, 4432, or 5332
without a 5-card major.
<p>
<code>semibalanced</code> returns true if the hand has no singletons
or voids, not six-card majors, and no seven-card minors.
<td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd><code>Tcl</code> with <code>shapecond</code>
<dt>Location:</dt>
<dd><code>lib/features.tcl</code>
</dl>
<p>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.</p>
</div>
</table>
<hr>
<a name="clubs"></a>
<a name="diamonds"></a>
<a name="hearts"></a>
<a name="spades"></a>
<h2>Commands: <code>clubs</code>, <code>diamonds</code>, <code>hearts</code>, <code>spades</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
<code>spades</code> <em>handname</em>
<code>spades</code> <code>hand</code> <code>{AKxx Axx AJxx Kx}</code>
</pre>
These implement the <a href="#hand">hand procedure</a> interface, and
return the suit lengths for the appropriate suit.
<td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>
<dt>Location:</dt>
<dd><code>tcl_deal.c</code>, function <code>tcl_suit_count</code>
</dl>
<p>These could be <em>shape procedures</em> but for speed reasons, I've
left them this way.</p>
</div>
</table>
<hr>
<h1>Holding Evaluators</h1>
<a name="hcp"></a>
<h2>Command: <code>hcp</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
hcp <em>handname</em>
hcp <em>handname</em> <em>suitname</em> [<em>suitname</em> ...]
hcp hand {<em>s h d c</em>}
hcp hand {<em>s h d c</em>} <em>suitname</em> [<em>suitname</em> ...]
</pre>
This procedure computes standard high card points - ace is 4, king
is 3, queen is 2, jack is 1. The procedure implements the
<a href="#holdingp">holding procedure</a> interface.
<td style="width: 35%"><div class='programmer'>
<b>For Programmers</b>
<dl>
<dt>Implementation:
<dd>C code
<dt>Location:
<dd>Built with additive.c, <code>tcl_create_additive</code>
and deal.c, <code>count_hcp</code>
</dl>
</div>
</table>
<hr>
<a name="newLTC"></a>
<h2>Command: <code>newLTC</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
newLTC <em>handname</em>
newLTC <em>handname</em> <em>suitname</em> [<em>suitname</em> ...]
newLTC hand {<em>s h d c</em>}
newLTC hand {<em>s h d c</em>} <em>suitname</em> [<em>suitname</em> ...]
</pre>
<p>Rex Livingston provided this implementation of the <a href="http://en.wikipedia.org/wiki/Losing_trick_count#New_Losing_Trick_Count_.28NLTC.29">New Losing Trick Count</a>, from a 2003 Bridge World article.</p>
<p>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.
<td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl code
<dt>Location:</dt>
<dd>lib/features.tcl</dd>
</dl>
</div>
</table>
<hr>
<a name="losers"></a>
<h2>Command: <code>losers</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
losers <em>handname</em>
losers <em>handname</em> <em>suitname</em> [<em>suitname</em> ...]
losers hand {<em>s h d c</em>}
losers hand {<em>s h d c</em>} <em>suitname</em> [<em>suitname</em> ...]
</pre>
This implements a <a href="#holdingp">holding procedure</a> which
computes the number of <em>half losers</em>. 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.
<td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C code
<dt>Location:</dt>
<dd>Built with additive.c, <code>tcl_create_additive</code>
and deal.c, <code>count_losers</code>
</dl>
It is probably better to reimplement in <code>Tcl</code> using
<a href="#holdingProc"><code>holdingProc</code></a>.
</div>
</table>
<hr>
<a name="binky"></a>
<h1>Binky Points Evaluators</h1>
<p>Binky Points are described in my <a href="http://bridge.thomasoandrews.com/valuations/">hand evaluations articles.</a></p>
<p>Binky Points are designed so that sum of your partnership's Binky Point values comes as close as possible to the number of tricks that your partnership can make, double dummy.</p>
<a name="binky_suit"></a>
<a name="binky_nt"></a>
<h2>Commands: <code>binky::suit</code> and <code>binky::nt</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
source lib/binky.tcl
binky::nt <em>handname</em>
binky::nt hand {<em>s h d c</em>}
binky::suit <em>handname</em>
binky::suit hand {<em>s h d c</em>}
</pre>
These two functions are <a href="#handInterface">hand procedures</a> which
computes the Binky Point values for a hand.
<td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl code
<dt>Location:</dt>
<dd><code>lib/binky.tcl</code> and <code>lib/binky-data.tcl</code>
</dl>
</div>
</table>
<h1>Bridge Logic and Utilities</h1>
<a name="lho"></a>
<a name="rho"></a>
<a name="partner"></a>
<h2>Commands: <code>lho</code>, <code>partner</code>, <code>rho</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign="top"><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
lho <em>handname</em>
rho <em>handname</em>
partner <em>handname</em>
</pre>
<h3>Summary</h3>
These routines accept one hand name and return another. For example,
"<code>lho north</code>" returns "<code>east</code>," and
"<code>partner east</code>"
returns "<code>west</code>."
<td style="width: 35%"><div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C code
<dt>Location:</dt>
<dd><code>tcl_deal.c</code>, function <code>tcl_other_hand</code>
</dl>
</div>
</table>
<hr>
<a name="holding"></a>
<h2>Commands: <code>holding</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
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 => ""
</pre>
<h3>Summary</h3>
<td style="width: 35%"><div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C code
<dt>Location:</dt>
<dd><code>holdings.c</code>, function <code>IDeal_HoldingCmd</code>
</dl>
</div>
</table>
<hr>
<a name="score"></a>
<h2>Command: <code>score</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
source lib/score.tcl
...
score <em>contract</em> <em>vulnerability</em> <em>tricks</em>
</pre>
<h3>Summary</h3>
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.
<p>
The <em>contract</em> is passed as a list:
<pre class='example'>
2 spades
2 spades undoubled
4 clubs doubled
6 notrump redoubled
</pre>
The <em>vulnerablity</em> is one of the words <code>vul</code> or
<code>nonvul</code>.
<p>
The <em>tricks</em> is the number of tricks taken by declarer.
<h3>Examples</h3>
<pre class='exaample'>
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
</pre>
<td style="width: 35%"><div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl
<dt>Location:</dt>
<dd><code>score.tcl</code>
</dl>
</div>
</table>
<hr>
<a name="dds"></a>
<h1>Double Dummy Solver</h1>
<p>Starting with Deal 3.1, I've included simple access to <a href='http://web.telia.com/~u07502278/'>Bo Haglund's double-dummy solver library.</a></p>
<a name="deal::tricks"></a>
<h2>Command: <code>deal::tricks</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal::tricks <em>declarer</em> <em>denomination</em>
</pre>
<h3>Summary</h3>
<p><code>deal::tricks</code> returns the maximum number of tricks makable by <em>declarer</em> in the given <em>denomination</em>.
<p><em>declarer</em> must be one of "north", "east", "south", or "west." By default, it is "south."</p>
<p><em>denomination</em> must be a suit name or "notrump." The default value is "notrump."</p>
<p>By default, deal::tricks uses the <a href="#tricks"><code>tricks</code></a> function, which calls Bo Haglund's double-dummy solver.</p>
<p>However, if you include "lib/gib.tcl", <code>deal::tricks</code> will call the GIB double dummy solver.</p>
<p><code>deal::tricks</code> 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.</p>
<p>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:</p>
<pre class='example'>
foreach denom {clubs diamonds hearts spades notrump} {
foreach hand {north east south west} {
set tricks [deal::tricks $hand $denom]
...
}
}
</pre>
<td style="width: 35%"><div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl</dd>
<dt>Location:</dt>
<dd><code>lib/features.tcl</code>
</dl>
</div>
</table>
<hr>
<a name="tricks"></a>
<h2>Command: tricks</h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
tricks [ <em>declarer</em> [ <em>denomination</em> [ <em>goal</em> ] ] ]
</pre>
<h3>Summary</h3>
<p>Unless you are using the <em>goal</em> parameter, you will probably want to use the <a href="#deal::tricks"><code>deal::tricks</code></a> command, since it has the
advantage of caching values.</p>
<p>When no goal is passed, "tricks" returns the maximum number of tricks makable by <em>declarer</em> in the given <em>denomination</em>.
<p>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.
<p><em>declarer</em> must be one of "north", "east", "south", or "west." By default, it is "south."</p>
<p><em>denomination</em> must be a suit name or "notrump." The default value is "notrump."
<p><em>goal</em> 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.</p>
<td style="width: 35%"><div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C, C++</dd>
<dt>Location:</dt>
<dd><code>dds.cpp, tcl_dds.c</code>
</dl>
</div>
</table>
<hr>
<a name="ddscmd"></a>
<h2>Command: dds</h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
dds [-reuse | -noreuse] [-diagram <em>diagram</em>] [-goal <em>goal</em>]
[-leader <em>leader</em>] [-trick <em>list of cards</em> [-trick <em>cards</em> ] ...] [ <em>declarer</em> [ <em>denomination</em> ] ]
</pre>
<h3>Summary</h3>
<p>The <code>dds</code> command gives even more refined access to Bo Haglund's double dummy engine, including the ability to solve problems with fewer than 52 cards.
<p>The <code>-reuse</code> flag tells the double-dummy solver to reuse the data it generated from the last call. For example, if the deal is identical to the previous call and played in the same denomination, you'll want to reuse the data.
<p>The <code>-noreuse</code> flag tells the double-dummy solver not to reuse the data. This is the default.
<p>The <code>-diagram</code> 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.
<p>The <code>-leader</code> flag tells the double-dummy solver who is on lead to the current trick.
<p>The <code>-trick</code> flag gives a list of cards played to the current trick.
<p>For example, to solve George Coffin's "Avoidance" end position from his <a href="http://www.rpbridge.net/9p01.htm">Great 88</a>, you would write:
<pre class='example'>
set diagram {
{A987 - A -}
{Q5 987 - -}
{64 K2 2 -}
{K2 AQ3 - -}
}
set tricks [dds -leader south -diagram $diagram south notrump]
...
</pre>
<p>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:
<pre class='example'>
set tricks [dds -leader south -diagram $diagram -trick 4S south notrump]
</pre>
You can also pass full tricks, as in:
<pre class='example'>
set tricks [dds -leader west -diagram $diagram -trick {4S KS 7S 5S} south notrump]
</pre>
<p>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.
<p>There are example tests of all the Great 88 in the file <code>tests/great88</code> that is included in this release.
</td>
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C, C++</dd>
<dt>Location:</dt>
<dd><code>dds.cpp, tcl_dds.c</code>
</dl>
</div>
</table>
<hr>
<a name="parscore"></a>
<h2>Command: <code>parscore</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
source lib/parscore.tcl
...
set result [parscore <em>dealer</em> <em>vul</em>]
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]
</pre>
<h3>Summary</h3>
This computes the double-dummy par result for the current deal.
<p>
The parscore routine returns a list of five values - the contract (in
the same form that is used by the <a href="#score"><code>score</code></a>
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.
<p>
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.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl
<dt>Location:</dt>
<dd><code>parscore.tcl</code>
</dl>
</div>
</table>
<hr>
<a name="gibstuff"></a>
<h1>GIB-related routines</h1>
These next routines use calls to the GIB double-dummy engine. You must have
a licensed version of <a href="http://www.gibware.com/">GIB</a>
installed on your computer for these routines to work. Also, these
routines only work on Windows at the moment.
<p>
<a name="gib::directory"></a>
<h2>Command: <code>gib::directory</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
source lib/gib.tcl
...
gib::directory <em>path</em>
</pre>
<h3>Summary</h3>
This tells the GIB-related routines where GIB is installed.
<p>
If this routine is not called, it defaults to GIB's default install
directory, <span class='nobr'><code>C:/Program Files/GIB</code>.</span>
<p>
<em>Note: your path should include forward slashes '<code>/</code>',
even on Windows.</em>
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl</dd>
<dt>Location:</dt>
<dd><code>gib.tcl</code>
</dl>
</div>
</table>
<hr>
<a name="gib::tricks"></a>
<h2>Command: <code>gib::tricks</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
source lib/gib.tcl
...
gib::tricks <em>declarer</em> <em>denomination</em>
</pre>
<h3>Summary</h3>
<p>You probably want to use the <a href="#deal::tricks"><code>deal::tricks</code></a> command, even when using GIB's double dummy solver.
<p><em>Denomination</em> can be a suit name or "<code>notrump</code>."
<em>Declarer</em> can be any hand name.
<p>
This routine returns the double-dummy number of tricks available
in this deal, in the given denomination by the given declarer.
<p>
If GIB is installed anywhere unusual, you will need to call
<a href="#gib::directory"><code>gib::directory</code></a> before
<code>deal::tricks</code> is called.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl</dd>
<dt>Location:</dt>
<dd><code>gib.tcl</code>
</dl>
</div>
</table>
<hr>
<h1>Bridge Command Builders</h1>
<p>A number of common types of bridge functions can easily be implemented to
run quickly via lookup tables, including
<a href="#holdingp">holding</a> and <a href="#shape">shape</a> procedures.
Deal lets the user take advantage of these two sorts of lookup procedures
relatively easily</p>
<a name="defvector"></a>
<h2>Command: <code>defvector</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
defvector <em>vec</em> <em>aceVal</em> [ <em>kingVal</em> ... ]
<em>vec</em> <em>handname</em>
<em>vec</em> <code>hand</code> {<em>text hand</em>}
<em>vec</em> <em>handname</em> <em>suitname</em> [ <em>suitname</em> ... ]
<em>vec</em> <em>handname</em> <em>suitname</em> [ <em>suitname</em> ... ]
<em>vec</em> <code>hand</code> {<em>text hand</em>} <em>suitname</em> ...
</pre>
<h3>Summary</h3>
This defines a <a href="#holdingp">holding procedure</a> which assigns
integer values to the various cards in the hand. For example
<pre class='example'>
defvector hcp6421 6 4 2 1
</pre>
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.
<p>
Vectors are limited to being integer-valued. For more complicated
holding procedures, use <a href="#holdingProc"><code>holdingProc</code></a>.</p>
<td style="width: 35%">
<div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C</dd>
<dt>Location:</dt>
<dd><code>vector.c</code></dd>
</dl>
<p>Vectors are slighly faster than their equivalent
<a href="#holdingProc"><code>holdingProc</code></a>. They are an
old optimization which remain mostly for backwards compatibility.
</div>
</table>
<hr>
<a name="holdingProc"></a>
<h2>Command: <code>holdingProc</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
</pre>
<p>
Temporarily, see the <a href="holding.html">seperate documentation</a>.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl>
<dt>Implementation: <dd>C
<dt>Location: <dd><code>holdings.c</code>, function <code>IDeal_DefHoldingProc</code>
</dl>
</div>
</table>
<hr>
<a name="shapeclass"></a>
<a name="shapecond"></a>
<a name="shapefunc"></a>
<h2>Commands: <code>shapeclass</code>, <code>shapecond</code>, and <code>shapefunc</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
shapeclass <em>name</em> {... <em>code</em> ...}
shapecond <em>name</em> {<em>expr</em>}
shapefunc <em>name</em> {... <em>code</em> ...}
<em>name</em> [ north | south | east | west ]
<em>name</em> eval <em>s</em> <em>h</em> <em>d</em> <em>c</em>
<em>name</em> shape {<em>s</em> <em>h</em> <em>d</em> <em>c</em>}
</pre>
A shape class (or equivalently, a shape condition) also has the list
subcommand:
<pre class='example'>
<em>name</em> list
</pre>
<h3>Summary</h3>
These commands create new procedures which fit the <a href="#shapes">shape
function</a> interface.
<p>
<code>shapeclass</code> and <code>shapecond</code> define procedures which returns boolean
values. <code>shapefunc</code> can return any type of data.
<code>shapecond</code> is actually an alias:
<pre class='example'>
shapecond <em>name</em> {<em>expr</em>}
</pre>
is the equivalent of:
<pre class='example'>
shapeclass <em>name</em> {
if {<em>expr</em>} {
return 1
} else {
return 0
}
</pre>
The <em>code</em> or <em>expr</em> is allowed to use the variables
<code>s</code>, <code>h</code>, <code>d</code>, or <code>c</code>.
<p>
More details can be found in the
<a href="advanced.html#shapefunc">Advanced Guide</a>.
<p>
The <code>list</code> subcommand for shape classes returns a list of
shapes that are in the class.
<p>
Why are there two subcommands, "eval" and "shape" which do the
roughly the same things?
<p>
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:
<pre class='example'>
shapecond Balanced {[SemiBalanced eval $s $h $d $c] && $s<5 && $h<5}
</pre>
On the other hand, if you have a shape - output by the, say, a
call to [north shape] you can evaluate it as:
<pre class='example'>
SemiBalanced shape [north shape]
</pre>
In fact, this is exactly equivalent to calling
<pre class='example'>
SemiBalanced north
</pre>
only slightly slower.
<p>Since these routines cache results in memory and use lookup
tables, you should not use any external state or global variables
inside them.
<td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation: <dd>C
<dt>Location: <dd><code>dist.c</code>, functions <code>tcl_shapeclass_define</code>,
<code>tcl_shapecond_define</code>, and <code>tcl_shapefunc_define</code>
</dl>
</div>
</table>
<hr>
<a name="patternclass"></a>
<a name="patterncond"></a>
<a name="patternfunc"></a>
<h2>Commands: <code>patternclass</code>, <code>patterncond</code>, and <code>patternfunc</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
patternclass <em>name</em> {... <em>code</em> ...}
patterncond <em>name</em> {<em>expr</em>}
patternfunc <em>name</em> {... <em>code</em> ...}
<em>name</em> [ north | south | east | west ]
<em>name</em> eval <em>s</em> <em>h</em> <em>d</em> <em>c</em>
<em>name</em> shape {<em>s</em> <em>h</em> <em>d</em> <em>c</em>}
</pre>
A pattern class (or equivalently, a shape condition) also has the list
subcommand:
<pre class='example'>
<em>name</em> list
</pre>
<h3>Summary</h3>
These commands create new procedures which fit the <a href="#shapes">shape
function</a> interface.
<p>
<code>patternclass</code> and <code>patterncond</code> define procedures which returns boolean
values. <code>patternfunc</code> can return any type of data.
<code>patterncond</code> is actually an alias:
<pre class='example'>
patterncond <em>name</em> {<em>expr</em>}
</pre>
is the equivalent of:
<pre class='example'>
patternclass <em>name</em> {
if {<em>expr</em>} {
return 1
} else {
return 0
}
</pre>
The <em>code</em> or <em>expr</em> is allowed to use the variables
<code>l1</code>, <code>l2</code>, <code>l3</code>, or <code>l4</code>, the suit lengths in descending order.
<p>
The <code>list</code> subcommand for pattern classes returns a list of
shapes (not patterns) that are in the class.
<p>
Why are there two subcommands, "eval" and "shape" which do the
roughly the same things?
<p>
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:
<pre class='example'>
shapecond Balanced {[SemiBalanced eval $s $h $d $c] && $s<5 && $h<5}
</pre>
On the other hand, if you have a shape - output by the, say, a
call to [north shape] you can evaluate it as:
<pre class='example'>
SemiBalanced shape [north shape]
</pre>
In fact, this is exactly equivalent to calling
<pre class='example'>
SemiBalanced north
</pre>
only slightly slower.
<p>Since these routines cache results in memory and use lookup
tables, you should not use any external state or global variables
inside them.
<td style="width: 35%">
<div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation: <dd>Tcl
<dt>Location: <dd><code>features.tcl</code>
</dl>
</div>
</table>
<hr>
<a name="statistics"></a>
<h1>Statistics</h1>
<a name="sdev"></a>
<h2>Command: <code>sdev</code></h2>
<table cellpadding=5 style="width: 100%">
<tr><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
sdev <em>name</em>
<em>name</em> add <em>data</em> [ <em>data</em> ... ]
<em>name</em> count
<em>name</em> average
<em>name</em> sdev
<em>name</em> rms
</pre>
<h3>Summary</h3>
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.
<p>
</td><td style="width: 35%">
<div class='programmer'><b>For Programmers</b><br>
<dl><dt>Implementation:</dt><dd>C code</dd>
<dt>Location:</dt><dd>stat.c, function <code>tcl_sdev_define</code>.
</dl>
<p>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.</p>
</div>
</table>
<hr>
<a name="correlation"></a>
<h2>Command: <code>correlation</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign="top"><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
correlation <em>name</em>
<em>name</em> add <em>xval</em> <em>yval</em> [ <em>xval</em> <em>yval</em> ... ]
<em>name</em> count
<em>name</em> correlate
<em>name</em> average [ x | y ]
<em>name</em> sdev [ x | y ]
<em>name</em> rms [ x | y ]
</pre>
<h3>Summary</h3>
The <code>correlation</code> declaration defines a routine much like
the <code>sdev</code> command, but each datapoint is a pair of values,
and it computes the linear correlation between the <em>x</em> and <em>y</em>
values.
<p>
You can also get individual data for the <code>x</code> and <code>y</code>
values.
<p>
If there is no data, it returns an error on <code>average</code>,
<code>correlate</code>, <code>sdev</code> and <code>rms</code>.
<p>
If there is only one pair entered, it will throw an error on
<code>sdev</code>.
<p>
</td><td style="width: 35%">
<div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt><dd>C code</dd>
<dt>Location:</dt><dd>stat.c, function <code>tcl_correlation_define</code>.
</dl>
<p>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.</p>
</div>
</table>
<h1>Utility Procedures </h1>
<a name="exitflag"></a>
<h2>Command Line: -x flag</h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal -x <em>filename</em> <arg> <arg> ...
</pre>
<p>The '-x' flag tells deal to source the file and then exit.</p>
<p>Before doing so, Deal puts remaining arguments into the variables <code>argc</code> and <code>argv</code>, and sets <code>argv0</code> to the filename of the script.
<p>This is useful if you want to skip the entire deal loop, and process stuff on your own. For example, the code in <code>tests/great88</code> 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.</p>
</td>
<td></td>
</table>
<a name="full_deal"></a>
<h2>Command: <code>full_deal</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
set deal [full_deal]
</pre>
<p>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 <a href="#ddscmd"><code>dds</code></a> with the <code>-diagram</code> flag, or remembering a deal after the end of the loop.
</td>
<td></td>
</table>
<a name="seed_deal"></a>
<h2>Command: <code>seed_deal</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
seed_deal <em>number</em>
</pre>
<h3>Command Line: -s</h3>
<pre class='example'>
$ deal -s <em>number</em> ...
</pre>
<h3>Summary</h3>
<p><code>seed_deal</code> is used to seed the random number generator, to make sure that Deal generates the same sequence of
random numbers.
<p>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 <code>main</code> inner loop, you should add the command "finish_deal" to the <code>main</code> section.
<pre class='example'>
main {
finish_deal
...
}
</pre>
<p>That bypasses some optimizations and forces an entire deal to be generated each time through <code>main</code>.
</table>
<a name="deal_deck"></a>
<h2>Command: <code>deal_deck</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal_deck
</pre>
<h3>Summary</h3>
<code>deal_deck</code> is called at every new deal,
even when all 52 cards are specified (<em>stacked</em>) precisely.
Imagine stacking cards as stacking them in an undealt <em>deck</em>,
but that the cards are only distributed to the hands when
<code>deal_deck</code> is called.
<p>
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 <a href="#deal::input">input formats.</a>
<p>
Stacked cards are permanently stacked until the deck is reset. In this code:
<pre class='example'>
stack_hand south {AKQ32 AJ53 K54 2}
deal_deck
deal_deck
puts [south spades]
</pre>
The output is "AKQ32". Use <a href="#reset_deck"><code>reset_deck</code></a>
to undo card stackings.
<p>
The <code>deal_deck</code> procedure does one thing rather complicated
when it is called, the first thing it does is execute all
code registered with the
<a href="#deal_reset_cmd"><code>deal_reset_cmds</code></a>.
This allows the script writer to do one of several things before
the deal is generated:
<ul>
<li>Delete metadata related to the deal. For example, the first time
the user calls <code>deal::tricks south spades</code> 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
<code>deal_deck</code>.
<li>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 <a href="#smartstack">smart stacking.</a>
</ul>
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C
<dt>Location:</dt>
<dd><code>tcl_deal.c</code>, function <code>tcl_deal_deck</code>
</dl>
</div>
</table>
<hr>
<a name="reset_deck"></a>
<h2>Command: <code>reset_deck</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
reset_deck
</pre>
<h3>Summary</h3>
This forgets about all stacked cards. The <em>deck</em>, from <em>Deal</em>'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
<a href="#deal_deck">deal_deck</a>.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C
<dt>Location:</dt>
<dd><code>tcl_deal.c</code>, function <code>tcl_reset_deck</code>
</dl>
</div>
</table>
<hr>
<a name="stack_hand"></a>
<a name="stack_cards"></a>
<h2>Commands: <code>stack_hand</code> and <code>stack_cards</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
stack_hand <em>handname</em> <em>hand</em>
stack_cards <em>handname</em> <em>suitname</em> <em>holding</em> [...]
</pre>
<h3>Summary</h3>
By default, these two routines just call <a href="#deck_stack_hand">
deck_stack_hand and deck_stack_cards,</a>
respectively - that is, they forcibly place cards in the deck.
<p>
But these routines are meant to be overridden. For example, when using
one of the <em>input formats</em> which reads deals from a file,
the format will redefine these two procedures to give errors.
<pre class='example'>
% deal -I "line foo.txt" -e "stack_cards south spades AJ"
Tcl stack dump of error info:
No card stacking with input format ::line
<em>...</em>
</pre>
A more complicated re-definition occurs in the <a name="#smartstack">
<code>smartstack</code> input format,</a> which alters its hand
generation depending on what cards are stacked where.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl>
<dt>Implementation:</dt>
<dd>C</dd>
<dt>Location:</dt>
<dd><code>hand.c</code>, function <code>tcl_stack_hand</code> and
<code>tcl_stack_cards</code>
</dl>
</div>
</table>
<hr>
<a name="deck_stack_hand"></a>
<a name="deck_stack_cards"></a>
<h2>Commands: <code>deck_stack_hand</code> and <code>deck_stack_cards</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deck_stack_hand <em>handname</em> <em>hand</em>
deck_stack_cards <em>handname</em> <em>suitname</em> <em>holding</em> [...]
</pre>
<h3>Summary</h3>
These routines are the "underlying" deck-stacking routines. Any cards
stacked with these routines remain stacked until the next call to
<a href="#reset_deck"><code>reset_deck</code></a>
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl>
<dt>Implementation:</dt>
<dd>C</dd>
<dt>Location:</dt>
<dd><code>hand.c</code>, function <code>tcl_stack_hand</code> and
<code>tcl_stack_cards</code>
</dl>
</div>
</table>
<hr>
<a name="stacked"></a>
<h2>Command: <code>stacked</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
stacked <em>handname</em>
</pre>
<h3>Summary</h3>
Determines what cards are stacked to this hand, returning them as
a list of holdings:
<pre class='example'>
south gets AS KH 3H QD JD TC 9C 8C
puts [stacked south]
</pre>
writes out the list:
<pre class='example'>
A K3 QJ T98
</pre>
This is useful for the <a href="#smartstack">smartstacker</a>, because
we don't want to force the user to stack cards *after* specifying conditions.
<pre class='example'>
stack_hand north {AJT KT3 KJ 75432}
deal::input smartstack south balanced hcp 20 21
</pre>
The call to <code>stack_hand</code> occurs before <code>smartstack</code>
is loaded, so <code>stack_hand</code> has not been redefined. So what
<code>smartstack</code> does is read the cards already stacked, and
use that for its initial conditions.
<p>
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C</dd>
<dt>Location:</dt>
<dd><code>tcl_deal.c</code>, function <code>tcl_stacked_cards</code>
</dl>
</div>
</table>
<hr>
<a name="deal::nostacking"></a>
<h2>Command: <code>deal::nostacking</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
::deal::nostacking
</pre>
<h3>Summary</h3>
This procedure redefines the <a href="#stack_hand">stack_hand and
stack_cards</a> procedures to generate error messages, and
generates an error if any cards are currently stacked.
<p>
This is used in all of the input formats which read complete deals from
files, and thus are incompatible with stacking.
<td style="width: 35%"><div class='programmer'>
<b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl code</dd>
<dt>Location:</dt>
<dd><code>lib/features.tcl</code>, function <code>deal::nostacking</code>
</dl>
</div>
</table>
<hr>
<a name="deal_reset_cmds"></a>
<h2>Command: <code>deal_reset_cmds</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal_reset_cmds {<em>...code...</em>} [ ... ]
</pre>
<h3>Summary</h3>
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
<a href="#deal_deck"><code>deal_deck</code></a> procedure, which, unless
you are doing something complicated, means it is called at the beginning
of each time through the evaluation loop.
<p>
<code>deal_reset_cmds</code> can be used so that metadata about the previous deal,
such as cached values and the like, are unset. See
<a href="#deal::metadata"><code>deal::metadata</code></a>.
<p>
It is also used for defining <a href="#deal::input">input formats,</a>
so that deals can be read from files. For example, the "line" input format
has the following routine declared:
<pre class='example'>
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}
}
}
</pre>
<p>
The key is that when <code>line::next</code> is done, it re-registers itself, making
sure that it is called next time through as well.
<p>
The <em>code</em> passed in to <code>deal_reset_cmds</code> 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.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>C</dd>
<dt>Location:</dt>
<dd><code>tcl_deal.c</code>, function <code>add_reset_cmds</code>
</dl>
</div>
</table>
<hr>
<a name="deal::metadata"></a>
<h2>Command: <code>deal::metadata</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal::metadata <em>name</em> {<em>...code...</em>}
</pre>
<h3>Summary</h3>
Currently, this is just a peculiar way of caching slow evaluation routines.
At the moment, the only place it is used is in
<a href="#deal::tricks"><code>deal::tricks</code></a>.
<p>
When you call <code>deal::metadata</code>, it will check to see if
there is a value associated with the <em>name</em> requested
already. If there is, the value is returned. If it does not, it evaluates the
specified code and associates the result with the <em>name</em>. The key
is, when the next deal is being analyzed, all the cached values are pitched.
<p>
This isn't really necessary or efficient in most cases, but with
evaluations which take some time, <em>e.g.</em> GIB calls, it
improves things.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd><code>Tcl</code>
<dt>Location:</dt>
<dd><code>lib/features.tcl</code>
</dl>
<p>In later releases, metadata read from input streams (say, the fields
from a PBN file) will also be stored here.
<p>
This procedure uses
<a href="#deal_reset_cmds"><code>deal_reset_cmds</code></a>.
The metadata is cleared each time the <code>deal_deck</code>
command is called.
</div>
</table>
<hr>
<h1>Input formats</h1>
<a name="deal::input"></a>
<h2>Command: <code>deal::input</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal::input <em>formatName</em> <em>args</em>
</pre>
<h3>Summary</h3>
The <code>deal::input</code> command is used to define an input source
for deals. It works as follows:
<ol>
<li>The file <code>input/<formatName>.tcl</code> is loaded. This
Tcl file should define a new Tcl 'namespace' with the name <em>formatName</em>,
with member procedures named <code>set_input</code> and <code>next</code>.
<li>Deal then calls
<code><formatName>::set_input <em>args</em></code>, which should
initialize the format reading. Usually, the argument(s) are one argument
representing the source file.
<li>The next deal, <code><formatName>::next</code> is called.
</ol>
</td>
<td style="width: 35%">
<div class='programmer'><b>For Programmers</b>
<dl>
<dt>Implementation:</dt>
<dd>Tcl code</dd>
<dt>Location:</dt>
<dd>lib/features.tcl</dd>
</dl>
</div></table>
<hr>
<a name="giblib"></a><a name="library.dat"></a>
<h2>Input Format: <code>giblib</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal::input giblib [<em>filename</em>]
</pre>
or on the command line:
<pre class='example'>
% deal -I giblib
</pre>
or
<pre class='example'>
% deal -I "giblib <em>filename</em>"
</pre>
<h3>Summary</h3>
<p>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 <a href="#deal::tricks"><code>deal::tricks</code></a>
will not entail calls to the GIB binaries.</p>
<p>
If no filename is given, the library tries to read from a file called
"library.dat" in the current directory.
<p>
The <code>-I</code> command-line flag is a quick alias for
<code>deal::input</code>, passing the next argument as
Tcl arguments to the <code>deal::input</code> command.
<td style="width: 35%">
<div class='programmer'><b>For Programmers</b>
<dl>
<dt>Implementation:</dt>
<dd>Tcl code</dd>
<dt>Location:</dt>
<dd>input/giblib.tcl</dd>
</dl>
<p>This procedure uses <a href="#deal_reset_cmds">deal_reset_cmds</a>.</p>
</div>
</table>
<hr>
<a name="line"></a>
<h2>Input Format: <code>line</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal::input line [<em>filename</em>]
</pre>
<h3>Summary</h3>
<p>Specifies that deals are read from the specified file in the format
written by Deal's "-l" option.
<p>
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:
<pre class='example'>
% deal -l 100000 > sample
% deal -e "deal::input line sample" -i query1
% deal -e "deal::input line sample" -i query2
</pre>
[ The <code>-e</code> option just evaluates the code in the next
argument as Tcl code. Alternative, you can use the <code>-I</code>
option, which is shorthand for input formats:
<pre class='example'>
% deal -I "line sample" -i query1
</pre>
The <code>-I <em>args</em></code> option is exactly the same as -e "deal::input <em>args</em>".]
<td style="width: 35%">
<div class='programmer'><b>For Programmers</b>
<dl>
<dt>Implementation:</dt>
<dd>Tcl code</dd>
<dt>Location:</dt>
<dd>input/line.tcl</dd>
</dl>
</div>
</table>
<a name="ddline"></a>
<h2>Input Format: <code>ddline</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal::input line [<em>filename</em>]
</pre>
<h3>Summary</h3>
<p>Specifies that deals are read from the specified file in the format
written by Deal's <a href="#format:ddline"><code>ddline</code> format.</a>
<p>The ddline format include doubled-dummy tricks data, so when using <code>ddline</code> for input, calls to <a href="deal::tricks">deal::tricks</a> return the data read from the file.
<td style="width: 35%">
<div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl code</dd>
<dt>Location:</dt>
<dd>input/line.tcl</dd>
</dl>
</div>
</table>
<a name="smartstack"></a>
<h2>Input: <code>smartstack</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
deal::input smartstack <em>hand</em> <em>shapeclass</em> [<em>holdproc</em> <em>min</em> <em>max</em>]
</pre>
or on the command line:
<pre class='example'>
% deal -I "smartstack <em>shapeclass</em> ..."
</pre>
<h3>Summary</h3>
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:
<pre class='example'>
deal::input smartstack south balanced hcp 27 27
</pre>
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 <code>smartstack</code>
first builds a large "factory" in memory, but once it is built, the
factory spits out hands matching this condition very quickly.
<p>
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 <code>smartstack</code>.
For example, if you wanted 1000 examples, <code>smartstack</code>
takes about 15 seconds, while the old deal will take about 45 minutes.
<p>
One interesting feature of <code>smartstack</code> 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.
<p>
The <code>smartstack</code> routine only works on one hand - after it
places cards in that hand, it generates the rest using the usual
algorithm.
<td style="width: 35%">
<div class='programmer'><b>For Programmers</b>
<dl>
<dt>Implementation:</dt>
<dd>Tcl code</dd>
<dt>Location:</dt>
<dd>input/smartstack.tcl, lib/handFactory.tcl</dd>
<dt>Notes</dt>
<dd>See the two articles from the bridge developers mailing list
describing the algorithm:
<a href="http://www.cirl.uoregon.edu/pipermail/developers/2001-February/000339.html">My first stab at describing it</a> and
<a href="http://www.cirl.uoregon.edu/pipermail/developers/2001-February/000342.html">some corrections.</a>
</dl>
</div>
</table>
<hr>
<h1>Formatting</h1>
<a name="write_deal"></a>
<h2>Command: <code>write_deal</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
write_deal
</pre>
<h3>Summary</h3>
This is the the name of a procedure which is called when deals are accepted.
By default, it writes the result in the format:
<pre class='example'>
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
--------------------------
</pre>
New output formats are defined by <em>redefining this routine</em>.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl
<dt>Location:</dt>
<dd><code>format/default</code>
</dl>
</div>
</table>
<hr>
<a name="flush_deal"></a>
<h2>Command: <code>flush_deal</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
flush_deal
</pre>
<h3>Summary</h3>
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.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl>
<dt>Implementation:</dt>
<dd>Tcl code</dd>
<dt>Location:</dt>
<dd><code>format/default</code>, function <code>flush_deal</code>
</dl>
</div>
</table>
<hr>
<a name="format:par"></a>
<h2>Output Format: <code>format/par</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
source format/par
</pre>
<h3>Summary</h3>
<p>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.
<pre class='example'>
$ 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"]
*
</pre>
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl</dd>
<dt>Location:</dt>
<dd><code>format/par</code></dd>
</dl>
</div>
</table>
<hr>
<a name="format:ddline"></a>
<h2>Output Format: <code>format/ddline</code></h2>
<table cellpadding=5 style="width: 100%">
<tr valign=top><td style="width: 65%">
<h3>Usage</h3>
<pre class='example'>
source format/ddline
</pre>
<h3>Summary</h3>
<p>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:
<pre class='example'>
$ deal -i format/ddline 100 > doubledummy.txt
</pre>
<p>then you can use the <a href="#ddline"><code>ddline</code> input format</a> to read the file back in:
<pre class='example'>
$ deal -I "ddline doubledummy.txt" -i query.tcl 100
</pre>
<p>And any call to <code>deal::tricks</code> in query.tcl will use the value stored doubledummy.txt.
<td style="width: 35%"><div class='programmer'><b>For Programmers</b>
<dl><dt>Implementation:</dt>
<dd>Tcl</dd>
<dt>Location:</dt>
<dd><code>format/ddline</code></dd>
</dl>
</div>
</table>
<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@thomasoandrews.com">deal@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>
|
