Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 3941 lines (3386 sloc) 142.042 kb
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 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940

@table @b

@item What this manual presents
This document provides a tutorial introduction to the Smalltalk language
in general, and the @gst{} implementation in particular.
It does not provide exhaustive coverage of every feature of the language
and its libraries; instead, it attempts to introduce a critical mass of
ideas and techniques to get the Smalltalk novice moving in the
right direction.

@item Who this manual is written for
This manual assumes that the reader is acquainted with
the basics of computer science, and has reasonable proficiency
with a procedural language such as C. It also assumes that the reader
is already familiar with the usual janitorial tasks associated with
programming: editing, moving files, and so forth.
@end table

@menu
* Getting started:: Starting to explore @gst{}
* Some classes:: Using some of the Smalltalk classes
* The hierarchy:: The Smalltalk class hierarchy
* Creating classes:: Creating a new class of objects
* Creating subclasses:: Adding subclasses to another class
* Code blocks (I):: Control structures in Smalltalk
* Code blocks (II):: Guess what? More control structures
* Debugging:: Things go bad in Smalltalk too!
* More subclassing:: Coexisting in the class hierarchy
* Streams:: A powerful abstraction useful in scripts
* Exception handling:: More sophisticated error handling
* Behind the scenes:: Some nice stuff from the Smalltalk innards
* And now:: Some final words
* The syntax:: For the most die-hard computer scientists
@end menu

@node Getting started
@section Getting started

@menu
* Starting Smalltalk:: Starting up Smalltalk
* Saying hello:: Saying hello
* What happened:: But how does it say hello?
* Doing math:: Smalltalk too can do it!
* Math in Smalltalk:: But in a peculiar way of course...
@end menu

@node Starting Smalltalk
@subsection Starting up Smalltalk

Assuming that @gst{} has been installed on your
system, starting it is as simple as:
@example
   @b{$} gst
@end example
the system loads in Smalltalk, and displays a startup banner
like:
@display
     GNU Smalltalk ready

     st>
@end display

You are now ready to try your hand at Smalltalk! By the
way, when you're ready to quit, you exit Smalltalk by typing
@kbd{control-D} on an empty line.

@node Saying hello
@subsection Saying hello
An initial exercise is to make Smalltalk say ``hello'' to
you. Type in the following line (@code{printNl} is a upper case
N and a lower case L):
@example
   'Hello, world' printNl
@end example
The system then prints back 'Hello, world' to you. It prints it
twice, the first time because you asked to print and the second
time because the snipped evaluated to the 'Hello, world' string.@footnote{
    You can also have the system print out a lot of statistics which
    provide information on the performance of the underlying Smalltalk
    engine. You can enable them by starting Smalltalk as:
@example
   @b{$} gst -V
@end example
}

@node What happened
@subsection What actually happened

The front-line Smalltalk interpreter gathers all text
until a '!' character and executes it. So the actual
Smalltalk code executed was:
@example
   'Hello, world' printNl
@end example

This code does two things. First, it creates an object of
type @code{String} which contains the characters ``Hello, world''.
Second, it sends the message named @code{printNl} to the object.
When the object is done processing the message, the code is
done and we get our prompt back.
You'll notice that we didn't say anything about printing
ing the string, even though that's in fact what happened.
This was very much on purpose: the code we typed in doesn't
know anything about printing strings. It knew how to get a
string object, and it knew how to send a message to that
object. That's the end of the story for the code we wrote.

But for fun, let's take a look at what happened when the
string object received the @code{printNl} message. The string object
then went to a table @footnote{Which table? This is determined by the type
of the object. An object has a type, known as the
class to which it belongs. Each class has a table
of methods. For the object we created, it is
known as a member of the @code{String} class. So we go
to the table associated with the String class.}
which lists the messages which strings can receive, and what code to
execute. It found that there is indeed an entry for
@code{printNl} in that table and ran this code. This code then walked through
its characters, printing each of them out to the terminal. @footnote{
Actually, the message @code{printNl} was inherited
from Object. It sent a @code{print} message, also
inherited by Object, which then sent @code{printOn:} to
the object, specifying that it print to the @code{Transcript}
object. The String class then prints its characters to the
standard output.}

The central point is that an object is entirely self-contained;
only the object knew how to print itself out. When we want an
object to print out, we ask the object itself to do the printing.

@node Doing math
@subsection Doing math

A similar piece of code prints numbers:
@example
  1234 printNl
@end example

Notice how we used the same message, but have sent it to a
new type of object---an integer (from class @code{Integer}). The
way in which an integer is printed is much different from
the way a string is printed on the inside, but because we
are just sending a message, we do not have to be aware of
this. We tell it to @code{printNl}, and it prints itself out.

As a user of an object, we can thus usually send a particular
message and expect basically the same kind of behavior,
regardless of object's internal structure (for
instance, we have seen that sending @code{printNl} to an object
makes the object print itself). In later chapters we will
see a wide range of types of objects. Yet all of them can
be printed out the same way---with @code{printNl}.

White space is ignored, except as it separates words.
This example could also have looked like:
@example
              1234 printNl
@end example

However, @gst{} tries to execute each line by itself if
possible. If you wanted to write the code on two lines, you
might have written something like:
@example
(1234
    printNl)
@end example

From now on, we'll omit @code{printNl} since @gst{}
does the service of printing the answer for us.

An integer can be sent a number of messages in addition
to just printing itself. An important set of messages for
integers are the ones which do math:

@example
   9 + 7
@end example

Answers (correctly!) the value 16. The way that it does
this, however, is a significant departure from a procedural
language.

@node Math in Smalltalk
@subsection Math in Smalltalk

In this case, what happened was that the object @code{9} (an
Integer), received a @code{+} message with an argument of @code{7}
(also an Integer). The @code{+} message for integers then caused
Smalltalk to create a new object @code{16} and return it as the
resultant object. This @code{16} object was then given the
@code{printNl} message, and printed @code{16} on the terminal.

Thus, math is not a special case in Smalltalk; it is
done, exactly like everything else, by creating objects, and
sending them messages. This may seem odd to the Smalltalk
novice, but this regularity turns out to be quite a boon:
once you've mastered just a few paradigms, all of the language
``falls into place''. Before you go on to the next
chapter, make sure you try math involving @code{*} (multiplication),
@code{-} (subtraction), and @code{/} (division) also. These
examples should get you started:

@example
   8 * (4 / 2)
   8 - (4 + 1)
   5 + 4
   2/3 + 7
   2 + 3 * 4
   2 + (3 * 4)
@end example

@node Some classes
@section Using some of the Smalltalk classes

This chapter has examples which need a place to hold
the objects they create. Such place is created automatically
as necessary; when you want to discard all the objects you
stored, write an exclamation mark at the end of the statement.

Now let's create some new objects.

@menu
* Arrays:: An array in Smalltalk
* Sets:: A set in Smalltalk
* Dictionaries:: Getting more sophisticated, eh?
* Closing thoughts:: There always ought to be some closing thoughts
@end menu

@node Arrays
@subsection An array in Smalltalk

An array in Smalltalk is similar to an array in any
other language, although the syntax may seem peculiar at
first. To create an array with room for 20 elements, do@footnote{
    @gst{} supports completion in the same way as Bash or @sc{gdb}.
    To enter the following line, you can for example type
    @samp{x := Arr@kbd{<TAB>} new: 20}. This can come in handy
    when you have to type long names such as @code{IdentityDictionary},
    which becomes @samp{Ide@kbd{<TAB>}D@kbd{<TAB>}}. Everything
    starting with a capital letter or ending with a colon can
    be completed.}:
@example
   x := Array new: 20
@end example

The @code{Array new: 20} creates the array; the @code{x :=} part
connects the name @code{x} with the object. Until you assign
something else to @code{x}, you can refer to this array by the name
@code{x}. Changing elements of the array is not done using the
@code{:=} operator; this operator is used only to bind names to
objects. In fact, you never modify data structures;
instead, you send a message to the object, and it will modify itself.

For instance:
@example
   x at: 1
@end example
@noindent
which prints:
@example
   nil
@end example

The slots of an array are initially set to ``nothing'' (which
Smalltalk calls @code{nil}). Let's set the first slot to the
number 99:
@example
   x at: 1 put: 99
@end example
@noindent
and now make sure the 99 is actually there:
@example
   x at: 1
@end example
@noindent
which then prints out:
@example
   99
@end example

These examples show how to manipulate an array. They also
show the standard way in which messages are passed arguments
ments. In most cases, if a message takes an argument, its
name will end with `:'.@footnote{Alert readers will remember that the math
examples of the previous chapter deviated from this.}

So when we said @code{x at: 1} we were sending a message to whatever
object was currently bound to @code{x} with an argument of 1. For an
array, this results in the first slot of the array being returned.

The second operation, @code{x at: 1 put: 99} is a message
with two arguments. It tells the array to place the second
argument (99) in the slot specified by the first (1). Thus,
when we re-examine the first slot, it does indeed now
contain 99.

There is a shorthand for describing the messages you
send to objects. You just run the message names together.
So we would say that our array accepts both the @code{at:} and
@code{at:put:} messages.

There is quite a bit of sanity checking built into an
array. The request
@example
   6 at: 1
@end example
@noindent
fails with an error; 6 is an integer, and can't be indexed. Further,
@example
   x at: 21
@end example
@noindent
fails with an error, because the array we created only has
room for 20 objects.

Finally, note that the object stored
in an array is just like any other object, so we can do
things like:
@example
   (x at: 1) + 1
@end example
@noindent
which (assuming you've been typing in the examples) will
print 100.

@node Sets
@subsection A set in Smalltalk

We're done with the array we've been using, so we'll
assign something new to our @code{x} variable. Note that we
don't need to do anything special about the old array: the
fact that nobody is using it any more will be automatically
detected, and the memory reclaimed. This is known as @i{garbage collection}
and it is generally done when Smalltalk finds that it is
running low on memory. So, to get our new object, simply do:
@example
   x := Set new
@end example
@noindent
which creates an empty set. To view its contents, do:
@example
   x
@end example

The kind of object is printed out (i.e., @code{Set}), and then the
members are listed within parenthesis. Since it's empty, we
see:
@example
   Set ()
@end example

Now let's toss some stuff into it. We'll add the numbers 5
and 7, plus the string 'foo'. This is also the first example
where we're using more than one statement, and thus a good place to present
the statement separator---the @code{.} period:

@example
   x add: 5. x add: 7. x add: 'foo'
@end example

Like Pascal, and unlike C, statements are separated rather than
terminated. Thus you need only use a @code{.} when you have finished
one statement and are starting another. This is why our last statement,
@code{^r}, does not have a @code{.} following. Once again like Pascal,
however, Smalltalk won't complain if your enter a spurious
statement separator after @i{the last} statement.

However, we can save a little typing by using a Smalltalk shorthand:

@example
   x add: 5; add: 7; add: 'foo'
@end example

This line does exactly what the previous one did.
The trick is that the semicolon operator causes
the message to be sent to the same object as the last message
sent. So saying @code{; add: 7} is the same as saying
@code{x add: 7}, because @code{x} was the last thing a message was sent
to.

This may not seem like such a big savings, but compare
the ease when your variable is named @code{aVeryLongVariableName}
instead of just @code{x}! We'll revisit some other occasions
where @code{;} saves you trouble, but for now let's continue with
our set. Type either version of the example, and make sure
that we've added 5, 7, and ``foo'':
@example
   x
@end example
@noindent

we'll see that it now contains our data:
@example
   Set ('foo' 5 7)
@end example

What if we add something twice? No problem---it just stays in
the set. So a set is like a big checklist---either it's in
there, or it isn't. To wit:
@example
   x add:5; add: 5; add: 5; add: 5; yourself
@end example

We've added @i{5} several times, but when we printed our set
back out, we just see:
@example
   Set ('foo' 5 7)
@end example

@code{yourself} is commonly sent at the end of the cascade,
if what you are interested in is the object itself---in this
case, we were not interested in the return value of @code{add: 5},
which happens to be @code{5} simply. There's nothing magic in
@code{yourself}; it is a unary message like @code{printNl},
which does nothing but returning the object itself. So you
can do this too:

@example
   x yourself
@end example

What you put into a set with @code{add:}, you can take out
with @code{remove:}. Try:

@example
   x remove: 5
   x printNl
@end example

The set now prints as:
@example
   Set ('foo' 7)
@end example

The ``5'' is indeed gone from the set.

We'll finish up with one more of the many things you
can do with a set---checking for membership. Try:
@example
   x includes: 7
   x includes: 5
@end example

From which we see that x does indeed contain 7, but not 5.
Notice that the answer is printed as @code{true} or @code{false}.
Once again, the thing returned is an object---in this case, an
object known as a boolean. We'll look at the use of
booleans later, but for now we'll just say that booleans are
nothing more than objects which can only either be true or
false---nothing else. So they're very useful for answers to
yes or no questions, like the ones we just posed. Let's
take a look at just one more kind of data structure:

@node Dictionaries
@subsection Dictionaries

A dictionary is a special kind of collection. With a
regular array, you must index it with integers. With
dictionaries, you can index it with any object at all.
Dictionaries thus provide a very powerful way of correlating
one piece of information to another. Their only downside is
that they are somewhat less efficient than simple arrays.
Try the following:
@example
   y := Dictionary new
   y at: 'One' put: 1
   y at: 'Two' put: 2
   y at: 1 put: 'One'
   y at: 2 put: 'Two'
@end example

This fills our dictionary in with some data. The data is
actually stored in pairs of key and value (the key is what
you give to @code{at:}---it specifies a slot; the value is what is
actually stored at that slot). Notice how we were able to
specify not only integers but also strings as both the key
and the value. In fact, we can use any kind of object we
want as either---the dictionary doesn't care.

Now we can map each key to a value:
@example
   y at: 1
   y at: 'Two'
@end example

which prints respectively:
@example
   'One'
   2
@end example

We can also ask a dictionary to print itself:
@example
   y
@end example
@noindent

which prints:
@example
   Dictionary (1->'One' 2->'Two' 'One'->1 'Two'->2 )
@end example
@noindent

where the first member of each pair is the key, and the second
the value. It is now time to take a final look at the objects
we have created, and send them to oblivion:

@example
   y
   x!
@end example

The exclamation mark deleted @gst{}'s knowledge of both
variables. Asking for them again will return just @code{nil}.

@node Closing thoughts
@subsection Closing thoughts

You've seen how Smalltalk provides you with some very
powerful data structures. You've also seen how Smalltalk
itself uses these same facilities to implement the language.
But this is only the tip of the iceberg---Smalltalk is much
more than a collection of ``neat'' facilities to use.
The objects and methods which are automatically available
are only the beginning of the foundation on which you
build your programs---Smalltalk allows you to add your own
objects and methods into the system, and then use them along
with everything else. The art of programming in Smalltalk
is the art of looking at your problems in terms of objects,
using the existing object types to good effect, and enhancing
Smalltalk with new types of objects. Now that you've
been exposed to the basics of Smalltalk manipulation, we can
begin to look at this object-oriented technique of programming.

@node The hierarchy
@section The Smalltalk class hierarchy

When programming in Smalltalk, you sometimes need to
create new kinds of objects, and define what various
messages will do to these objects. In the next chapter we will
create some new classes, but first we need to understand how
Smalltalk organizes the types and objects it contains.
Because this is a pure ``concept'' chapter, without any actual
Smalltalk code to run, we will keep it short and to the
point.

@menu
* Class Object:: The grandfather of every class
* Animals:: A classic in learning OOP!
* But why:: The bottom line of the class hierarchy
@end menu

@node Class Object
@subsection Class @code{Object}

Smalltalk organizes all of its classes as a tree hierarchy.
At the very top of this hierarchy is class @i{Object}.
Following somewhere below it are more specific classes, such
as the ones we've worked with---strings, integers, arrays, and
so forth. They are grouped together based on their similarities;
for instance, types of objects which may be compared
as greater or less than each other fall under a class known
as @i{Magnitude}.

One of the first tasks when creating a new object is to
figure out where within this hierarchy your object falls.
Coming up with an answer to this problem is at least as much
art as science, and there are no hard-and-fast rules to nail
it down. We'll take a look at three kinds of objects to
give you a feel for how this organization matters.

@node Animals
@subsection Animals

Imagine that we have three kinds of objects, representing
@i{Animals}, @i{Parrots}, and @i{Pigs}. Our messages will be
@i{eat}, @i{sing}, and @i{snort}. Our first pass at
inserting these objects into the Smalltalk hierarchy would
organize them like:
@example
   @r{Object}
       @r{Animals}
       @r{Parrots}
       @r{Pigs}
@end example

This means that Animals, Parrots, and Pigs are all direct
descendants of @i{Object}, and are not descendants of each
other.

Now we must define how each animal responds to each
kind of message.

@example
       @r{Animals}
           @r{eat --> Say ``I have now eaten''}
           @r{sing --> Error}
           @r{snort --> Error}
       @r{Parrots}
           @r{eat --> Say ``I have now eaten''}
           @r{sing --> Say ``Tweet''}
           @r{snort --> Error}
       @r{Pigs}
           @r{eat --> Say ``I have now eaten"''}
           @r{sing --> Error}
           @r{snort --> Say ``Oink''}
@end example

Notice how we kept having to indicate an action for @i{eat}.
An experienced object designer would immediately recognize
this as a clue that we haven't set up our hierarchy correctly.
Let's try a different organization:
@example
   @r{Object}
       @r{Animals}
           @r{Parrots}
                  @r{Pigs}
@end example

That is, Parrots inherit from Animals, and Pigs from Parrots.
Now Parrots inherit all of the actions from Animals,
and Pigs from both Parrots and Animals. Because of this
inheritance, we may now define a new set of actions which
spares us the redundancy of the previous set:
@example
       @r{Animals}
           @r{eat --> Say ``I have now eaten''}
           @r{sing --> Error}
           @r{snort --> Error}
       @r{Parrots}
           @r{sing --> Say ``Tweet''}
       @r{Pigs}
           @r{snort --> Say ``Oink''}
@end example

Because Parrots and Pigs both inherit from Animals, we have
only had to define the @i{eat} action once. However, we have
made one mistake in our class setup---what happens when we
tell a Pig to @i{sing}? It says ``Tweet'', because we have put
Pigs as an inheritor of Parrots. Let's try one final
organization:
@example
   @r{Object}
       @r{Animals}
           @r{Parrots}
           @r{Pigs}
@end example

Now Parrots and Pigs inherit from Animals, but not from each
other. Let's also define one final pithy set of actions:
@example
       @r{Animals}
           @r{eat --> Say ``I have eaten''}
       @r{Parrots}
           @r{sing --> Say ``Tweet''}
       @r{Pigs}
           @r{snort --> Say ``Oink''}
@end example

The change is just to leave out messages which are inappropriate.
If Smalltalk detects that a message is not known by
an object or any of its ancestors, it will automatically
give an error---so you don't have to do this sort of thing
yourself. Notice that now sending @i{sing} to a Pig does
indeed not say ``Tweet''---it will cause a Smalltalk error
instead.

@node But why
@subsection The bottom line of the class hierarchy

The goal of the class hierarchy is to allow you to
organize objects into a relationship which allows a particular
object to inherit the code of its ancestors. Once you
have identified an effective organization of types, you
should find that a particular technique need only be implemented
once, then inherited by the children below. This
keeps your code smaller, and allows you to fix a bug in a
particular algorithm in only once place---then have all users
of it just inherit the fix.

You will find your decisions for adding objects change
as you gain experience. As you become more familiar with
the existing set of objects and messages, your selections
will increasingly ``fit in'' with the existing ones. But even
a Smalltalk @i{pro} stops and thinks carefully at this stage,
so don't be daunted if your first choices seem difficult and
error-prone.

@node Creating classes
@section Creating a new class of objects

With the basic techniques presented in the preceding
chapters, we're ready do our first real Smalltalk program.
In this chapter we will construct three new types of objects
(known as @i{classes}), using the Smalltalk technique of
inheritance to tie the classes together, create new objects
belonging to these classes (known as creating instances of
the class), and send messages to these objects.

We'll exercise all this by implementing a toy home-finance
accounting system. We will keep track of our overall
cash, and will have special handling for our checking
and savings accounts. From this point on, we will be defining
classes which will be used in future chapters. Since
you will probably not be running this whole tutorial in one
Smalltalk session, it would be nice to save off the state of
Smalltalk and resume it without having to retype all the
previous examples. To save the current state of @gst{},
type:

@example
   ObjectMemory snapshot: 'myimage.im'
@end example
@noindent

and from your shell, to later restart Smalltalk from this
``snapshot'':
@example
   @b{$} gst -I myimage.im
@end example

Such a snapshot currently takes a little more than a megabyte,
and contains all variables, classes, and definitions you
have added.

@menu
* A new class:: Creating a new class
* Documenting the class:: So anybody will know what it's about
* Defining methods:: So it will be useful
* Instance methods:: One of two kind of methods (the others,
                                 class methods, are above)
* A look at our object:: which will sorely show that something
                                 is still missing.
* Moving money around:: Let's make it more fun!
* Next coming:: Yeah, what's next?!?
@end menu

@node A new class
@subsection Creating a new class

Guess how you create a new class? This should be getting
monotonous by now---by sending a message to an object.
The way we create our first ``custom'' class is by sending the
following message:

@example
   Object subclass: #Account.
   Account instanceVariableNames: 'balance'.
@end example

Quite a mouthful, isn't it? @gst{} provides a
simpler way to write this, but for now let's stick with this.
Conceptually, it isn't really that bad. The Smalltalk variable
@i{Object} is bound to the grand-daddy of all classes on the
system. What we're doing here is telling the @i{Object} class
that we want to add to it a subclass known as @i{Account}.
Then, @code{instanceVariableNames: 'balance'} tells the new
class that each of its objects (@dfn{instances}) will have a
hidden variable named @code{balance}.

@node Documenting the class
@subsection Documenting the class

The next step is to associate a description with the
class. You do this by sending a message to the new class:
@example
   Account comment:
   'I represent a place to deposit and withdraw money'
@end example

A description is associated with every Smalltalk class, and
it's considered good form to add a description to each new
class you define. To get the description for a given class:
@example
   Account comment
@end example

And your string is printed back to you. Try this with class
Integer, too:
@example
   Integer comment
@end example

However, there is another way to define classes. This still
translates to sending objects, but looks more like a traditional
programming language or scripting language:

@example
Object subclass: Account [
    | balance |
    <comment:
        'I represent a place to deposit and withdraw money'>
]
@end example

This has created a class. If we want to access it again, for
example to modify the comment, we can do so like this:

@example
Account extend [
    <comment:
        'I represent a place to withdraw money that has been deposited'>
]
@end example

This instructs Smalltalk to pick an existing class, rather than
trying to create a subclass.

@node Defining methods
@subsection Defining a method for the class

We have created a class, but it isn't ready to do any
work for us---we have to define some messages which the class
can process first. We'll start at the beginning by defining
methods for instance creation:
@example
    Account class extend [
       new [
           | r |
           <category: 'instance creation'>
           r := super new.
           r init.
           ^r
      ]
   ]
@end example

The important points about this are:

@itemize @bullet
@item
@code{Account class} means that we are defining messages which are
to be sent to the Account class itself.

@item
@code{<category: 'instance creation'>}
is more documentation support; it says that the methods
we are defining supports creating objects of type
Account.

@item
The text starting with @code{new [} and ending with @code{]}
defined what action to take for the message @code{new}.
When you enter this definition, @gst{} will simply
give you another prompt, but your method has been compiled in
and is ready for use. @gst{} is pretty quiet on successful
method definitions---but you'll get plenty of error
messages if there's a problem!

If you're familiar with other Smalltalks, note that the body
of the method is always in brackets.
@end itemize

The best way to describe how this method works is to
step through it. Imagine we sent a message to the new class
Account with the command line:
@example
   Account new
@end example

@code{Account} receives the message @code{new} and looks up
how to process this message. It finds our new definition, and
starts running it. The first line, @code{| r |}, creates a local
variable named @code{r} which can be used as a placeholder for
the objects we create. @code{r} will go away as soon as the message
is done being processed; note the parallel with @code{balance}, which
goes away as soon as the object is not used anymore. And note that
here you have to declare local variables explicitly, unlike what
you did in previous examples.

The first real step is to actually create the object.
The line @code{r := super new} does this using a fancy trick.
The word @code{super} stands for the same object that the message
@code{new} was originally sent to (remember? it's @code{Account}),
except that when Smalltalk goes to search for the methods,
it starts one level higher up in the hierarchy than the current
level. So for a method in the Account class, this is
the Object class (because the class Account inherits from is
Object---go back and look at how we created the Account
class), and the Object class' methods then execute some code
in response to the @code{#new} message. As it turns out, Object
will do the actual creation of the object when sent a @code{#new}
message.

One more time in slow motion: the Account method @code{#new}
wants to do some fiddling about when new objects are created,
but he also wants to let his parent do some work with
a method of the same name. By saying @code{r := super new} he
is letting his parent create the object, and then he is attaching
it to the variable @code{r}. So after this line of code executes,
we have a brand new object of type Account, and @code{r}
is bound to it. You will understand this better as time
goes on, but for now scratch your head once, accept it as a
recipe, and keep going.

We have the new object, but we haven't set it up correctly.
Remember the hidden variable @code{balance} which we saw
in the beginning of this chapter? @code{super new} gives us the
object with the @code{balance} field containing nothing, but we want
our balance field to start at 0. @footnote{And unlike C, Smalltalk
draws a distinction between @code{0} and @code{nil}. @code{nil}
is the @i{nothing} object, and you will receive an error if you
try to do, say, math on it. It really does matter that we
initialize our instance variable to the number 0 if we wish
to do math on it in the future.}

So what we need to do is ask the object to set itself up.
By saying @code{r init}, we are sending the @code{init}
message to our new Account. We'll define
this method in the next section---for now just assume that
sending the @code{init} message will get our Account set up.

Finally, we say @code{^r}. In English, this is @i{return what
r is attached to}. This means that whoever sent to Account
the @code{new} message will get back this brand new account. At
the same time, our temporary variable @code{r} ceases to exist.

@node Instance methods
@subsection Defining an instance method

We need to define the @code{init} method for our Account
objects, so that our @code{new} method defined above will work.
Here's the Smalltalk code:
@example
Account extend [
    init [
        <category: 'initialization'>
        balance := 0
    ]
]
@end example

It looks quite a bit like the previous method definition,
except that the first one said
@code{Account class extend}, and ours says
@code{Account extend}.

The difference is that the first one defined a method for
messages sent directly to @code{Account}, but the second one is
for messages which are sent to Account objects once they are
created.

The method named @code{init} has only one line, @code{balance := 0}.
This initializes the hidden variable @code{balance} (actually
called an instance variable) to zero, which makes
sense for an account balance. Notice that the method
doesn't end with @code{^r} or anything like it: this method
doesn't return a value to the message sender. When you do
not specify a return value, Smalltalk defaults the return
value to the object currently executing. For clarity of
programming, you might consider explicitly returning @code{self}
in cases where you intend the return value to be used.@footnote{
And why didn't the designers default the
return value to nil? Perhaps they didn't appreciate
the value of void functions. After all, at
the time Smalltalk was being designed, C didn't
even have a void data type.}

Before going on, ere is how you could have written this code in a
single declaration (i.e.@: without using @code{extend}):

@example
Object subclass: Account [
    | balance |
    <comment:
        'I represent a place to deposit and withdraw money'>
    Account class >> new [
        <category: 'instance creation'>
        | r |
        r := super new.
        r init.
        ^r
    ]
    init [
        <category: 'initialization'>
        balance := 0
    ]
]
@end example

@node A look at our object
@subsection Looking at our Account

Let's create an instance of class Account:
@example
   a := Account new
@end example

Can you guess what this does? The @code{Smalltalk at: #a put: <something>}
creates a Smalltalk variable. And the @code{Account new} creates a new
Account, and returns it. So this line creates a Smalltalk
variable named @code{a}, and attaches it to a new Account---all in
one line. It also prints the Account object we just created:
@example
   an Account
@end example

Hmmm... not very informative. The problem is that we didn't
tell our Account how to print itself, so we're just getting
the default system @code{printNl} method---which tells what the
object is, but not what it contains. So clearly we must add
such a method:
@example
    Account extend [
        printOn: stream [
            <category: 'printing'>
            super printOn: stream.
            stream nextPutAll: ' with balance: '.
            balance printOn: stream
        ]
    ]
@end example

Now give it a try again:
@example
   a
@end example

@noindent
which prints:
@example
   an Account with balance: 0
@end example

This may seem a little strange. We added a new method,
printOn:, and our printNl message starts behaving differently.
It turns out that the printOn: message is the central
printing function---once you've defined it, all of the
other printing methods end up calling it. Its argument is a
place to print to---quite often it is the variable @code{Transcript}.
This variable is usually hooked to your terminal, and thus
you get the printout to your screen.

The @code{super printOn: stream} lets our parent do what it
did before---print out what our type is. The @code{an Account}
part of the printout came from this.
@code{stream nextPutAll: ' with balance: '} creates the
string @code{ with balance: }, and prints it out to the stream,
too; note that we don't use @code{printOn:} here because that would
enclose our string within quotes. Finally, @code{balance printOn: stream}
asks whatever object is hooked to the @code{balance} variable to print
itself to the stream. We set @code{balance} to 0, so the 0 gets printed out.

@node Moving money around
@subsection Moving money around

We can now create accounts, and look at them. As it
stands, though, our balance will always be 0---what a tragedy!
Our final methods will let us deposit and spend money.
They're very simple:

@example
   Account extend [
       spend: amount [
           <category: 'moving money'>
           balance := balance - amount
       ]
       deposit: amount [
           <category: 'moving money'>
           balance := balance + amount
       ]
   ]
@end example

With these methods you can now deposit and spend amounts of
money. Try these operations:
@example
   a deposit: 125
   a deposit: 20
   a spend: 10
@end example

@node Next coming
@subsection What's next?

We now have a generic concept, an ``Account''. We can create them,
check their balance, and move money in and out of
them. They provide a good foundation, but leave out important
information that particular types of accounts might
want. In the next chapter, we'll take a look at fixing this
problem using subclasses.

@node Creating subclasses
@section Two Subclasses for the Account Class

This chapter continues from the previous chapter in
demonstrating how one creates classes and subclasses in
Smalltalk. In this chapter we will create two special subclasses
of Account, known as Checking and Savings. We will
continue to inherit the capabilities of Account, but will
tailor the two kinds of objects to better manage particular
kinds of accounts.

@menu
* The Savings class:: One of the two subclasses we'll put together
* The Checking class:: And here is the other
* Writing checks:: Only in Smalltalk, of course
@end menu

@node The Savings class
@subsection The Savings class

We create the Savings class as a subclass of Account.
It holds money, just like an Account, but has an additional
property that we will model: it is paid interest based on
its balance. We create the class Savings as a subclass of
Account.
@example
   Account subclass: Savings [
       | interest |
@end example

This is already telling something:
the instance variable @code{interest} will accumulate interest
paid. Thus, in addition to the @code{spend:} and
@code{deposit:} messages which we inherit from our parent,
Account, we will need to define a method to add in interest
deposits, and a way to clear the interest variable (which
we would do yearly, after we have paid taxes). We first define
a method for allocating a new account---we need to make sure that the
interest field starts at 0.

We can do so within the @code{Account subclass: Savings} scope,
which we have not closed above.
@example
   init [
       <category: 'initialization'>
       interest := 0.
       ^super init
   ]
@end example

Recall that the parent took care of the @code{new} message, and
created a new object of the appropriate size. After creation,
the parent also sent an @code{init} message to the new
object. As a subclass of Account, the new object will
receive the @code{init} message first; it sets up its own
instance variable, and then passes the @code{init} message up the
chain to let its parent take care of its part of the
initialization.

With our new @code{Savings} account created, we can define
two methods for dealing specially with such an account:

@example
   interest: amount [
       interest := interest + amount.
       self deposit: amount
   ]
   clearInterest [
       | oldinterest |
       oldinterest := interest.
       interest := 0.
       ^oldinterest
   ]
@end example

We are now finished, and close the class scope:

@example
]
@end example

The first method says that we add the @code{amount} to our
running total of interest. The line @code{self deposit: amount}
tells Smalltalk to send ourselves a message, in this case
@code{deposit: amount}. This then causes Smalltalk to look up
the method for @code{deposit:}, which it finds in our parent,
Account. Executing this method then updates our overall
balance.@footnote{@code{self} is much like @code{super}, except that
@code{self} will start looking for a method at the bottom
of the type hierarchy for the object, while
@code{super} starts looking one level up from the current
level. Thus, using @code{super} forces inheritance,
but @code{self} will find the first definition
of the message which it can.}

One may wonder why we don't just replace this with the
simpler @code{balance := balance + amount}. The answer lies
in one of the philosophies of object-oriented languages in general,
and Smalltalk in particular. Our goal is to encode a
technique for doing something once only, and then re-using
that technique when needed. If we had directly encoded
@code{balance := balance + amount} here, there would have been
two places that knew how to update the balance from a
deposit. This may seem like a useless difference. But consider
if later we decided to start counting the number of
deposits made. If we had encoded
@code{balance := balance + amount} in each place that needed to
update the balance, we would have to hunt each of them down in
order to update the count of deposits. By sending @code{self}
the message @code{deposit:}, we need only update this method
once; each sender of this message would then automatically get the correct
up-to-date technique for updating the balance.

The second method, @code{clearInterest}, is simpler. We
create a temporary variable @code{oldinterest} to hold the current
amount of interest. We then zero out our interest to
start the year afresh. Finally, we return the old interest
as our result, so that our year-end accountant can see how
much we made.@footnote{Of course, in a real accounting system we
would never discard such information---we'd probably
throw it into a Dictionary object, indexed by the
year that we're finishing. The ambitious might
want to try their hand at implementing such an
enhancement.}


@node The Checking class
@subsection The Checking class

Our second subclass of Account represents a checking
account. We will keep track of two facets:

@itemize @bullet
@item
What check number we are on

@item
How many checks we have left in our checkbook
@end itemize

We will define this as another subclass of Account:
@example
Account subclass: Checking [
    | checknum checksleft |
@end example

We have two instance variables, but we really only need to
initialize one of them---if there are no checks left, the current
check number can't matter. Remember, our parent class
Account will send us the @code{init} message. We don't need our
own class-specific @code{new} function, since our parent's will
provide everything we need.
@example
    init [
       <category: 'initialization'>
       checksleft := 0.
       ^super init
   ]
@end example

As in Savings, we inherit most of abilities from our superclass,
Account. For initialization, we leave @code{checknum}
alone, but set the number of checks in our checkbook to
zero. We finish by letting our parent class do its own
initialization.

@node Writing checks
@subsection Writing checks

We will finish this chapter by adding a method for
spending money through our checkbook. The mechanics of taking
a message and updating variables should be familiar:
@example
   newChecks: number count: checkcount [
       <category: 'spending'>
       checknum := number.
       checksleft := checkcount
   ]

   writeCheck: amount [
       <category: 'spending'>
       | num |
       num := checknum.
       checknum := checknum + 1.
       checksleft := checksleft - 1.
       self spend: amount.
       ^ num
   ]
]
@end example

@code{newChecks:} fills our checkbook with checks. We record
what check number we're starting with, and update the count
of the number of checks in the checkbook.

@code{writeCheck:} merely notes the next check number, then
bumps up the check number, and down the check count. The
message @code{self spend: amount} resends the message
@code{spend:} to our own object. This causes its method to be looked
up by Smalltalk. The method is then found in our parent class,
Account, and our balance is then updated to reflect our
spending.

You can try the following examples:
@example
   c := Checking new
   c deposit: 250
   c newChecks: 100 count: 50
   c writeCheck: 32
   c
@end example

For amusement, you might want to add a printOn: message to
the checking class so you can see the checking-specific
information.

In this chapter, you have seen how to create subclasses
of your own classes. You have added new methods, and inherited
methods from the parent classes. These techniques provide
the majority of the structure for building solutions to
problems. In the following chapters we will be filling in
details on further language mechanisms and types, and providing
details on how to debug software written in Smalltalk.

@node Code blocks (I)
@section Code blocks

The Account/Saving/Checking example from the last chapter
has several deficiencies. It has no record of the
checks and their values. Worse, it allows you to write a
check when there are no more checks---the Integer value for
the number of checks will just calmly go negative! To fix
these problems we will need to introduce more sophisticated
control structures.

@menu
* Conditions:: Making some decisions
* Iteration:: Making some loops
@end menu

@node Conditions
@subsection Conditions and decision making

Let's first add some code to keep you from writing too
many checks. We will simply update our current method for
the Checking class; if you have entered the methods from the
previous chapters, the old definition will be overridden by
this new one.
@example
Checking extend [
    writeCheck: amount [
       | num |

       (checksleft < 1)
           ifTrue: [ ^self error: 'Out of checks' ].
       num := checknum.
       checknum := checknum + 1.
       checksleft := checksleft - 1.
       self spend: amount
       ^ num
   ]
]
@end example

The two new lines are:
@example
   (checksleft < 1)
       ifTrue: [ ^self error: 'Out of checks' ].
@end example

At first glance, this appears to be a completely new structure.
But, look again! The only new construct is the square
brackets, which appear within a method and not only surround it.

The first line is a simple boolean expression. @code{checksleft}
is our integer, as initialized by our Checking class.
It is sent the message @code{<}, and the argument 1. The current
number bound to @code{checksleft} compares itself against 1, and
returns a boolean object telling whether it is less than 1.

Now this boolean, which is either true or false, is sent the
message @code{ifTrue:}, with an argument which is called a code
block. A code block is an object, just like any other. But
instead of holding a number, or a Set, it holds executable
statements. So what does a boolean do with a code block which
is an argument to a @code{ifTrue:} message? It depends on which boolean!
If the object is the @code{true} object, it executes the code
block it has been handed. If it is the @code{false} object, it
returns without executing the code block. So the traditional
@i{conditional construct} has been replaced in
Smalltalk with boolean objects which execute the indicated
code block or not, depending on their truth-value.
@footnote{It is interesting to note that because of the
way conditionals are done, conditional constructs
are not part of the Smalltalk language, instead they are
merely a defined behavior for the Boolean class of
objects.}

In the case of our example, the actual code within the
block sends an error message to the current object. @code{error:}
is handled by the parent class Object, and will pop up an
appropriate complaint when the user tries to write too many
checks. In general, the way you handle a fatal error in
Smalltalk is to send an error message to yourself (through
the @code{self} pseudo-variable), and let the error handling
mechanisms inherited from the Object class take over.

As you might guess, there is also an @code{ifFalse:} message
which booleans accept. It works exactly like @code{ifTrue:},
except that the logic has been reversed; a boolean @code{false}
will execute the code block, and a boolean @code{true} will not.

You should take a little time to play with this method
of representing conditionals. You can run your checkbook,
but can also invoke the conditional functions directly:
@example
   true ifTrue: [ 'Hello, world!' printNl ]
   false ifTrue: [ 'Hello, world!' printNl ]
   true ifFalse: [ 'Hello, world!' printNl ]
   false ifFalse: [ 'Hello, world!' printNl ]
@end example

@node Iteration
@subsection Iteration and collections

Now that we have some sanity checking in place, it
remains for us to keep a log of the checks we write. We
will do so by adding a Dictionary object to our Checking
class, logging checks into it, and providing some messages
for querying our check-writing history. But this enhancement
brings up a very interesting question---when we change
the ``shape'' of an object (in this case, by adding our dictionary
as a new instance variable to the Checking class),
what happens to the existing class, and its objects?
The answer is that the old objects are mutated to keep their
new shape, and all methods are recompiled so that they work
with the new shape. New objects will have exactly the same shape
as old ones, but old objects might happen to be initialized
incorrectly (since the newly added variables will be simply
put to nil). As this can lead to very puzzling behavior, it is
usually best to eradicate all of the old objects, and then
implement your changes.

If this were more than a toy object
accounting system, this would probably entail saving the
objects off, converting to the new class, and reading the
objects back into the new format. For now, we'll just
ignore what's currently there, and define our latest Checking
class.

@example
Checking extend [
    | history |
@end example

This is the same syntax as the last time we defined a checking account,
except that we start with @code{extend} (since the class is already
there). Then, the two instance variables we had defined remain, and we
add a new @code{history} variable; the old methods will be recompiled
without errors. We must now feed in our definitions for each of the
messages our object can handle, since we are basically defining a new
class under an old name.

With our new Checking instance variable, we are all set to start recording
our checking history. Our first change will be in the handling of the
@code{init} message:
@example
       init [
           <category: 'initialization'>
           checksleft := 0.
           history := Dictionary new.
           ^ super init
       ]
@end example

This provides us with a Dictionary, and hooks it to our new
@code{history} variable.

Our next method records each check as it's written.
The method is a little more involved, as we've added some
more sanity checks to the writing of checks.

@example
   writeCheck: amount [
       <category: 'spending'>
       | num |

       "Sanity check that we have checks left in our checkbook"
       (checksleft < 1)
           ifTrue: [ ^self error: 'Out of checks' ].

       "Make sure we've never used this check number before"
       num := checknum.
       (history includesKey: num)
           ifTrue: [ ^self error: 'Duplicate check number' ].

       "Record the check number and amount"
       history at: num put: amount.

       "Update our next checknumber, checks left, and balance"
       checknum := checknum + 1.
       checksleft := checksleft - 1.
       self spend: amount.
       ^ num
   ]
@end example

We have added three things to our latest version of
@code{writeCheck:}. First, since our routine has become somewhat
involved, we have added comments. In Smalltalk, single
quotes are used for strings; double quotes enclose comments.
We have added comments before each section of code.

Second, we have added a sanity check on the check number
we propose to use. Dictionary objects respond to the
@code{includesKey:} message with a boolean, depending on whether
something is currently stored under the given key in the
dictionary. If the check number is already used, the @code{error:}
message is sent to our object, aborting the operation.

Finally, we add a new entry to the dictionary. We have
already seen the @code{at:put:} message (often found written
as @code{#at:put:}, with a sharp in front of it) at the start of
this tutorial. Our use here simply associates a check number with
an amount of money spent.@footnote{You might start to wonder what
one would do if you wished to associate two pieces of
information under one key. Say, the value and who the
check was written to. There are several ways; the
best would probably be to create a new, custom
object which contained this information, and then
store this object under the check number key in
the dictionary. It would also be valid (though
probably overkill) to store a dictionary as the
value---and then store as many pieces of information
as you'd like under each slot!} With this, we now have a working Checking
class, with reasonable sanity checks and per-check information.

Let us finish the chapter by enhancing our ability to
get access to all this information. We will start with some
simple print-out functions.

@example
   printOn: stream [
       super printOn: stream.
       ', checks left: ' printOn: stream.
       checksleft printOn: stream.
       ', checks written: ' printOn: stream.
       (history size) printOn: stream.
   ]
   check: num [
       | c |
       c := history
           at: num
           ifAbsent: [ ^self error: 'No such check #' ].
       ^c
   ]
@end example

There should be very few surprises here. We format and
print our information, while letting our parent classes handle
their own share of the work. When looking up a check
number, we once again take advantage of the fact that blocks
of executable statements are an object; in this case, we are
using the @code{at:ifAbsent:} message supported by the
Dictionary class. As you can probably anticipate, if the
requested key value is not found in the
dictionary, the code block is executed. This allows us to
customize our error handling, as the generic error would only
tell the user ``key not found''.

While we can look up a check if we know its number, we
have not yet written a way to ``riffle through'' our collection
of checks. The following function loops over the
checks, printing them out one per line. Because there is
currently only a single numeric value under each key, this
might seem wasteful. But we have already considered storing
multiple values under each check number, so it is best to
leave some room for each item. And, of course, because we
are simply sending a printing message to an object, we will
not have to come back and re-write this code so long as the
object in the dictionary honors our @code{printNl}/@code{printOn:} messages
sages.

@example
    printChecks [
        history keysAndValuesDo: [ :key :value |
            key print.
            ' - ' print.
            value printNl.
        ]
    ]
]
@end example

We still see a code block object being passed to the
dictionary, but @code{:key :value |} is something new. A code
block can optionally receive arguments. In this case, the
two arguments represent a key/value pair.
If you only wanted the value portion, you could call
history with a @code{do:} message instead; if you only wanted the
key portion, you could call history with a @code{keysDo:} message instead.

We then invoke our printing interface upon them. We don't want a
newline until the end, so the @code{print} message is used instead.
It is pretty much the same as @code{printNl}, since both implicitly use
@code{Transcript}, except it doesn't add a newline.

It is important that you be clear that in principle there is
no relationship between the code block and the dictionary you
passed it to. The dictionary just invokes the passed code block
with a key/value pair when processing a keysAndValuesDo: message. But
the same two-parameter code block can be passed to any message that
wishes to evaluate it (and passes the exact number of parameters to
it). In the next chapter
we'll see more on how code blocks are used; we'll also look at how
you can invoke code blocks in your own code.

@node Code blocks (II)
@section Code blocks, part two

In the last chapter, we looked at how code blocks could
be used to build conditional expressions, and how you could
iterate across all entries in a collection.@footnote{The
  @code{do:} message is understood by most types
  of Smalltalk collections. It works for the
  Dictionary class, as well as sets, arrays, strings,
  intervals, linked lists, bags, and streams. The
  @code{keysDo:} message, for example, works only with dictionaries.}
We built our own code blocks, and handed them off for use by system
objects. But there is nothing magic about invoking code
blocks; your own code will often need to do so. This chapter
will shows some examples of loop construction in
Smalltalk, and then demonstrate how you invoke code blocks
for yourself.

@menu
* Integer loops:: Well, Smalltalk too has them
* Intervals:: And of course here's a peculiar way to use them
* Invoking code blocks:: You can do it, too
@end menu

@node Integer loops
@subsection Integer loops

Integer loops are constructed by telling a number to
drive the loop. Try this example to count from 1 to 20:
@example
   1 to: 20 do: [:x | x printNl ]
@end example

There's also a way to count up by more than one:
@example
   1 to: 20 by: 2 do: [:x | x printNl ]
@end example

Finally, counting down is done with a negative step:
@example
   20 to: 1 by: -1 do: [:x | x printNl ]
@end example

Note that the @code{x} variable is local to the block.
@example
   x
@end example
@noindent
just prints @code{nil}.

@node Intervals
@subsection Intervals
     It is also possible to represent a range of numbers as
a standalone object. This allows you to represent a range
of numbers as a single object, which can be passed around
the system.
@example
   i := Interval from: 5 to: 10
   i do: [:x | x printNl]
@end example

As with the integer loops, the Interval class can also
represent steps greater than 1. It is done much like it was
for our numeric loop above:
@example
   i := (Interval from: 5 to: 10 by: 2)
   i do: [:x| x printNl]
@end example

@node Invoking code blocks
@subsection Invoking code blocks

Let us revisit the checking example and add a method
for scanning only checks over a certain amount. This would
allow our user to find ``big'' checks, by passing in a value
below which we will not invoke their function. We will
invoke their code block with the check number as an argument
ment; they can use our existing check: message to get the
amount.

@example
   Checking extend [
       checksOver: amount do: aBlock
           history keysAndValuesDo: [:key :value |
               (value > amount)
                      ifTrue: [aBlock value: key]
           ]
   ]
@end example

The structure of this loop is much like our printChecks message
sage from chapter 6. However, in this case we consider each
entry, and only invoke the supplied block if the check's
value is greater than the specified amount. The line:

@example
   ifTrue: [aBlock value: key]
@end example

@noindent
invokes the user-supplied block, passing as an argument the
key, which is the check number. The @code{value:}
message, when received by a code block, causes the code
block to execute. Code blocks take @code{value}, @code{value:},
@code{value:value:}, and @code{value:value:value:} messages, so you
can pass from 0 to 3 arguments to a code block.@footnote{
There is also a @code{valueWithArguments:} message
which accepts an array holding as many arguments
as you would like.}

You might find it puzzling that an association takes a
@code{value} message, and so does a code block. Remember, each
object can do its own thing with a message. A code block gets
run when it receives a @code{value} message. An association merely
returns the value part of its key/value pair. The fact that
both take the same message is, in this case, coincidence.

Let's quickly set up a new checking account with $250
(wouldn't this be nice in real life?) and write a couple
checks. Then we'll see if our new method does the job
correctly:
@example
   mycheck := Checking new.
   mycheck deposit: 250
   mycheck newChecks: 100 count: 40
   mycheck writeCheck: 10
   mycheck writeCheck: 52
   mycheck writeCheck: 15
   mycheck checksOver: 1 do: [:x | x printNl]
   mycheck checksOver: 17 do: [:x | x printNl]
   mycheck checksOver: 200 do: [:x | x printNl]
@end example

We will finish this chapter with an alternative way of
writing our @code{checksOver:} code. In this example, we will use
the message @code{select:} to pick the checks which exceed our
value, instead of doing the comparison ourselves. We can
then invoke the new resulting collection against the user's
code block.

@example
   Checking extend [
       checksOver: amount do: aBlock [
           | chosen |
           chosen := history select: [:amt| amt > amount].
           chosen keysDo: aBlock
       ]
   ]
@end example

Note that @code{extend} will also overwrite methods. Try
the same tests as above, they should yield the same result!

@node Debugging
@section When Things Go Bad

So far we've been working with examples which work the
first time. If you didn't type them in correctly, you probably
received a flood of unintelligible complaints. You
probably ignored the complaints, and typed the example
again.

When developing your own Smalltalk code, however, these
messages are the way you find out what went wrong. Because
your objects, their methods, the error printout, and your
interactive environment are all contained within the same
Smalltalk session, you can use these error messages to debug
your code using very powerful techniques.

@menu
* Simple errors:: Those that only happen in examples
* Nested calls:: Those that actually happen in real life
* Looking at objects:: Trying to figure it out
@end menu

@node Simple errors
@subsection A Simple Error

First, let's take a look at a typical error. Type:
@example
   7 plus: 1
@end example

This will print out:
@example
   7 did not understand selector 'plus:'
   <blah blah>
   UndefinedObject>>#executeStatements
@end example

The first line is pretty simple; we sent a message to the
@code{7} object which was not understood; not surprising since
the @code{plus:} operation should have been @code{+}. Then there are
a few lines of gobbledegook: just ignore them, they reflect
the fact that the error passed throgh @gst{}'s exception
handling system. The remaining line reflect the way the
@gst{} invokes code which we type to our command prompt; it
generates a block of code which is invoked via an internal
method @code{executeStatements} defined in class Object and evaluated
like @code{nil executeStatements} (nil is an instance of @i{UndefinedObject}).
Thus, this output tells you that you directly typed a line which sent an
invalid message to the @code{7} object.

All the error output but the first line is actually a
stack backtrace. The most recent call is the one nearer the
top of the screen. In the next example, we will cause an
error which happens deeper within an object.

@node Nested calls
@subsection Nested Calls

Type the following lines:
@example
   x := Dictionary new
   x at: 1
@end example

The error you receive will look like:
@example
   Dictionary new: 31 "<0x33788>" error: key not found
   @i{@r{@dots{}blah blah@dots{}}}
   Dictionary>>#error:
   [] in Dictionary>>#at:
   [] in Dictionary>>#at:ifAbsent:
   Dictionary(HashedCollection)>>#findIndex:ifAbsent:
   Dictionary>>#at:ifAbsent:
   Dictionary>>#at:
   UndefinedObject(Object)>>#executeStatements
@end example

The error itself is pretty clear; we asked for something
within the Dictionary which wasn't there. The object
which had the error is identified as @code{Dictionary new: 31}.
A Dictionary's default size is 31; thus, this is the object
we created with @code{Dictionary new}.

The stack backtrace shows us the inner structure of how
a Dictionary responds to the @code{#at:} message. Our hand-entered
command causes the usual entry for @code{UndefinedObject(Object)}.
Then we see a Dictionary object responding to an @code{#at:} message
(the ``Dictionary>>#at:'' line). This code called the object
with an @code{#at:ifAbsent:} message. All of a sudden,
Dictionary calls that strange method @code{#findIndex:ifAbsent:},
which evaluates two blocks, and then the error happens.

To understand this better, it is necessary to know that
a very common way to handle errors in Smalltalk is to
hand down a block of code which will be called when an error
occurs. For the Dictionary code, the @code{at:} message passes
in a block of code to the at:ifAbsent: code to be called
when @code{at:ifAbsent:} can't find the given key, and
@code{at:ifAbsent:} does the same with @code{findIndex:ifAbsent:}.
Thus, without even looking at the code for Dictionary itself, we can
guess something of the code for Dictionary's implementation:

@example
   findIndex: key ifAbsent: errCodeBlock [
       @i{@r{@dots{}look for key@dots{}}}
       (keyNotFound) ifTrue: [ ^(errCodeBlock value) ]
       @i{@r{@dots{}}}
   ]

   at: key [
       ^self at: key ifAbsent: [^self error: 'key not found']
   ]
@end example

Actually, @code{findIndex:ifAbsent:} lies in class @code{HashedCollection},
as that @code{Dictionary(HashedCollection)} in the backtrace says.

It would be nice if each entry on the stack backtrace included
source line numbers. Unfortunately, at this point @gst{} doesn't
provide this feature. Of course, you have the source code
available...


@node Looking at objects
@subsection Looking at Objects

When you are chasing an error, it is often helpful to
examine the instance variables of your objects. While
strategic calls to @code{printNl} will no doubt help, you can look at an
object without having to write all the code yourself. The
@code{inspect} message works on any object, and dumps out the
values of each instance variable within the object.@footnote{When using
the Blox GUI, it actually pops up a so-called @dfn{Inspector window}.}

Thus:
@example
   x := Interval from: 1 to: 5.
   x inspect
@end example

displays:
@example
   An instance of Interval
   start: 1
   stop: 5
   step: 1
   contents: [
       [1]: 1
       [2]: 2
       [3]: 3
       [4]: 4
       [5]: 5
   ]
@end example

We'll finish this chapter by emphasizing a technique
which has already been covered: the use of the @code{error:}
message in your own objects. As you saw in the case of Dictionary,
an object can send itself an @code{error:} message with a
descriptive string to abort execution and dump a stack backtrace.
You should plan on using this technique in your own
objects. It can be used both for explicit user-caused
errors, as well as in internal sanity checks.


@node More subclassing
@section Coexisting in the Class Hierarchy

The early chapters of this tutorial discussed classes in
one of two ways. The ``toy'' classes we developed were rooted
at Object; the system-provided classes were treated as
immutable entities. While one shouldn't modify the behavior
of the standard classes lightly, ``plugging in'' your own
classes in the right place among their system-provided
brethren can provide you powerful new classes with very little
effort.

This chapter will create two complete classes which
enhance the existing Smalltalk hierarchy. The discussion
will start with the issue of where to connect our new
classes, and then continue onto implementation. Like most
programming efforts, the result will leave many possibilities
for improvements. The framework, however, should begin
to give you an intuition of how to develop your own
Smalltalk classes.

@menu
* The existing hierarchy:: We've been talking about it for a while,
                                     so here it is at last
* Playing with Arrays:: Again.
* New kinds of Numbers:: Sounds interesting, doesn't it?
* Inheritance and Polymorphism:: Sounds daunting, doesn't it?
@end menu

@node The existing hierarchy
@subsection The Existing Class Hierarchy

To discuss where a new class might go, it is helpful to
have a map of the current classes. The following is the
basic class hierarchy of @gst{}. Indentation means
that the line inherits from the earlier line with one less
level of indentation.@footnote{This listing is courtesy of the
printHierarchy method supplied by @gst{} author Steve
Byrne. It's in the @file{kernel/Browser.st} file.}.

@display
@t{ }Object
@t{ }Behavior
@t{ }ClassDescription
@t{ }Class
@t{ }Metaclass
@t{ }BlockClosure
@t{ }Boolean
@t{ }False
@t{ }True
@t{ }Browser
@t{ }CFunctionDescriptor
@t{ }CObject
@t{ }CAggregate
@t{ }CArray
@t{ }CPtr
@t{ }CCompound
@t{ }CStruct
@t{ }CUnion
@t{ }CScalar
@t{ }CChar
@t{ }CDouble
@t{ }CFloat
@t{ }CInt
@t{ }CLong
@t{ }CShort
@t{ }CSmalltalk
@t{ }CString
@t{ }CUChar
@t{ }CByte
@t{ }CBoolean
@t{ }CUInt
@t{ }CULong
@t{ }CUShort
@t{ }Collection
@t{ }Bag
@t{ }MappedCollection
@t{ }SequenceableCollection
@t{ }ArrayedCollection
@t{ }Array
@t{ }ByteArray
@t{ }WordArray
@t{ }LargeArrayedCollection
@t{ }LargeArray
@t{ }LargeByteArray
@t{ }LargeWordArray
@t{ }CompiledCode
@t{ }CompiledMethod
@t{ }CompiledBlock
@t{ }Interval
@t{ }CharacterArray
@t{ }String
@t{ }Symbol
@t{ }LinkedList
@t{ }Semaphore
@t{ }OrderedCollection
@t{ }RunArray
@t{ }SortedCollection
@t{ }HashedCollection
@t{ }Dictionary
@t{ }IdentityDictionary
@t{ }MethodDictionary
@t{ }RootNamespace
@t{ }Namespace
@t{ }SystemDictionary
@t{ }Set
@t{ }IdentitySet
@t{ }ContextPart
@t{ }BlockContext
@t{ }MethodContext
@t{ }CType
@t{ }CArrayCType
@t{ }CPtrCType
@t{ }CScalarCType
@t{ }Delay
@t{ }DLD
@t{ }DumperProxy
@t{ }AlternativeObjectProxy
@t{ }NullProxy
@t{ }VersionableObjectProxy
@t{ }PluggableProxy
@t{ }File
@t{ }Directory
@t{ }FileSegment
@t{ }Link
@t{ }Process
@t{ }SymLink
@t{ }Magnitude
@t{ }Association
@t{ }Character
@t{ }Date
@t{ }LargeArraySubpart
@t{ }Number
@t{ }Float
@t{ }Fraction
@t{ }Integer
@t{ }LargeInteger
@t{ }LargeNegativeInteger
@t{ }LargePositiveInteger
@t{ }LargeZeroInteger
@t{ }SmallInteger
@t{ }Time
@t{ }Memory
@t{ }Message
@t{ }DirectedMessage
@t{ }MethodInfo
@t{ }NullProxy
@t{ }PackageLoader
@t{ }Point
@t{ }ProcessorScheduler
@t{ }Rectangle
@t{ }SharedQueue
@t{ }Signal
@t{ }Exception
@t{ }Error
@t{ }Halt
@t{ }ArithmeticError
@t{ }ZeroDivide
@t{ }MessageNotUnderstood
@t{ }UserBreak
@t{ }Notification
@t{ }Warning
@t{ }Stream
@t{ }ObjectDumper
@t{ }PositionableStream
@t{ }ReadStream
@t{ }WriteStream
@t{ }ReadWriteStream
@t{ }ByteStream
@t{ }FileStream
@t{ }Random
@t{ }TextCollector
@t{ }TokenStream
@t{ }TrappableEvent
@t{ }CoreException
@t{ }ExceptionCollection
@t{ }UndefinedObject
@t{ }ValueAdaptor
@t{ }NullValueHolder
@t{ }PluggableAdaptor
@t{ }DelayedAdaptor
@t{ }ValueHolder
@end display

While initially a daunting list, you should take the
time to hunt down the classes we've examined in this tutorial
so far. Notice, for instance, how an Array is a subclass
below the @i{SequenceableCollection} class. This makes sense;
you can walk an Array from one end to the other. By contrast,
notice how this is not true for Sets: it doesn't make sense
to walk a Set from one end to the other.

A little puzzling is the relationship of a Bag to a Set, since
a Bag is actually a Set supporting multiple occurrences of its
elements. The answer lies in the purpose of both a Set and a
Bag. Both hold an unordered collection of objects; but a Bag
needs to be optimized for the case when an object has possibly
thousands of occurrences, while a Set is optimized for checking
object uniqueness. That's why Set being a subclass or Bag, or
the other way round, would be a source of problems in the actual
implementation of the class. Currently a Bag holds a Dictionary
associating each object to each count; it would be feasible however
to have Bag as a subclass of HashedCollection and a sibling of Set.

Look at the treatment of numbers---starting with the class
@i{Magnitude}. While numbers can indeed be ordered by @emph{less than},
@emph{greater than}, and so forth, so can a number of other
objects. Each subclass of Magnitude is such an
object. So we can compare characters with other characters,
dates with other dates, and times with other times, as well
as numbers with numbers.

Finally, you will have probably noted some pretty strange classes,
representing language entities that you might have never thought
of as objects themselves: @i{Namespace}, @i{Class} and even
@i{CompiledMethod}. They are the base of Smalltalk's ``reflection''
mechanism which will be discussed later, in @ref{Why is #new
there?!?, , The truth on metaclasses}.

@node Playing with Arrays
@subsection Playing with Arrays

Imagine that you need an array, but alas you need that if an index
is out of bounds, it returns nil. You could modify the Smalltalk
implementation, but that might break some code in the image, so it
is not practical. Why not add a subclass?

@example
   "We could subclass from Array, but that class is specifically
    optimized by the VM (which assumes, among other things, that
    it does not have any instance variables). So we use its
    abstract superclass instead. The discussion below holds
    equally well."
   ArrayedCollection subclass: NiledArray [
       <shape: #pointer>

       boundsCheck: index [
           ^(index < 1) | (index > (self basicSize))
       ]

       at: index [
           ^(self boundsCheck: index)
               ifTrue: [ nil ]
               ifFalse: [ super at: index ]
       ]

       at: index put: val [
           ^(self boundsCheck: index)
               ifTrue: [ val ]
               ifFalse: [ super at: index put: val ]
       ]
   ]
@end example

Much of the machinery of adding a class should be
familiar. We see another declaration like @code{comment:},
that is @code{shape:} message. This sets up @code{NiledArray}
to have the same underlying
structure of an @code{Array} object; we'll delay discussing this
until the chapter on the nuts and bolts of arrays. In any
case, we inherit all of the actual knowledge of how to create
arrays, reference them, and so forth. All that we do is
intercept @code{at:} and @code{at:put:} messages, call our common
function to validate the array index, and do something special
if the index is not valid. The way that we coded
the bounds check bears a little examination.

Making a first cut at coding the bounds check, you
might have coded the bounds check in NiledArray's methods
twice (once for @code{at:}, and again for @code{at:put:}. As
always, it's preferable to code things once, and then re-use them.
So we instead add a method for bounds checking @code{boundsCheck:}, and
use it for both cases. If we ever wanted to enhance the
bounds checking (perhaps emit an error if the index is < 1 and
answer nil only for indices greater than the array size?), we only
have to change it in one place.

The actual math for calculating whether the bounds have
been violated is a little interesting. The first part of
the expression returned by the method:
@example
   (index < 1) | (index > (self basicSize))
@end example

@noindent
is true if the index is less than 1, otherwise it's false.
This part of the expression thus becomes the boolean object
true or false. The boolean object then receives the message
@code{|}, and the argument @code{(index > (self basicSize))}.
@code{|} means ``or''---we want to OR together the two possible
out-of-range checks. What is the second part of the expression?
@footnote{Smalltalk also offers an @code{or:} message, which
is different in a subtle way from @code{|}. or: takes
a code block, and only invokes the code block if
it's necessary to determine the value of the
expression. This is analogous to the guaranteed C
semantic that @code{||} evaluates left-to-right only as
far as needed. We could have written the expressions
as @code{((index < 1) or: [index > (self basicSize)])}.
Since we expect both sides of or: to be
false most of the time, there isn't much reason to
delay evaluation of either side in this case.}

@code{index} is our argument, an integer; it receives the
message @code{>}, and thus will compare itself to the value
@code{self basicSize} returns. While we haven't covered the
underlying structures Smalltalk uses to build arrays, we can
briefly say that the @code{#basicSize} message returns the number
of elements the Array object can contain. So the index is checked
to see if it's less than 1 (the lowest legal Array index) or
greater than the highest allocated slot in the Array. If it
is either (the @code{|} operator!), the expression is true,
otherwise false.

From there it's downhill; our boolean object, returned by
@code{boundsCheck:}, receives the @code{ifTrue:ifFalse:} message,
and a code block which will do the appropriate thing. Why do we
have @code{at:put:} return val? Well, because that's what it's
supposed to do: look at every implementor of @code{at:put} or @code{at:}
and you'll find that it returns its second parameter. In general, the
result is discarded; but one could write a program which uses it, so
we'll write it this way anyway.


@node New kinds of Numbers
@subsection Adding a New Kind of Number

If we were programming an application which did a large
amount of complex math, we could probably manage it with a
number of two-element arrays. But we'd forever be writing
in-line code for the math and comparisons; it would be much
easier to just implement an object class to support the complex
numeric type. Where in the class hierarchy would it be
placed?

You've probably already guessed---but let's step down the
hierarchy anyway. Everything inherits from Object, so
that's a safe starting point. Complex numbers can not be
compared with @code{<} and @code{>}, and yet we strongly suspect that,
since they are numbers, we should place them under the Number
class. But Number inherits from Magnitude---how do we
resolve this conflict? A subclass can place itself under a
superclass which allows some operations the subclass doesn't
wish to allow. All that you must do is make sure you intercept
these messages and return an error. So we will place
our new Complex class under Number, and make sure to disallow
comparisons.

One can reasonably ask whether the real and imaginary
parts of our complex number will be integer or floating
point. In the grand Smalltalk tradition, we'll just leave
them as objects, and hope that they respond to numeric messages
reasonably. If they don't, the user will doubtless
receive errors and be able to track back their mistake with
little fuss.

We'll define the four basic math operators, as well as
the (illegal) relationals. We'll add @code{printOn:} so that the
printing methods work, and that should give us our Complex
class. The class as presented suffers some limitations,
which we'll cover later in the chapter.

@example
   Number subclass: Complex [
       | realpart imagpart |

       "This is a quick way to define class-side methods."
       Complex class >> new [
           <category: 'instance creation'>
           ^self error: 'use real:imaginary:'
       ]
       Complex class >> new: ignore [
           <category: 'instance creation'>
           ^self new
       ]
       Complex class >> real: r imaginary: i [
           <category: 'instance creation'>
           ^(super new) setReal: r setImag: i
       ]

       setReal: r setImag: i [
           <category: 'basic'>
           realpart := r.
           imagpart := i.
           ^self
       ]

       real [
           <category: 'basic'>
           ^realpart
       ]
       imaginary [
           <category: 'basic'>
           ^imagpart
       ]

       + val [
           <category: 'math'>
           ^Complex real: (realpart + val real)
               imaginary: (imagpart + val imaginary)
       ]
       - val [
           <category: 'math'>
           ^Complex real: (realpart - val real)
               imaginary: (imagpart - val imaginary)
       ]
       * val [
           <category: 'math'>
           ^Complex real: (realpart * val real) - (imagpart * val imaginary)
               imaginary: (imagpart * val real) + (realpart * val imaginary)
       ]
       / val [
           <category: 'math'>
           | d r i |
           d := (val real * val real) + (val imaginary * val imaginary).
           r := ((realpart * val real) + (imagpart * val imaginary)).
           i := ((imagpart * val real) - (realpart * val imaginary)).
           ^Complex real: r / d imaginary: i / d
       ]

       = val [
           <category: 'comparison'>
           ^(realpart = val real) & (imagpart = val imaginary)
       ]

       "All other comparison methods are based on <"
       < val [
           <category: 'comparison'>
           ^self shouldNotImplement
       ]

       printOn: aStream [
           <category: 'printing'>
           realpart printOn: aStream.
           aStream nextPut: $+.
           imagpart printOn: aStream.
           aStream nextPut: $i
       ]
   ]
@end example

There should be surprisingly little which is actually
new in this example. The printing method uses both @code{printOn:}
as well as @code{nextPut:} to do its printing. While we haven't
covered it, it's pretty clear that @code{$+} generates the ASCII
character @code{+} as an object@footnote{A @gst{} extension
  allows you to type characters by ASCII code too, as in
  @code{$<43>}.}, and @code{nextPut:} puts its argument
as the next thing on the stream.

The math operations all generate a new object, calculating
the real and imaginary parts, and invoking the Complex
class to create the new object. Our creation code is a
little more compact than earlier examples; instead of using
a local variable to name the newly-created object, we just
use the return value and send a message directly to the new
object. Our initialization code explicitly returns self;
what would happen if we left this off?

@node Inheritance and Polymorphism
@subsection Inheritance and Polymorphism

This is a good time to look at what we've done with the
two previous examples at a higher level. With the
NiledArray class, we inherited almost all of the functionality
ality of arrays, with only a little bit of code added to
address our specific needs. While you may have not thought
to try it, all the existing methods for an Array continue to
work without further effort-you might find it interesting to
ponder why the following still works:
@example
   a := NiledArray new: 10
   a at: 5 put: 1234
   a do: [:i| i printNl ]
@end example

The strength of inheritance is that you focus on the incremental
changes you make; the things you don't change will generally
continue to work.

In the Complex class, the value of polymorphism was
exercised. A Complex number responds to exactly the same
set of messages as any other number. If you had handed this
code to someone, they would know how to do math with Complex
numbers without further instruction. Compare this with C,
where a complex number package would require the user to
first find out if the complex-add function was
complex_plus(), or perhaps complex_add(), or add_complex(),
or@dots{}

However, one glaring deficiency is present in the Complex class:
what happens if you mix normal numbers with Complex numbers?
Currently, the Complex class assumes that it will only
interact with other Complex numbers. But this is unrealistic:
mathematically, a ``normal'' number is simply one with an
imaginary part of 0. Smalltalk was designed to allow numbers
to coerce themselves into a form which will work with
other numbers.

The system is clever and requires very little additional
code. Unfortunately, it would have tripled the
amount of explanation required. If you're interested in how
coercion works in @gst{}, you should find the
Smalltalk library source, and trace back the execution of
the @code{retry:coercing:} messages. You want to consider the
value which the @code{generality} message returns for each type
of number. Finally, you need to examine the @code{coerce:} handling
in each numeric class.


@node Streams
@section Smalltalk Streams

Our examples have used a mechanism extensively, even
though we haven't discussed it yet. The Stream class provides
a framework for a number of data structures, including
input and output functionality, queues, and endless sources
of dynamically-generated data. A Smalltalk stream is quite
similar to the UNIX streams you've used from C. A stream
provides a sequential view to an underlying resource; as you
read or write elements, the stream position advances until
you finally reach the end of the underlying medium. Most
streams also allow you to set the current position, providing
random access to the medium.

@menu
* The output stream:: Which, even though you maybe didn't know
                                     it, we've used all the time
* Your own stream:: Which, instead, is something new
* Files:: Which are streams too
* Dynamic Strings:: A useful application of Streams
@end menu

@node The output stream
@subsection The Output Stream

The examples in this book all work because they write
their output to the @code{Transcript} stream. Each class implements
the @code{printOn:} method, and writes its output to the supplied
stream. The @code{printNl} method all objects use is simply to
send the current object a @code{printOn:} message whose argument is
@code{Transcript} (by default attached to the standard output stream
found in the @code{stdout} global). You can invoke the standard output stream
directly:
@example
   'Hello, world' printOn: stdout
   stdout inspect
@end example

@noindent
or you can do the same for the Transcript, which is yet another stream:
@example
   'Hello, world' printOn: stdout
   Transcript inspect
@end example

@noindent
the last @code{inspect} statement will show you how the @code{Transcript} is
linked to @code{stdout}@footnote{Try executing it under Blox, where the
Transcript is linked to the omonymous window!}.

@node Your own stream
@subsection Your Own Stream

Unlike a pipe you might create in C, the underlying
storage of a Stream is under your control. Thus, a Stream
can provide an anonymous buffer of data, but it can also
provide a stream-like interpretation to an existing array of
data. Consider this example:
@example
   a := Array new: 10
   a at: 4 put: 1234
   a at: 9 put: 5678
   s := ReadWriteStream on: a.
   s inspect
   s position: 1
   s inspect
   s nextPut: 11; nextPut: 22
   (a at: 1) printNl
   a do: [:x| x printNl]
   s position: 2
   s do: [:x| x printNl]
   s position: 5
   s do: [:x| x printNl]
   s inspect
@end example

The key is the @code{on:} message; it tells a stream class to
create itself in terms of the existing storage. Because of
polymorphism, the object specified by on: does not have to
be an Array; any object which responds to numeric at: messages
can be used. If you happen to have the NiledArray
class still loaded from the previous chapter, you might try
streaming over that kind of array instead.

You're wondering if you're stuck with having to know
how much data will be queued in a Stream at the time you
create the stream. If you use the right class of stream,
the answer is no. A ReadStream provides read-only access to
an existing collection. You will receive an error if you
try to write to it. If you try to read off the end of the
stream, you will also get an error.

By contrast, WriteStream and ReadWriteStream (used in
our example) will tell the underlying collection to grow
when you write off the end of the existing collection. Thus,
if you want to write several strings, and don't want to add up their
lengths yourself:

@example
   s := ReadWriteStream on: String new
   s inspect
   s nextPutAll: 'Hello, '
   s inspect
   s nextPutAll: 'world'
   s inspect
   s position: 1
   s inspect
   s do: [:c | stdout nextPut: c ]
   s contents
@end example

In this case, we have used a String as the collection
for the Stream. The @code{printOn:} messages add bytes to the initially
empty string. Once we've added the data, you can
continue to treat the data as a stream. Alternatively, you
can ask the stream to return to you the underlying object.
After that, you can use the object (a String, in this example)
using its own access methods.

There are many amenities available on a stream object.
You can ask if there's more to read with @code{atEnd}. You can
query the position with @code{position}, and set it with @code{position:}.
You can see what will be read next with @code{peek}, and
you can read the next element with @code{next}.

In the writing direction, you can write an element with
@code{nextPut:}. You don't need to worry about objects doing a
@code{printOn:} with your stream as a destination; this operation
ends up as a sequence of @code{nextPut:} operations to your stream.
If you have a collection of things to write, you can use
@code{nextPutAll:} with the collection as an argument; each member
of the collection will be written onto the stream. If you
want to write an object to the stream several times, you
can use @code{next:put:}, like this:

@example
   s := ReadWriteStream on: (Array new: 0)
   s next: 4 put: 'Hi!'
   s position: 1
   s do: [:x | x printNl]
@end example

@node Files
@subsection Files

Streams can also operate on files. If you wanted to
dump the file @file{/etc/passwd} to your terminal, you could
create a stream on the file, and then stream over its contents:
@example
   f := FileStream open: '/etc/passwd' mode: FileStream read
   f linesDo: [ :c | Transcript nextPutAll: c; nl ]
   f position: 30
   25 timesRepeat: [ Transcript nextPut: (f next) ]
   f close
@end example

and, of course, you can load Smalltalk source code into your
image:
@example
   FileStream fileIn: '/Users/myself/src/source.st'
@end example

@node Dynamic Strings
@subsection Dynamic Strings

Streams provide a powerful abstraction for a number of
data structures. Concepts like current position, writing
the next position, and changing the way you view a data
structure when convenient combine to let you write compact,
powerful code. The last example is taken from the actual
Smalltalk source code---it shows a general method for making
an object print itself onto a string.

@example
   printString [
       | stream |
       stream := WriteStream on: (String new).
       self printOn: stream.
       ^stream contents
   ]
@end example

This method, residing in Object, is inherited by every
class in Smalltalk. The first line creates a WriteStream
which stores on a String whose length is currently 0
(@code{String new} simply creates an empty string. It
then invokes the current object with @code{printOn:}. As the
object prints itself to ``stream'', the String grows to accommodate
new characters. When the object is done printing,
the method simply returns the underlying string.

As we've written code, the assumption has been that
printOn: would go to the terminal. But replacing a stream
to a file like @file{/dev/tty} with a stream to a data
structure (@code{String new}) works just as well. The last line
tells the Stream to return its underlying collection, which will
be the string which has had all the printing added to it. The
result is that the @code{printString} message returns an object of
the String class whose contents are the printed representation
of the very object receiving the message.


@node Exception handling
@section Exception handling in Smalltalk

Up to this point of the tutorial, you used the original Smalltalk-80
error signalling mechanism:

@example
   check: num [
       | c |
       c := history
           at: num
           ifAbsent: [ ^self error: 'No such check #' ].
       ^c
   ]
@end example

In the above code, if a matching check number is found, the method will
answer the object associated to it. If no prefix is found, Smalltalk
will unwind the stack and print an error message including the message
you gave and stack information.

@example
CheckingAccount new: 31 "<0x33788>" error: No such check #
@i{@r{@dots{}blah blah@dots{}}}
CheckingAccount>>#error:
[] in Dictionary>>#at:ifAbsent:
Dictionary(HashedCollection)>>#findIndex:ifAbsent:
Dictionary>>#at:ifAbsent:
[] in CheckingAccount>>#check:
CheckingAccount>>#check:
UndefinedObject(Object)>>#executeStatements
@end example

Above we see the object that received the #error: message, the message
text itself, and the frames (innermost-first) running when the error was
captured by the system. In addition, the rest of the code in methods
like @code{CheckingAccount>>#check:} was not executed.

So simple error reporting gives us most of the features we want:

@itemize @bullet
@item
Execution stops immediately, preventing programs from continuing as if
nothing is wrong.

@item
The failing code provides a more-or-less useful error message.

@item
Basic system state information is provided for diagnosis.

@item
A debugger can drill further into the state, providing information like
details of the receivers and arguments on the stack.
@end itemize

However, there is a more powerful and complex error handling mechanism,
that is @dfn{exception}. They are like "exceptions" in other programming
languages, but are more powerful and do not always indicate error
conditions. Even though we use the term "signal" often with regard
to them, do not confuse them with the signals like @code{SIGTERM} and
@code{SIGINT} provided by some operating systems; they are a different
concept altogether.

Deciding to use exceptions instead of @code{#error:} is a matter of
aesthetics, but you can use a simple rule: use exceptions only if you want
to provide callers with a way to recover sensibly from certain errors,
and then only for signalling those particular errors.

For example, if you are writing a word processor, you might provide the
user with a way to make regions of text read-only. Then, if the user
tries to edit the text, the objects that model the read-only text can
signal a @code{ReadOnlyText} or other kind of exception, whereupon the
user interface code can stop the exception from unwinding and report
the error to the user.

When in doubt about whether exceptions would be useful, err on the side
of simplicity; use @code{#error:} instead. It is much easier to convert an
#error: to an explicit exception than to do the opposite.

@menu
* Creating exceptions:: Starting to use the mechanism
* Raising exceptions:: What to do when exceptional events happen
* Handling exceptions:: The other side
* When an exception isn't handled:: Default actions
* Creating new exception classes:: Your own exceptions
* Hooking into the stack unwinding:: An alternative exception handling system
* Handler stack unwinding caveat:: Differences with other languages
@end menu

@node Creating exceptions
@subsection Creating exceptions

@gst{} provides a few exceptions, all of which are subclasses of
@code{Exception}. Most of the ones you might want to create yourself are
in the @code{SystemExceptions} namespace. You can browse the builtin
exceptions in the base library reference, and look at their names with
@code{Exception printHierarchy}.

Some useful examples from the system exceptions are
@code{SystemExceptions.InvalidValue}, whose meaning should be obvious, and
@code{SystemExceptions.WrongMessageSent}, which we will demonstrate below.

Let's say that you change one of your classes to no longer support #new
for creating new instances. However, because you use the first-class
classes feature of Smalltalk, it is not so easy to find and change
all sends. Now, you can do something like this:

@example
Object subclass: Toaster [
    Toaster class >> new [
        ^SystemExceptions.WrongMessageSent
            signalOn: #new useInstead: #toast:
    ]

    Toaster class >> toast: reason [
        ^super new reason: reason; yourself
    ]

    ...
]
@end example

Admittedly, this doesn't quite fit the conditions for using exceptions.
However, since the exception type is already provided, it is probably
easier to use it than #error: when you are doing defensive programming
of this sort.

@node Raising exceptions
@subsection Raising exceptions

Raising an exception is really a two-step process. First, you create
the exception object; then, you send it @code{#signal}.

If you look through the hierarchy, you'll see many class methods
that combine these steps for convenience. For example, the class
@code{Exception} provides @code{#new} and @code{#signal}, where the
latter is just @code{^self new signal}.

You may be tempted to provide only a signalling variant of your own
exception creation methods. However, this creates the problem that
your subclasses will not be able to trivially provide new instance
creation methods.

@example
Error subclass: ReadOnlyText [
    ReadOnlyText class >> signalOn: aText range: anInterval [
        ^self new initText: aText range: anInterval; signal
    ]

    initText: aText range: anInterval [
        <category: 'private'>
        ...
    ]
]
@end example

Here, if you ever want to subclass @code{ReadOnlyText} and add new
information to the instance before signalling it, you'll have to use
the private method @code{#initText:range:}.

We recommend leaving out the signalling instance-creation variant in new
code, as it saves very little work and makes signalling code less clear.
Use your own judgement and evaluation of the situation to determine when
to include a signalling variant.

@node Handling exceptions
@subsection Handling exceptions

To handle an exception when it occurs in a particular block of code,
use @code{#on:do:} like this:

@example
^[someText add: inputChar beforeIndex: i]
    on: ReadOnlyText
    do: [:sig | sig return: nil]
@end example

This code will put a handler for @code{ReadOnlyText} signals on the
handler stack while the first block is executing. If such an exception
occurs, and it is not handled by any handlers closer to the point of
signalling on the stack (known as "inner handlers"), the exception object
will pass itself to the handler block given as the @code{do:} argument.

You will almost always want to use this object to handle the exception
somehow. There are six basic handler actions, all sent as messages to
the exception object:

@table @code
@item return:
Exit the block that received this @code{#on:do:}, returning the given value.
You can also leave out the argument by sending @code{#return}, in which case
it will be nil. If you want this handler to also handle exceptions in
whatever value you might provide, you should use @code{#retryUsing:} with a
block instead.

@item retry
Acts sort of like a "goto" by restarting the first block. Obviously,
this can lead to an infinite loop if you don't fix the situation that
caused the exception.

@code{#retry} is a good way to implement reinvocation upon recovery,
because it does not increase the stack height. For example, this:

@example
  frobnicate: n [
    ^[do some stuff with n]
        on: SomeError
        do: [:sig | sig return: (self frobnicate: n + 1)]
    ]
@end example

@noindent
should be replaced with retry:

@example
  frobnicate: aNumber [
    | n |
    n := aNumber.
    ^[do some stuff with n]
        on: SomeError
        do: [:sig | n := 1 + n. sig retry]
  ]
@end example

@item retryUsing:
Like @code{#retry}, except that it effectively replaces the original
block with the one given as an argument.

@item pass
If you want to tell the exception to let an outer handler handle it,
use @code{#pass} instead of @code{#signal}. This is just like rethrowing
a caught exception in other languages.

@item resume:
This is the really interesting one. Instead of unwinding the stack,
this will effectively answer the argument from the @code{#signal} send.
Code that sends @code{#signal} to resumable exceptions can use this
value, or ignore it, and continue executing. You can also leave out
the argument, in which case the @code{#signal} send will answer nil.
Exceptions that want to be resumable must register this capability by
answering @code{true} from the @code{#isResumable} method, which is
checked on every @code{#resume:} send.

@item outer
This is like @code{#pass}, but if an outer handler uses @code{#resume:},
this handler block will be resumed (and @code{#outer} will answer the
argument given to @code{#resume:}) rather than the piece of code that
sent @code{#signal} in the first place.
@end table

None of these methods return to the invoking handler block except for
@code{#outer}, and that only in certain cases described for it above.

Exceptions provide several more features; see the methods on the classes
@code{Signal} and @code{Exception} for the various things you can do
with them. Fortunately, the above methods can do what you want in almost
all cases.

If you don't use one of these methods or another exception feature to exit
your handler, Smalltalk will assume that you meant to @code{sig return:}
whatever you answer from your handler block. We don't recommend relying
on this; you should use an explicit @code{sig return:} instead.

A quick shortcut to handling multiple exception types is the
@code{ExceptionSet}, which allows you to have a single handler for the
exceptions of a union of classes:

@example
^[do some stuff with n]
    on: SomeError, ReadOnlyError
    do: [:sig | ...]
@end example

In this code, any @code{SomeError} or @code{ReadOnlyError} signals will
be handled by the given handler block.

@node When an exception isn't handled
@subsection When an exception isn't handled

Every exception chooses one of the above handler actions by default when
no handler is found, or they all use @code{#pass}. This is invoked by
sending @code{#defaultAction} to the class.

One example of a default action is presented above as part of the example
of @code{#error:} usage; that default action prints a message, backtrace,
and unwinds the stack all the way.

The easiest way to choose a default action for your own exception classes
is to subclass from an exception class that already chose the right one,
as explained in the next section. For example, some exceptions, such
as warnings, resume by default, and thus should be treated as if they
will almost always resume.

Selecting by superclass is by no means a requirement. Specializing your
@code{Error} subclass to be resumable, or even to resume by default,
is perfectly acceptable when it makes sense for your design.

@node Creating new exception classes
@subsection Creating new exception classes

If you want code to be able to handle your signalled exceptions, you will
probably want to provide a way to pick those kinds out automatically.
The easiest way to do this is to subclass @code{Exception}.

First, you should choose an exception class to specialize. @code{Error}
is the best choice for non-resumable exceptions, and @code{Notification}
or its subclass @code{Warning} is best for exceptions that should resume
with @code{nil} by default.

Exceptions are just normal objects; include whatever information you think
would be useful to handlers. Note that there are two textual description
fields, a @dfn{description} and a @dfn{message text}. The description,
if provided, should be a more-or-less constant string answered from a
override method on @code{#description}, meant to describe all instances
of your exception class. The message text is meant to be provided at
the point of signalling, and should be used for any extra information
that code might want to provide. Your signalling code can provide the
@code{messageText} by using @code{#signal:} instead of @code{#signal}.
This is yet another reason why signalling variants of instance creation
messages can be more trouble than they're worth.

@node Hooking into the stack unwinding
@subsection Hooking into the stack unwinding

More often useful than even @code{#on:do:} is @code{#ensure:}, which
guarantees that some code is executed when the stack unwinds, whether
because of normal execution or because of a signalled exception.

Here is an example of use of @code{#ensure:} and a situation where the
stack can unwind even without a signal:

@example
Object subclass: ExecuteWithBreak [
  | breakBlock |

  break: anObject [
    breakBlock value: anObject
  ]

  valueWithBreak: aBlock [
    "Sets up breakBlock before entering the block,
     and passes self to the block."
    | oldBreakBlock |
    oldBreakBlock := breakBlock.
    ^[breakBlock := [:arg | ^arg].
      aBlock value]
        ensure: [breakBlock := oldBreakBlock]
  ]
]
@end example

This class provides a way to stop the execution of a block without
exiting the whole method as using @code{^} inside a block would do.
The use of @code{#ensure:} guarantees (hence the name "ensure") that even
if @code{breakBlock} is invoked or an error is handled by unwinding,
the old ``break block'' will be restored.

The definition of @code{breakBlock} is extremely simply; it is an
example of the general unwinding feature of blocks, that you have
probably already used:

@example
       (history includesKey: num)
           ifTrue: [ ^self error: 'Duplicate check number' ].
@end example

You have probably been using @code{#ensure:} without knowing. For example,
@code{File>>#withReadStreamDo:} uses it to ensure that the file is
closed when leaving the block.

@node Handler stack unwinding caveat
@subsection Handler stack unwinding caveat

One important difference between Smalltalk and other languages is
that when a handler is invoked, the stack is not unwound.
The Smalltalk exception system is designed this way because it's rare
to write code that could break because of this difference, and the
@code{#resume:} feature doesn't make sense if the stack is unwound.
It is easy enough to unwind a stack later, and is not so easy to wind
it again if done too early.

For almost all applications, this will not matter, but it technically
changes the semantics significantly so should be kept in mind. One
important case in which it might matter is when using @code{#ensure:}
blocks @emph{and} exception handlers. For comparison, this Smalltalk
code:

@example
| n |
n := 42.
[[self error: 'error'] ensure: [n := 24]]
    on: Error
    do: [:sig | n printNl. sig return].
n printNl.
@end example

@noindent
will put "42" followed by "24" on the transcript, because the @code{n :=
24} will not be executed until @code{sig return} is invoked, unwinding
the stack. Similar Java code acts differently:

@example
int n = 42;
try
  @{
    try @{throw new Exception ("42");@}
    finally @{n = 24;@}
  @}
catch (Exception e)
  @{
    System.out.println (n);
  @}
System.out.println (n);
@end example

@noindent
printing "24" twice, because the stack unwinds before executing the
catch block.

@node Behind the scenes
@section Some nice stuff from the Smalltalk innards

Just like with everything else, you'd probably end up asking yourself:
how's it done? So here's this chapter, just to wheten your appetite...

@menu
* Inside Arrays:: Delving into something old
* Two flavors of equality:: Delving into something new
* Why is #new there?!?:: Or, the truth on metaclasses
* Performance:: Hmm... they told me Smalltalk is slow...
@end menu

@node Inside Arrays
@subsection How Arrays Work
Smalltalk provides a very adequate selection of predefined
classes from which to choose. Eventually, however,
you will find the need to code a new basic data structure.
Because Smalltalk's most fundamental storage allocation
facilities are arrays, it is important that you understand
how to use them to gain efficient access to this kind of
storage.

@b{The Array Class.} Our examples have already shown the Array class, and
its use is fairly obvious. For many applications, it will
fill all your needs---when you need an array in a new class,
you keep an instance variable, allocate a new Array and
assign it to the variable, and then send array accesses via
the instance variable.

This technique even works for string-like objects,
although it is wasteful of storage. An Array object uses a
Smalltalk pointer for each slot in the array; its exact size
is transparent to the programmer, but you can generally
guess that it'll be roughly the word size of your machine.
@footnote{For @gst{}, the size of a C @code{long}, which
is usually 32 bits.} For storing an array of characters, therefore,
an Array works but is inefficient.

@b{Arrays at a Lower Level.} So let's step down to a lower level of data
structure. A ByteArray is much like an Array, but each slot holds only
an integer from 0 to 255-and each slot uses only a byte of
storage. If you only needed to store small quantities in
each array slot, this would therefore be a much more efficient
choice than an Array. As you might guess, this is the
type of array which a String uses.

Aha! But when you go back to chapter 9 and look at the
Smalltalk hierarchy, you notice that String does not inherit
from ByteArray. To see why, we must delve down yet another
level, and arrive at the basic methods for setting up the
structure of the instances of a class.

When we implemented our NiledArray example, we used
@code{<shape: #inherit>}. The shape is exactly that:
the fundamental structure of Smalltalk objects created within a given
class. Let's consider the differences in the next sub-sections.

@table @asis
@item Nothing
The default shape specifies the simplest
Smalltalk object. The object consists only of the storage
needed to hold the instance variables. In C, this would be
a simple structure with zero or more scalar fields.@footnote{C
requires one or more; zero is allowed in Smalltalk}.

@item @code{#pointer}
Storage is still allocated for any instance
variables, but the objects of the class must be created with a
@code{new:} message.
The number passed as an argument to @code{new:} causes the new
object, in addition to the space for instance variables, to
also have that many slots of unnamed (indexed) storage allocated.
The analog in C would be to have a dynamically allocated structure
with some scalar fields, followed at its end by a array of pointers.

@item @code{#byte}
The storage allocated as specified by new: is an array of bytes.
The analog in C would be a dynamically allocated structure with
scalar fields@footnote{This is not always true for other Smalltalk
implementations, who don't allow instance variables in variableByteSubclasses
and variableWordSubclasses.}, followed by a array of @code{char}.

@item @code{#word}
The storage allocated as specified by new: is an array of C unsigned longs,
which are represented in Smalltalk by Integer objects. The analog in
C would be a dynamically allocated structure with scalar fields, followed
by an array of @code{long}. This kind of subclass is only used in a few
places in Smalltalk.

@item @code{#character}
The storage allocated as specified by new: is an array of characters.
The analog in C would be a dynamically allocated structure with
scalar fields, followed by a array of @code{char}.
@end table

There are many more shapes for more specialized usage. All of them
specify the same kind of ``array-like'' behavior, with different
data types.

How to access this new arrays? You already know how to access instance
variables---by name. But there doesn't seem to be a name for this new
storage. The way an object accesses it is to send itself
array-type messages like @code{at:}, @code{at:put:}, and so forth.

The problem is when an object wants to add a new level
of interpretation to these messages. Consider
a Dictionary---it is a pointer-holding object
but its @code{at:} message is in terms of a key, not an integer
index of its storage. Since it has redefined the @code{at:} message, how
does it access its fundamental storage?

The answer is that Smalltalk has defined @code{basicAt:} and
@code{basicAt:put:}, which will access the basic storage even when
the @code{at:} and @code{at:put:} messages have been defined to provide
a different abstraction.

This can get pretty confusing in the abstract, so let's
do an example to show how it's pretty simple in practice.
Smalltalk arrays tend to start at 1; let's define an array
type whose permissible range is arbitrary.

@example
   ArrayedCollection subclass: RangedArray [
       | offset |
       <comment: 'I am an Array whose base is arbitrary'>
       RangedArray class >> new: size [
           <category: 'instance creation'>
           ^self new: size base: 1
       ]
       RangedArray class >> new: size base: b [
           <category: 'instance creation'>
           ^(super new: size) init: b
       ]

       init: b [
           <category: 'init'>
           offset := (b - 1). "- 1 because basicAt: works with a 1 base"
           ^self
      ]
      rangeCheck: i [
           <category: 'basic'>
           (i <= offset) | (i > (offset + self basicSize)) ifTrue: [
               'Bad index value: ' printOn: stderr.
               i printOn: stderr.
               Character nl printOn: stderr.
               ^self error: 'illegal index'
           ]
       ]
       at: [
           self rangeCheck: i.
           ^self basicAt: i - offset
       ]
       at: i put: v [
           self rangeCheck: i.
           ^self basicAt: i - offset put: v
       ]
   ]
@end example

The code has two parts; an initialization, which simply
records what index you wish the array to start with, and the
at: messages, which adjust the requested index so that the
underlying storage receives its 1-based index instead.
We've included a range check; its
utility will demonstrate itself in a moment:
@example
   a := RangedArray new: 10 base: 5.
   a at: 5 put: 0
   a at: 4 put: 1
@end example

Since 4 is below our base of 5, a range check error occurs.
But this check can catch more than just our own misbehavior!

@example
   a do: [:x| x printNl]
@end example

Our do: message handling is broken! The stack backtrace
pretty much tells the story:

@example
   RangedArray>>#rangeCheck:
   RangedArray>>#at:
   RangedArray>>#do:
@end example

Our code received a do: message. We didn't define one, so
we inherited the existing do: handling. We see that an
Integer loop was constructed, that a code block was invoked,
and that our own at: code was invoked. When we range
checked, we trapped an illegal index. Just by coincidence,
this version of our range checking code also dumps the
index. We see that do: has assumed that all arrays start at
1.

The immediate fix is obvious; we implement our own do:

@example
   RangedArray extend [
       do: aBlock [
           <category: 'basic'>
           1 to: (self basicSize) do: [:x|
               aBlock value: (self basicAt: x)
           ]
       ]
   ]
@end example

But the issues start to run deep. If our parent class
believed that it knew enough to assume a starting index of
1@footnote{Actually, in @gst{} @code{do:} is not the only
message assuming that.}, why didn't it also assume that it could
call basicAt:? The answer is that of the two choices, the designer
of the parent class chose the one which was less likely to cause
trouble; in fact all standard Smalltalk collections do have indices
starting at 1, yet not all of them are implemented so
that calling basicAt: would work.@footnote{Some of these classes
actually redefine @code{do:} for performance reasons, but they
would work even if the parent class' implementation of @code{do:}
was kept.}

Object-oriented methodology says that one object should be
entirely opaque to another. But what sort of privacy should
there be between a higher class and its subclasses? How
many assumption can a subclass make about its superclass,
and how many can the superclass make before it begins
infringing on the sovereignty of its subclasses?

Alas, there are rarely easy answers, and this is just an example.
For this particular problem, there is an easy solution. When the
storage need not be accessed with peak efficiency, you can use the
existing array classes. When every access counts, having the
storage be an integral part of your own object allows for
the quickest access---but remember that when you move into this
area, inheritance and polymorphism become trickier, as
each level must coordinate its use of the underlying array
with other levels.


@node Two flavors of equality
@subsection Two flavors of equality
As first seen in chapter two, Smalltalk keys its dictionary
with things like @i{#word}, whereas we generally use
@i{'word'}. The former, as it turns out, is from class Symbol.
The latter is from class String. What's the real difference
between a Symbol and a String? To answer the question, we'll
use an analogy from C.

In C, if you have a function for comparing strings, you
might try to write it:
@example
   streq(char *p, char *q)
   @{
       return (p == q);
   @}
@end example

But clearly this is wrong! The reason is that you can have
two copies of a string, each with the same contents but each
at its own address. A correct string compare must walk its
way through the strings and compare each element.

In Smalltalk, exactly the same issue exists, although
the details of manipulating storage addresses are hidden.
If we have two Smalltalk strings, both with the same contents,
we don't necessarily know if they're at the same
storage address. In Smalltalk terms, we don't know if
they're the same object.

The Smalltalk dictionary is searched frequently. To
speed the search, it would be nice to not have to compare
the characters of each element, but only compare the address
itself. To do this, you need to have a guarantee that all
strings with the same contents are the same object. The
String class, created like:
@example
   y := 'Hello'
@end example
@noindent
does not satisfy this. Each time you execute this line, you
may well get a new object. But a very similar class, Symbol,
will always return the same object:
@example
   y := #Hello
@end example

In general, you can use strings for almost all your tasks.
If you ever get into a performance-critical function which
looks up strings, you can switch to Symbol. It takes longer
to create a Symbol, and the memory for a Symbol is never
freed (since the class has to keep tabs on it indefinitely
to guarantee it continues to return the same object). You
can use it, but use it with care.

This tutorial has generally used the strcmp()-ish kind of
checks for equality. If you ever need to ask the question
``is this the same object?'', you use the @code{==} operator
instead of @code{=}:
@example
   x := y := 'Hello'
   (x = y) printNl
   (x == y) printNl
   y := 'Hel', 'lo'
   (x = y) printNl
   (x == y) printNl
   x := #Hello
   y := #Hello
   (x = y) printNl
   (x == y) printNl
@end example

Using C terms, @code{=} compares contents like @code{strcmp()}.
@code{==} compares storage addresses, like a pointer comparison.

@node Why is #new there?!?
@subsection The truth about metaclasses

Everybody, sooner or later, looks for the implementation of the
@code{#new} method in Object class. To their surprise, they
don't find it; if they're really smart, they search for implementors
of #new in the image and they find out it is implemented by
@code{Behavior}... which turns out to be a subclass of Object! The
truth starts showing to their eyes about that sentence that everybody
says but few people understand: ``classes are objects''.

Huh? Classes are objects?!? Let me explain.

@ifinfo
Open up an image; then type the text following the
@code{st>} prompt.
@end ifinfo
@ifhtml
Open up an image; then type the text following the
@code{st>} prompt.
@end ifhtml
@iftex
Open up an image; then type the text printed in
@t{mono-spaced} font.
@end iftex

@display
    st> @t{Set superclass!}
    HashedCollection

    st> @t{HashedCollection superclass!}
    Collection

    st> @t{Collection superclass!}
    Object

    st> @t{Object superclass!}
    nil
@end display

Nothing new for now. Let's try something else:

@display
    st> @t{#(1 2 3) class!}
    Array

    st> @t{'123' class!}
    String

    st> @t{Set class!}
    Set class

    st> @t{Set class class!}
    Metaclass
@end display

You get it, that strange @code{Set class} thing is something
called ``a meta-class''... let's go on:

@display
    st> @t{^Set class superclass!}
    Collection class

    st> @t{^Collection class superclass!}
    Object class
@end display

You see, there is a sort of `parallel' hierarchy between classes
and metaclasses. When you create a class, Smalltalk creates a
metaclass; and just like a class describes how methods for its
instances work, a metaclass describes how class methods for that
same class work.

@code{Set} is an instance of the metaclass, so when you invoke
the @code{#new} class method, you can also say you are invoking
an instance method implemented by @code{Set class}. Simply put,
class methods are a lie: they're simply instance methods that
are understood by instances of metaclasses.

Now you would expect that @code{Object class superclass} answers
@code{nil class}, that is @code{UndefinedObject}. Yet you saw that
@code{#new} is not implemented there... let's try it:

@display
    st> @t{^Object class superclass!}
    Class
@end display

Uh?!? Try to read it aloud: the @code{Object class} class inherits
from the @code{Class} class. @code{Class} is the abstract superclass
of all metaclasses, and provides the logic that allows you to create
classes in the image. But it is not the termination point:

@display
    st> @t{^Class superclass!}
    ClassDescription

    st> @t{^ClassDescription superclass!}
    Behavior

    st> @t{^Behavior superclass!}
    Object
@end display

Class is a subclass of other classes. @code{ClassDescription} is
abstract; @code{Behavior} is concrete but lacks the methods
and state that allow classes to have named instance variables,
class comments and more. Its instances are called
@emph{light-weight} classes because they don't have separate
metaclasses, instead they all share @code{Behavior} itself as
their metaclass.

Evaluating @code{Behavior superclass} we have worked our way up to
class Object again: Object is the superclass of all instances as well
as all metaclasses. This complicated system is extremely powerful,
and allows you to do very interesting things that you probably did
without thinking about it---for example, using methods such as
@code{#error:} or @code{#shouldNotImplement} in class methods.

Now, one final question and one final step: what are metaclasses
instances of? The question makes sense: if everything has a class,
should not metaclasses have one?

Evaluate the following:

@display
    st> @t{meta := Set class}
    st> @t{0 to: 4 do: [ :i |}
    st> @t{ i timesRepeat: [ Transcript space ]}
    st> @t{ meta printNl}
    st> @t{ meta := meta class}
    st> @t{]}
    Set class
     Metaclass
      Metaclass class
       Metaclass
        Metaclass class
    0
@end display

If you send @code{#class} repeatedly, it seems that you end up
in a loop made of class @code{Metaclass}@footnote{Which turns
out to be another subclass of @code{ClassDescription}.} and its
own metaclass, @code{Metaclass class}. It looks like class
Metaclass is @i{an instance of an instance of itself}.

To understand the role of @code{Metaclass}, it can be useful
to know that the class creation is implemented there.
Think about it.

@itemize @bullet
@item
@code{Random class} implements creation and
initialization of its instances' random number seed;
analogously, @code{Metaclass class} implements creation and
initialization of its instances, which are metaclasses.

@item
And @code{Metaclass} implements creation and initialization of
its instances, which are classes (subclasses of @code{Class}).
@end itemize

The circle is closed. In the end, this mechanism implements a
clean, elegant and (with some contemplation) understandable
facility for self-definition of classes. In other words, it
is what allows classes to talk about themselves, posing the
foundation for the creation of browsers.


@node Performance
@subsection The truth of Smalltalk performance

Everybody says Smalltalk is slow, yet this is not completely true for
at least three reasons. First, most of the time in graphical applications
is spent waiting for the user to ``do something'', and most of the time
in scripting applications (which @gst{} is particularly well
versed in) is spent in disk I/O; implementing a travelling salesman
problem in Smalltalk would indeed be slow, but for most real applications
you can indeed exchange performance for Smalltalk's power and development
speed.

Second, Smalltalk's automatic memory management is faster than C's manual
one. Most C programs are sped up if you relink them with one of the
garbage collecting systems available for C or C++.

Third, even though very few Smalltalk virtual machines are as optimized as,
say, the Self environment (which reaches half the speed of optimized C!),
they do perform some optimizations on Smalltalk code which make them run
many times faster than a naive bytecode interpreter. Peter Deutsch, who
among other things invented the idea of a just-in-time compiler like those
you are used to seeing for Java@footnote{And like the one that @gst{}
includes as an experimental feature.}, once observed that implementing a
language like Smalltalk efficiently requires the implementor to cheat...
but that's okay as long as you don't get caught. That is, as long as you
don't break the language semantics. Let's look at some of these optimizations.

For certain frequently used 'special selectors', the compiler emits a
send-special-selector bytecode instead of a send-message bytecode.
Special selectors have one of three behaviors:

@itemize @bullet
@item
A few selectors are assigned to special bytecode solely in order to
save space. This is the case for @code{#do:} for example.

@item
Three selectors (@code{#at:}, @code{#at:put:}, @code{#size}) are
assigned to special bytecodes because they are subject to a special
caching optimization. These selectors often result in calling a
virtual machine primitive, so @gst{} remembers which primitve
was last called as the result of sending them. If we send @code{#at:}
100 times for the same class, the last 99 sends are directly mapped
to the primitive, skipping the method lookup phase.

@item
For some pairs of receiver classes and special selectors, the
interpreter never looks up the method in the class; instead it swiftly
executes the same code which is tied to a particular primitive. Of
course a special selector whose receiver or argument is not of the
right class to make a no-lookup pair is looked up normally.
@end itemize

No-lookup methods do contain a primitive number specification,
@code{<primitive: xx>}, but it is used only when the method is
reached through a @code{#perform:@dots{}} message send. Since
the method is not normally looked up, deleting the primitive name
specification cannot in general prevent this primitive from running.
No-lookup pairs are listed below:

@multitable @columnfractions .35 .1 .55
@item @code{Integer}/@code{Integer} @*
@code{Float}/@code{Integer} @*
@code{Float}/@code{Float}
@tab @ @* for
@tab @ @* @code{+ - * = ~= > < >= <=}

@item @code{Integer}/@code{Integer}
@tab for
@tab @code{// \\ bitOr: bitShift: bitAnd:}

@item Any pair of objects
@tab for
@tab @code{== isNil notNil class}

@item BlockClosure
@tab for
@tab @code{value value: blockCopy:}@footnote{You
won't ever send this message in Smalltalk programs. The compiler uses it when
compiling blocks.}
@end multitable

Other messages are open coded by the compiler. That is, there are
no message sends for these messages---if the compiler sees blocks
without temporaries and with the correct number of arguments at the
right places, the compiler unwinds them using jump bytecodes,
producing very efficient code. These are:

@example
  to:by:do: if the second argument is an integer literal
  to:do:
  timesRepeat:
  and:, or:
  ifTrue:ifFalse:, ifFalse:ifTrue:, ifTrue:, ifFalse:
  whileTrue:, whileFalse:
@end example

Other minor optimizations are done. Some are done by a peephole optimizer
which is ran on the compiled bytecodes. Or, for example, when @gst{} pushes a
boolean value on the stack, it automatically checks whether the following
bytecode is a jump (which is a common pattern resulting from most of the
open-coded messages above) and combines the execution of the two bytecodes.
All these snippets can be optimized this way:

@example
  1 to: 5 do: [ :i | @dots{} ]
  a < b and: [ @dots{} ]
  myObject isNil ifTrue: [ @dots{} ]
@end example

That's all. If you want to know more, look at the virtual machine's source
code in @file{libgst/interp-bc.inl} and at the compiler in
@file{libgst/comp.c}.

@node And now
@section Some final words

The question is always how far to go in one document.
At this point, you know how to create classes. You know how
to use inheritance, polymorphism, and the basic storage management
mechanisms of Smalltalk. You've also seen a sampling
of Smalltalk's powerful classes. The rest of this
chapter simply points out areas for further study; perhaps a
newer version of this document might cover these in further
chapters.

@table @b

@item Viewing the Smalltalk Source Code
Lots of experience can be gained by looking at the source code
for system methods; all of them are visible: data structure classes,
the innards of the magic that makes classes be themselves objects and
have a class, a compiler written in Smalltalk itself, the classes
that implement the Smalltalk GUI and those that wrap sockets.

@item Other Ways to Collect Objects
We've seen Array, ByteArray, Dictionary, Set, and the
various streams. You'll want to look at the Bag,
OrderedCollection, and SortedCollection classes. For special purposes,
you'll want to examine the CObject and CType hierarchies.

@item Flow of Control
@gst{} has support for non-preemptive multiple threads of
execution. The state is embodied in a Process class object;
you'll also want to look at the Semaphore and ProcessorScheduler
class.

@item Smalltalk Virtual Machine
@gst{} is implemented as a virtual instruction
set. By invoking @gst{} with the @code{-D} option, you can
view the byte opcodes which are generated as files on the
command line are loaded. Similarly, running @gst{}
with @code{-E} will trace the execution of instructions in your
methods.

You can look at the @gst{} source to gain more information
on the instruction set. With a few modifications, it is based
on the set described in the canonical book from two of the
original designers of Smalltalk: @i{Smalltalk-80: The Language
and its Implementation}, by Adele Goldberg and David Robson.

@item Where to get Help
The Usenet @t{comp.lang.smalltalk} newsgroup is read by many people
with a great deal of Smalltalk experience. There are several
commercial Smalltalk implementations; you can buy support for
these, though it isn't cheap. For the @gst{} system in
particular, you can try the mailing list at:
@example
   @mailto{help-smalltalk@@gnu.org}
@end example

No guarantees, but the subscribers will surely do their best!
@end table


@node The syntax
@section A Simple Overview of Smalltalk Syntax

Smalltalk's power comes from its treatment of objects.
In this document, we've mostly avoided the issue of syntax
by using strictly parenthesized expressions as needed. When
this leads to code which is hard to read due to the density
of parentheses, a knowledge of Smalltalk's syntax can let
you simplify expressions. In general, if it was hard for
you to tell how an expression would parse, it will be hard
for the next person, too.

The following presentation presents the grammar a couple
of related elements at a time. We use an EBNF style of
grammar. The form:
@example
   [ @dots{} ]
@end example

@noindent
means that ``@dots{}'' can occur zero or one times.

@example
   [ @dots{} ]*
@end example

@noindent
means zero or more;

@example
   [ @dots{} ]+
@end example

@noindent
means one or more.

@example
   @dots{} | @dots{} [ | @dots{} ]*
@end example

@noindent
means that one of the variants must be chosen. Characters
in double quotes refer to the literal characters. Most elements
may be separated by white space; where this is not legal, the
elements are presented without white space
between them.

@table @b

@item @t{methods: ``!'' id [``class''] ``methodsFor:'' string ``!'' [method ``!'']+ ``!''}
Methods are introduced by first naming a class (the id element),
specifying ``class'' if you're adding class methods
instead of instance methods, and sending a string argument
to the @code{methodsFor:} message. Each method is terminated with
an ``!''; two bangs in a row (with a space in the middle)
signify the end of the new methods.

@item @t{method: message [pragma] [temps] exprs}
@itemx @t{message: id | binsel id | [keysel id]+}
@itemx @t{pragma: ``<'' keymsg ``>''}
@itemx @t{temps: ``|'' [id]* ``|''}
A method definition starts out with a kind of template. The
message to be handled is specified with the message names
spelled out and identifiers in the place of arguments. A
special kind of definition is the pragma; it has not been
covered in this tutorial and it provides a way to mark a
method specially as well as the interface to the underlying
Smalltalk virtual machine. temps is the declaration
of local variables. Finally, exprs (covered soon) is
the actual code for implementing the method.

@item @t{unit: id | literal | block | arrayconstructor | ``('' expr ``)''}
@itemx @t{unaryexpr: unit [ id ]+}
@itemx @t{primary: unit | unaryexpr}
These are the ``building blocks'' of Smalltalk expressions. A
unit represents a single Smalltalk value, with the highest
syntactic precedence. A unaryexpr is simply a unit which
receives a number of unary messages. A unaryexpr has the
next highest precedence. A primary is simply a convenient
left-hand-side name for one of the above.

@item @t{exprs: [expr ``.'']* [[``^''] expr]}
@itemx @t{expr: [id ``:='']* expr2} @*
@itemx @t{expr2: primary | msgexpr [ ``;'' cascade ]*}
A sequence of expressions is separated by dots and can end
with a returned value (@code{^}). There can be leading assignments;
unlike C, assignments apply only to simple variable names. An
expression is either a primary (with highest precedence) or
a more complex message. cascade does not apply to primary
constructions, as they are too simple to require the construct.
Since all primary construct are unary, you can just add more unary messages:
@example
   1234 printNl printNl printNl
@end example

@item @t{msgexpr: unaryexpr | binexpr | keyexpr}
A complex message is either a unary message (which we have
already covered), a binary message (@code{+}, @code{-}, and so forth),
or a keyword message (@code{at:}, @code{new:}, @dots{}) Unary has the
highest precedence, followed by binary, and keyword messages
have the lowest precedence. Examine the two versions of the
following messages. The second have had parentheses added
to show the default precedence.
@example
   myvar at: 2 + 3 put: 4
   mybool ifTrue: [ ^ 2 / 4 roundup ]

   (myvar at: (2 + 3) put: (4))
   (mybool ifTrue: ([ ^ (2 / (4 roundup)) ]))
@end example

@item @t{cascade: id | binmsg | keymsg}
A cascade is used to direct further messages to the same
object which was last used. The three types of messages (
id is how you send a unary message) can thus be sent.

@item @t{binexpr: primary binmsg [ binmsg ]*}
@itemx @t{binmsg: binsel primary}
@itemx @t{binsel: binchar[binchar]}
A binary message is sent to an object, which primary has
identified. Each binary message is a binary selector, constructed
from one or two characters, and an argument which
is also provided by a primary.
@example
   1 + 2 - 3 / 4
@end example

@noindent
which parses as:
@example
   (((1 + 2) - 3) / 4)
@end example

@item @t{keyexpr: keyexpr2 keymsg}
@itemx @t{keyexpr2: binexpr | primary}
@itemx @t{keymsg: [keysel keyw2]+}
@itemx @t{keysel: id``:''}
Keyword expressions are much like binary expressions, except
that the selectors are made up of identifiers with a colon
appended. Where the arguments to a binary function can only
be from primary, the arguments to a keyword can be binary
expressions or primary ones. This is because keywords have
the lowest precedence.

@item @t{block: ``['' [[``:'' id]* ``|'' ] [temps] exprs ``]''}
A code block is square brackets around a collection of
Smalltalk expressions. The leading ``: id'' part is for block
arguments. Note that it is possible for a block to have
temporary variables of its own.

@item @t{arrayconstructor: ``@{'' exprs ``@}''}
Not covered in this tutorial, this syntax allows to create
arrays whose values are not literals, but are instead evaluated
at run-time. Compare @code{#(a b)}, which results in an Array
of two symbols @code{#a} and @code{#b}, to @code{@{a. b+c@}} which
results in an Array whose two elements are the contents of variable
@code{a} and the result of summing @code{c} to @code{b}.

@item @t{literal: number | string | charconst | symconst | arrayconst | binding | eval}
@itemx @t{arrayconst: ``#'' array | ``#'' bytearray}
@itemx @t{bytearray: ``['' [number]* ``]''}
@itemx @t{array: ``('' [literal | array | bytearray | arraysym | ]* ``)''}
@itemx @t{number: [[dig]+ ``r''] [``-''] [alphanum]+ [``.'' [alphanum]+] [exp [``-''][dig]+].}
@itemx @t{string: "'"[char]*"'"}
@itemx @t{charconst: ``$''char}
@itemx @t{symconst: ``#''symbol | ``#''string }
@itemx @t{arraysym: [id | ``:'']*}
@itemx @t{exp: ``d'' | ``e'' | ``q'' | ``s''}
We have already shown the use of many of these constants.
Although not covered in this tutorial, numbers can have a base
specified at their front, and a trailing scientific notation.
We have seen examples of character, string, and symbol constants.
Array constants are simple enough; they would look like:
@example
   a := #(1 2 'Hi' $x #Hello 4 16r3F)
@end example

There are also ByteArray constants, whose elements are constrained
to be integers between 0 and 255; they would look like:
@example
   a := #[1 2 34 16r8F 26r3H 253]
@end example

Finally, there are three types of floating-point constants with
varying precision (the one with the @code{e} being the less
precise, followed by @code{d} and @code{q}), and scaled-decimal
constants for a special class which does exact computations but
truncates comparisons to a given number of decimals. For example,
@code{1.23s4} means ``the value @code{1.23}, with four significant
decimal digits''.

@item @t{binding: ``#@{'' [id ``.'']* id ``@}''}
This syntax has not been used in the tutorial, and results in an
Association literal (known as a @dfn{variable binding}) tied to
the class that is named between braces. For example,
@code{#@{Class@} value} is the same as @code{Class}. The
dot syntax is required for supporting namespaces:
@code{#@{Smalltalk.Class@}} is the same as
@code{Smalltalk associationAt: #Class}, but is resolved
at compile-time rather than at run-time.

@item @t{symbol: id | binsel | keysel[keysel]*}
Symbols are mostly used to represent the names of methods.
Thus, they can hold simple identifiers, binary selectors,
and keyword selectors:
@example
   #hello
   #+
   #at:put:
@end example

@itemx @t{eval: ``##('' [temps] exprs ``)''}
This syntax also has not been used in the tutorial, and results
in evaluating an arbitrarily complex expression at compile-time,
and substituting the result: for example @code{##(Object allInstances
size)} is the number of instances of @code{Object} held in the
image @emph{at the time the method is compiled}.

@item @t{id: letter[alphanum]*}
@itemx @t{binchar: ``+'' | ``-'' | ``*'' | ``/'' | ``~'' | ``|'' | ``,'' |}
@itemx @t{``<'' | ``>'' | ``='' | ``&'' | ``@@'' | ``?'' | ``\'' | ``%''}
@itemx @t{alphanum: dig | letter}
@itemx @t{letter: ``A''..``Z''}
@itemx @t{dig: ``0''..``9''}
These are the categories of characters and how they are combined
at the most basic level. binchar simply lists the
characters which can be combined to name a binary message.

@end table
Something went wrong with that request. Please try again.