summaryrefslogtreecommitdiffstats
path: root/test/test_unicode_literals.py
blob: 6c1b7ec915c60321e62c7c44728f5486921e772f (plain)
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
from __future__ import unicode_literals

# Allow direct execution
import os
import sys
import unittest
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

import io
import re

rootDir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

IGNORED_FILES = [
    'setup.py',  # http://bugs.python.org/issue13943
    'conf.py',
    'buildserver.py',
]

IGNORED_DIRS = [
    '.git',
    '.tox',
]

from test.helper import assertRegexpMatches


class TestUnicodeLiterals(unittest.TestCase):
    def test_all_files(self):
        for dirpath, dirnames, filenames in os.walk(rootDir):
            for ignore_dir in IGNORED_DIRS:
                if ignore_dir in dirnames:
                    # If we remove the directory from dirnames os.walk won't
                    # recurse into it
                    dirnames.remove(ignore_dir)
            for basename in filenames:
                if not basename.endswith('.py'):
                    continue
                if basename in IGNORED_FILES:
                    continue

                fn = os.path.join(dirpath, basename)
                with io.open(fn, encoding='utf-8') as inf:
                    code = inf.read()

                if "'" not in code and '"' not in code:
                    continue
                assertRegexpMatches(
                    self,
                    code,
                    r'(?:(?:#.*?|\s*)\n)*from __future__ import (?:[a-z_]+,\s*)*unicode_literals',
                    'unicode_literals import  missing in %s' % fn)

                m = re.search(r'(?<=\s)u[\'"](?!\)|,|$)', code)
                if m is not None:
                    self.assertTrue(
                        m is None,
                        'u present in %s, around %s' % (
                            fn, code[m.start() - 10:m.end() + 10]))


if __name__ == '__main__':
    unittest.main()
>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 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 5700 5701 5702 5703 5704 5705 5706 5707 5708 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 5750 5751 5752 5753 5754 5755 5756 5757 5758 5759 5760 5761 5762 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 5896 5897 5898 5899 5900 5901 5902 5903 5904 5905 5906 5907 5908 5909 5910 5911 5912 5913 5914 5915 5916 5917 5918 5919 5920 5921 5922 5923 5924 5925 5926 5927 5928 5929 5930 5931 5932 5933 5934 5935 5936 5937 5938 5939 5940 5941 5942 5943 5944 5945 5946 5947 5948 5949 5950 5951 5952 5953 5954 5955 5956 5957 5958 5959 5960 5961 5962 5963 5964 5965 5966 5967 5968 5969 5970 5971 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993 5994 5995 5996 5997 5998 5999 6000 6001 6002 6003 6004 6005 6006 6007 6008 6009 6010 6011 6012 6013 6014 6015 6016 6017 6018 6019 6020 6021 6022 6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041 6042 6043 6044 6045 6046 6047 6048 6049 6050 6051 6052 6053 6054 6055 6056 6057 6058 6059 6060 6061 6062 6063 6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 6078 6079 6080 6081 6082 6083 6084 6085 6086 6087 6088 6089 6090 6091 6092 6093 6094 6095 6096 6097 6098 6099 6100 6101 6102 6103 6104 6105 6106 6107 6108 6109 6110 6111 6112 6113 6114 6115 6116 6117 6118 6119 6120 6121 6122 6123 6124 6125 6126 6127 6128 6129 6130 6131 6132 6133 6134 6135 6136 6137 6138 6139 6140 6141 6142 6143 6144 6145 6146 6147 6148 6149 6150 6151 6152 6153 6154 6155 6156 6157 6158 6159 6160 6161 6162 6163 6164 6165 6166 6167 6168 6169 6170 6171 6172 6173 6174 6175 6176 6177 6178 6179 6180 6181 6182 6183 6184 6185 6186 6187 6188 6189 6190 6191 6192 6193 6194 6195 6196 6197 6198 6199 6200 6201 6202 6203 6204 6205 6206 6207 6208 6209 6210 6211 6212 6213 6214 6215 6216 6217 6218 6219 6220 6221 6222 6223 6224 6225 6226 6227 6228 6229 6230 6231 6232 6233 6234 6235 6236 6237 6238 6239 6240 6241 6242 6243 6244 6245 6246 6247 6248 6249 6250 6251 6252 6253 6254 6255 6256 6257 6258 6259 6260 6261 6262 6263 6264 6265 6266 6267 6268 6269 6270 6271 6272 6273 6274 6275 6276 6277 6278 6279 6280 6281 6282 6283 6284 6285 6286 6287 6288 6289 6290 6291 6292 6293 6294 6295 6296 6297 6298 6299 6300 6301 6302 6303 6304 6305 6306 6307 6308 6309 6310 6311 6312 6313 6314 6315 6316 6317 6318 6319 6320 6321 6322 6323 6324 6325 6326 6327 6328 6329 6330 6331 6332 6333 6334 6335 6336 6337 6338 6339 6340 6341 6342 6343 6344 6345 6346 6347 6348 6349 6350 6351 6352 6353 6354 6355 6356 6357 6358 6359 6360 6361 6362 6363 6364 6365 6366 6367 6368 6369 6370 6371 6372 6373 6374 6375 6376 6377 6378 6379 6380 6381 6382 6383 6384 6385 6386 6387 6388 6389 6390 6391 6392 6393 6394 6395 6396 6397 6398 6399 6400 6401 6402 6403 6404 6405 6406 6407 6408 6409 6410 6411 6412 6413 6414 6415 6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 6429 6430 6431 6432 6433 6434 6435 6436 6437 6438 6439 6440 6441 6442 6443 6444 6445 6446 6447 6448 6449 6450 6451 6452 6453 6454 6455 6456 6457 6458 6459 6460 6461 6462 6463 6464 6465 6466 6467 6468 6469 6470 6471 6472 6473 6474 6475 6476 6477 6478 6479 6480 6481 6482 6483 6484 6485 6486 6487 6488 6489 6490 6491 6492 6493 6494 6495 6496 6497 6498 6499 6500 6501 6502 6503 6504 6505 6506 6507 6508 6509 6510 6511 6512 6513 6514 6515 6516 6517 6518 6519 6520 6521 6522 6523 6524 6525 6526 6527 6528 6529 6530 6531 6532 6533 6534 6535 6536 6537 6538 6539 6540 6541 6542 6543 6544 6545 6546 6547 6548 6549 6550 6551 6552 6553 6554 6555 6556 6557 6558 6559 6560 6561 6562 6563 6564 6565 6566 6567 6568 6569 6570 6571 6572 6573 6574 6575 6576 6577 6578 6579 6580 6581 6582 6583 6584 6585 6586 6587 6588 6589 6590 6591 6592 6593 6594 6595 6596 6597 6598 6599 6600 6601 6602 6603 6604 6605 6606 6607 6608 6609 6610 6611 6612 6613 6614 6615 6616 6617 6618 6619 6620 6621 6622 6623 6624 6625 6626 6627 6628 6629 6630 6631 6632 6633 6634 6635 6636 6637 6638 6639 6640 6641 6642 6643 6644 6645 6646 6647 6648 6649 6650 6651 6652 6653 6654 6655 6656 6657 6658 6659 6660 6661 6662 6663 6664 6665 6666 6667 6668 6669 6670 6671 6672 6673 6674 6675 6676 6677 6678 6679 6680 6681 6682 6683 6684 6685 6686 6687 6688 6689 6690 6691 6692 6693 6694 6695 6696 6697 6698 6699 6700 6701 6702 6703 6704 6705 6706 6707 6708 6709 6710 6711 6712 6713 6714 6715 6716 6717 6718 6719 6720 6721 6722 6723 6724 6725 6726 6727 6728 6729 6730 6731 6732 6733 6734 6735 6736 6737 6738 6739 6740 6741 6742 6743 6744 6745 6746 6747 6748 6749 6750 6751 6752 6753 6754 6755 6756 6757 6758 6759 6760 6761 6762 6763 6764 6765 6766 6767 6768 6769 6770 6771 6772 6773 6774 6775 6776 6777 6778 6779 6780 6781 6782 6783 6784 6785 6786 6787 6788 6789 6790 6791 6792 6793 6794 6795 6796 6797 6798 6799 6800 6801 6802 6803 6804 6805 6806 6807 6808 6809 6810 6811 6812 6813 6814 6815 6816 6817 6818 6819 6820 6821 6822 6823 6824 6825 6826 6827 6828 6829 6830 6831 6832 6833 6834 6835 6836 6837 6838 6839 6840 6841 6842 6843 6844 6845 6846 6847 6848 6849 6850 6851 6852 6853 6854 6855 6856 6857 6858 6859 6860 6861 6862 6863 6864 6865 6866 6867 6868 6869 6870 6871 6872 6873 6874 6875 6876 6877 6878 6879 6880 6881 6882 6883 6884 6885 6886 6887 6888 6889 6890 6891 6892 6893 6894 6895 6896 6897 6898 6899 6900 6901 6902 6903 6904 6905 6906 6907 6908 6909 6910 6911 6912 6913 6914 6915 6916 6917 6918 6919 6920 6921 6922 6923 6924 6925 6926 6927 6928 6929 6930 6931 6932 6933 6934 6935 6936 6937 6938 6939 6940 6941 6942 6943 6944 6945 6946 6947 6948 6949 6950 6951 6952 6953 6954 6955 6956 6957 6958 6959 6960 6961 6962 6963 6964 6965 6966 6967 6968 6969 6970 6971 6972 6973 6974 6975 6976 6977 6978 6979 6980 6981 6982 6983 6984 6985 6986 6987 6988 6989 6990 6991 6992 6993 6994 6995 6996 6997 6998 6999 7000 7001 7002 7003 7004 7005 7006 7007 7008 7009 7010 7011 7012 7013 7014 7015 7016 7017 7018 7019 7020 7021 7022 7023 7024 7025 7026 7027 7028 7029 7030 7031 7032 7033 7034 7035 7036 7037 7038 7039 7040 7041 7042 7043 7044 7045 7046 7047 7048 7049 7050 7051 7052 7053 7054 7055 7056 7057 7058 7059 7060 7061 7062 7063 7064 7065 7066 7067 7068 7069 7070 7071 7072 7073 7074 7075 7076 7077 7078 7079 7080 7081 7082 7083 7084 7085 7086 7087 7088 7089 7090 7091 7092 7093 7094 7095 7096 7097 7098 7099 7100 7101 7102 7103 7104 7105 7106 7107 7108 7109 7110 7111 7112 7113 7114 7115 7116 7117 7118 7119 7120 7121 7122 7123 7124 7125 7126 7127 7128 7129 7130 7131 7132 7133 7134 7135 7136 7137 7138 7139 7140 7141 7142 7143 7144 7145 7146 7147 7148 7149 7150 7151 7152 7153 7154 7155 7156 7157 7158 7159 7160 7161 7162 7163 7164 7165 7166 7167 7168 7169 7170 7171 7172 7173 7174 7175 7176 7177 7178 7179 7180 7181 7182 7183 7184 7185 7186 7187 7188 7189 7190 7191 7192 7193 7194 7195 7196 7197 7198 7199 7200 7201 7202 7203 7204 7205 7206 7207 7208 7209 7210 7211 7212 7213 7214 7215 7216 7217 7218 7219 7220 7221 7222 7223 7224 7225 7226 7227 7228 7229 7230 7231 7232 7233 7234 7235 7236 7237 7238 7239 7240 7241 7242 7243 7244 7245 7246 7247 7248 7249 7250 7251 7252 7253 7254 7255 7256 7257 7258 7259 7260 7261 7262 7263 7264 7265 7266 7267 7268 7269 7270 7271 7272 7273 7274 7275 7276 7277 7278 7279 7280 7281 7282 7283 7284 7285 7286 7287 7288 7289 7290 7291 7292 7293 7294 7295 7296 7297 7298 7299 7300 7301 7302 7303 7304 7305 7306 7307 7308 7309 7310 7311 7312 7313 7314 7315 7316 7317 7318 7319 7320 7321 7322 7323 7324 7325 7326 7327 7328 7329 7330 7331 7332 7333 7334 7335 7336 7337 7338 7339 7340 7341 7342 7343 7344 7345 7346 7347 7348 7349 7350 7351 7352 7353 7354 7355 7356 7357 7358 7359 7360 7361 7362 7363 7364 7365 7366 7367 7368 7369 7370 7371 7372 7373 7374 7375 7376 7377 7378 7379 7380 7381 7382 7383 7384 7385 7386 7387 7388 7389 7390 7391 7392 7393 7394 7395 7396 7397 7398 7399 7400 7401 7402 7403 7404 7405 7406 7407 7408 7409 7410 7411 7412 7413 7414 7415 7416 7417 7418 7419 7420 7421 7422 7423 7424 7425 7426 7427 7428 7429 7430 7431 7432 7433 7434 7435 7436 7437 7438 7439 7440 7441 7442 7443 7444 7445 7446 7447 7448 7449 7450 7451 7452 7453 7454 7455 7456 7457 7458 7459 7460 7461 7462 7463 7464 7465 7466 7467 7468 7469 7470 7471 7472 7473 7474 7475 7476 7477 7478 7479 7480 7481 7482 7483 7484 7485 7486 7487 7488 7489 7490 7491 7492 7493 7494 7495 7496 7497 7498 7499 7500 7501 7502 7503 7504 7505 7506 7507 7508 7509 7510 7511 7512 7513 7514 7515 7516 7517 7518 7519 7520 7521 7522 7523 7524 7525 7526 7527 7528 7529 7530 7531 7532 7533 7534 7535 7536 7537 7538 7539 7540 7541 7542 7543 7544 7545 7546 7547 7548 7549 7550 7551 7552 7553 7554 7555 7556 7557 7558 7559 7560 7561 7562 7563 7564 7565 7566 7567 7568 7569 7570 7571 7572 7573 7574 7575 7576 7577 7578 7579 7580 7581 7582 7583 7584 7585 7586 7587 7588 7589 7590 7591 7592 7593 7594 7595 7596 7597 7598 7599 7600 7601 7602 7603 7604 7605 7606 7607 7608 7609 7610 7611 7612 7613 7614 7615 7616 7617 7618 7619 7620 7621 7622 7623 7624 7625 7626 7627 7628 7629 7630 7631 7632 7633 7634 7635 7636 7637 7638 7639 7640 7641 7642 7643 7644 7645 7646 7647 7648 7649 7650 7651 7652 7653 7654 7655 7656 7657 7658 7659 7660 7661 7662 7663 7664 7665 7666 7667 7668 7669 7670 7671 7672 7673 7674 7675 7676 7677 7678 7679 7680 7681 7682 7683 7684 7685 7686 7687 7688 7689 7690 7691 7692 7693 7694 7695 7696 7697 7698 7699 7700 7701 7702 7703 7704 7705 7706 7707 7708 7709 7710 7711 7712 7713 7714 7715 7716 7717 7718 7719 7720 7721 7722 7723 7724 7725 7726 7727 7728 7729 7730 7731 7732 7733 7734 7735 7736 7737 7738 7739 7740 7741 7742 7743 7744 7745 7746 7747 7748 7749 7750 7751 7752 7753 7754 7755 7756 7757 7758 7759 7760 7761 7762 7763 7764 7765 7766 7767 7768 7769 7770 7771 7772 7773 7774 7775 7776 7777 7778 7779 7780 7781 7782 7783 7784 7785 7786 7787 7788 7789 7790 7791 7792 7793 7794 7795 7796 7797 7798 7799 7800 7801 7802 7803 7804 7805 7806 7807 7808 7809 7810 7811 7812 7813 7814 7815 7816 7817 7818 7819 7820 7821 7822 7823 7824 7825 7826 7827 7828 7829 7830 7831 7832 7833 7834 7835 7836 7837 7838 7839 7840 7841 7842 7843 7844 7845 7846 7847 7848 7849 7850 7851 7852 7853 7854 7855 7856 7857 7858 7859 7860 7861 7862 7863 7864 7865 7866 7867 7868 7869 7870 7871 7872 7873 7874 7875 7876 7877 7878 7879 7880 7881 7882 7883 7884 7885 7886 7887 7888 7889 7890 7891 7892 7893 7894 7895 7896 7897 7898 7899 7900 7901 7902 7903 7904 7905 7906 7907 7908 7909 7910 7911 7912 7913 7914 7915 7916 7917 7918 7919 7920 7921 7922 7923 7924 7925 7926 7927 7928 7929 7930 7931 7932 7933 7934 7935 7936 7937 7938 7939 7940 7941 7942 7943 7944 7945 7946 7947 7948 7949 7950 7951 7952 7953 7954 7955 7956 7957 7958 7959 7960 7961 7962 7963 7964 7965 7966 7967 7968 7969 7970 7971 7972 7973 7974 7975 7976 7977 7978 7979 7980 7981 7982 7983 7984 7985 7986 7987 7988 7989 7990 7991 7992 7993 7994 7995 7996 7997 7998 7999 8000 8001 8002 8003 8004 8005 8006 8007 8008 8009 8010 8011 8012 8013 8014 8015 8016 8017 8018 8019 8020 8021 8022 8023 8024 8025 8026 8027 8028 8029 8030 8031 8032 8033 8034 8035 8036 8037 8038 8039 8040 8041 8042 8043 8044 8045 8046 8047 8048 8049 8050 8051 8052 8053 8054 8055 8056 8057 8058 8059 8060 8061 8062 8063 8064 8065 8066 8067 8068 8069 8070 8071 8072 8073 8074 8075 8076 8077 8078 8079 8080 8081 8082 8083 8084 8085 8086 8087 8088 8089 8090 8091 8092 8093 8094 8095 8096 8097 8098 8099 8100 8101 8102 8103 8104 8105 8106 8107 8108 8109 8110 8111 8112 8113 8114 8115 8116 8117 8118 8119 8120 8121 8122 8123 8124 8125 8126 8127 8128 8129 8130 8131 8132 8133 8134 8135 8136 8137 8138 8139 8140 8141 8142 8143 8144 8145 8146 8147 8148 8149 8150 8151 8152 8153 8154 8155 8156 8157 8158 8159 8160 8161 8162 8163 8164 8165 8166 8167 8168 8169 8170 8171 8172 8173 8174 8175 8176 8177 8178 8179 8180 8181 8182 8183 8184 8185 8186 8187 8188 8189 8190 8191 8192 8193 8194 8195 8196 8197 8198 8199 8200 8201 8202 8203 8204 8205 8206 8207 8208 8209 8210 8211 8212 8213 8214 8215 8216 8217 8218 8219 8220 8221 8222 8223 8224 8225 8226 8227 8228 8229 8230 8231 8232 8233 8234 8235 8236 8237 8238 8239 8240 8241 8242 8243 8244 8245 8246 8247 8248 8249 8250 8251 8252 8253 8254 8255 8256 8257 8258 8259 8260 8261 8262 8263 8264 8265 8266 8267 8268 8269 8270 8271 8272 8273 8274 8275 8276 8277 8278 8279 8280 8281 8282 8283 8284 8285 8286 8287 8288 8289 8290 8291 8292 8293 8294 8295 8296 8297 8298 8299 8300 8301 8302 8303 8304 8305 8306 8307 8308 8309 8310 8311 8312 8313 8314 8315 8316 8317 8318 8319 8320 8321 8322 8323 8324 8325 8326 8327 8328 8329 8330 8331 8332 8333 8334 8335 8336 8337 8338 8339 8340 8341 8342 8343 8344 8345 8346 8347 8348 8349 8350 8351 8352 8353 8354 8355 8356 8357 8358 8359 8360 8361 8362 8363 8364 8365 8366 8367 8368 8369 8370 8371 8372 8373 8374 8375 8376 8377 8378 8379 8380 8381 8382 8383 8384 8385 8386 8387 8388 8389 8390 8391 8392 8393 8394 8395 8396 8397 8398 8399 8400 8401 8402 8403 8404 8405 8406 8407 8408 8409 8410 8411 8412 8413 8414 8415 8416 8417 8418 8419 8420 8421 8422 8423 8424 8425 8426 8427 8428 8429 8430 8431 8432 8433 8434 8435 8436 8437 8438 8439 8440 8441 8442 8443 8444 8445 8446 8447 8448 8449 8450 8451 8452 8453 8454 8455 8456 8457 8458 8459 8460 8461 8462 8463 8464 8465 8466 8467 8468 8469 8470 8471 8472 8473 8474 8475 8476 8477 8478 8479 8480 8481 8482 8483 8484 8485 8486 8487 8488 8489 8490 8491 8492 8493 8494 8495 8496 8497 8498 8499 8500 8501 8502 8503 8504 8505 8506 8507 8508 8509 8510 8511 8512 8513 8514 8515 8516 8517 8518 8519 8520 8521 8522 8523 8524 8525 8526 8527 8528 8529 8530 8531 8532 8533 8534 8535 8536 8537 8538 8539 8540 8541 8542 8543 8544 8545 8546 8547 8548 8549 8550 8551 8552 8553 8554 8555 8556 8557 8558 8559 8560 8561 8562 8563 8564 8565 8566 8567 8568 8569 8570 8571 8572 8573 8574 8575 8576 8577 8578 8579 8580 8581 8582 8583 8584 8585 8586 8587 8588 8589 8590 8591 8592 8593 8594 8595 8596 8597 8598 8599 8600 8601 8602 8603 8604 8605 8606 8607 8608 8609 8610 8611 8612 8613 8614 8615 8616 8617 8618 8619 8620 8621 8622 8623 8624 8625 8626 8627 8628 8629 8630 8631 8632 8633 8634 8635 8636 8637 8638 8639 8640 8641 8642 8643 8644 8645 8646 8647 8648 8649 8650 8651 8652 8653 8654 8655 8656 8657 8658 8659 8660 8661 8662 8663 8664 8665 8666 8667 8668 8669 8670 8671 8672 8673 8674 8675 8676 8677 8678 8679 8680 8681 8682 8683 8684 8685 8686 8687 8688 8689 8690 8691 8692 8693 8694 8695 8696 8697 8698 8699 8700 8701 8702 8703 8704 8705 8706 8707 8708 8709 8710 8711 8712 8713 8714 8715 8716 8717 8718 8719 8720 8721 8722 8723 8724 8725 8726 8727 8728 8729 8730 8731 8732 8733 8734 8735 8736 8737 8738 8739 8740 8741 8742 8743 8744 8745 8746 8747 8748 8749 8750 8751 8752 8753 8754 8755 8756 8757 8758 8759 8760 8761 8762 8763 8764 8765 8766 8767 8768 8769 8770 8771 8772 8773 8774 8775 8776 8777 8778 8779 8780 8781 8782 8783 8784 8785 8786 8787 8788 8789 8790 8791 8792 8793 8794 8795 8796 8797 8798 8799 8800 8801 8802 8803 8804 8805 8806 8807 8808 8809 8810 8811 8812 8813 8814 8815 8816 8817 8818 8819 8820 8821 8822 8823 8824 8825 8826 8827 8828 8829 8830 8831 8832 8833 8834 8835 8836 8837 8838 8839 8840 8841 8842 8843 8844 8845 8846 8847 8848 8849 8850 8851 8852 8853 8854 8855 8856 8857 8858 8859 8860 8861 8862 8863 8864 8865 8866 8867 8868 8869 8870 8871 8872 8873 8874 8875 8876 8877 8878 8879 8880 8881 8882 8883 8884 8885 8886 8887 8888 8889 8890 8891 8892 8893 8894 8895 8896 8897 8898 8899 8900 8901 8902 8903 8904 8905 8906 8907 8908 8909 8910 8911 8912 8913 8914 8915 8916 8917 8918 8919 8920 8921 8922 8923 8924 8925 8926 8927 8928 8929 8930 8931 8932 8933 8934 8935 8936 8937 8938 8939 8940 8941 8942 8943 8944 8945 8946 8947 8948 8949 8950 8951 8952 8953 8954 8955 8956 8957 8958 8959 8960 8961 8962 8963 8964 8965 8966 8967 8968 8969 8970 8971 8972 8973 8974 8975 8976 8977 8978 8979 8980 8981 8982 8983 8984 8985 8986 8987 8988 8989 8990 8991 8992 8993 8994 8995 8996 8997 8998 8999 9000 9001 9002 9003 9004 9005 9006 9007 9008 9009 9010 9011 9012 9013 9014 9015 9016 9017 9018 9019 9020 9021 9022 9023 9024 9025 9026 9027 9028 9029 9030 9031 9032 9033 9034 9035 9036 9037 9038 9039 9040 9041 9042 9043 9044 9045 9046 9047 9048 9049 9050 9051 9052 9053 9054 9055 9056 9057 9058 9059 9060 9061 9062 9063 9064 9065 9066 9067 9068 9069 9070 9071 9072 9073 9074 9075 9076 9077 9078 9079 9080 9081 9082 9083 9084 9085 9086 9087 9088 9089 9090 9091 9092 9093 9094 9095 9096 9097 9098 9099 9100 9101 9102 9103 9104 9105 9106 9107 9108 9109 9110 9111 9112 9113 9114 9115 9116 9117 9118 9119 9120 9121 9122 9123 9124 9125 9126 9127 9128 9129 9130 9131 9132 9133 9134 9135 9136 9137 9138 9139 9140 9141 9142 9143 9144 9145 9146 9147 9148 9149 9150 9151 9152 9153 9154 9155 9156 9157 9158 9159 9160 9161 9162 9163 9164 9165 9166 9167 9168 9169 9170 9171 9172 9173 9174 9175 9176 9177 9178 9179 9180 9181 9182 9183 9184 9185 9186 9187 9188 9189 9190 9191 9192 9193 9194 9195 9196 9197 9198 9199 9200 9201 9202 9203 9204 9205 9206 9207 9208 9209 9210 9211 9212 9213 9214 9215 9216 9217 9218 9219 9220 9221 9222 9223 9224 9225 9226 9227 9228 9229 9230 9231 9232 9233 9234 9235 9236 9237 9238 9239 9240 9241 9242 9243 9244 9245 9246 9247 9248 9249 9250 9251 9252 9253 9254 9255 9256 9257 9258 9259 9260 9261 9262 9263 9264 9265 9266 9267 9268 9269 9270 9271 9272 9273 9274 9275 9276 9277 9278 9279 9280 9281 9282 9283 9284 9285 9286 9287 9288 9289 9290 9291 9292 9293 9294 9295 9296 9297 9298 9299 9300 9301 9302 9303 9304 9305 9306 9307 9308 9309 9310 9311 9312 9313 9314 9315 9316 9317 9318 9319 9320 9321 9322 9323 9324 9325 9326 9327 9328 9329 9330 9331 9332 9333 9334 9335 9336 9337 9338 9339 9340 9341 9342 9343 9344 9345 9346 9347 9348 9349 9350 9351 9352 9353 9354 9355 9356 9357 9358 9359 9360 9361 9362 9363 9364 9365 9366 9367 9368 9369 9370 9371 9372 9373 9374 9375 9376 9377 9378 9379 9380 9381 9382 9383 9384 9385 9386 9387 9388 9389 9390 9391 9392 9393 9394 9395 9396 9397 9398 9399 9400 9401 9402 9403 9404 9405 9406 9407 9408 9409 9410 9411 9412 9413 9414 9415 9416 9417 9418 9419 9420 9421 9422 9423 9424 9425 9426 9427 9428 9429 9430 9431 9432 9433 9434 9435 9436 9437 9438 9439 9440 9441 9442 9443 9444 9445 9446 9447 9448 9449 9450 9451 9452 9453 9454 9455 9456 9457 9458 9459 9460 9461 9462 9463 9464 9465 9466 9467 9468 9469 9470 9471 9472 9473 9474 9475 9476 9477 9478 9479 9480 9481 9482 9483 9484 9485 9486 9487 9488 9489 9490 9491 9492 9493 9494 9495 9496 9497 9498 9499 9500 9501 9502 9503 9504 9505 9506 9507 9508 9509 9510 9511 9512 9513 9514 9515 9516 9517 9518 9519 9520 9521 9522 9523 9524 9525 9526 9527 9528 9529 9530 9531 9532 9533 9534 9535 9536 9537 9538 9539 9540 9541 9542 9543 9544 9545 9546 9547 9548 9549 9550 9551 9552 9553 9554 9555 9556 9557 9558 9559 9560 9561 9562 9563 9564 9565 9566 9567 9568 9569 9570 9571 9572 9573 9574 9575 9576 9577 9578 9579 9580 9581 9582 9583 9584 9585 9586 9587 9588 9589 9590 9591 9592 9593 9594 9595 9596 9597 9598 9599 9600 9601 9602 9603 9604 9605 9606 9607 9608 9609 9610 9611 9612 9613 9614 9615 9616 9617 9618 9619 9620 9621 9622 9623 9624 9625 9626 9627 9628 9629 9630 9631 9632 9633 9634 9635 9636 9637 9638 9639 9640 9641 9642 9643 9644 9645 9646 9647 9648 9649 9650 9651 9652 9653 9654 9655 9656 9657 9658 9659 9660 9661 9662 9663 9664 9665 9666 9667 9668 9669 9670 9671 9672 9673 9674 9675 9676 9677 9678 9679 9680 9681 9682 9683 9684 9685 9686 9687 9688 9689 9690 9691 9692 9693 9694 9695 9696 9697 9698 9699 9700 9701 9702 9703 9704 9705 9706 9707 9708 9709 9710 9711 9712 9713 9714 9715 9716 9717 9718 9719 9720 9721 9722 9723 9724 9725 9726 9727 9728 9729 9730 9731 9732 9733 9734 9735 9736 9737 9738 9739 9740 9741 9742 9743 9744 9745 9746 9747 9748 9749 9750 9751 9752 9753 9754 9755 9756 9757 9758 9759 9760 9761 9762 9763 9764 9765 9766 9767 9768 9769 9770 9771 9772 9773 9774 9775 9776 9777 9778 9779 9780 9781 9782 9783 9784 9785 9786 9787 9788 9789 9790 9791 9792 9793 9794 9795 9796 9797 9798 9799 9800 9801 9802 9803 9804 9805 9806 9807 9808 9809 9810 9811 9812 9813 9814 9815 9816 9817 9818 9819 9820 9821 9822 9823 9824 9825 9826 9827 9828 9829 9830 9831 9832 9833 9834 9835 9836 9837 9838 9839 9840 9841 9842 9843 9844 9845 9846 9847 9848 9849 9850 9851 9852 9853 9854 9855 9856 9857 9858 9859 9860 9861 9862 9863 9864 9865 9866 9867 9868 9869 9870 9871 9872 9873 9874 9875 9876 9877 9878 9879 9880 9881 9882 9883 9884 9885 9886 9887 9888 9889 9890 9891 9892 9893 9894 9895 9896 9897 9898 9899 9900 9901 9902 9903 9904 9905 9906 9907 9908 9909 9910 9911 9912 9913 9914 9915 9916 9917 9918 9919 9920 9921 9922 9923 9924 9925 9926 9927 9928 9929 9930 9931 9932 9933 9934 9935 9936 9937 9938 9939 9940 9941 9942 9943 9944 9945 9946 9947 9948 9949 9950 9951 9952 9953 9954 9955 9956 9957 9958 9959 9960 9961 9962 9963 9964 9965 9966 9967 9968 9969 9970 9971 9972 9973 9974 9975 9976 9977 9978 9979 9980 9981 9982 9983 9984 9985 9986 9987 9988 9989 9990 9991 9992 9993 9994 9995 9996 9997 9998 9999 10000 10001 10002 10003 10004 10005 10006 10007 10008 10009 10010 10011 10012 10013 10014 10015 10016 10017 10018 10019 10020 10021 10022 10023 10024 10025 10026 10027 10028 10029 10030 10031 10032 10033 10034 10035 10036 10037 10038 10039 10040 10041 10042 10043 10044 10045 10046 10047 10048 10049 10050 10051 10052 10053 10054 10055 10056 10057 10058 10059 10060 10061 10062 10063 10064 10065 10066 10067 10068 10069 10070 10071 10072 10073 10074 10075 10076 10077 10078 10079 10080 10081 10082 10083 10084 10085 10086 10087 10088 10089 10090 10091 10092 10093 10094 10095 10096 10097 10098 10099 10100 10101 10102 10103 10104 10105 10106 10107 10108 10109 10110 10111 10112 10113 10114 10115 10116 10117 10118 10119 10120 10121 10122 10123 10124 10125 10126 10127 10128 10129 10130 10131 10132 10133 10134 10135 10136 10137 10138 10139 10140 10141 10142 10143 10144 10145 10146 10147 10148 10149 10150 10151 10152 10153 10154 10155 10156 10157 10158 10159 10160 10161 10162 10163 10164 10165 10166 10167 10168 10169 10170 10171 10172 10173 10174 10175 10176 10177 10178 10179 10180 10181 10182 10183 10184 10185 10186 10187 10188 10189 10190 10191 10192 10193 10194 10195 10196 10197 10198 10199 10200 10201 10202 10203 10204 10205 10206 10207 10208 10209 10210 10211 10212 10213 10214 10215 10216 10217 10218 10219 10220 10221 10222 10223 10224 10225 10226 10227 10228 10229 10230 10231 10232 10233 10234 10235 10236 10237 10238 10239 10240 10241 10242 10243 10244 10245 10246 10247 10248 10249 10250 10251 10252 10253 10254 10255 10256 10257 10258 10259 10260 10261 10262 10263 10264 10265 10266 10267 10268 10269 10270 10271 10272 10273 10274 10275 10276 10277 10278 10279 10280 10281 10282 10283 10284 10285 10286 10287 10288 10289 10290 10291 10292 10293 10294 10295 10296 10297 10298 10299 10300 10301 10302 10303 10304 10305 10306 10307 10308 10309 10310 10311 10312 10313 10314 10315 10316 10317 10318 10319 10320 10321 10322 10323 10324 10325 10326 10327 10328 10329 10330 10331 10332 10333 10334 10335 10336 10337 10338 10339 10340 10341 10342 10343 10344 10345 10346 10347 10348 10349 10350 10351 10352 10353 10354 10355 10356 10357 10358 10359 10360 10361 10362 10363 10364 10365 10366 10367 10368 10369 10370 10371 10372 10373 10374 10375 10376 10377 10378 10379 10380 10381 10382 10383 10384 10385 10386 10387 10388 10389 10390 10391 10392 10393 10394 10395 10396 10397 10398 10399 10400 10401 10402 10403 10404 10405 10406 10407 10408 10409 10410 10411 10412 10413 10414 10415 10416 10417 10418 10419 10420 10421 10422 10423 10424 10425 10426 10427 10428 10429 10430 10431 10432 10433 10434 10435 10436 10437 10438 10439 10440 10441 10442 10443 10444 10445 10446 10447 10448 10449 10450 10451 10452 10453 10454 10455 10456 10457 10458 10459 10460 10461 10462 10463 10464 10465 10466 10467 10468 10469 10470 10471 10472 10473 10474 10475 10476 10477 10478 10479 10480 10481 10482 10483 10484 10485 10486 10487 10488 10489 10490 10491 10492 10493 10494 10495 10496 10497 10498 10499 10500 10501 10502 10503 10504 10505 10506 10507 10508 10509 10510 10511 10512 10513 10514 10515 10516 10517 10518 10519 10520 10521 10522 10523 10524 10525 10526 10527 10528 10529 10530 10531 10532 10533 10534 10535 10536 10537 10538 10539 10540 10541 10542 10543 10544 10545 10546 10547 10548 10549 10550 10551 10552 10553 10554 10555 10556 10557 10558 10559 10560 10561 10562 10563 10564 10565 10566 10567 10568 10569 10570 10571 10572 10573 10574 10575 10576 10577 10578 10579 10580 10581 10582 10583 10584 10585 10586 10587 10588 10589 10590 10591 10592 10593 10594 10595 10596 10597 10598 10599 10600 10601 10602 10603 10604 10605 10606 10607 10608 10609 10610 10611 10612 10613 10614 10615 10616 10617 10618 10619 10620 10621 10622 10623 10624 10625 10626 10627 10628 10629 10630 10631 10632 10633 10634 10635 10636 10637 10638 10639 10640 10641 10642 10643 10644 10645 10646 10647 10648 10649 10650 10651 10652 10653 10654 10655 10656 10657 10658 10659 10660 10661 10662 10663 10664 10665 10666 10667 10668 10669 10670 10671 10672 10673 10674 10675 10676 10677 10678 10679 10680 10681 10682 10683 10684 10685 10686 10687 10688 10689 10690 10691 10692 10693 10694 10695 10696 10697 10698 10699 10700 10701 10702 10703 10704 10705 10706 10707 10708 10709 10710 10711 10712 10713 10714 10715 10716 10717 10718 10719 10720 10721 10722 10723 10724 10725 10726 10727 10728 10729 10730 10731 10732 10733 10734 10735 10736 10737 10738 10739 10740 10741 10742 10743 10744 10745 10746 10747 10748 10749 10750 10751 10752 10753 10754 10755 10756 10757 10758 10759 10760 10761 10762 10763 10764 10765 10766 10767 10768 10769 10770 10771 10772 10773 10774 10775 10776 10777 10778 10779 10780 10781 10782 10783 10784 10785 10786 10787 10788 10789 10790 10791 10792 10793 10794 10795 10796 10797 10798 10799 10800 10801 10802 10803 10804 10805 10806 10807 10808 10809 10810 10811 10812 10813 10814 10815 10816 10817 10818 10819 10820 10821 10822 10823 10824 10825 10826 10827 10828 10829 10830 10831 10832 10833 10834 10835 10836 10837 10838 10839 10840 10841 10842 10843 10844 10845 10846 10847 10848 10849 10850 10851 10852 10853 10854 10855 10856 10857 10858 10859 10860 10861 10862 10863 10864 10865 10866 10867 10868 10869 10870 10871 10872 10873 10874 10875 10876 10877 10878 10879 10880 10881 10882 10883 10884 10885 10886 10887 10888 10889 10890 10891 10892 10893 10894 10895 10896 10897 10898 10899 10900 10901 10902 10903 10904 10905 10906 10907 10908 10909 10910 10911 10912 10913 10914 10915 10916 10917 10918 10919 10920 10921 10922 10923 10924 10925 10926 10927 10928 10929 10930 10931 10932 10933 10934 10935 10936 10937 10938 10939 10940 10941 10942 10943 10944 10945 10946 10947 10948 10949 10950 10951 10952 10953 10954 10955 10956 10957 10958 10959 10960 10961 10962 10963 10964 10965 10966 10967 10968 10969 10970 10971 10972 10973 10974 10975 10976 10977 10978 10979 10980 10981 10982 10983 10984 10985 10986 10987 10988 10989 10990 10991 10992 10993 10994 10995 10996 10997 10998 10999 11000 11001 11002 11003 11004 11005 11006 11007 11008 11009 11010 11011 11012 11013 11014 11015 11016 11017 11018 11019 11020 11021 11022 11023 11024 11025 11026 11027 11028 11029 11030 11031 11032 11033 11034 11035 11036 11037 11038 11039 11040 11041 11042 11043 11044 11045 11046 11047 11048 11049 11050 11051 11052 11053 11054 11055 11056 11057 11058 11059 11060 11061 11062 11063 11064 11065 11066 11067 11068 11069 11070 11071 11072 11073 11074 11075 11076 11077 11078 11079 11080 11081 11082 11083 11084 11085 11086 11087 11088 11089 11090 11091 11092 11093 11094 11095 11096 11097 11098 11099 11100 11101 11102 11103 11104 11105 11106 11107 11108 11109 11110 11111 11112 11113 11114 11115 11116 11117 11118 11119 11120 11121 11122 11123 11124 11125 11126 11127 11128 11129 11130 11131 11132 11133 11134 11135 11136 11137 11138 11139 11140 11141 11142 11143 11144 11145 11146 11147 11148 11149 11150 11151 11152 11153 11154 11155 11156 11157 11158 11159 11160 11161 11162 11163 11164 11165 11166 11167 11168 11169 11170 11171 11172 11173 11174 11175 11176 11177 11178 11179 11180 11181 11182 11183 11184 11185 11186 11187 11188 11189 11190 11191 11192 11193 11194 11195 11196 11197 11198 11199 11200 11201 11202 11203 11204 11205 11206 11207 11208 11209 11210 11211 11212 11213 11214 11215 11216 11217 11218 11219 11220 11221 11222 11223 11224 11225 11226 11227 11228 11229 11230 11231 11232 11233 11234 11235 11236 11237 11238 11239 11240 11241 11242 11243 11244 11245 11246 11247 11248 11249 11250 11251 11252 11253 11254 11255 11256 11257 11258 11259 11260 11261 11262 11263 11264 11265 11266 11267 11268 11269 11270 11271 11272 11273 11274 11275 11276 11277 11278 11279 11280 11281 11282 11283 11284 11285 11286 11287 11288 11289 11290 11291 11292 11293 11294 11295 11296 11297 11298 11299 11300 11301 11302 11303 11304 11305 11306 11307 11308 11309 11310 11311 11312 11313 11314 11315 11316 11317 11318 11319 11320 11321 11322 11323 11324 11325 11326 11327 11328 11329 11330 11331 11332 11333 11334 11335 11336 11337 11338 11339 11340 11341 11342 11343 11344 11345 11346 11347 11348 11349 11350 11351 11352 11353 11354 11355 11356 11357 11358 11359 11360 11361 11362 11363 11364 11365 11366 11367 11368 11369 11370 11371 11372 11373 11374 11375 11376 11377 11378 11379 11380 11381 11382 11383 11384 11385 11386 11387 11388 11389 11390 11391 11392 11393 11394 11395 11396 11397 11398 11399 11400 11401 11402 11403 11404 11405 11406 11407 11408 11409 11410 11411 11412 11413 11414 11415 11416 11417 11418 11419 11420 11421 11422 11423 11424 11425 11426 11427 11428 11429 11430 11431 11432 11433 11434 11435 11436 11437 11438 11439 11440 11441 11442 11443 11444 11445 11446 11447 11448 11449 11450 11451 11452 11453 11454 11455 11456 11457 11458 11459 11460 11461 11462 11463 11464 11465 11466 11467 11468 11469 11470 11471 11472 11473 11474 11475 11476 11477 11478 11479 11480 11481 11482 11483 11484 11485 11486 11487 11488 11489 11490 11491 11492 11493 11494 11495 11496 11497 11498 11499 11500 11501 11502 11503 11504 11505 11506 11507 11508 11509 11510 11511 11512 11513 11514 11515 11516 11517 11518 11519 11520 11521 11522 11523 11524 11525 11526 11527 11528 11529 11530 11531 11532 11533 11534 11535 11536 11537 11538 11539 11540 11541 11542 11543 11544 11545 11546 11547 11548 11549 11550 11551 11552 11553 11554 11555 11556 11557 11558 11559 11560 11561 11562 11563 11564 11565 11566 11567 11568 11569 11570 11571 11572 11573 11574 11575 11576 11577 11578 11579 11580 11581 11582 11583 11584 11585 11586 11587 11588 11589 11590 11591 11592 11593 11594 11595 11596 11597 11598 11599 11600 11601 11602 11603 11604 11605 11606 11607 11608 11609 11610 11611 11612 11613 11614 11615 11616 11617 11618 11619 11620 11621 11622 11623 11624 11625 11626 11627 11628 11629 11630 11631 11632 11633 11634 11635 11636 11637 11638 11639 11640 11641 11642 11643 11644 11645 11646 11647 11648 11649 11650 11651 11652 11653 11654 11655 11656 11657 11658 11659 11660 11661 11662 11663 11664 11665 11666 11667 11668 11669 11670 11671 11672 11673 11674 11675 11676 11677 11678 11679 11680 11681 11682 11683 11684 11685 11686 11687 11688 11689 11690 11691 11692 11693 11694 11695 11696 11697 11698 11699 11700 11701 11702 11703 11704 11705 11706 11707 11708 11709 11710 11711 11712 11713 11714 11715 11716 11717 11718 11719 11720 11721 11722 11723 11724 11725 11726 11727 11728 11729 11730 11731 11732 11733 11734 11735 11736 11737 11738 11739 11740 11741 11742 11743 11744 11745 11746 11747 11748 11749 11750 11751 11752 11753 11754 11755 11756 11757 11758 11759 11760 11761 11762 11763 11764 11765 11766 11767 11768 11769 11770 11771 11772 11773 11774 11775 11776 11777 11778 11779 11780 11781 11782 11783 11784 11785 11786 11787 11788 11789 11790 11791 11792 11793 11794 11795 11796 11797 11798 11799 11800 11801 11802 11803 11804 11805 11806 11807 11808 11809 11810 11811 11812 11813 11814 11815 11816 11817 11818 11819 11820 11821 11822 11823 11824 11825 11826 11827 11828 11829 11830 11831 11832 11833 11834 11835 11836 11837 11838 11839 11840 11841 11842 11843 11844 11845 11846 11847 11848 11849 11850 11851 11852 11853 11854 11855 11856 11857 11858 11859 11860 11861 11862 11863 11864 11865 11866 11867 11868 11869 11870 11871 11872 11873 11874 11875 11876 11877 11878 11879 11880 11881 11882 11883 11884 11885 11886 11887 11888 11889 11890 11891 11892 11893 11894 11895 11896 11897 11898 11899 11900 11901 11902 11903 11904 11905 11906 11907 11908 11909 11910 11911 11912 11913 11914 11915 11916 11917 11918 11919 11920 11921 11922 11923 11924 11925 11926 11927 11928 11929 11930 11931 11932 11933 11934 11935 11936 11937 11938 11939 11940 11941 11942 11943 11944 11945 11946 11947 11948 11949 11950 11951 11952 11953 11954 11955 11956 11957 11958 11959 11960 11961 11962 11963 11964 11965 11966 11967 11968 11969 11970 11971 11972 11973 11974 11975 11976 11977 11978 11979 11980 11981 11982 11983 11984 11985 11986 11987 11988 11989 11990 11991 11992 11993 11994 11995 11996 11997 11998 11999 12000 12001 12002 12003 12004 12005 12006 12007 12008 12009 12010 12011 12012 12013 12014 12015 12016 12017 12018 12019 12020 12021 12022 12023 12024 12025 12026 12027 12028 12029 12030 12031 12032 12033 12034 12035 12036 12037 12038 12039 12040 12041 12042 12043 12044 12045 12046 12047 12048 12049 12050 12051 12052 12053 12054 12055 12056 12057 12058 12059 12060 12061 12062 12063 12064 12065 12066 12067 12068 12069 12070 12071 12072 12073 12074 12075 12076 12077 12078 12079 12080 12081 12082 12083 12084 12085 12086 12087 12088 12089 12090 12091 12092 12093 12094 12095 12096 12097 12098 12099 12100 12101 12102 12103 12104 12105 12106 12107 12108 12109 12110 12111 12112 12113 12114 12115 12116 12117 12118 12119 12120 12121 12122 12123 12124 12125 12126 12127 12128 12129 12130 12131 12132 12133 12134 12135 12136 12137 12138 12139 12140 12141 12142 12143 12144 12145 12146 12147 12148 12149 12150 12151 12152 12153 12154 12155 12156 12157 12158 12159 12160 12161 12162 12163 12164 12165 12166 12167 12168 12169 12170 12171 12172 12173 12174 12175 12176 12177 12178 12179 12180 12181 12182 12183 12184 12185 12186 12187 12188 12189 12190 12191 12192 12193 12194 12195 12196 12197 12198 12199 12200 12201 12202 12203 12204 12205 12206 12207 12208 12209 12210 12211 12212 12213 12214 12215 12216 12217 12218 12219 12220 12221 12222 12223 12224 12225 12226 12227 12228 12229 12230 12231 12232 12233 12234 12235 12236 12237 12238 12239 12240 12241 12242 12243 12244 12245 12246 12247 12248 12249 12250 12251 12252 12253 12254 12255 12256 12257 12258 12259 12260 12261 12262 12263 12264 12265 12266 12267 12268 12269 12270 12271 12272 12273 12274 12275 12276 12277 12278 12279 12280 12281 12282 12283 12284 12285 12286 12287 12288 12289 12290 12291 12292 12293 12294 12295 12296 12297 12298 12299 12300 12301 12302 12303 12304 12305 12306 12307 12308 12309 12310 12311 12312 12313 12314 12315 12316 12317 12318 12319 12320 12321 12322 12323 12324 12325 12326 12327 12328 12329 12330 12331 12332 12333 12334 12335 12336 12337 12338 12339 12340 12341 12342 12343 12344 12345 12346 12347 12348 12349 12350 12351 12352 12353 12354 12355 12356 12357 12358 12359 12360 12361 12362 12363 12364 12365 12366 12367 12368 12369 12370 12371 12372 12373 12374 12375 12376 12377 12378 12379 12380 12381 12382 12383 12384 12385 12386 12387 12388 12389 12390 12391 12392 12393 12394 12395 12396 12397 12398 12399 12400 12401 12402 12403 12404 12405 12406 12407 12408 12409 12410 12411 12412 12413 12414 12415 12416 12417 12418 12419 12420 12421 12422 12423 12424 12425 12426 12427 12428 12429 12430 12431 12432 12433 12434 12435 12436 12437 12438 12439 12440 12441 12442 12443 12444 12445 12446 12447 12448 12449 12450 12451 12452 12453 12454 12455 12456 12457 12458 12459 12460 12461 12462 12463 12464 12465 12466 12467 12468 12469 12470 12471 12472 12473 12474 12475 12476 12477 12478 12479 12480 12481 12482 12483 12484 12485 12486 12487 12488 12489 12490 12491 12492 12493 12494 12495 12496 12497 12498 12499 12500 12501 12502 12503 12504 12505 12506 12507 12508 12509 12510 12511 12512 12513 12514 12515 12516 12517 12518 12519 12520 12521 12522 12523 12524 12525 12526 12527 12528 12529 12530 12531 12532 12533 12534 12535 12536 12537 12538 12539 12540 12541 12542 12543 12544 12545 12546 12547 12548 12549 12550 12551 12552 12553 12554 12555 12556 12557 12558 12559 12560 12561 12562 12563 12564 12565 12566 12567 12568 12569 12570 12571 12572 12573 12574 12575 12576 12577 12578 12579 12580 12581 12582 12583 12584 12585 12586 12587 12588 12589 12590 12591 12592 12593 12594 12595 12596 12597 12598 12599 12600 12601 12602 12603 12604 12605 12606 12607 12608 12609 12610 12611 12612 12613 12614 12615 12616 12617 12618 12619 12620 12621 12622 12623 12624 12625 12626 12627 12628 12629 12630 12631 12632 12633 12634 12635 12636 12637 12638 12639 12640 12641 12642 12643 12644 12645 12646 12647 12648 12649 12650 12651 12652 12653 12654 12655 12656 12657 12658 12659 12660 12661 12662 12663 12664 12665 12666 12667 12668 12669 12670 12671 12672 12673 12674 12675 12676 12677 12678 12679 12680 12681 12682 12683 12684 12685 12686 12687 12688 12689 12690 12691 12692 12693 12694 12695 12696 12697 12698 12699 12700 12701 12702 12703 12704 12705 12706 12707 12708 12709 12710 12711 12712 12713 12714 12715 12716 12717 12718 12719 12720 12721 12722 12723 12724 12725 12726 12727 12728 12729 12730 12731 12732 12733 12734 12735 12736 12737 12738 12739 12740 12741 12742 12743 12744 12745 12746 12747 12748 12749 12750 12751 12752 12753 12754 12755 12756 12757 12758 12759 12760 12761 12762 12763 12764 12765 12766 12767 12768 12769 12770 12771 12772 12773 12774 12775 12776 12777 12778 12779 12780 12781 12782 12783 12784 12785 12786 12787 12788 12789 12790 12791 12792 12793 12794 12795 12796 12797 12798 12799 12800 12801 12802 12803 12804 12805 12806 12807 12808 12809 12810 12811 12812 12813 12814 12815 12816 12817 12818 12819 12820 12821 12822 12823 12824 12825 12826 12827 12828 12829 12830 12831 12832 12833 12834 12835 12836 12837 12838 12839 12840 12841 12842 12843 12844 12845 12846 12847 12848 12849 12850 12851 12852 12853 12854 12855 12856 12857 12858 12859 12860 12861 12862 12863 12864 12865 12866 12867 12868 12869 12870 12871 12872 12873 12874 12875 12876 12877 12878 12879 12880 12881 12882 12883 12884 12885 12886 12887 12888 12889 12890 12891 12892 12893 12894 12895 12896 12897 12898 12899 12900 12901 12902 12903 12904 12905 12906 12907 12908 12909 12910 12911 12912 12913 12914 12915 12916 12917 12918 12919 12920 12921 12922 12923 12924 12925 12926 12927 12928 12929 12930 12931 12932 12933 12934 12935 12936 12937 12938 12939 12940 12941 12942 12943 12944 12945 12946 12947 12948 12949 12950 12951 12952 12953 12954 12955 12956 12957 12958 12959 12960 12961 12962 12963 12964 12965 12966 12967 12968 12969 12970 12971 12972 12973 12974 12975 12976 12977 12978 12979 12980 12981 12982 12983 12984 12985 12986 12987 12988 12989 12990 12991 12992 12993 12994 12995 12996 12997 12998 12999 13000 13001 13002 13003 13004 13005 13006 13007 13008 13009 13010 13011 13012 13013 13014 13015 13016 13017 13018 13019 13020 13021 13022 13023 13024 13025 13026 13027 13028 13029 13030 13031 13032 13033 13034 13035 13036 13037 13038 13039 13040 13041 13042 13043 13044 13045 13046 13047 13048 13049 13050 13051 13052 13053 13054 13055 13056 13057 13058 13059 13060 13061 13062 13063 13064 13065 13066 13067 13068 13069 13070 13071 13072 13073 13074 13075 13076 13077 13078 13079 13080 13081 13082 13083 13084 13085 13086 13087 13088 13089 13090 13091 13092 13093 13094 13095 13096 13097 13098 13099 13100 13101 13102 13103 13104 13105 13106 13107 13108 13109 13110 13111 13112 13113 13114 13115 13116 13117 13118 13119 13120 13121 13122 13123 13124 13125 13126 13127 13128 13129 13130 13131 13132 13133 13134 13135 13136 13137 13138 13139 13140 13141 13142 13143 13144 13145 13146 13147 13148 13149 13150 13151 13152 13153 13154 13155 13156 13157 13158 13159 13160 13161 13162 13163 13164 13165 13166 13167 13168 13169 13170 13171 13172 13173 13174 13175 13176 13177 13178 13179 13180 13181 13182 13183 13184 13185 13186 13187 13188 13189 13190 13191 13192 13193 13194 13195 13196 13197 13198 13199 13200 13201 13202 13203 13204 13205 13206 13207 13208 13209 13210 13211 13212 13213 13214 13215 13216 13217 13218 13219 13220 13221 13222 13223 13224 13225 13226 13227 13228 13229 13230 13231 13232 13233 13234 13235 13236 13237 13238 13239 13240 13241 13242 13243 13244 13245 13246 13247 13248 13249 13250 13251 13252 13253 13254 13255 13256 13257 13258 13259 13260 13261 13262 13263 13264 13265 13266 13267 13268 13269 13270 13271 13272 13273 13274 13275 13276 13277 13278 13279 13280 13281 13282 13283 13284 13285 13286 13287 13288 13289 13290 13291 13292 13293 13294 13295 13296 13297 13298 13299 13300 13301 13302 13303 13304 13305 13306 13307 13308 13309 13310 13311 13312 13313 13314 13315 13316 13317 13318 13319 13320 13321 13322 13323 13324 13325 13326 13327 13328 13329 13330 13331 13332 13333 13334 13335 13336 13337 13338 13339 13340 13341 13342 13343 13344 13345 13346 13347 13348 13349 13350 13351 13352 13353 13354 13355 13356 13357 13358 13359 13360 13361 13362 13363 13364 13365 13366 13367 13368 13369 13370 13371 13372 13373 13374 13375 13376 13377 13378 13379 13380 13381 13382 13383 13384 13385 13386 13387 13388 13389 13390 13391 13392 13393 13394 13395 13396 13397 13398 13399 13400 13401 13402 13403 13404 13405 13406 13407 13408 13409 13410 13411 13412 13413 13414 13415 13416 13417 13418 13419 13420 13421 13422 13423 13424 13425 13426 13427 13428 13429 13430 13431 13432 13433 13434 13435 13436 13437 13438 13439 13440 13441 13442 13443 13444 13445 13446 13447 13448 13449 13450 13451 13452 13453 13454 13455 13456 13457 13458 13459 13460 13461 13462 13463 13464 13465 13466 13467 13468 13469 13470 13471 13472 13473 13474 13475 13476 13477 13478 13479 13480 13481 13482 13483 13484 13485 13486 13487 13488 13489 13490 13491 13492 13493 13494 13495 13496 13497 13498 13499 13500 13501 13502 13503 13504 13505 13506 13507 13508 13509 13510 13511 13512 13513 13514 13515 13516 13517 13518 13519 13520 13521 13522 13523 13524 13525 13526 13527 13528 13529 13530 13531 13532 13533 13534 13535 13536 13537 13538 13539 13540 13541 13542 13543 13544 13545 13546 13547 13548 13549 13550 13551 13552 13553 13554 13555 13556 13557 13558 13559 13560 13561 13562 13563 13564 13565 13566 13567 13568 13569 13570 13571 13572 13573 13574 13575 13576 13577 13578 13579 13580 13581 13582 13583 13584 13585 13586 13587 13588 13589 13590 13591 13592 13593 13594 13595 13596 13597 13598 13599 13600 13601 13602 13603 13604 13605 13606 13607 13608 13609 13610 13611 13612 13613 13614 13615 13616 13617 13618 13619 13620 13621 13622 13623 13624 13625 13626 13627 13628 13629 13630 13631 13632 13633 13634 13635 13636 13637 13638 13639 13640 13641 13642 13643 13644 13645 13646 13647 13648 13649 13650 13651 13652 13653 13654 13655 13656 13657 13658 13659 13660 13661 13662 13663 13664 13665 13666 13667 13668 13669 13670 13671 13672 13673 13674 13675 13676 13677 13678 13679 13680 13681 13682 13683 13684 13685 13686 13687 13688 13689 13690 13691 13692 13693 13694 13695 13696 13697 13698 13699 13700 13701 13702 13703 13704 13705 13706 13707 13708 13709 13710 13711 13712 13713 13714 13715 13716 13717 13718 13719 13720 13721 13722 13723 13724 13725 13726 13727 13728 13729 13730 13731 13732 13733 13734 13735 13736 13737 13738 13739 13740 13741 13742 13743 13744 13745 13746 13747 13748 13749 13750 13751 13752 13753 13754 13755 13756 13757 13758 13759 13760 13761 13762 13763 13764 13765 13766 13767 13768 13769 13770 13771 13772 13773 13774 13775 13776 13777 13778 13779 13780 13781 13782 13783 13784 13785 13786 13787 13788 13789 13790 13791 13792 13793 13794 13795 13796 13797 13798 13799 13800 13801 13802 13803 13804 13805 13806 13807 13808 13809 13810 13811 13812 13813 13814 13815 13816 13817 13818 13819 13820 13821 13822 13823 13824 13825 13826 13827 13828 13829 13830 13831 13832 13833 13834 13835 13836 13837 13838 13839 13840 13841 13842 13843 13844 13845 13846 13847 13848 13849 13850 13851 13852 13853 13854 13855 13856 13857 13858 13859 13860 13861 13862 13863 13864 13865 13866 13867 13868 13869 13870 13871 13872 13873 13874 13875 13876 13877 13878 13879 13880 13881 13882 13883 13884 13885 13886 13887 13888 13889 13890 13891 13892 13893 13894 13895 13896 13897 13898 13899 13900 13901 13902 13903 13904 13905 13906 13907 13908 13909 13910 13911 13912 13913 13914 13915 13916 13917 13918 13919 13920 13921 13922 13923 13924 13925 13926 13927 13928 13929 13930 13931 13932 13933 13934 13935 13936 13937 13938 13939 13940 13941 13942 13943 13944 13945 13946 13947 13948 13949 13950 13951 13952 13953 13954 13955 13956 13957 13958 13959 13960 13961 13962 13963 13964 13965 13966 13967 13968 13969 13970 13971 13972 13973 13974 13975 13976 13977 13978 13979 13980 13981 13982 13983 13984 13985 13986 13987 13988 13989 13990 13991 13992 13993 13994 13995 13996 13997 13998 13999 14000 14001 14002 14003 14004 14005 14006 14007 14008 14009 14010 14011 14012 14013 14014 14015 14016 14017 14018 14019 14020 14021 14022 14023 14024 14025 14026 14027 14028 14029 14030 14031 14032 14033 14034 14035 14036 14037 14038 14039 14040 14041 14042 14043 14044 14045 14046 14047 14048 14049 14050 14051 14052 14053 14054 14055 14056 14057 14058 14059 14060 14061 14062 14063 14064 14065 14066 14067 14068 14069 14070 14071 14072 14073 14074 14075 14076 14077 14078 14079 14080 14081 14082 14083 14084 14085 14086 14087 14088 14089 14090 14091 14092 14093 14094 14095 14096 14097 14098 14099 14100 14101 14102 14103 14104 14105 14106 14107 14108 14109 14110 14111 14112 14113 14114 14115 14116 14117 14118 14119 14120 14121 14122 14123 14124 14125 14126 14127 14128 14129 14130 14131 14132 14133 14134 14135 14136 14137 14138 14139 14140 14141 14142 14143 14144 14145 14146 14147 14148 14149 14150 14151 14152 14153 14154 14155 14156 14157 14158 14159 14160 14161 14162 14163 14164 14165 14166 14167 14168 14169 14170 14171 14172 14173 14174 14175 14176 14177 14178 14179 14180 14181 14182 14183 14184 14185 14186 14187 14188 14189 14190 14191 14192 14193 14194 14195 14196 14197 14198 14199 14200 14201 14202 14203 14204 14205 14206 14207 14208 14209 14210 14211 14212 14213 14214 14215 14216 14217 14218 14219 14220 14221 14222 14223 14224 14225 14226 14227 14228 14229 14230 14231 14232 14233 14234 14235 14236 14237 14238 14239 14240 14241 14242 14243 14244 14245 14246 14247 14248 14249 14250 14251 14252 14253 14254 14255 14256 14257 14258 14259 14260 14261 14262 14263 14264 14265 14266 14267 14268 14269 14270 14271 14272 14273 14274 14275 14276 14277 14278 14279 14280 14281 14282 14283 14284 14285 14286 14287 14288 14289 14290 14291 14292 14293 14294 14295 14296 14297 14298 14299 14300 14301 14302 14303 14304 14305 14306 14307 14308 14309 14310 14311 14312 14313 14314 14315 14316 14317 14318 14319 14320 14321 14322 14323 14324 14325 14326 14327 14328 14329 14330 14331 14332 14333 14334 14335 14336 14337 14338 14339 14340 14341 14342 14343 14344 14345 14346 14347 14348 14349 14350 14351 14352 14353 14354 14355 14356 14357 14358 14359 14360 14361 14362 14363 14364 14365 14366 14367 14368 14369 14370 14371 14372 14373 14374 14375 14376 14377 14378 14379 14380 14381 14382 14383 14384 14385 14386 14387 14388 14389 14390 14391 14392 14393 14394 14395 14396 14397 14398 14399 14400 14401 14402 14403 14404 14405 14406 14407 14408 14409 14410 14411 14412 14413 14414 14415 14416 14417 14418 14419 14420 14421 14422 14423 14424 14425 14426 14427 14428 14429 14430 14431 14432 14433 14434 14435 14436 14437 14438 14439 14440 14441 14442 14443 14444 14445 14446 14447 14448 14449 14450 14451 14452 14453 14454 14455 14456 14457 14458 14459 14460 14461 14462 14463 14464 14465 14466 14467 14468 14469 14470 14471 14472 14473 14474 14475 14476 14477 14478 14479 14480 14481 14482 14483 14484 14485 14486 14487 14488 14489 14490 14491 14492 14493 14494 14495 14496 14497 14498 14499 14500 14501 14502 14503 14504 14505 14506 14507 14508 14509 14510 14511 14512 14513 14514 14515 14516 14517 14518 14519 14520 14521 14522 14523 14524 14525 14526 14527 14528 14529 14530 14531 14532 14533 14534 14535 14536 14537 14538 14539 14540 14541 14542 14543 14544 14545 14546 14547 14548 14549 14550 14551 14552 14553 14554 14555 14556 14557 14558 14559 14560 14561 14562 14563 14564 14565 14566 14567 14568 14569 14570 14571 14572 14573 14574 14575 14576 14577 14578 14579 14580 14581 14582 14583 14584 14585 14586 14587 14588 14589 14590 14591 14592 14593 14594 14595 14596 14597 14598 14599 14600 14601 14602 14603 14604 14605 14606 14607 14608 14609 14610 14611 14612 14613 14614 14615 14616 14617 14618 14619 14620 14621 14622 14623 14624 14625 14626 14627 14628 14629 14630 14631 14632 14633 14634 14635 14636 14637 14638 14639 14640 14641 14642 14643 14644 14645 14646 14647 14648 14649 14650 14651 14652 14653 14654 14655 14656 14657 14658 14659 14660 14661 14662 14663 14664 14665 14666 14667 14668 14669 14670 14671 14672 14673 14674 14675 14676 14677 14678 14679 14680 14681 14682 14683 14684 14685 14686 14687 14688 14689 14690 14691 14692 14693 14694 14695 14696 14697 14698 14699 14700 14701 14702 14703 14704 14705 14706 14707 14708 14709 14710 14711 14712 14713 14714 14715 14716 14717 14718 14719 14720 14721 14722 14723 14724 14725 14726 14727 14728 14729 14730 14731 14732 14733 14734 14735 14736 14737 14738 14739 14740 14741 14742 14743 14744 14745 14746 14747 14748 14749 14750 14751 14752 14753 14754 14755 14756 14757 14758 14759 14760 14761 14762 14763 14764 14765 14766 14767 14768 14769 14770 14771 14772 14773 14774 14775 14776 14777 14778 14779 14780 14781 14782 14783 14784 14785 14786 14787 14788 14789 14790 14791 14792 14793 14794 14795 14796 14797 14798 14799 14800 14801 14802 14803 14804 14805 14806 14807 14808 14809 14810 14811 14812 14813 14814 14815 14816 14817 14818 14819 14820 14821 14822 14823 14824 14825 14826 14827 14828 14829 14830 14831 14832 14833 14834 14835 14836 14837 14838 14839 14840 14841 14842 14843 14844 14845 14846 14847 14848 14849 14850 14851 14852 14853 14854 14855 14856 14857 14858 14859 14860 14861 14862 14863 14864 14865 14866 14867 14868 14869 14870 14871 14872 14873 14874 14875 14876 14877 14878 14879 14880 14881 14882 14883 14884 14885 14886 14887 14888 14889 14890 14891 14892 14893 14894 14895 14896 14897 14898 14899 14900 14901 14902 14903 14904 14905 14906 14907 14908 14909 14910 14911 14912 14913 14914 14915 14916 14917 14918 14919 14920 14921 14922 14923 14924 14925 14926 14927 14928 14929 14930 14931 14932 14933 14934 14935 14936 14937 14938 14939 14940 14941 14942 14943 14944 14945 14946 14947 14948 14949 14950 14951 14952 14953 14954 14955 14956 14957 14958 14959 14960 14961 14962 14963 14964 14965 14966 14967 14968 14969 14970 14971 14972 14973 14974 14975 14976 14977 14978 14979 14980 14981 14982 14983 14984 14985 14986 14987 14988 14989 14990 14991 14992 14993 14994 14995 14996 14997 14998 14999 15000 15001 15002 15003 15004 15005 15006 15007 15008 15009 15010 15011 15012 15013 15014 15015 15016 15017 15018 15019 15020 15021 15022 15023 15024 15025 15026 15027 15028 15029 15030 15031 15032 15033 15034 15035 15036 15037 15038 15039 15040 15041 15042 15043 15044 15045 15046 15047 15048 15049 15050 15051 15052 15053 15054 15055 15056 15057 15058 15059 15060 15061 15062 15063 15064 15065 15066 15067 15068 15069 15070 15071 15072 15073 15074 15075 15076 15077 15078 15079 15080 15081 15082 15083 15084 15085 15086 15087 15088 15089 15090 15091 15092 15093 15094 15095 15096 15097 15098 15099 15100 15101 15102 15103 15104 15105 15106 15107 15108 15109 15110 15111 15112 15113 15114 15115 15116 15117 15118 15119 15120 15121 15122 15123 15124 15125 15126 15127 15128 15129 15130 15131 15132 15133 15134 15135 15136 15137 15138 15139 15140 15141 15142 15143 15144 15145 15146 15147 15148 15149 15150 15151 15152 15153 15154 15155 15156 15157 15158 15159 15160 15161 15162 15163 15164 15165 15166 15167 15168 15169 15170 15171 15172 15173 15174 15175 15176 15177 15178 15179 15180 15181 15182 15183 15184 15185 15186 15187 15188 15189 15190 15191 15192 15193 15194 15195 15196 15197 15198 15199 15200 15201 15202 15203 15204 15205 15206 15207 15208 15209 15210 15211 15212 15213 15214 15215 15216 15217 15218 15219 15220 15221 15222 15223 15224 15225 15226 15227 15228 15229 15230 15231 15232 15233 15234 15235 15236 15237 15238 15239 15240 15241 15242 15243 15244 15245 15246 15247 15248 15249 15250 15251 15252 15253 15254 15255 15256 15257 15258 15259 15260 15261 15262 15263 15264 15265 15266 15267 15268 15269 15270 15271 15272 15273 15274 15275 15276 15277 15278 15279 15280 15281 15282 15283 15284 15285 15286 15287 15288 15289 15290 15291 15292 15293 15294 15295 15296 15297 15298 15299 15300 15301 15302 15303 15304 15305 15306 15307 15308 15309 15310 15311 15312 15313 15314 15315 15316 15317 15318 15319 15320 15321 15322 15323 15324 15325 15326 15327 15328 15329 15330 15331 15332 15333 15334 15335 15336 15337 15338 15339 15340 15341 15342 15343 15344 15345 15346 15347 15348 15349 15350 15351 15352 15353 15354 15355 15356 15357 15358 15359 15360 15361 15362 15363 15364 15365 15366 15367 15368 15369 15370 15371 15372 15373 15374 15375 15376 15377 15378 15379 15380 15381 15382 15383 15384 15385 15386 15387 15388 15389 15390 15391 15392 15393 15394 15395 15396 15397 15398 15399 15400 15401 15402 15403 15404 15405 15406 15407 15408 15409 15410 15411 15412 15413 15414 15415 15416 15417 15418 15419 15420 15421 15422 15423 15424 15425 15426 15427 15428 15429 15430 15431 15432 15433 15434 15435 15436 15437 15438 15439 15440 15441 15442 15443 15444 15445 15446 15447 15448 15449 15450 15451 15452 15453 15454 15455 15456 15457 15458 15459 15460 15461 15462 15463 15464 15465 15466 15467 15468 15469 15470 15471 15472 15473 15474 15475 15476 15477 15478 15479 15480 15481 15482 15483 15484 15485 15486 15487 15488 15489 15490 15491 15492 15493 15494 15495 15496 15497 15498 15499 15500 15501 15502 15503 15504 15505 15506 15507 15508 15509 15510 15511 15512 15513 15514 15515 15516 15517 15518 15519 15520 15521 15522 15523 15524 15525 15526 15527 15528 15529 15530 15531 15532 15533 15534 15535 15536 15537 15538 15539 15540 15541 15542 15543 15544 15545 15546 15547 15548 15549 15550 15551 15552 15553 15554 15555 15556 15557 15558 15559 15560 15561 15562 15563 15564 15565 15566 15567 15568 15569 15570 15571 15572 15573 15574 15575 15576 15577 15578 15579 15580 15581 15582 15583 15584 15585 15586 15587 15588 15589 15590 15591 15592 15593 15594 15595 15596 15597 15598 15599 15600 15601 15602 15603 15604 15605 15606 15607 15608 15609 15610 15611 15612 15613 15614 15615 15616 15617 15618 15619 15620 15621 15622 15623 15624 15625 15626 15627 15628 15629 15630 15631 15632 15633 15634 15635 15636 15637 15638 15639 15640 15641 15642 15643 15644 15645 15646 15647 15648 15649 15650 15651 15652 15653 15654 15655 15656 15657 15658 15659 15660 15661 15662 15663 15664 15665 15666 15667 15668 15669 15670 15671 15672 15673 15674 15675 15676 15677 15678 15679 15680 15681 15682 15683 15684 15685 15686 15687 15688 15689 15690 15691 15692 15693 15694 15695 15696 15697 15698 15699 15700 15701 15702 15703 15704 15705 15706 15707 15708 15709 15710 15711 15712 15713 15714 15715 15716 15717 15718 15719 15720 15721 15722 15723 15724 15725 15726 15727 15728 15729 15730 15731 15732 15733 15734 15735 15736 15737 15738 15739 15740 15741 15742 15743 15744 15745 15746 15747 15748 15749 15750 15751 15752 15753 15754 15755 15756 15757 15758 15759 15760 15761 15762 15763 15764 15765 15766 15767 15768 15769 15770 15771 15772 15773 15774 15775 15776 15777 15778 15779 15780 15781 15782 15783 15784 15785 15786 15787 15788 15789 15790 15791 15792 15793 15794 15795 15796 15797 15798 15799 15800 15801 15802 15803 15804 15805 15806 15807 15808 15809 15810 15811 15812 15813 15814 15815 15816 15817 15818 15819 15820 15821 15822 15823 15824 15825 15826 15827 15828 15829 15830 15831 15832 15833 15834 15835 15836 15837 15838 15839 15840 15841 15842 15843 15844 15845 15846 15847 15848 15849 15850 15851 15852 15853 15854 15855 15856 15857 15858 15859 15860 15861 15862 15863 15864 15865 15866 15867 15868 15869 15870 15871 15872 15873 15874 15875 15876 15877 15878 15879 15880 15881 15882 15883 15884 15885 15886 15887 15888 15889 15890 15891 15892 15893 15894 15895 15896 15897 15898 15899 15900 15901 15902 15903 15904 15905 15906 15907 15908 15909 15910 15911 15912 15913 15914 15915 15916 15917 15918 15919 15920 15921 15922 15923 15924 15925 15926 15927 15928 15929 15930 15931 15932 15933 15934 15935 15936 15937 15938 15939 15940 15941 15942 15943 15944 15945 15946 15947 15948 15949 15950 15951 15952 15953 15954 15955 15956 15957 15958 15959 15960 15961 15962 15963 15964 15965 15966 15967 15968 15969 15970 15971 15972 15973 15974 15975 15976 15977 15978 15979 15980 15981 15982 15983 15984 15985 15986 15987 15988 15989 15990 15991 15992 15993 15994 15995 15996 15997 15998 15999 16000 16001 16002 16003 16004 16005 16006 16007 16008 16009 16010 16011 16012 16013 16014 16015 16016 16017 16018 16019 16020 16021 16022 16023 16024 16025 16026 16027 16028 16029 16030 16031 16032 16033 16034 16035 16036 16037 16038 16039 16040 16041 16042 16043 16044 16045 16046 16047 16048 16049 16050 16051 16052 16053 16054 16055 16056 16057 16058 16059 16060 16061 16062 16063 16064 16065 16066 16067 16068 16069 16070 16071 16072 16073 16074 16075 16076 16077 16078 16079 16080 16081 16082 16083 16084 16085 16086 16087 16088 16089 16090 16091 16092 16093 16094 16095 16096 16097 16098 16099 16100 16101 16102 16103 16104 16105 16106 16107 16108 16109 16110 16111 16112 16113 16114 16115 16116 16117 16118 16119 16120 16121 16122 16123 16124 16125 16126 16127 16128 16129 16130 16131 16132 16133 16134 16135 16136 16137 16138 16139 16140 16141 16142 16143 16144 16145 16146 16147 16148 16149 16150 16151 16152 16153 16154 16155 16156 16157 16158 16159 16160 16161 16162 16163 16164 16165 16166 16167 16168 16169 16170 16171 16172 16173 16174 16175 16176 16177 16178 16179 16180 16181 16182 16183 16184 16185 16186 16187 16188 16189 16190 16191 16192 16193 16194 16195 16196 16197 16198 16199 16200 16201 16202 16203 16204 16205 16206 16207 16208 16209 16210 16211 16212 16213 16214 16215 16216 16217 16218 16219 16220 16221 16222 16223 16224 16225 16226 16227 16228 16229 16230 16231 16232 16233 16234 16235 16236 16237 16238 16239 16240 16241 16242 16243 16244 16245 16246 16247 16248 16249 16250 16251 16252 16253 16254 16255 16256 16257 16258 16259 16260 16261 16262 16263 16264 16265 16266 16267 16268 16269 16270 16271 16272 16273 16274 16275 16276 16277 16278 16279 16280 16281 16282 16283 16284 16285 16286 16287 16288 16289 16290 16291 16292 16293 16294 16295 16296 16297 16298 16299 16300 16301 16302 16303 16304 16305 16306 16307 16308 16309 16310 16311 16312 16313 16314 16315 16316 16317 16318 16319 16320 16321 16322 16323 16324 16325 16326 16327 16328 16329 16330 16331 16332 16333 16334 16335 16336 16337 16338 16339 16340 16341 16342 16343 16344 16345 16346 16347 16348 16349 16350 16351 16352 16353 16354 16355 16356 16357 16358 16359 16360 16361 16362 16363 16364 16365 16366 16367 16368 16369 16370 16371 16372 16373 16374 16375 16376 16377 16378 16379 16380 16381 16382 16383 16384 16385 16386 16387 16388 16389 16390 16391 16392 16393 16394 16395 16396 16397 16398 16399 16400 16401 16402 16403 16404 16405 16406 16407 16408 16409 16410 16411 16412 16413 16414 16415 16416 16417 16418 16419 16420 16421 16422 16423 16424 16425 16426 16427 16428 16429 16430 16431 16432 16433 16434 16435 16436 16437 16438 16439 16440 16441 16442 16443 16444 16445 16446 16447 16448 16449 16450 16451 16452 16453 16454 16455 16456 16457 16458 16459 16460 16461 16462 16463 16464 16465 16466 16467 16468 16469 16470 16471 16472 16473 16474 16475 16476 16477 16478 16479 16480 16481 16482 16483 16484 16485 16486 16487 16488 16489 16490 16491 16492 16493 16494 16495 16496 16497 16498 16499 16500 16501 16502 16503 16504 16505 16506 16507 16508 16509 16510 16511 16512 16513 16514 16515 16516 16517 16518 16519 16520 16521 16522 16523 16524 16525 16526 16527 16528 16529 16530 16531 16532 16533 16534 16535 16536 16537 16538 16539 16540 16541 16542 16543 16544 16545 16546 16547 16548 16549 16550 16551 16552 16553 16554 16555 16556 16557 16558 16559 16560 16561 16562 16563 16564 16565 16566 16567 16568 16569 16570 16571 16572 16573 16574 16575 16576 16577 16578 16579 16580 16581 16582 16583 16584 16585 16586 16587 16588 16589 16590 16591 16592 16593 16594 16595 16596 16597 16598 16599 16600 16601 16602 16603 16604 16605 16606 16607 16608 16609 16610 16611 16612 16613 16614 16615 16616 16617 16618 16619 16620 16621 16622 16623 16624 16625 16626 16627 16628 16629 16630 16631 16632 16633 16634 16635 16636 16637 16638 16639 16640 16641 16642 16643 16644 16645 16646 16647 16648 16649 16650 16651 16652 16653 16654 16655 16656 16657 16658 16659 16660 16661 16662 16663 16664 16665 16666 16667 16668 16669 16670 16671 16672 16673 16674 16675 16676 16677 16678 16679 16680 16681 16682 16683 16684 16685 16686 16687 16688 16689 16690 16691 16692 16693 16694 16695 16696 16697 16698 16699 16700 16701 16702 16703 16704 16705 16706 16707 16708 16709 16710 16711 16712 16713 16714 16715 16716 16717 16718 16719 16720 16721 16722 16723 16724 16725 16726 16727 16728 16729 16730 16731 16732 16733 16734 16735 16736 16737 16738 16739 16740 16741 16742 16743 16744 16745 16746 16747 16748 16749 16750 16751 16752 16753 16754 16755 16756 16757 16758 16759 16760 16761 16762 16763 16764 16765 16766 16767 16768 16769 16770 16771 16772 16773 16774 16775 16776 16777 16778 16779 16780 16781 16782 16783 16784 16785 16786 16787 16788 16789 16790 16791 16792 16793 16794 16795 16796 16797 16798 16799 16800 16801 16802 16803 16804 16805 16806 16807 16808 16809 16810 16811 16812 16813 16814 16815 16816 16817 16818 16819 16820 16821 16822 16823 16824 16825 16826 16827 16828 16829 16830 16831 16832 16833 16834 16835 16836 16837 16838 16839 16840 16841 16842 16843 16844 16845 16846 16847 16848 16849 16850 16851 16852 16853 16854 16855 16856 16857 16858 16859 16860 16861 16862 16863 16864 16865 16866 16867 16868 16869 16870 16871 16872 16873 16874 16875 16876 16877 16878 16879 16880 16881 16882 16883 16884 16885 16886 16887 16888 16889 16890 16891 16892 16893 16894 16895 16896 16897 16898 16899 16900 16901 16902 16903 16904 16905 16906 16907 16908 16909 16910 16911 16912 16913 16914 16915 16916 16917 16918 16919 16920 16921 16922 16923 16924 16925 16926 16927 16928 16929 16930 16931 16932 16933 16934 16935 16936 16937 16938 16939 16940 16941 16942 16943 16944 16945 16946 16947 16948 16949 16950 16951 16952 16953 16954 16955 16956 16957 16958 16959 16960 16961 16962 16963 16964 16965 16966 16967 16968 16969 16970 16971 16972 16973 16974 16975 16976 16977 16978 16979 16980 16981 16982 16983 16984 16985 16986 16987 16988 16989 16990 16991 16992 16993 16994 16995 16996 16997 16998 16999 17000 17001 17002 17003 17004 17005 17006 17007 17008 17009 17010 17011 17012 17013 17014 17015 17016 17017 17018 17019 17020 17021 17022 17023 17024 17025 17026 17027 17028 17029 17030 17031 17032 17033 17034 17035 17036 17037 17038 17039 17040 17041 17042 17043 17044 17045 17046 17047 17048 17049 17050 17051 17052 17053 17054 17055 17056 17057 17058 17059 17060 17061 17062 17063 17064 17065 17066 17067 17068 17069 17070 17071 17072 17073 17074 17075 17076 17077 17078 17079 17080 17081 17082 17083 17084 17085 17086 17087 17088 17089 17090 17091 17092 17093 17094 17095 17096 17097 17098 17099 17100 17101 17102 17103 17104 17105 17106 17107 17108 17109 17110 17111 17112 17113 17114 17115 17116 17117 17118 17119 17120 17121 17122 17123 17124 17125 17126 17127 17128 17129 17130 17131 17132 17133 17134 17135 17136 17137 17138 17139 17140 17141 17142 17143 17144 17145 17146 17147 17148 17149 17150 17151 17152 17153 17154 17155 17156 17157 17158 17159 17160 17161 17162 17163 17164 17165 17166 17167 17168 17169 17170 17171 17172 17173 17174 17175 17176 17177 17178 17179 17180 17181 17182 17183 17184 17185 17186 17187 17188 17189 17190 17191 17192 17193 17194 17195 17196 17197 17198 17199 17200 17201 17202 17203 17204 17205 17206 17207 17208 17209 17210 17211 17212 17213 17214 17215 17216 17217 17218 17219 17220 17221 17222 17223 17224 17225 17226 17227 17228 17229 17230 17231 17232 17233 17234 17235 17236 17237 17238 17239 17240 17241 17242 17243 17244 17245 17246 17247 17248 17249 17250 17251 17252 17253 17254 17255 17256 17257 17258 17259 17260 17261 17262 17263 17264 17265 17266 17267 17268 17269 17270 17271 17272 17273 17274 17275 17276 17277 17278 17279 17280 17281 17282 17283 17284 17285 17286 17287 17288 17289 17290 17291 17292 17293 17294 17295 17296 17297 17298 17299 17300 17301 17302 17303 17304 17305 17306 17307 17308 17309 17310 17311 17312 17313 17314 17315 17316 17317 17318 17319 17320 17321 17322 17323 17324 17325 17326 17327 17328 17329 17330 17331 17332 17333 17334 17335 17336 17337 17338 17339 17340 17341 17342 17343 17344 17345 17346 17347 17348 17349 17350 17351 17352 17353 17354 17355 17356 17357 17358 17359 17360 17361 17362 17363 17364 17365 17366 17367 17368 17369 17370 17371 17372 17373 17374 17375 17376 17377 17378 17379 17380 17381 17382 17383 17384 17385 17386 17387 17388 17389 17390 17391 17392 17393 17394 17395 17396 17397 17398 17399 17400 17401 17402 17403 17404 17405 17406 17407 17408 17409 17410 17411 17412 17413 17414 17415 17416 17417 17418 17419 17420 17421 17422 17423 17424 17425 17426 17427 17428 17429 17430 17431 17432 17433 17434 17435 17436 17437 17438 17439 17440 17441 17442 17443 17444 17445 17446 17447 17448 17449 17450 17451 17452 17453 17454 17455 17456 17457 17458 17459 17460 17461 17462 17463 17464 17465 17466 17467 17468 17469 17470 17471 17472 17473 17474 17475 17476 17477 17478 17479 17480 17481 17482 17483 17484 17485 17486 17487 17488 17489 17490 17491 17492 17493 17494 17495 17496 17497 17498 17499 17500 17501 17502 17503 17504 17505 17506 17507 17508 17509 17510 17511 17512 17513 17514 17515 17516 17517 17518 17519 17520 17521 17522 17523 17524 17525 17526 17527 17528 17529 17530 17531 17532 17533 17534 17535 17536 17537 17538 17539 17540 17541 17542 17543 17544 17545 17546 17547 17548 17549 17550 17551 17552 17553 17554 17555 17556 17557 17558 17559 17560 17561 17562 17563 17564 17565 17566 17567 17568 17569 17570 17571 17572 17573 17574 17575 17576 17577 17578 17579 17580 17581 17582 17583 17584 17585 17586 17587 17588 17589 17590 17591 17592 17593 17594 17595 17596 17597 17598 17599 17600 17601 17602 17603 17604 17605 17606 17607 17608 17609 17610 17611 17612 17613 17614 17615 17616 17617 17618 17619 17620 17621 17622 17623 17624 17625 17626 17627 17628 17629 17630 17631 17632 17633 17634 17635 17636 17637 17638 17639 17640 17641 17642 17643 17644 17645 17646 17647 17648 17649 17650 17651 17652 17653 17654 17655 17656 17657 17658 17659 17660 17661 17662 17663 17664 17665 17666 17667 17668 17669 17670 17671 17672 17673 17674 17675 17676 17677 17678 17679 17680 17681 17682 17683 17684 17685 17686 17687 17688 17689 17690 17691 17692 17693 17694 17695 17696 17697 17698 17699 17700 17701 17702 17703 17704 17705 17706 17707 17708 17709 17710 17711 17712 17713 17714 17715 17716 17717 17718 17719 17720 17721 17722 17723 17724 17725 17726 17727 17728 17729 17730 17731 17732 17733 17734 17735 17736 17737 17738 17739 17740 17741 17742 17743 17744 17745 17746 17747 17748 17749 17750 17751 17752 17753 17754 17755 17756 17757 17758 17759 17760 17761 17762 17763 17764 17765 17766 17767 17768 17769 17770 17771 17772 17773 17774 17775 17776 17777 17778 17779 17780 17781 17782 17783 17784 17785 17786 17787 17788 17789 17790 17791 17792 17793 17794 17795 17796 17797 17798 17799 17800 17801 17802 17803 17804 17805 17806 17807 17808 17809 17810 17811 17812 17813 17814 17815 17816 17817 17818 17819 17820 17821 17822 17823 17824 17825 17826 17827 17828 17829 17830 17831 17832 17833 17834 17835 17836 17837 17838 17839 17840 17841 17842 17843 17844 17845 17846 17847 17848 17849 17850 17851 17852 17853 17854 17855 17856 17857 17858 17859 17860 17861 17862 17863 17864 17865 17866 17867 17868 17869 17870 17871 17872 17873 17874 17875 17876 17877 17878 17879 17880 17881 17882 17883 17884 17885 17886 17887 17888 17889 17890 17891 17892 17893 17894 17895 17896 17897 17898 17899 17900 17901 17902 17903 17904 17905 17906 17907 17908 17909 17910 17911 17912 17913 17914 17915 17916 17917 17918 17919 17920 17921 17922 17923 17924 17925 17926 17927 17928 17929 17930 17931 17932 17933 17934 17935 17936 17937 17938 17939 17940 17941 17942 17943 17944 17945 17946 17947 17948 17949 17950 17951 17952 17953 17954 17955 17956 17957 17958 17959 17960 17961 17962 17963 17964 17965 17966 17967 17968 17969 17970 17971 17972 17973 17974 17975 17976 17977 17978 17979 17980 17981 17982 17983 17984 17985 17986 17987 17988 17989 17990 17991 17992 17993 17994 17995 17996 17997 17998 17999 18000 18001 18002 18003 18004 18005 18006 18007 18008 18009 18010 18011 18012 18013 18014 18015 18016 18017 18018 18019 18020 18021 18022 18023 18024 18025 18026 18027 18028 18029 18030 18031 18032 18033 18034 18035 18036 18037 18038 18039 18040 18041 18042 18043 18044 18045 18046 18047 18048 18049 18050 18051 18052 18053 18054 18055 18056 18057 18058 18059 18060 18061 18062 18063 18064 18065 18066 18067 18068 18069 18070 18071 18072 18073 18074 18075 18076 18077 18078 18079 18080 18081 18082 18083 18084 18085 18086 18087 18088 18089 18090 18091 18092 18093 18094 18095 18096 18097 18098 18099 18100 18101 18102 18103 18104 18105 18106 18107 18108 18109 18110 18111 18112 18113 18114 18115 18116 18117 18118 18119 18120 18121 18122 18123 18124 18125 18126 18127 18128 18129 18130 18131 18132 18133 18134 18135 18136 18137 18138 18139 18140 18141 18142 18143 18144 18145 18146 18147 18148 18149 18150 18151 18152 18153 18154 18155 18156 18157 18158 18159 18160 18161 18162 18163 18164 18165 18166 18167 18168 18169 18170 18171 18172 18173 18174 18175 18176 18177 18178 18179 18180 18181 18182 18183 18184 18185 18186 18187 18188 18189 18190 18191 18192 18193 18194 18195 18196 18197 18198 18199 18200 18201 18202 18203 18204 18205 18206 18207 18208 18209 18210 18211 18212 18213 18214 18215 18216 18217 18218 18219 18220 18221 18222 18223 18224 18225 18226 18227 18228 18229 18230 18231 18232 18233 18234 18235 18236 18237 18238 18239 18240 18241 18242 18243 18244 18245 18246 18247 18248 18249 18250 18251 18252 18253 18254 18255 18256 18257 18258 18259 18260 18261 18262 18263 18264 18265 18266 18267 18268 18269 18270 18271 18272 18273 18274 18275 18276 18277 18278 18279 18280 18281 18282 18283 18284 18285 18286 18287 18288 18289 18290 18291 18292 18293 18294 18295 18296 18297 18298 18299 18300 18301 18302 18303 18304 18305 18306 18307 18308 18309 18310 18311 18312 18313 18314 18315 18316 18317 18318 18319 18320 18321 18322 18323 18324 18325 18326 18327 18328 18329 18330 18331 18332 18333 18334 18335 18336 18337 18338 18339 18340 18341 18342 18343 18344 18345 18346 18347 18348 18349 18350 18351 18352 18353 18354 18355 18356 18357 18358 18359 18360 18361 18362 18363 18364 18365 18366 18367 18368 18369 18370 18371 18372 18373 18374 18375 18376 18377 18378 18379 18380 18381 18382 18383 18384 18385 18386 18387 18388 18389 18390 18391 18392 18393 18394 18395 18396 18397 18398 18399 18400 18401 18402 18403 18404 18405 18406 18407 18408 18409 18410 18411 18412 18413 18414 18415 18416 18417 18418 18419 18420 18421 18422 18423 18424 18425 18426 18427 18428 18429 18430 18431 18432 18433 18434 18435 18436 18437 18438 18439 18440 18441 18442 18443 18444 18445 18446 18447 18448 18449 18450 18451 18452 18453 18454 18455 18456 18457 18458 18459 18460 18461 18462 18463 18464 18465 18466 18467 18468 18469 18470 18471 18472 18473 18474 18475 18476 18477 18478 18479 18480 18481 18482 18483 18484 18485 18486 18487 18488 18489 18490 18491 18492 18493 18494 18495 18496 18497 18498 18499 18500 18501 18502 18503 18504 18505 18506 18507 18508 18509 18510 18511 18512 18513 18514 18515 18516 18517 18518 18519 18520 18521 18522 18523 18524 18525 18526 18527 18528 18529 18530 18531 18532 18533 18534 18535 18536 18537 18538 18539 18540 18541 18542 18543 18544 18545 18546 18547 18548 18549 18550 18551 18552 18553 18554 18555 18556 18557 18558 18559 18560 18561 18562 18563 18564 18565 18566 18567 18568 18569 18570 18571 18572 18573 18574 18575 18576 18577 18578 18579 18580 18581 18582 18583 18584 18585 18586 18587 18588 18589 18590 18591 18592 18593 18594 18595 18596 18597 18598 18599 18600 18601 18602 18603 18604 18605 18606 18607 18608 18609 18610 18611 18612 18613 18614 18615 18616 18617 18618 18619 18620 18621 18622 18623 18624 18625 18626 18627 18628 18629 18630 18631 18632 18633 18634 18635 18636 18637 18638 18639 18640 18641 18642 18643 18644 18645 18646 18647 18648 18649 18650 18651 18652 18653 18654 18655 18656 18657 18658 18659 18660 18661 18662 18663 18664 18665 18666 18667 18668 18669 18670 18671 18672 18673 18674 18675 18676 18677 18678 18679 18680 18681 18682 18683 18684 18685 18686 18687 18688 18689 18690 18691 18692 18693 18694 18695 18696 18697 18698 18699 18700 18701 18702 18703 18704 18705 18706 18707 18708 18709 18710 18711 18712 18713 18714 18715 18716 18717 18718 18719 18720 18721 18722 18723 18724 18725 18726 18727 18728 18729 18730 18731 18732 18733 18734 18735 18736 18737 18738 18739 18740 18741 18742 18743 18744 18745 18746 18747 18748 18749 18750 18751 18752 18753 18754 18755 18756 18757 18758 18759 18760 18761 18762 18763 18764 18765 18766 18767 18768 18769 18770 18771 18772 18773 18774 18775 18776 18777 18778 18779 18780 18781 18782 18783 18784 18785 18786 18787 18788 18789 18790 18791 18792 18793 18794 18795 18796 18797 18798 18799 18800 18801 18802 18803 18804 18805 18806 18807 18808 18809 18810 18811 18812 18813 18814 18815 18816 18817 18818 18819 18820 18821 18822 18823 18824 18825 18826 18827 18828 18829 18830 18831 18832 18833 18834 18835 18836 18837 18838 18839 18840 18841 18842 18843 18844 18845 18846 18847 18848 18849 18850 18851 18852 18853 18854 18855 18856 18857 18858 18859 18860 18861 18862 18863 18864 18865 18866 18867 18868 18869 18870 18871 18872 18873 18874 18875 18876 18877 18878 18879 18880 18881 18882 18883 18884 18885 18886 18887 18888 18889 18890 18891 18892 18893 18894 18895 18896 18897 18898 18899 18900 18901 18902 18903 18904 18905 18906 18907 18908 18909 18910 18911 18912 18913 18914 18915 18916 18917 18918 18919 18920 18921 18922 18923 18924 18925 18926 18927 18928 18929 18930 18931 18932 18933 18934 18935 18936 18937 18938 18939 18940 18941 18942 18943 18944 18945 18946 18947 18948 18949 18950 18951 18952 18953 18954 18955 18956 18957 18958 18959 18960 18961 18962 18963 18964 18965 18966 18967 18968 18969 18970 18971 18972 18973 18974 18975 18976 18977 18978 18979 18980 18981 18982 18983 18984 18985 18986 18987 18988 18989 18990 18991 18992 18993 18994 18995 18996 18997 18998 18999 19000 19001 19002 19003 19004 19005 19006 19007 19008 19009 19010 19011 19012 19013 19014 19015 19016 19017 19018 19019 19020 19021 19022 19023 19024 19025 19026 19027 19028 19029 19030 19031 19032 19033 19034 19035 19036 19037 19038 19039 19040 19041 19042 19043 19044 19045 19046 19047 19048 19049 19050 19051 19052 19053 19054 19055 19056 19057 19058 19059 19060 19061 19062 19063 19064 19065 19066 19067 19068 19069 19070 19071 19072 19073 19074 19075 19076 19077 19078 19079 19080 19081 19082 19083 19084 19085 19086 19087 19088 19089 19090 19091 19092 19093 19094 19095 19096 19097 19098 19099 19100 19101 19102 19103 19104 19105 19106 19107 19108 19109 19110 19111 19112 19113 19114 19115 19116 19117 19118 19119 19120 19121 19122 19123 19124 19125 19126 19127 19128 19129 19130 19131 19132 19133 19134 19135 19136 19137 19138 19139 19140 19141 19142 19143 19144 19145 19146 19147 19148 19149 19150 19151 19152 19153 19154 19155 19156 19157 19158 19159 19160 19161 19162 19163 19164 19165 19166 19167 19168 19169 19170 19171 19172 19173 19174 19175 19176 19177 19178 19179 19180 19181 19182 19183 19184 19185 19186 19187 19188 19189 19190 19191 19192 19193 19194 19195 19196 19197 19198 19199 19200 19201 19202 19203 19204 19205 19206 19207 19208 19209 19210 19211 19212 19213 19214 19215 19216 19217 19218 19219 19220 19221 19222 19223 19224 19225 19226 19227 19228 19229 19230 19231 19232 19233 19234 19235 19236 19237 19238 19239 19240 19241 19242 19243 19244 19245 19246 19247 19248 19249 19250 19251 19252 19253 19254 19255 19256 19257 19258 19259 19260 19261 19262 19263 19264 19265 19266 19267 19268 19269 19270 19271 19272 19273 19274 19275 19276 19277 19278 19279 19280 19281 19282 19283 19284 19285 19286 19287 19288 19289 19290 19291 19292 19293 19294 19295 19296 19297 19298 19299 19300 19301 19302 19303 19304 19305 19306 19307 19308 19309 19310 19311 19312 19313 19314 19315 19316 19317 19318 19319 19320 19321 19322 19323 19324 19325 19326 19327 19328 19329 19330 19331 19332 19333 19334 19335 19336 19337 19338 19339 19340 19341 19342 19343 19344 19345 19346 19347 19348 19349 19350 19351 19352 19353 19354 19355 19356 19357 19358 19359 19360 19361 19362 19363 19364 19365 19366 19367 19368 19369 19370 19371 19372 19373 19374 19375 19376 19377 19378 19379 19380 19381 19382 19383 19384 19385 19386 19387 19388 19389 19390 19391 19392 19393 19394 19395 19396 19397 19398 19399 19400 19401 19402 19403 19404 19405 19406 19407 19408 19409 19410 19411 19412 19413 19414 19415 19416 19417 19418 19419 19420 19421 19422 19423 19424 19425 19426 19427 19428 19429 19430 19431 19432 19433 19434 19435 19436 19437 19438 19439 19440 19441 19442 19443 19444 19445 19446 19447 19448 19449 19450 19451 19452 19453 19454 19455 19456 19457 19458 19459 19460 19461 19462 19463 19464 19465 19466 19467 19468 19469 19470 19471 19472 19473 19474 19475 19476 19477 19478 19479 19480 19481 19482 19483 19484 19485 19486 19487 19488 19489 19490 19491 19492 19493 19494 19495 19496 19497 19498 19499 19500 19501 19502 19503 19504 19505 19506 19507 19508 19509 19510 19511 19512 19513 19514 19515 19516 19517 19518 19519 19520 19521 19522 19523 19524 19525 19526 19527 19528 19529 19530 19531 19532 19533 19534 19535 19536 19537 19538 19539 19540 19541 19542 19543 19544 19545 19546 19547 19548 19549 19550 19551 19552 19553 19554 19555 19556 19557 19558 19559 19560 19561 19562 19563 19564 19565 19566 19567 19568 19569 19570 19571 19572 19573 19574 19575 19576 19577 19578 19579 19580 19581 19582 19583 19584 19585 19586 19587 19588 19589 19590 19591 19592 19593 19594 19595 19596 19597 19598 19599 19600 19601 19602 19603 19604 19605 19606 19607 19608 19609 19610 19611 19612 19613 19614 19615 19616 19617 19618 19619 19620 19621 19622 19623 19624 19625 19626 19627 19628 19629 19630 19631 19632 19633 19634 19635 19636 19637 19638 19639 19640 19641 19642 19643 19644 19645 19646 19647 19648 19649 19650 19651 19652 19653 19654 19655 19656 19657 19658 19659 19660 19661 19662 19663 19664 19665 19666 19667 19668 19669 19670 19671 19672 19673 19674 19675 19676 19677 19678 19679 19680 19681 19682 19683 19684 19685 19686 19687 19688 19689 19690 19691 19692 19693 19694 19695 19696 19697 19698 19699 19700 19701 19702 19703 19704 19705 19706 19707 19708 19709 19710 19711 19712 19713 19714 19715 19716 19717 19718 19719 19720 19721 19722 19723 19724 19725 19726 19727 19728 19729 19730 19731 19732 19733 19734 19735 19736 19737 19738 19739 19740 19741 19742 19743 19744 19745 19746 19747 19748 19749 19750 19751 19752 19753 19754 19755 19756 19757 19758 19759 19760 19761 19762 19763 19764 19765 19766 19767 19768 19769 19770 19771 19772 19773 19774 19775 19776 19777 19778 19779 19780 19781 19782 19783 19784 19785 19786 19787 19788 19789 19790 19791 19792 19793 19794 19795 19796 19797 19798 19799 19800 19801 19802 19803 19804 19805 19806 19807 19808 19809 19810 19811 19812 19813 19814 19815 19816 19817 19818 19819 19820 19821 19822 19823 19824 19825 19826 19827 19828 19829 19830 19831 19832 19833 19834 19835 19836 19837 19838 19839 19840 19841 19842 19843 19844 19845 19846 19847 19848 19849 19850 19851 19852 19853 19854 19855 19856 19857 19858 19859 19860 19861 19862 19863 19864 19865 19866 19867 19868 19869 19870 19871 19872 19873 19874 19875 19876 19877 19878 19879 19880 19881 19882 19883 19884 19885 19886 19887 19888 19889 19890 19891 19892 19893 19894 19895 19896 19897 19898 19899 19900 19901 19902 19903 19904 19905 19906 19907 19908 19909 19910 19911 19912 19913 19914 19915 19916 19917 19918 19919 19920 19921 19922 19923 19924 19925 19926 19927 19928 19929 19930 19931 19932 19933 19934 19935 19936 19937 19938 19939 19940 19941 19942 19943 19944 19945 19946 19947 19948 19949 19950 19951 19952 19953 19954 19955 19956 19957 19958 19959 19960 19961 19962 19963 19964 19965 19966 19967 19968 19969 19970 19971 19972 19973 19974 19975 19976 19977 19978 19979 19980 19981 19982 19983 19984 19985 19986 19987 19988 19989 19990 19991 19992 19993 19994 19995 19996 19997 19998 19999 20000 20001 20002 20003 20004 20005 20006 20007 20008 20009 20010 20011 20012 20013 20014 20015 20016 20017 20018 20019 20020 20021 20022 20023 20024 20025 20026 20027 20028 20029 20030 20031 20032 20033 20034 20035 20036 20037 20038 20039 20040 20041 20042 20043 20044 20045 20046 20047 20048 20049 20050 20051 20052 20053 20054 20055 20056 20057 20058 20059 20060 20061 20062 20063 20064 20065 20066 20067 20068 20069 20070 20071 20072 20073 20074 20075 20076 20077 20078 20079 20080 20081 20082 20083 20084 20085 20086 20087 20088 20089 20090 20091 20092 20093 20094 20095 20096 20097 20098 20099 20100 20101 20102 20103 20104 20105 20106 20107 20108 20109 20110 20111 20112 20113 20114 20115 20116 20117 20118 20119 20120 20121 20122 20123 20124 20125 20126 20127 20128 20129 20130 20131 20132 20133 20134 20135 20136 20137 20138 20139 20140 20141 20142 20143 20144 20145 20146 20147 20148 20149 20150 20151 20152 20153 20154 20155 20156 20157 20158 20159 20160 20161 20162 20163 20164 20165 20166 20167 20168 20169 20170 20171 20172 20173 20174 20175 20176 20177 20178 20179 20180 20181 20182 20183 20184 20185 20186 20187 20188 20189 20190 20191 20192 20193 20194 20195 20196 20197 20198 20199 20200 20201 20202 20203 20204 20205 20206 20207 20208 20209 20210 20211 20212 20213 20214 20215 20216 20217 20218 20219 20220 20221 20222 20223 20224 20225 20226 20227 20228 20229 20230 20231 20232 20233 20234 20235 20236 20237 20238 20239 20240 20241 20242 20243 20244 20245 20246 20247 20248 20249 20250 20251 20252 20253 20254 20255 20256 20257 20258 20259 20260 20261 20262 20263 20264 20265 20266 20267 20268 20269 20270 20271 20272 20273 20274 20275 20276 20277 20278 20279 20280 20281 20282 20283 20284 20285 20286 20287 20288 20289 20290 20291 20292 20293 20294 20295 20296 20297 20298 20299 20300 20301 20302 20303 20304 20305 20306 20307 20308 20309 20310 20311 20312 20313 20314 20315 20316 20317 20318 20319 20320 20321 20322 20323 20324 20325 20326 20327 20328 20329 20330 20331 20332 20333 20334 20335 20336 20337 20338 20339 20340 20341 20342 20343 20344 20345 20346 20347 20348 20349 20350 20351 20352 20353 20354 20355 20356 20357 20358 20359 20360 20361 20362 20363 20364 20365 20366 20367 20368 20369 20370 20371 20372 20373 20374 20375 20376 20377 20378 20379 20380 20381 20382 20383 20384 20385 20386 20387 20388 20389 20390 20391 20392 20393 20394 20395 20396 20397 20398 20399 20400 20401 20402 20403 20404 20405 20406 20407 20408 20409 20410 20411 20412 20413 20414 20415 20416 20417 20418 20419 20420 20421 20422 20423 20424 20425 20426 20427 20428 20429 20430 20431 20432 20433 20434 20435 20436 20437 20438 20439 20440 20441 20442 20443 20444 20445 20446 20447 20448 20449 20450 20451 20452 20453 20454 20455 20456 20457 20458 20459 20460 20461 20462 20463 20464 20465 20466 20467 20468 20469 20470 20471 20472 20473 20474 20475 20476 20477 20478 20479 20480 20481 20482 20483 20484 20485 20486 20487 20488 20489 20490 20491 20492 20493 20494 20495 20496 20497 20498 20499 20500 20501 20502 20503 20504 20505 20506 20507 20508 20509 20510 20511 20512 20513 20514 20515 20516 20517 20518 20519 20520 20521 20522 20523 20524 20525 20526 20527 20528 20529 20530 20531 20532 20533 20534 20535 20536 20537 20538 20539 20540 20541 20542 20543 20544 20545 20546 20547 20548 20549 20550 20551 20552 20553 20554 20555 20556 20557 20558 20559 20560 20561 20562 20563 20564 20565 20566 20567 20568 20569 20570 20571 20572 20573 20574 20575 20576 20577 20578 20579 20580 20581 20582 20583 20584 20585 20586 20587 20588 20589 20590 20591 20592 20593 20594 20595 20596 20597 20598 20599 20600 20601 20602 20603 20604 20605 20606 20607 20608 20609 20610 20611 20612 20613 20614 20615 20616 20617 20618 20619 20620 20621 20622 20623 20624 20625 20626 20627 20628 20629 20630 20631 20632 20633 20634 20635 20636 20637 20638 20639 20640 20641 20642 20643 20644 20645 20646 20647 20648 20649 20650 20651 20652 20653 20654 20655 20656 20657 20658 20659 20660 20661 20662 20663 20664 20665 20666 20667 20668 20669 20670 20671 20672 20673 20674 20675 20676 20677 20678 20679 20680 20681 20682 20683 20684 20685 20686 20687 20688 20689 20690 20691 20692 20693 20694 20695 20696 20697 20698 20699 20700 20701 20702 20703 20704 20705 20706 20707 20708 20709 20710 20711 20712 20713 20714 20715 20716 20717 20718 20719 20720 20721 20722 20723 20724 20725 20726 20727 20728 20729 20730 20731 20732 20733 20734 20735 20736 20737 20738 20739 20740 20741 20742 20743 20744 20745 20746 20747 20748 20749 20750 20751 20752 20753 20754 20755 20756 20757 20758 20759 20760 20761 20762 20763 20764 20765 20766 20767 20768 20769 20770 20771 20772 20773 20774 20775 20776 20777 20778 20779 20780 20781 20782 20783 20784 20785 20786 20787 20788 20789 20790 20791 20792 20793 20794 20795 20796 20797 20798 20799 20800 20801 20802 20803 20804 20805 20806 20807 20808 20809 20810 20811 20812 20813 20814 20815 20816 20817 20818 20819 20820 20821 20822 20823 20824 20825 20826 20827 20828 20829 20830 20831 20832 20833 20834 20835 20836 20837 20838 20839 20840 20841 20842 20843 20844 20845 20846 20847 20848 20849 20850 20851 20852 20853 20854 20855 20856 20857 20858 20859 20860 20861 20862 20863 20864 20865 20866 20867 20868 20869 20870 20871 20872 20873 20874 20875 20876 20877 20878 20879 20880 20881 20882 20883 20884 20885 20886 20887 20888 20889 20890 20891 20892 20893 20894 20895 20896 20897 20898 20899 20900 20901 20902 20903 20904 20905 20906 20907 20908 20909 20910 20911 20912 20913 20914 20915 20916 20917 20918 20919 20920 20921 20922 20923 20924 20925 20926 20927 20928 20929 20930 20931 20932 20933 20934 20935 20936 20937 20938 20939 20940 20941 20942 20943 20944 20945 20946 20947 20948 20949 20950 20951 20952 20953 20954 20955 20956 20957 20958 20959 20960 20961 20962 20963 20964 20965 20966 20967 20968 20969 20970 20971 20972 20973 20974 20975 20976 20977 20978 20979 20980 20981 20982 20983 20984 20985 20986 20987 20988 20989 20990 20991 20992 20993 20994 20995 20996 20997 20998 20999 21000 21001 21002 21003 21004 21005 21006 21007 21008 21009 21010 21011 21012 21013 21014 21015 21016 21017 21018 21019 21020 21021 21022 21023 21024 21025 21026 21027 21028 21029 21030 21031 21032 21033 21034 21035 21036 21037 21038 21039 21040 21041 21042 21043 21044 21045 21046 21047 21048 21049 21050 21051 21052 21053 21054 21055 21056 21057 21058 21059 21060 21061 21062 21063 21064 21065 21066 21067 21068 21069 21070 21071 21072 21073 21074 21075 21076 21077 21078 21079 21080 21081 21082 21083 21084 21085 21086 21087 21088 21089 21090 21091 21092 21093 21094 21095 21096 21097 21098 21099 21100 21101 21102 21103 21104 21105 21106 21107 21108 21109 21110 21111 21112 21113 21114 21115 21116 21117 21118 21119 21120 21121 21122 21123 21124 21125 21126 21127 21128 21129 21130 21131 21132 21133 21134 21135 21136 21137 21138 21139 21140 21141 21142 21143 21144 21145 21146 21147 21148 21149 21150 21151 21152 21153 21154 21155 21156 21157 21158 21159 21160 21161 21162 21163 21164 21165 21166 21167 21168 21169 21170 21171 21172 21173 21174 21175 21176 21177 21178 21179 21180 21181 21182 21183 21184 21185 21186 21187 21188 21189 21190 21191 21192 21193 21194 21195 21196 21197 21198 21199 21200 21201 21202 21203 21204 21205 21206 21207 21208 21209 21210 21211 21212 21213 21214 21215 21216 21217 21218 21219 21220 21221 21222 21223 21224 21225 21226 21227 21228 21229 21230 21231 21232 21233 21234 21235 21236 21237 21238 21239 21240 21241 21242 21243 21244 21245 21246 21247 21248 21249 21250 21251 21252 21253 21254 21255 21256 21257 21258 21259 21260 21261 21262 21263 21264 21265 21266 21267 21268 21269 21270 21271 21272 21273 21274 21275 21276 21277 21278 21279 21280 21281 21282 21283 21284 21285 21286 21287 21288 21289 21290 21291 21292 21293 21294 21295 21296 21297 21298 21299 21300 21301 21302 21303 21304 21305 21306 21307 21308 21309 21310 21311 21312 21313 21314 21315 21316 21317 21318 21319 21320 21321 21322 21323 21324 21325 21326 21327 21328 21329 21330 21331 21332 21333 21334 21335 21336 21337 21338 21339 21340 21341 21342 21343 21344 21345 21346 21347 21348 21349 21350 21351 21352 21353 21354 21355 21356 21357 21358 21359 21360 21361 21362 21363 21364 21365 21366 21367 21368 21369 21370 21371 21372 21373 21374 21375 21376 21377 21378 21379 21380 21381 21382 21383 21384 21385 21386 21387 21388 21389 21390 21391 21392 21393 21394 21395 21396 21397 21398 21399 21400 21401 21402 21403 21404 21405 21406 21407 21408 21409 21410 21411 21412 21413 21414 21415 21416 21417 21418 21419 21420 21421 21422 21423 21424 21425 21426 21427 21428 21429 21430 21431 21432 21433 21434 21435 21436 21437 21438 21439 21440 21441 21442 21443 21444 21445 21446 21447 21448 21449 21450 21451 21452 21453 21454 21455 21456 21457 21458 21459 21460 21461 21462 21463 21464 21465 21466 21467 21468 21469 21470 21471 21472 21473 21474 21475 21476 21477 21478 21479 21480 21481 21482 21483 21484 21485 21486 21487 21488 21489 21490 21491 21492 21493 21494 21495 21496 21497 21498 21499 21500 21501 21502 21503 21504 21505 21506 21507 21508 21509 21510 21511 21512 21513 21514 21515 21516 21517 21518 21519 21520 21521 21522 21523 21524 21525 21526 21527 21528 21529 21530 21531 21532 21533 21534 21535 21536 21537 21538 21539 21540 21541 21542 21543 21544 21545 21546 21547 21548 21549 21550 21551 21552 21553 21554 21555 21556 21557 21558 21559 21560 21561 21562 21563 21564 21565 21566 21567 21568 21569 21570 21571 21572 21573 21574 21575 21576 21577 21578 21579 21580 21581 21582 21583 21584 21585 21586 21587 21588 21589 21590 21591 21592 21593 21594 21595 21596 21597 21598 21599 21600 21601 21602 21603 21604 21605 21606 21607 21608 21609 21610 21611 21612 21613 21614 21615 21616 21617 21618 21619 21620 21621 21622 21623 21624 21625 21626 21627 21628 21629 21630 21631 21632 21633 21634 21635 21636 21637 21638 21639 21640 21641 21642 21643 21644 21645 21646 21647 21648 21649 21650 21651 21652 21653 21654 21655 21656 21657 21658 21659 21660 21661 21662 21663 21664 21665 21666 21667 21668 21669 21670 21671 21672 21673 21674 21675 21676 21677 21678 21679 21680 21681 21682 21683 21684 21685 21686 21687 21688 21689 21690 21691 21692 21693 21694 21695 21696 21697 21698 21699 21700 21701 21702 21703 21704 21705 21706 21707 21708 21709 21710 21711 21712 21713 21714 21715 21716 21717 21718 21719 21720 21721 21722 21723 21724 21725 21726 21727 21728 21729 21730 21731 21732 21733 21734 21735 21736 21737 21738 21739 21740 21741 21742 21743 21744 21745 21746 21747 21748 21749 21750 21751 21752 21753 21754 21755 21756 21757 21758 21759 21760 21761 21762 21763 21764 21765 21766 21767 21768 21769 21770 21771 21772 21773 21774 21775 21776 21777 21778 21779 21780 21781 21782 21783 21784 21785 21786 21787 21788 21789 21790 21791 21792 21793 21794 21795 21796 21797 21798 21799 21800 21801 21802 21803 21804 21805 21806 21807 21808 21809 21810 21811 21812 21813 21814 21815 21816 21817 21818 21819 21820 21821 21822 21823 21824 21825 21826 21827 21828 21829 21830 21831 21832 21833 21834 21835 21836 21837 21838 21839 21840 21841 21842 21843 21844 21845 21846 21847 21848 21849 21850 21851 21852 21853 21854 21855 21856 21857 21858 21859 21860 21861 21862 21863 21864 21865 21866 21867 21868 21869 21870 21871 21872 21873 21874 21875 21876 21877 21878 21879 21880 21881 21882 21883 21884 21885 21886 21887 21888 21889 21890 21891 21892 21893 21894 21895 21896 21897 21898 21899 21900 21901 21902 21903 21904 21905 21906 21907 21908 21909 21910 21911 21912 21913 21914 21915 21916 21917 21918 21919 21920 21921 21922 21923 21924 21925 21926 21927 21928 21929 21930 21931 21932 21933 21934 21935 21936 21937 21938 21939 21940 21941 21942 21943 21944 21945 21946 21947 21948 21949 21950 21951 21952 21953 21954 21955 21956 21957 21958 21959 21960 21961 21962 21963 21964 21965 21966 21967 21968 21969 21970 21971 21972 21973 21974 21975 21976 21977 21978 21979 21980 21981 21982 21983 21984 21985 21986 21987 21988 21989 21990 21991 21992 21993 21994 21995 21996 21997 21998 21999 22000 22001 22002 22003 22004 22005 22006 22007 22008 22009 22010 22011 22012 22013 22014 22015 22016 22017 22018 22019 22020 22021 22022 22023 22024 22025 22026 22027 22028 22029 22030 22031 22032 22033 22034 22035 22036 22037 22038 22039 22040 22041 22042 22043 22044 22045 22046 22047 22048 22049 22050 22051 22052 22053 22054 22055 22056 22057 22058 22059 22060 22061 22062 22063 22064 22065 22066 22067 22068 22069 22070 22071 22072 22073 22074 22075 22076 22077 22078 22079 22080 22081 22082 22083 22084 22085 22086 22087 22088 22089 22090 22091 22092 22093 22094 22095 22096 22097 22098 22099 22100 22101 22102 22103 22104 22105 22106 22107 22108 22109 22110 22111 22112 22113 22114 22115 22116 22117 22118 22119 22120 22121 22122 22123 22124 22125 22126 22127 22128 22129 22130 22131 22132 22133 22134 22135 22136 22137 22138 22139 22140 22141 22142 22143 22144 22145 22146 22147 22148 22149 22150 22151 22152 22153 22154 22155 22156 22157 22158 22159 22160 22161 22162 22163 22164 22165 22166 22167 22168 22169 22170 22171 22172 22173 22174 22175 22176 22177 22178 22179 22180 22181 22182 22183 22184 22185 22186 22187 22188 22189 22190 22191 22192 22193 22194 22195 22196 22197 22198 22199 22200 22201 22202 22203 22204 22205 22206 22207 22208 22209 22210 22211 22212 22213 22214 22215 22216 22217 22218 22219 22220 22221 22222 22223 22224 22225 22226 22227 22228 22229 22230 22231 22232 22233 22234 22235 22236 22237 22238 22239 22240 22241 22242 22243 22244 22245 22246 22247 22248 22249 22250 22251 22252 22253 22254 22255 22256 22257 22258 22259 22260 22261 22262 22263 22264 22265 22266 22267 22268 22269 22270 22271 22272 22273 22274 22275 22276 22277 22278 22279 22280 22281 22282 22283 22284 22285 22286 22287 22288 22289 22290 22291 22292 22293 22294 22295 22296 22297 22298 22299 22300 22301 22302 22303 22304 22305 22306 22307 22308 22309 22310 22311 22312 22313 22314 22315 22316 22317 22318 22319 22320 22321 22322 22323 22324 22325 22326 22327 22328 22329 22330 22331 22332 22333 22334 22335 22336 22337 22338 22339 22340 22341 22342 22343 22344 22345 22346 22347 22348 22349 22350 22351 22352 22353 22354 22355 22356 22357 22358 22359 22360 22361 22362 22363 22364 22365 22366 22367 22368 22369 22370 22371 22372 22373 22374 22375 22376 22377 22378 22379 22380 22381 22382 22383 22384 22385 22386 22387 22388 22389 22390 22391 22392 22393 22394 22395 22396 22397 22398 22399 22400 22401 22402 22403 22404 22405 22406 22407 22408 22409 22410 22411 22412 22413 22414 22415 22416 22417 22418 22419 22420 22421 22422 22423 22424 22425 22426 22427 22428 22429 22430 22431 22432 22433 22434 22435 22436 22437 22438 22439 22440 22441 22442 22443 22444 22445 22446 22447 22448 22449 22450 22451 22452 22453 22454 22455 22456 22457 22458 22459 22460 22461 22462 22463 22464 22465 22466 22467 22468 22469 22470 22471 22472 22473 22474 22475 22476 22477 22478 22479 22480 22481 22482 22483 22484 22485 22486 22487 22488 22489 22490 22491 22492 22493 22494 22495 22496 22497 22498 22499 22500 22501 22502 22503 22504 22505 22506 22507 22508 22509 22510 22511 22512 22513 22514 22515 22516 22517 22518 22519 22520 22521 22522 22523 22524 22525 22526 22527 22528 22529 22530 22531 22532 22533 22534 22535 22536 22537 22538 22539 22540 22541 22542 22543 22544 22545 22546 22547 22548 22549 22550 22551 22552 22553 22554 22555 22556 22557 22558 22559 22560 22561 22562 22563 22564 22565 22566 22567 22568 22569 22570 22571 22572 22573 22574 22575 22576 22577 22578 22579 22580 22581 22582 22583 22584 22585 22586 22587 22588 22589 22590 22591 22592 22593 22594 22595 22596 22597 22598 22599 22600 22601 22602 22603 22604 22605 22606 22607 22608 22609 22610 22611 22612 22613 22614 22615 22616 22617 22618 22619 22620 22621 22622 22623 22624 22625 22626 22627 22628 22629 22630 22631 22632 22633 22634 22635 22636 22637 22638 22639 22640 22641 22642 22643 22644 22645 22646 22647 22648 22649 22650 22651 22652 22653 22654 22655 22656 22657 22658 22659 22660 22661 22662 22663 22664 22665 22666 22667 22668 22669 22670 22671 22672 22673 22674 22675 22676 22677 22678 22679 22680 22681 22682 22683 22684 22685 22686 22687 22688 22689 22690 22691 22692 22693 22694 22695 22696 22697 22698 22699 22700 22701 22702 22703 22704 22705 22706 22707 22708 22709 22710 22711 22712 22713 22714 22715 22716 22717 22718 22719 22720 22721 22722 22723 22724 22725 22726 22727 22728 22729 22730 22731 22732 22733 22734 22735 22736 22737 22738 22739 22740 22741 22742 22743 22744 22745 22746 22747 22748 22749 22750 22751 22752 22753 22754 22755 22756 22757 22758 22759 22760 22761 22762 22763 22764 22765 22766 22767 22768 22769 22770 22771 22772 22773 22774 22775 22776 22777 22778 22779 22780 22781 22782 22783 22784 22785 22786 22787 22788 22789 22790 22791 22792 22793 22794 22795 22796 22797 22798 22799 22800 22801 22802 22803 22804 22805 22806 22807 22808 22809 22810 22811 22812 22813 22814 22815 22816 22817 22818 22819 22820 22821 22822 22823 22824 22825 22826 22827 22828 22829 22830 22831 22832 22833 22834 22835 22836 22837 22838 22839 22840 22841 22842 22843 22844 22845 22846 22847 22848 22849 22850 22851 22852 22853 22854 22855 22856 22857 22858 22859 22860 22861 22862 22863 22864 22865 22866 22867 22868 22869 22870 22871 22872 22873 22874 22875 22876 22877 22878 22879 22880 22881 22882 22883 22884 22885 22886 22887 22888 22889 22890 22891 22892 22893 22894 22895 22896 22897 22898 22899 22900 22901 22902 22903 22904 22905 22906 22907 22908 22909 22910 22911 22912 22913 22914 22915 22916 22917 22918 22919 22920 22921 22922 22923 22924 22925 22926 22927 22928 22929 22930 22931 22932 22933 22934 22935 22936 22937 22938 22939 22940 22941 22942 22943 22944 22945 22946 22947 22948 22949 22950 22951 22952 22953 22954 22955 22956 22957 22958 22959 22960 22961 22962 22963 22964 22965 22966 22967 22968 22969 22970 22971 22972 22973 22974 22975 22976 22977 22978 22979 22980 22981 22982 22983 22984 22985 22986 22987 22988 22989 22990 22991 22992 22993 22994 22995 22996 22997 22998 22999 23000 23001 23002 23003 23004 23005 23006 23007 23008 23009 23010 23011 23012 23013 23014 23015 23016 23017 23018 23019 23020 23021 23022 23023 23024 23025 23026 23027 23028 23029 23030 23031 23032 23033 23034 23035 23036 23037 23038 23039 23040 23041 23042 23043 23044 23045 23046 23047 23048 23049 23050 23051 23052 23053 23054 23055 23056 23057 23058 23059 23060 23061 23062 23063 23064 23065 23066 23067 23068 23069 23070 23071 23072 23073 23074 23075 23076 23077 23078 23079 23080 23081 23082 23083 23084 23085 23086 23087 23088 23089 23090 23091 23092 23093 23094 23095 23096 23097 23098 23099 23100 23101 23102 23103 23104 23105 23106 23107 23108 23109 23110 23111 23112 23113 23114 23115 23116 23117 23118 23119 23120 23121 23122 23123 23124 23125 23126 23127 23128 23129 23130 23131 23132 23133 23134 23135 23136 23137 23138 23139 23140 23141 23142 23143 23144 23145 23146 23147 23148 23149 23150 23151 23152 23153 23154 23155 23156 23157 23158 23159 23160 23161 23162 23163 23164 23165 23166 23167 23168 23169 23170 23171 23172 23173 23174 23175 23176 23177 23178 23179 23180 23181 23182 23183 23184 23185 23186 23187 23188 23189 23190 23191 23192 23193 23194 23195 23196 23197 23198 23199 23200 23201 23202 23203 23204 23205 23206 23207 23208 23209 23210 23211 23212 23213 23214 23215 23216 23217 23218 23219 23220 23221 23222 23223 23224 23225 23226 23227 23228 23229 23230 23231 23232 23233 23234 23235 23236 23237 23238 23239 23240 23241 23242 23243 23244 23245 23246 23247 23248 23249 23250 23251 23252 23253 23254 23255 23256 23257 23258 23259 23260 23261 23262 23263 23264 23265 23266 23267 23268 23269 23270 23271 23272 23273 23274 23275 23276 23277 23278 23279 23280 23281 23282 23283 23284 23285 23286 23287 23288 23289 23290 23291 23292 23293 23294 23295 23296 23297 23298 23299 23300 23301 23302 23303 23304 23305 23306 23307 23308 23309 23310 23311 23312 23313 23314 23315 23316 23317 23318 23319 23320 23321 23322 23323 23324 23325 23326 23327 23328 23329 23330 23331 23332 23333 23334 23335 23336 23337 23338 23339 23340 23341 23342 23343 23344 23345 23346 23347 23348 23349 23350 23351 23352 23353 23354 23355 23356 23357 23358 23359 23360 23361 23362 23363 23364 23365 23366 23367 23368 23369 23370 23371 23372 23373 23374 23375 23376 23377 23378 23379 23380 23381 23382 23383 23384 23385 23386 23387 23388 23389 23390 23391 23392 23393 23394 23395 23396 23397 23398 23399 23400 23401 23402 23403 23404 23405 23406 23407 23408 23409 23410 23411 23412 23413 23414 23415 23416 23417 23418 23419 23420 23421 23422 23423 23424 23425 23426 23427 23428 23429 23430 23431 23432 23433 23434 23435 23436 23437 23438 23439 23440 23441 23442 23443 23444 23445 23446 23447 23448 23449 23450 23451 23452 23453 23454 23455 23456 23457 23458 23459 23460 23461 23462 23463 23464 23465 23466 23467 23468 23469 23470 23471 23472 23473 23474 23475 23476 23477 23478 23479 23480 23481 23482 23483 23484 23485 23486 23487 23488 23489 23490 23491 23492 23493 23494 23495 23496 23497 23498 23499 23500 23501 23502 23503 23504 23505 23506 23507 23508 23509 23510 23511 23512 23513 23514 23515 23516 23517 23518 23519 23520 23521 23522 23523 23524 23525 23526 23527 23528 23529 23530 23531 23532 23533 23534 23535 23536 23537 23538 23539 23540 23541 23542 23543 23544 23545 23546 23547 23548 23549 23550 23551 23552 23553 23554 23555 23556 23557 23558 23559 23560 23561 23562 23563 23564 23565 23566 23567 23568 23569 23570 23571 23572 23573 23574 23575 23576 23577 23578 23579 23580 23581 23582 23583 23584 23585 23586 23587 23588 23589 23590 23591 23592 23593 23594 23595 23596 23597 23598 23599 23600 23601 23602 23603 23604 23605 23606 23607 23608 23609 23610 23611 23612 23613 23614 23615 23616 23617 23618 23619 23620 23621 23622 23623 23624 23625 23626 23627 23628 23629 23630 23631 23632 23633 23634 23635 23636 23637 23638 23639 23640 23641 23642 23643 23644 23645 23646 23647 23648 23649 23650 23651 23652 23653 23654 23655 23656 23657 23658 23659 23660 23661 23662 23663 23664 23665 23666 23667 23668 23669 23670 23671 23672 23673 23674 23675 23676 23677 23678 23679 23680 23681 23682 23683 23684 23685 23686 23687 23688 23689 23690 23691 23692 23693 23694 23695 23696 23697 23698 23699 23700 23701 23702 23703 23704 23705 23706 23707 23708 23709 23710 23711 23712 23713 23714 23715 23716 23717 23718 23719 23720 23721 23722 23723 23724 23725 23726 23727 23728 23729 23730 23731 23732 23733 23734 23735 23736 23737 23738 23739 23740 23741 23742 23743 23744 23745 23746 23747 23748 23749 23750 23751 23752 23753 23754 23755 23756 23757 23758 23759 23760 23761 23762 23763 23764 23765 23766 23767 23768 23769 23770 23771 23772 23773 23774 23775 23776 23777 23778 23779 23780 23781 23782 23783 23784 23785 23786 23787 23788 23789 23790 23791 23792 23793 23794 23795 23796 23797 23798 23799 23800 23801 23802 23803 23804 23805 23806 23807 23808 23809 23810 23811 23812 23813 23814 23815 23816 23817 23818 23819 23820 23821 23822 23823 23824 23825 23826 23827 23828 23829 23830 23831 23832 23833 23834 23835 23836 23837 23838 23839 23840 23841 23842 23843 23844 23845 23846 23847 23848 23849 23850 23851 23852 23853 23854 23855 23856 23857 23858 23859 23860 23861 23862 23863 23864 23865 23866 23867 23868 23869 23870 23871 23872 23873 23874 23875 23876 23877 23878 23879 23880 23881 23882 23883 23884 23885 23886 23887 23888 23889 23890 23891 23892 23893 23894 23895 23896 23897 23898 23899 23900 23901 23902 23903 23904 23905 23906 23907 23908 23909 23910 23911 23912 23913 23914 23915 23916 23917 23918 23919 23920 23921 23922 23923 23924 23925 23926 23927 23928 23929 23930 23931 23932 23933 23934 23935 23936 23937 23938 23939 23940 23941 23942 23943 23944 23945 23946 23947 23948 23949 23950 23951 23952 23953 23954 23955 23956 23957 23958 23959 23960 23961 23962 23963 23964 23965 23966 23967 23968 23969 23970 23971 23972 23973 23974 23975 23976 23977 23978 23979 23980 23981 23982 23983 23984 23985 23986 23987 23988 23989 23990 23991 23992 23993 23994 23995 23996 23997 23998 23999 24000 24001 24002 24003 24004 24005 24006 24007 24008 24009 24010 24011 24012 24013 24014 24015 24016 24017 24018 24019 24020 24021 24022 24023 24024 24025 24026 24027 24028 24029 24030 24031 24032 24033 24034 24035 24036 24037 24038 24039 24040 24041 24042 24043 24044 24045 24046 24047 24048 24049 24050 24051 24052 24053 24054 24055 24056 24057 24058 24059 24060 24061 24062 24063 24064 24065 24066 24067 24068 24069 24070 24071 24072 24073 24074 24075 24076 24077 24078 24079 24080 24081 24082 24083 24084 24085 24086 24087 24088 24089 24090 24091 24092 24093 24094 24095 24096 24097 24098 24099 24100 24101 24102 24103 24104 24105 24106 24107 24108 24109 24110 24111 24112 24113 24114 24115 24116 24117 24118 24119 24120 24121 24122 24123 24124 24125 24126 24127 24128 24129 24130 24131 24132 24133 24134 24135 24136 24137 24138 24139 24140 24141 24142 24143 24144 24145 24146 24147 24148 24149 24150 24151 24152 24153 24154 24155 24156 24157 24158 24159 24160 24161 24162 24163 24164 24165 24166 24167 24168 24169 24170 24171 24172 24173 24174 24175 24176 24177 24178 24179 24180 24181 24182 24183 24184 24185 24186 24187 24188 24189 24190 24191 24192 24193 24194 24195 24196 24197 24198 24199 24200 24201 24202 24203 24204 24205 24206 24207 24208 24209 24210 24211 24212 24213 24214 24215 24216 24217 24218 24219 24220 24221 24222 24223 24224 24225 24226 24227 24228 24229 24230 24231 24232 24233 24234 24235 24236 24237 24238 24239 24240 24241 24242 24243 24244 24245 24246 24247 24248 24249 24250 24251 24252 24253 24254 24255 24256 24257 24258 24259 24260 24261 24262 24263 24264 24265 24266 24267 24268 24269 24270 24271 24272 24273 24274 24275 24276 24277 24278 24279 24280 24281 24282 24283 24284 24285 24286 24287 24288 24289 24290 24291 24292 24293 24294 24295 24296 24297 24298 24299 24300 24301 24302 24303 24304 24305 24306 24307 24308 24309 24310 24311 24312 24313 24314 24315 24316 24317 24318 24319 24320 24321 24322 24323 24324 24325 24326 24327 24328 24329 24330 24331 24332 24333 24334 24335 24336 24337 24338 24339 24340 24341 24342 24343 24344 24345 24346 24347 24348 24349 24350 24351 24352 24353 24354 24355 24356 24357 24358 24359 24360 24361 24362 24363 24364 24365 24366 24367 24368 24369 24370 24371 24372 24373 24374 24375 24376 24377 24378 24379 24380 24381 24382 24383 24384 24385 24386 24387 24388 24389 24390 24391 24392 24393 24394 24395 24396 24397 24398 24399 24400 24401 24402 24403 24404 24405 24406 24407 24408 24409 24410 24411 24412 24413 24414 24415 24416 24417 24418 24419 24420 24421 24422 24423 24424 24425 24426 24427 24428 24429 24430 24431 24432 24433 24434 24435 24436 24437 24438 24439 24440 24441 24442 24443 24444 24445 24446 24447 24448 24449 24450 24451 24452 24453 24454 24455 24456 24457 24458 24459 24460 24461 24462 24463 24464 24465 24466 24467 24468 24469 24470 24471 24472 24473 24474 24475 24476 24477 24478 24479 24480 24481 24482 24483 24484 24485 24486 24487 24488 24489 24490 24491 24492 24493 24494 24495 24496 24497 24498 24499 24500 24501 24502 24503 24504 24505 24506 24507 24508 24509 24510 24511 24512 24513 24514 24515 24516 24517 24518 24519 24520 24521 24522 24523 24524 24525 24526 24527 24528 24529 24530 24531 24532 24533 24534 24535 24536 24537 24538 24539 24540 24541 24542 24543 24544 24545 24546 24547 24548 24549 24550 24551 24552 24553 24554 24555 24556 24557 24558 24559 24560 24561 24562 24563 24564 24565 24566 24567 24568 24569 24570 24571 24572 24573 24574 24575 24576 24577 24578 24579 24580 24581 24582 24583 24584 24585 24586 24587 24588 24589 24590 24591 24592 24593 24594 24595 24596 24597 24598 24599 24600 24601 24602 24603 24604 24605 24606 24607 24608 24609 24610 24611 24612 24613 24614 24615 24616 24617 24618 24619 24620 24621 24622 24623 24624 24625 24626 24627 24628 24629 24630 24631 24632 24633 24634 24635 24636 24637 24638 24639 24640 24641 24642 24643 24644 24645 24646 24647 24648 24649 24650 24651 24652 24653 24654 24655 24656 24657 24658 24659 24660 24661 24662 24663 24664 24665 24666 24667 24668 24669 24670 24671 24672 24673 24674 24675 24676 24677 24678 24679 24680 24681 24682 24683 24684 24685 24686 24687 24688 24689 24690 24691 24692 24693 24694 24695 24696 24697 24698 24699 24700 24701 24702 24703 24704 24705 24706 24707 24708 24709 24710 24711 24712 24713 24714 24715 24716 24717 24718 24719 24720 24721 24722 24723 24724 24725 24726 24727 24728 24729 24730 24731 24732 24733 24734 24735 24736 24737 24738 24739 24740 24741 24742 24743 24744 24745 24746 24747 24748 24749 24750 24751 24752 24753 24754 24755 24756 24757 24758 24759 24760 24761 24762 24763 24764 24765 24766 24767 24768 24769 24770 24771 24772 24773 24774 24775 24776 24777 24778 24779 24780 24781 24782 24783 24784 24785 24786 24787 24788 24789 24790 24791 24792 24793 24794 24795 24796 24797 24798 24799 24800 24801 24802 24803 24804 24805 24806 24807 24808 24809 24810 24811 24812 24813 24814 24815 24816 24817 24818 24819 24820 24821 24822 24823 24824 24825 24826 24827 24828 24829 24830 24831 24832 24833 24834 24835 24836 24837 24838 24839 24840 24841 24842 24843 24844 24845 24846 24847 24848 24849 24850 24851 24852 24853 24854 24855 24856 24857 24858 24859 24860 24861 24862 24863 24864 24865 24866 24867 24868 24869 24870 24871 24872 24873 24874 24875 24876 24877 24878 24879 24880 24881 24882 24883 24884 24885 24886 24887 24888 24889 24890 24891 24892 24893 24894 24895 24896 24897 24898 24899 24900 24901 24902 24903 24904 24905 24906 24907 24908 24909 24910 24911 24912 24913 24914 24915 24916 24917 24918 24919 24920 24921 24922 24923 24924 24925 24926 24927 24928 24929 24930 24931 24932 24933 24934 24935 24936 24937 24938 24939 24940 24941 24942 24943 24944 24945 24946 24947 24948 24949 24950 24951 24952 24953 24954 24955 24956 24957 24958 24959 24960 24961 24962 24963 24964 24965 24966 24967 24968 24969 24970 24971 24972 24973 24974 24975 24976 24977 24978 24979 24980 24981 24982 24983 24984 24985 24986 24987 24988 24989 24990 24991 24992 24993 24994 24995 24996 24997 24998 24999 25000 25001 25002 25003 25004 25005 25006 25007 25008 25009 25010 25011 25012 25013 25014 25015 25016 25017 25018 25019 25020 25021 25022 25023 25024 25025 25026 25027 25028 25029 25030 25031 25032 25033 25034 25035 25036 25037 25038 25039 25040 25041 25042 25043 25044 25045 25046 25047 25048 25049 25050 25051 25052 25053 25054 25055 25056 25057 25058 25059 25060 25061 25062 25063 25064 25065 25066 25067 25068 25069 25070 25071 25072 25073 25074 25075 25076 25077 25078 25079 25080 25081 25082 25083 25084 25085 25086 25087 25088 25089 25090 25091 25092 25093 25094 25095 25096 25097 25098 25099 25100 25101 25102 25103 25104 25105 25106 25107 25108 25109 25110 25111 25112 25113 25114 25115 25116 25117 25118 25119 25120 25121 25122 25123 25124 25125 25126 25127 25128 25129 25130 25131 25132 25133 25134 25135 25136 25137 25138 25139 25140 25141 25142 25143 25144 25145 25146 25147 25148 25149 25150 25151 25152 25153 25154 25155 25156 25157 25158 25159 25160 25161 25162 25163 25164 25165 25166 25167 25168 25169 25170 25171 25172 25173 25174 25175 25176 25177 25178 25179 25180 25181 25182 25183 25184 25185 25186 25187 25188 25189 25190 25191 25192 25193 25194 25195 25196 25197 25198 25199 25200 25201 25202 25203 25204 25205 25206 25207 25208 25209 25210 25211 25212 25213 25214 25215 25216 25217 25218 25219 25220 25221 25222 25223 25224 25225 25226 25227 25228 25229 25230 25231 25232 25233 25234 25235 25236 25237 25238 25239 25240 25241 25242 25243 25244 25245 25246 25247 25248 25249 25250 25251 25252 25253 25254 25255 25256 25257 25258 25259 25260 25261 25262 25263 25264 25265 25266 25267 25268 25269 25270 25271 25272 25273 25274 25275 25276 25277 25278 25279 25280 25281 25282 25283 25284 25285 25286 25287 25288 25289 25290 25291 25292 25293 25294 25295 25296 25297 25298 25299 25300 25301 25302 25303 25304 25305 25306 25307 25308 25309 25310 25311 25312 25313 25314 25315 25316 25317 25318 25319 25320 25321 25322 25323 25324 25325 25326 25327 25328 25329 25330 25331 25332 25333 25334 25335 25336 25337 25338 25339 25340 25341 25342 25343 25344 25345 25346 25347 25348 25349 25350 25351 25352 25353 25354 25355 25356 25357 25358 25359 25360 25361 25362 25363 25364 25365 25366 25367 25368 25369 25370 25371 25372 25373 25374 25375 25376 25377 25378 25379 25380 25381 25382 25383 25384 25385 25386 25387 25388 25389 25390 25391 25392 25393 25394 25395 25396 25397 25398 25399 25400 25401 25402 25403 25404 25405 25406 25407 25408 25409 25410 25411 25412 25413 25414 25415 25416 25417 25418 25419 25420 25421 25422 25423 25424 25425 25426 25427 25428 25429 25430 25431 25432 25433 25434 25435 25436 25437 25438 25439 25440 25441 25442 25443 25444 25445 25446 25447 25448 25449 25450 25451 25452 25453 25454 25455 25456 25457 25458 25459 25460 25461 25462 25463 25464 25465 25466 25467 25468 25469 25470 25471 25472 25473 25474 25475 25476 25477 25478 25479 25480 25481 25482 25483 25484 25485 25486 25487 25488 25489 25490 25491 25492 25493 25494 25495 25496 25497 25498 25499 25500 25501 25502 25503 25504 25505 25506 25507 25508 25509 25510 25511 25512 25513 25514 25515 25516 25517 25518 25519 25520 25521 25522 25523 25524 25525 25526 25527 25528 25529 25530 25531 25532 25533 25534 25535 25536 25537 25538 25539 25540 25541 25542 25543 25544 25545 25546 25547 25548 25549 25550 25551 25552 25553 25554 25555 25556 25557 25558 25559 25560 25561 25562 25563 25564 25565 25566 25567 25568 25569 25570 25571 25572 25573 25574 25575 25576 25577 25578 25579 25580 25581 25582 25583 25584 25585 25586 25587 25588 25589 25590 25591 25592 25593 25594 25595 25596 25597 25598 25599 25600 25601 25602 25603 25604 25605 25606 25607 25608 25609 25610 25611 25612 25613 25614 25615 25616 25617 25618 25619 25620 25621 25622 25623 25624 25625 25626 25627 25628 25629 25630 25631 25632 25633 25634 25635 25636 25637 25638 25639 25640 25641 25642 25643 25644 25645 25646 25647 25648 25649 25650 25651 25652 25653 25654 25655 25656 25657 25658 25659 25660 25661 25662 25663 25664 25665 25666 25667 25668 25669 25670 25671 25672 25673 25674 25675 25676 25677 25678 25679 25680 25681 25682 25683 25684 25685 25686 25687 25688 25689 25690 25691 25692 25693 25694 25695 25696 25697 25698 25699 25700 25701 25702 25703 25704 25705 25706 25707 25708 25709 25710 25711 25712 25713 25714 25715 25716 25717 25718 25719 25720 25721 25722 25723 25724 25725 25726 25727 25728 25729 25730 25731 25732 25733 25734 25735 25736 25737 25738 25739 25740 25741 25742 25743 25744 25745 25746 25747 25748 25749 25750 25751 25752 25753 25754 25755 25756 25757 25758 25759 25760 25761 25762 25763 25764 25765 25766 25767 25768 25769 25770 25771 25772 25773 25774 25775 25776 25777 25778 25779 25780 25781 25782 25783 25784 25785 25786 25787 25788 25789 25790 25791 25792 25793 25794 25795 25796 25797 25798 25799 25800 25801 25802 25803 25804 25805 25806 25807 25808 25809 25810 25811 25812 25813 25814 25815 25816 25817 25818 25819 25820 25821 25822 25823 25824 25825 25826 25827 25828 25829 25830 25831 25832 25833 25834 25835 25836 25837 25838 25839 25840 25841 25842 25843 25844 25845 25846 25847 25848 25849 25850 25851 25852 25853 25854 25855 25856 25857 25858 25859 25860 25861 25862 25863 25864 25865 25866 25867 25868 25869 25870 25871 25872 25873 25874 25875 25876 25877 25878 25879 25880 25881 25882 25883 25884 25885 25886 25887 25888 25889 25890 25891 25892 25893 25894 25895 25896 25897 25898 25899 25900 25901 25902 25903 25904 25905 25906 25907 25908 25909 25910 25911 25912 25913 25914 25915 25916 25917 25918 25919 25920 25921 25922 25923 25924 25925 25926 25927 25928 25929 25930 25931 25932 25933 25934 25935 25936 25937 25938 25939 25940 25941 25942 25943 25944 25945 25946 25947 25948 25949 25950 25951 25952 25953 25954 25955 25956 25957 25958 25959 25960 25961 25962 25963 25964 25965 25966 25967 25968 25969 25970 25971 25972 25973 25974 25975 25976 25977 25978 25979 25980 25981 25982 25983 25984 25985 25986 25987 25988 25989 25990 25991 25992 25993 25994 25995 25996 25997 25998 25999 26000 26001 26002 26003 26004 26005 26006 26007 26008 26009 26010 26011 26012 26013 26014 26015 26016 26017 26018 26019 26020 26021 26022 26023 26024 26025 26026 26027 26028 26029 26030 26031 26032 26033 26034 26035 26036 26037 26038 26039 26040 26041 26042 26043 26044 26045 26046 26047 26048 26049 26050 26051 26052 26053 26054 26055 26056 26057 26058 26059 26060 26061 26062 26063 26064 26065 26066 26067 26068 26069 26070 26071 26072 26073 26074 26075 26076 26077 26078 26079 26080 26081 26082 26083 26084 26085 26086 26087 26088 26089 26090 26091 26092 26093 26094 26095 26096 26097 26098 26099 26100 26101 26102 26103 26104 26105 26106 26107 26108 26109 26110 26111 26112 26113 26114 26115 26116 26117 26118 26119 26120 26121 26122 26123 26124 26125 26126 26127 26128 26129 26130 26131 26132 26133 26134 26135 26136 26137 26138 26139 26140 26141 26142 26143 26144 26145 26146 26147 26148 26149 26150 26151 26152 26153 26154 26155 26156 26157 26158 26159 26160 26161 26162 26163 26164 26165 26166 26167 26168 26169 26170 26171 26172 26173 26174 26175 26176 26177 26178 26179 26180 26181 26182 26183 26184 26185 26186 26187 26188 26189 26190 26191 26192 26193 26194 26195 26196 26197 26198 26199 26200 26201 26202 26203 26204 26205 26206 26207 26208 26209 26210 26211 26212 26213 26214 26215 26216 26217 26218 26219 26220 26221 26222 26223 26224 26225 26226 26227 26228 26229 26230 26231 26232 26233 26234 26235 26236 26237 26238 26239 26240 26241 26242 26243 26244 26245 26246 26247 26248 26249 26250 26251 26252 26253 26254 26255 26256 26257 26258 26259 26260 26261 26262 26263 26264 26265 26266 26267 26268 26269 26270 26271 26272 26273 26274 26275 26276 26277 26278 26279 26280 26281 26282 26283 26284 26285 26286 26287 26288 26289 26290 26291 26292 26293 26294 26295 26296 26297 26298 26299 26300 26301 26302 26303 26304 26305 26306 26307 26308 26309 26310 26311 26312 26313 26314 26315 26316 26317 26318 26319 26320 26321 26322 26323 26324 26325 26326 26327 26328 26329 26330 26331 26332 26333 26334 26335 26336 26337 26338 26339 26340 26341 26342 26343 26344 26345 26346 26347 26348 26349 26350 26351 26352 26353 26354 26355 26356 26357 26358 26359 26360 26361 26362 26363 26364 26365 26366 26367 26368 26369 26370 26371 26372 26373 26374 26375 26376 26377 26378 26379 26380 26381 26382 26383 26384 26385 26386 26387 26388 26389 26390 26391 26392 26393 26394 26395 26396 26397 26398 26399 26400 26401 26402 26403 26404 26405 26406 26407 26408 26409 26410 26411 26412 26413 26414 26415 26416 26417 26418 26419 26420 26421 26422 26423 26424 26425 26426 26427 26428 26429 26430 26431 26432 26433 26434 26435 26436 26437 26438 26439 26440 26441 26442 26443 26444 26445 26446 26447 26448 26449 26450 26451 26452 26453 26454 26455 26456 26457 26458 26459 26460 26461 26462 26463 26464 26465 26466 26467 26468 26469 26470 26471 26472 26473 26474 26475 26476 26477 26478 26479 26480 26481 26482 26483 26484 26485 26486 26487 26488 26489 26490 26491 26492 26493 26494 26495 26496 26497 26498 26499 26500 26501 26502 26503 26504 26505 26506 26507 26508 26509 26510 26511 26512 26513 26514 26515 26516 26517 26518 26519 26520 26521 26522 26523 26524 26525 26526 26527 26528 26529 26530 26531 26532 26533 26534 26535 26536 26537 26538 26539 26540 26541 26542 26543 26544 26545 26546 26547 26548 26549 26550 26551 26552 26553 26554 26555 26556 26557 26558 26559 26560 26561 26562 26563 26564 26565 26566 26567 26568 26569 26570 26571 26572 26573 26574 26575 26576 26577 26578 26579 26580 26581 26582 26583 26584 26585 26586 26587 26588 26589 26590 26591 26592 26593 26594 26595 26596 26597 26598 26599 26600 26601 26602 26603 26604 26605 26606 26607 26608 26609 26610 26611 26612 26613 26614 26615 26616 26617 26618 26619 26620 26621 26622 26623 26624 26625 26626 26627 26628 26629 26630 26631 26632 26633 26634 26635 26636 26637 26638 26639 26640 26641 26642 26643 26644 26645 26646 26647 26648 26649 26650 26651 26652 26653 26654 26655 26656 26657 26658 26659 26660 26661 26662 26663 26664 26665 26666 26667 26668 26669 26670 26671 26672 26673 26674 26675 26676 26677 26678 26679 26680 26681 26682 26683 26684 26685 26686 26687 26688 26689 26690 26691 26692 26693 26694 26695 26696 26697 26698 26699 26700 26701 26702 26703 26704 26705 26706 26707 26708 26709 26710 26711 26712 26713 26714 26715 26716 26717 26718 26719 26720 26721 26722 26723 26724 26725 26726 26727 26728 26729 26730 26731 26732 26733 26734 26735 26736 26737 26738 26739 26740 26741 26742 26743 26744 26745 26746 26747 26748 26749 26750 26751 26752 26753 26754 26755 26756 26757 26758 26759 26760 26761 26762 26763 26764 26765 26766 26767 26768 26769 26770 26771 26772 26773 26774 26775 26776 26777 26778 26779 26780 26781 26782 26783 26784 26785 26786 26787 26788 26789 26790 26791 26792 26793 26794 26795 26796 26797 26798 26799 26800 26801 26802 26803 26804 26805 26806 26807 26808 26809 26810 26811 26812 26813 26814 26815 26816 26817 26818 26819 26820 26821 26822 26823 26824 26825 26826 26827 26828 26829 26830 26831 26832 26833 26834 26835 26836 26837 26838 26839 26840 26841 26842 26843 26844 26845 26846 26847 26848 26849 26850 26851 26852 26853 26854 26855 26856 26857 26858 26859 26860 26861 26862 26863 26864 26865 26866 26867 26868 26869 26870 26871 26872 26873 26874 26875 26876 26877 26878 26879 26880 26881 26882 26883 26884 26885 26886 26887 26888 26889 26890 26891 26892 26893 26894 26895 26896 26897 26898 26899 26900 26901 26902 26903 26904 26905 26906 26907 26908 26909 26910 26911 26912 26913 26914 26915 26916 26917 26918 26919 26920 26921 26922 26923 26924 26925 26926 26927 26928 26929 26930 26931 26932 26933 26934 26935 26936 26937 26938 26939 26940 26941 26942 26943 26944 26945 26946 26947 26948 26949 26950 26951 26952 26953 26954 26955 26956 26957 26958 26959 26960 26961 26962 26963 26964 26965 26966 26967 26968 26969 26970 26971 26972 26973 26974 26975 26976 26977 26978 26979 26980 26981 26982 26983 26984 26985 26986 26987 26988 26989 26990 26991 26992 26993 26994 26995 26996 26997 26998 26999 27000 27001 27002 27003 27004 27005 27006 27007 27008 27009 27010 27011 27012 27013 27014 27015 27016 27017 27018 27019 27020 27021 27022 27023 27024 27025 27026 27027 27028 27029 27030 27031 27032 27033 27034 27035 27036 27037 27038 27039 27040 27041 27042 27043 27044 27045 27046 27047 27048 27049 27050 27051 27052 27053 27054 27055 27056 27057 27058 27059 27060 27061 27062 27063 27064 27065 27066 27067 27068 27069 27070 27071 27072 27073 27074 27075 27076 27077 27078 27079 27080 27081 27082 27083 27084 27085 27086 27087 27088 27089 27090 27091 27092 27093 27094 27095 27096 27097 27098 27099 27100 27101 27102 27103 27104 27105 27106 27107 27108 27109 27110 27111 27112 27113 27114 27115 27116 27117 27118 27119 27120 27121 27122 27123 27124 27125 27126 27127 27128 27129 27130 27131 27132 27133 27134 27135 27136 27137 27138 27139 27140 27141 27142 27143 27144 27145 27146 27147 27148 27149 27150 27151 27152 27153 27154 27155 27156 27157 27158 27159 27160 27161 27162 27163 27164 27165 27166 27167 27168 27169 27170 27171 27172 27173 27174 27175 27176 27177 27178 27179 27180 27181 27182 27183 27184 27185 27186 27187 27188 27189 27190 27191 27192 27193 27194 27195 27196 27197 27198 27199 27200 27201 27202 27203 27204 27205 27206 27207 27208 27209 27210 27211 27212 27213 27214 27215 27216 27217 27218 27219 27220 27221 27222 27223 27224 27225 27226 27227 27228 27229 27230 27231 27232 27233 27234 27235 27236 27237 27238 27239 27240 27241 27242 27243 27244 27245 27246 27247 27248 27249 27250 27251 27252 27253 27254 27255 27256 27257 27258 27259 27260 27261 27262 27263 27264 27265 27266 27267 27268 27269 27270 27271 27272 27273 27274 27275 27276 27277 27278 27279 27280 27281 27282 27283 27284 27285 27286 27287 27288 27289 27290 27291 27292 27293 27294 27295 27296 27297 27298 27299 27300 27301 27302 27303 27304 27305 27306 27307 27308 27309 27310 27311 27312 27313 27314 27315 27316 27317 27318 27319 27320 27321 27322 27323 27324 27325 27326 27327 27328 27329 27330 27331 27332 27333 27334 27335 27336 27337 27338 27339 27340 27341 27342 27343 27344 27345 27346 27347 27348 27349 27350 27351 27352 27353 27354 27355 27356 27357 27358 27359 27360 27361 27362 27363 27364 27365 27366 27367 27368 27369 27370 27371 27372 27373 27374 27375 27376 27377 27378 27379 27380 27381 27382 27383 27384 27385 27386 27387 27388 27389 27390 27391 27392 27393 27394 27395 27396 27397 27398 27399 27400 27401 27402 27403 27404 27405 27406 27407 27408 27409 27410 27411 27412 27413 27414 27415 27416 27417 27418 27419 27420 27421 27422 27423 27424 27425 27426 27427 27428 27429 27430 27431 27432 27433 27434 27435 27436 27437 27438 27439 27440 27441 27442 27443 27444 27445 27446 27447 27448 27449 27450 27451 27452 27453 27454 27455 27456 27457 27458 27459 27460 27461 27462 27463 27464 27465 27466 27467 27468 27469 27470 27471 27472 27473 27474 27475 27476 27477 27478 27479 27480 27481 27482 27483 27484 27485 27486 27487 27488 27489 27490 27491 27492 27493 27494 27495 27496 27497 27498 27499 27500 27501 27502 27503 27504 27505 27506 27507 27508 27509 27510 27511 27512 27513 27514 27515 27516 27517 27518 27519 27520 27521 27522 27523 27524 27525 27526 27527 27528 27529 27530 27531 27532 27533 27534 27535 27536 27537 27538 27539 27540 27541 27542 27543 27544 27545 27546 27547 27548 27549 27550 27551 27552 27553 27554 27555 27556 27557 27558 27559 27560 27561 27562 27563 27564 27565 27566 27567 27568 27569 27570 27571 27572 27573 27574 27575 27576 27577 27578 27579 27580 27581 27582 27583 27584 27585 27586 27587 27588 27589 27590 27591 27592 27593 27594 27595 27596 27597 27598 27599 27600 27601 27602 27603 27604 27605 27606 27607 27608 27609 27610 27611 27612 27613 27614 27615 27616 27617 27618 27619 27620 27621 27622 27623 27624 27625 27626 27627 27628 27629 27630 27631 27632 27633 27634 27635 27636 27637 27638 27639 27640 27641 27642 27643 27644 27645 27646 27647 27648 27649 27650 27651 27652 27653 27654 27655 27656 27657 27658 27659 27660 27661 27662 27663 27664 27665 27666 27667 27668 27669 27670 27671 27672 27673 27674 27675 27676 27677 27678 27679 27680 27681 27682 27683 27684 27685 27686 27687 27688 27689 27690 27691 27692 27693 27694 27695 27696 27697 27698 27699 27700 27701 27702 27703 27704 27705 27706 27707 27708 27709 27710 27711 27712 27713 27714 27715 27716 27717 27718 27719 27720 27721 27722 27723 27724 27725 27726 27727 27728 27729 27730 27731 27732 27733 27734 27735 27736 27737 27738 27739 27740 27741 27742 27743 27744 27745 27746 27747 27748 27749 27750 27751 27752 27753 27754 27755 27756 27757 27758 27759 27760 27761 27762 27763 27764 27765 27766 27767 27768 27769 27770 27771 27772 27773 27774 27775 27776 27777 27778 27779 27780 27781 27782 27783 27784 27785 27786 27787 27788 27789 27790 27791 27792 27793 27794 27795 27796 27797 27798 27799 27800 27801 27802 27803 27804 27805 27806 27807 27808 27809 27810 27811 27812 27813 27814 27815 27816 27817 27818 27819 27820 27821 27822 27823 27824 27825 27826 27827 27828 27829 27830 27831 27832 27833 27834 27835 27836 27837 27838 27839 27840 27841 27842 27843 27844 27845 27846 27847 27848 27849 27850 27851 27852 27853 27854 27855 27856 27857 27858 27859 27860 27861 27862 27863 27864 27865 27866 27867 27868 27869 27870 27871 27872 27873 27874 27875 27876 27877 27878 27879 27880 27881 27882 27883 27884 27885 27886 27887 27888 27889 27890 27891 27892 27893 27894 27895 27896 27897 27898 27899 27900 27901 27902 27903 27904 27905 27906 27907 27908 27909 27910 27911 27912 27913 27914 27915 27916 27917 27918 27919 27920 27921 27922 27923 27924 27925 27926 27927 27928 27929 27930 27931 27932 27933 27934 27935 27936 27937 27938 27939 27940 27941 27942 27943 27944 27945 27946 27947 27948 27949 27950 27951 27952 27953 27954 27955 27956 27957 27958 27959 27960 27961 27962 27963 27964 27965 27966 27967 27968 27969 27970 27971 27972 27973 27974 27975 27976 27977 27978 27979 27980 27981 27982 27983 27984 27985 27986 27987 27988 27989 27990 27991 27992 27993 27994 27995 27996 27997 27998 27999 28000 28001 28002 28003 28004 28005 28006 28007 28008 28009 28010 28011 28012 28013 28014 28015 28016 28017 28018 28019 28020 28021 28022 28023 28024 28025 28026 28027 28028 28029 28030 28031 28032 28033 28034 28035 28036 28037 28038 28039 28040 28041 28042 28043 28044 28045 28046 28047 28048 28049 28050 28051 28052 28053 28054 28055 28056 28057 28058 28059 28060 28061 28062 28063 28064 28065 28066 28067 28068 28069 28070 28071 28072 28073 28074 28075 28076 28077 28078 28079 28080 28081 28082 28083 28084 28085 28086 28087 28088 28089 28090 28091 28092 28093 28094 28095 28096 28097 28098 28099 28100 28101 28102 28103 28104 28105 28106 28107 28108 28109 28110 28111 28112 28113 28114 28115 28116 28117 28118 28119 28120 28121 28122 28123 28124 28125 28126 28127 28128 28129 28130 28131 28132 28133 28134 28135 28136 28137 28138 28139 28140 28141 28142 28143 28144 28145 28146 28147 28148 28149 28150 28151 28152 28153 28154 28155 28156 28157 28158 28159 28160 28161 28162 28163 28164 28165 28166 28167 28168 28169 28170 28171 28172 28173 28174 28175 28176 28177 28178 28179 28180 28181 28182 28183 28184 28185 28186 28187 28188 28189 28190 28191 28192 28193 28194 28195 28196 28197 28198 28199 28200 28201 28202 28203 28204 28205 28206 28207 28208 28209 28210 28211 28212 28213 28214 28215 28216 28217 28218 28219 28220 28221 28222 28223 28224 28225 28226 28227 28228 28229 28230 28231 28232 28233 28234 28235 28236 28237 28238 28239 28240 28241 28242 28243 28244 28245 28246 28247 28248 28249 28250 28251 28252 28253 28254 28255 28256 28257 28258 28259 28260 28261 28262 28263 28264 28265 28266 28267 28268 28269 28270 28271 28272 28273 28274 28275 28276 28277 28278 28279 28280 28281 28282 28283 28284 28285 28286 28287 28288 28289 28290 28291 28292 28293 28294 28295 28296 28297 28298 28299 28300 28301 28302 28303 28304 28305 28306 28307 28308 28309 28310 28311 28312 28313 28314 28315 28316 28317 28318 28319 28320 28321 28322 28323 28324 28325 28326 28327 28328 28329 28330 28331 28332 28333 28334 28335 28336 28337 28338 28339 28340 28341 28342 28343 28344 28345 28346 28347 28348 28349 28350 28351 28352 28353 28354 28355 28356 28357 28358 28359 28360 28361 28362 28363 28364 28365 28366 28367 28368 28369 28370 28371 28372 28373 28374 28375 28376 28377 28378 28379 28380 28381 28382 28383 28384 28385 28386 28387 28388 28389 28390 28391 28392 28393 28394 28395 28396 28397 28398 28399 28400 28401 28402 28403 28404 28405 28406 28407 28408 28409 28410 28411 28412 28413 28414 28415 28416 28417 28418 28419 28420 28421 28422 28423 28424 28425 28426 28427 28428 28429 28430 28431 28432 28433 28434 28435 28436 28437 28438 28439 28440 28441 28442 28443 28444 28445 28446 28447 28448 28449 28450 28451 28452 28453 28454 28455 28456 28457 28458 28459 28460 28461 28462 28463 28464 28465 28466 28467 28468 28469 28470 28471 28472 28473 28474 28475 28476 28477 28478 28479 28480 28481 28482 28483 28484 28485 28486 28487 28488 28489 28490 28491 28492 28493 28494 28495 28496 28497 28498 28499 28500 28501 28502 28503 28504 28505 28506 28507 28508 28509 28510 28511 28512 28513 28514 28515 28516 28517 28518 28519 28520 28521 28522 28523 28524 28525 28526 28527 28528 28529 28530 28531 28532 28533 28534 28535 28536 28537 28538 28539 28540 28541 28542 28543 28544 28545 28546 28547 28548 28549 28550 28551 28552 28553 28554 28555 28556 28557 28558 28559 28560 28561 28562 28563 28564 28565 28566 28567 28568 28569 28570 28571 28572 28573 28574 28575 28576 28577 28578 28579 28580 28581 28582 28583 28584 28585 28586 28587 28588 28589 28590 28591 28592 28593 28594 28595 28596 28597 28598 28599 28600 28601 28602 28603 28604 28605 28606 28607 28608 28609 28610 28611 28612 28613 28614 28615 28616 28617 28618 28619 28620 28621 28622 28623 28624 28625 28626 28627 28628 28629 28630 28631 28632 28633 28634 28635 28636 28637 28638 28639 28640 28641 28642 28643 28644 28645 28646 28647 28648 28649 28650 28651 28652 28653 28654 28655 28656 28657 28658 28659 28660 28661 28662 28663 28664 28665 28666 28667 28668 28669 28670 28671 28672 28673 28674 28675 28676 28677 28678 28679 28680 28681 28682 28683 28684 28685 28686 28687 28688 28689 28690 28691 28692 28693 28694 28695 28696 28697 28698 28699 28700 28701 28702 28703 28704 28705 28706 28707 28708 28709 28710 28711 28712 28713 28714 28715 28716 28717 28718 28719 28720 28721 28722 28723 28724 28725 28726 28727 28728 28729 28730 28731 28732 28733 28734 28735 28736 28737 28738 28739 28740 28741 28742 28743 28744 28745 28746 28747 28748 28749 28750 28751 28752 28753 28754 28755 28756 28757 28758 28759 28760 28761 28762 28763 28764 28765 28766 28767 28768 28769 28770 28771 28772 28773 28774 28775 28776 28777 28778 28779 28780 28781 28782 28783 28784 28785 28786 28787 28788 28789 28790 28791 28792 28793 28794 28795 28796 28797 28798 28799 28800 28801 28802 28803 28804 28805 28806 28807 28808 28809 28810 28811 28812 28813 28814 28815 28816 28817 28818 28819 28820 28821 28822 28823 28824 28825 28826 28827 28828 28829 28830 28831 28832 28833 28834 28835 28836 28837 28838 28839 28840 28841 28842 28843 28844 28845 28846 28847 28848 28849 28850 28851 28852 28853 28854 28855 28856 28857 28858 28859 28860 28861 28862 28863 28864 28865 28866 28867 28868 28869 28870 28871 28872 28873 28874 28875 28876 28877 28878 28879 28880 28881 28882 28883 28884 28885 28886 28887 28888 28889 28890 28891 28892 28893 28894 28895 28896 28897 28898 28899 28900 28901 28902 28903 28904 28905 28906 28907 28908 28909 28910 28911 28912 28913 28914 28915 28916 28917 28918 28919 28920 28921 28922 28923 28924 28925 28926 28927 28928 28929 28930 28931 28932 28933 28934 28935 28936 28937 28938 28939 28940 28941 28942 28943 28944 28945 28946 28947 28948 28949 28950 28951 28952 28953 28954 28955 28956 28957 28958 28959 28960 28961 28962 28963 28964 28965 28966 28967 28968 28969 28970 28971 28972 28973 28974 28975 28976 28977 28978 28979 28980 28981 28982 28983 28984 28985 28986 28987 28988 28989 28990 28991 28992 28993 28994 28995 28996 28997 28998 28999 29000 29001 29002 29003 29004 29005 29006 29007 29008 29009 29010 29011 29012 29013 29014 29015 29016 29017 29018 29019 29020 29021 29022 29023 29024 29025 29026 29027 29028 29029 29030 29031 29032 29033 29034 29035 29036 29037 29038 29039 29040 29041 29042 29043 29044 29045 29046 29047 29048 29049 29050 29051 29052 29053 29054 29055 29056 29057 29058 29059 29060 29061 29062 29063 29064 29065 29066 29067 29068 29069 29070 29071 29072 29073 29074 29075 29076 29077 29078 29079 29080 29081 29082 29083 29084 29085 29086 29087 29088 29089 29090 29091 29092 29093 29094 29095 29096 29097 29098 29099 29100 29101 29102 29103 29104 29105 29106 29107 29108 29109 29110 29111 29112 29113 29114 29115 29116 29117 29118 29119 29120 29121 29122 29123 29124 29125 29126 29127 29128 29129 29130 29131 29132 29133 29134 29135 29136 29137 29138 29139 29140 29141 29142 29143 29144 29145 29146 29147 29148 29149 29150 29151 29152 29153 29154 29155 29156 29157 29158 29159 29160 29161 29162 29163 29164 29165 29166 29167 29168 29169 29170 29171 29172 29173 29174 29175 29176 29177 29178 29179 29180 29181 29182 29183 29184 29185 29186 29187 29188 29189 29190 29191 29192 29193 29194 29195 29196 29197 29198 29199 29200 29201 29202 29203 29204 29205 29206 29207 29208 29209 29210 29211 29212 29213 29214 29215 29216 29217 29218 29219 29220 29221 29222 29223 29224 29225 29226 29227 29228 29229 29230 29231 29232 29233 29234 29235 29236 29237 29238 29239 29240 29241 29242 29243 29244 29245 29246 29247 29248 29249 29250 29251 29252 29253 29254 29255 29256 29257 29258 29259 29260 29261 29262 29263 29264 29265 29266 29267 29268 29269 29270 29271 29272 29273 29274 29275 29276 29277 29278 29279 29280 29281 29282 29283 29284 29285 29286 29287 29288 29289 29290 29291 29292 29293 29294 29295 29296 29297 29298 29299 29300 29301 29302 29303 29304 29305 29306 29307 29308 29309 29310 29311 29312 29313 29314 29315 29316 29317 29318 29319 29320 29321 29322 29323 29324 29325 29326 29327 29328 29329 29330 29331 29332 29333 29334 29335 29336 29337 29338 29339 29340 29341 29342 29343 29344 29345 29346 29347 29348 29349 29350 29351 29352 29353 29354 29355 29356 29357 29358 29359 29360 29361 29362 29363 29364 29365 29366 29367 29368 29369 29370 29371 29372 29373 29374 29375 29376 29377 29378 29379 29380 29381 29382 29383 29384 29385 29386 29387 29388 29389 29390 29391 29392 29393 29394 29395 29396 29397 29398 29399 29400 29401 29402 29403 29404 29405 29406 29407 29408 29409 29410 29411 29412 29413 29414 29415 29416 29417 29418 29419 29420 29421 29422 29423 29424 29425 29426 29427 29428 29429 29430 29431 29432 29433 29434 29435 29436 29437 29438 29439 29440 29441 29442 29443 29444 29445 29446 29447 29448 29449 29450 29451 29452 29453 29454 29455 29456 29457 29458 29459 29460 29461 29462 29463 29464 29465 29466 29467 29468 29469 29470 29471 29472 29473 29474 29475 29476 29477 29478 29479 29480 29481 29482 29483 29484 29485 29486 29487 29488 29489 29490 29491 29492 29493 29494 29495 29496 29497 29498 29499 29500 29501 29502 29503 29504 29505 29506 29507 29508 29509 29510 29511 29512 29513 29514 29515 29516 29517 29518 29519 29520 29521 29522 29523 29524 29525 29526 29527 29528 29529 29530 29531 29532 29533 29534 29535 29536 29537 29538 29539 29540 29541 29542 29543 29544 29545 29546 29547 29548 29549 29550 29551 29552 29553 29554 29555 29556 29557 29558 29559 29560 29561 29562 29563 29564 29565 29566 29567 29568 29569 29570 29571 29572 29573 29574 29575 29576 29577 29578 29579 29580 29581 29582 29583 29584 29585 29586 29587 29588 29589 29590 29591 29592 29593 29594 29595 29596 29597 29598 29599 29600 29601 29602 29603 29604 29605 29606 29607 29608 29609 29610 29611 29612 29613 29614 29615 29616 29617 29618 29619 29620 29621 29622 29623 29624 29625 29626 29627 29628 29629 29630 29631 29632 29633 29634 29635 29636 29637 29638 29639 29640 29641 29642 29643 29644 29645 29646 29647 29648 29649 29650 29651 29652 29653 29654 29655 29656 29657 29658 29659 29660 29661 29662 29663 29664 29665 29666 29667 29668 29669 29670 29671 29672 29673 29674 29675 29676 29677 29678 29679 29680 29681 29682 29683 29684 29685 29686 29687 29688 29689 29690 29691 29692 29693 29694 29695 29696 29697 29698 29699 29700 29701 29702 29703 29704 29705 29706 29707 29708 29709 29710 29711 29712 29713 29714 29715 29716 29717 29718 29719 29720 29721 29722 29723 29724 29725 29726 29727 29728 29729 29730 29731 29732 29733 29734 29735 29736 29737 29738 29739 29740 29741 29742 29743 29744 29745 29746 29747 29748 29749 29750 29751 29752 29753 29754 29755 29756 29757 29758 29759 29760 29761 29762 29763 29764 29765 29766 29767 29768 29769 29770 29771 29772 29773 29774 29775 29776 29777 29778 29779 29780 29781 29782 29783 29784 29785 29786 29787 29788 29789 29790 29791 29792 29793 29794 29795 29796 29797 29798 29799 29800 29801 29802 29803 29804 29805 29806 29807 29808 29809 29810 29811 29812 29813 29814 29815 29816 29817 29818 29819 29820 29821 29822 29823 29824 29825 29826 29827 29828 29829 29830 29831 29832 29833 29834 29835 29836 29837 29838 29839 29840 29841 29842 29843 29844 29845 29846 29847 29848 29849 29850 29851 29852 29853 29854 29855 29856 29857 29858 29859 29860 29861 29862 29863 29864 29865 29866 29867 29868 29869 29870 29871 29872 29873 29874 29875 29876 29877 29878 29879 29880 29881 29882 29883 29884 29885 29886 29887 29888 29889 29890 29891 29892 29893 29894 29895 29896 29897 29898 29899 29900 29901 29902 29903 29904 29905 29906 29907 29908 29909 29910 29911 29912 29913 29914 29915 29916 29917 29918 29919 29920 29921 29922 29923 29924 29925 29926 29927 29928 29929 29930 29931 29932 29933 29934 29935 29936 29937 29938 29939 29940 29941 29942 29943 29944 29945 29946 29947 29948 29949 29950 29951 29952 29953 29954 29955 29956 29957 29958 29959 29960 29961 29962 29963 29964 29965 29966 29967 29968 29969 29970 29971 29972 29973 29974 29975 29976 29977 29978 29979 29980 29981 29982 29983 29984 29985 29986 29987 29988 29989 29990 29991 29992 29993 29994 29995 29996 29997 29998 29999 30000 30001 30002 30003 30004 30005 30006 30007 30008 30009 30010 30011 30012 30013 30014 30015 30016 30017 30018 30019 30020 30021 30022 30023 30024 30025 30026 30027 30028 30029 30030 30031 30032 30033 30034 30035 30036 30037 30038 30039 30040 30041 30042 30043 30044 30045 30046 30047 30048 30049 30050 30051 30052 30053 30054 30055 30056 30057 30058 30059 30060 30061 30062 30063 30064 30065 30066 30067 30068 30069 30070 30071 30072 30073 30074 30075 30076 30077 30078 30079 30080 30081 30082 30083 30084 30085 30086 30087 30088 30089 30090 30091 30092 30093 30094 30095 30096 30097 30098 30099 30100 30101 30102 30103 30104 30105 30106 30107 30108 30109 30110 30111 30112 30113 30114 30115 30116 30117 30118 30119 30120 30121 30122 30123 30124 30125 30126 30127 30128 30129 30130 30131 30132 30133 30134 30135 30136 30137 30138 30139 30140 30141 30142 30143 30144 30145 30146 30147 30148 30149 30150 30151 30152 30153 30154 30155 30156 30157 30158 30159 30160 30161 30162 30163 30164 30165 30166 30167 30168 30169 30170 30171 30172 30173 30174 30175 30176 30177 30178 30179 30180 30181 30182 30183 30184 30185 30186 30187 30188 30189 30190 30191 30192 30193 30194 30195 30196 30197 30198 30199 30200 30201 30202 30203 30204 30205 30206 30207 30208 30209 30210 30211 30212 30213 30214 30215 30216 30217 30218 30219 30220 30221 30222 30223 30224 30225 30226 30227 30228 30229 30230 30231 30232 30233 30234 30235 30236 30237 30238 30239 30240 30241 30242 30243 30244 30245 30246 30247 30248 30249 30250 30251 30252 30253 30254 30255 30256 30257 30258 30259 30260 30261 30262 30263 30264 30265 30266 30267 30268 30269 30270 30271 30272 30273 30274 30275 30276 30277 30278 30279 30280 30281 30282 30283 30284 30285 30286 30287 30288 30289 30290 30291 30292 30293 30294 30295 30296 30297 30298 30299 30300 30301 30302 30303 30304 30305 30306 30307 30308 30309 30310 30311 30312 30313 30314 30315 30316 30317 30318 30319 30320 30321 30322 30323 30324 30325 30326 30327 30328 30329 30330 30331 30332 30333 30334 30335 30336 30337 30338 30339 30340 30341 30342 30343 30344 30345 30346 30347 30348 30349 30350 30351 30352 30353 30354 30355 30356 30357 30358 30359 30360 30361 30362 30363 30364 30365 30366 30367 30368 30369 30370 30371 30372 30373 30374 30375 30376 30377 30378 30379 30380 30381 30382 30383 30384 30385 30386 30387 30388 30389 30390 30391 30392 30393 30394 30395 30396 30397 30398 30399 30400 30401 30402 30403 30404 30405 30406 30407 30408 30409 30410 30411 30412 30413 30414 30415 30416 30417 30418 30419 30420 30421 30422 30423 30424 30425 30426 30427 30428 30429 30430 30431 30432 30433 30434 30435 30436 30437 30438 30439 30440 30441 30442 30443 30444 30445 30446 30447 30448 30449 30450 30451 30452 30453 30454 30455 30456 30457 30458 30459 30460 30461 30462 30463 30464 30465 30466 30467 30468 30469 30470 30471 30472 30473 30474 30475 30476 30477 30478 30479 30480 30481 30482 30483 30484 30485 30486 30487 30488 30489 30490 30491 30492 30493 30494 30495 30496 30497 30498 30499 30500 30501 30502 30503 30504 30505 30506 30507 30508 30509 30510 30511 30512 30513 30514 30515 30516 30517 30518 30519 30520 30521 30522 30523 30524 30525 30526 30527 30528 30529 30530 30531 30532 30533 30534 30535 30536 30537 30538 30539 30540 30541 30542 30543 30544 30545 30546 30547 30548 30549 30550 30551 30552 30553 30554 30555 30556 30557 30558 30559 30560 30561 30562 30563 30564 30565 30566 30567 30568 30569 30570 30571 30572 30573 30574 30575 30576 30577 30578 30579 30580 30581 30582 30583 30584 30585 30586 30587 30588 30589 30590 30591 30592 30593 30594 30595 30596 30597 30598 30599 30600 30601 30602 30603 30604 30605 30606 30607 30608 30609 30610 30611 30612 30613 30614 30615 30616 30617 30618 30619 30620 30621 30622 30623 30624 30625 30626 30627 30628 30629 30630 30631 30632 30633 30634 30635 30636 30637 30638 30639 30640 30641 30642 30643 30644 30645 30646 30647 30648 30649 30650 30651 30652 30653 30654 30655 30656 30657 30658 30659 30660 30661 30662 30663 30664 30665 30666 30667 30668 30669 30670 30671 30672 30673 30674 30675 30676 30677 30678 30679 30680 30681 30682 30683 30684 30685 30686 30687 30688 30689 30690 30691 30692 30693 30694 30695 30696 30697 30698 30699 30700 30701 30702 30703 30704 30705 30706 30707 30708 30709 30710 30711 30712 30713 30714 30715 30716 30717 30718 30719 30720 30721 30722 30723 30724 30725 30726 30727 30728 30729 30730 30731 30732 30733 30734 30735 30736 30737 30738 30739 30740 30741 30742 30743 30744 30745 30746 30747 30748 30749 30750 30751 30752 30753 30754 30755 30756 30757 30758 30759 30760 30761 30762 30763 30764 30765 30766 30767 30768 30769 30770 30771 30772 30773 30774 30775 30776 30777 30778 30779 30780 30781 30782 30783 30784 30785 30786 30787 30788 30789 30790 30791 30792 30793 30794 30795 30796 30797 30798 30799 30800 30801 30802 30803 30804 30805 30806 30807 30808 30809 30810 30811 30812 30813 30814 30815 30816 30817 30818 30819 30820 30821 30822 30823 30824 30825 30826 30827 30828 30829 30830 30831 30832 30833 30834 30835 30836 30837 30838 30839 30840 30841 30842 30843 30844 30845 30846 30847 30848 30849 30850 30851 30852 30853 30854 30855 30856 30857 30858 30859 30860 30861 30862 30863 30864 30865 30866 30867 30868 30869 30870 30871 30872 30873 30874 30875 30876 30877 30878 30879 30880 30881 30882 30883 30884 30885 30886 30887 30888 30889 30890 30891 30892 30893 30894 30895 30896 30897 30898 30899 30900 30901 30902 30903 30904 30905 30906 30907 30908 30909 30910 30911 30912 30913 30914 30915 30916 30917 30918 30919 30920 30921 30922 30923 30924 30925 30926 30927 30928 30929 30930 30931 30932 30933 30934 30935 30936 30937 30938 30939 30940 30941 30942 30943 30944 30945 30946 30947 30948 30949 30950 30951 30952 30953 30954 30955 30956 30957 30958 30959 30960 30961 30962 30963 30964 30965 30966 30967 30968 30969 30970 30971 30972 30973 30974 30975 30976 30977 30978 30979 30980 30981 30982 30983 30984 30985 30986 30987 30988 30989 30990 30991 30992 30993 30994 30995 30996 30997 30998 30999 31000 31001 31002 31003 31004 31005 31006 31007 31008 31009 31010 31011 31012 31013 31014 31015 31016 31017 31018 31019 31020 31021 31022 31023 31024 31025 31026 31027 31028 31029 31030 31031 31032 31033 31034 31035 31036 31037 31038 31039 31040 31041 31042 31043 31044 31045 31046 31047 31048 31049 31050 31051 31052 31053 31054 31055 31056 31057 31058 31059 31060 31061 31062 31063 31064 31065 31066 31067 31068 31069 31070 31071 31072 31073 31074 31075 31076 31077 31078 31079 31080 31081 31082 31083 31084 31085 31086 31087 31088 31089 31090 31091 31092 31093 31094 31095 31096 31097 31098 31099 31100 31101 31102 31103 31104 31105 31106 31107 31108 31109 31110 31111 31112 31113 31114 31115 31116 31117 31118 31119 31120 31121 31122 31123 31124 31125 31126 31127 31128 31129 31130 31131 31132 31133 31134 31135 31136 31137 31138 31139 31140 31141 31142 31143 31144 31145 31146 31147 31148 31149 31150 31151 31152 31153 31154 31155 31156 31157 31158 31159 31160 31161 31162 31163 31164 31165 31166 31167 31168 31169 31170 31171 31172 31173 31174 31175 31176 31177 31178 31179 31180 31181 31182 31183 31184 31185 31186 31187 31188 31189 31190 31191 31192 31193 31194 31195 31196 31197 31198 31199 31200 31201 31202 31203 31204 31205 31206 31207 31208 31209 31210 31211 31212 31213 31214 31215 31216 31217 31218 31219 31220 31221 31222 31223 31224 31225 31226 31227 31228 31229 31230 31231 31232 31233 31234 31235 31236 31237 31238 31239 31240 31241 31242 31243 31244 31245 31246 31247 31248 31249 31250 31251 31252 31253 31254 31255 31256 31257 31258 31259 31260 31261 31262 31263 31264 31265 31266 31267 31268 31269 31270 31271 31272 31273 31274 31275 31276 31277 31278 31279 31280 31281 31282 31283 31284 31285 31286 31287 31288 31289 31290 31291 31292 31293 31294 31295 31296 31297 31298 31299 31300 31301 31302 31303 31304 31305 31306 31307 31308 31309 31310 31311 31312 31313 31314 31315 31316 31317 31318 31319 31320 31321 31322 31323 31324 31325 31326 31327 31328 31329 31330 31331 31332 31333 31334 31335 31336 31337 31338 31339 31340 31341 31342 31343 31344 31345 31346 31347 31348 31349 31350 31351 31352 31353 31354 31355 31356 31357 31358 31359 31360 31361 31362 31363 31364 31365 31366 31367 31368 31369 31370 31371 31372 31373 31374 31375 31376 31377 31378 31379 31380 31381 31382 31383 31384 31385 31386 31387 31388 31389 31390 31391 31392 31393 31394 31395 31396 31397 31398 31399 31400 31401 31402 31403 31404 31405 31406 31407 31408 31409 31410 31411 31412 31413 31414 31415 31416 31417 31418 31419 31420 31421 31422 31423 31424 31425 31426 31427 31428 31429 31430 31431 31432 31433 31434 31435 31436 31437 31438 31439 31440 31441 31442 31443 31444 31445 31446 31447 31448 31449 31450 31451 31452 31453 31454 31455 31456 31457 31458 31459 31460 31461 31462 31463 31464 31465 31466 31467 31468 31469 31470 31471 31472 31473 31474 31475 31476 31477 31478 31479 31480 31481 31482 31483 31484 31485 31486 31487 31488 31489 31490 31491 31492 31493 31494 31495 31496 31497 31498 31499 31500 31501 31502 31503 31504 31505 31506 31507 31508 31509 31510 31511 31512 31513 31514 31515 31516 31517 31518 31519 31520 31521 31522 31523 31524 31525 31526 31527 31528 31529 31530 31531 31532 31533 31534 31535 31536 31537 31538 31539 31540 31541 31542 31543 31544 31545 31546 31547 31548 31549 31550 31551 31552 31553 31554 31555 31556 31557 31558 31559 31560 31561 31562 31563 31564 31565 31566 31567 31568 31569 31570 31571 31572 31573 31574 31575 31576 31577 31578 31579 31580 31581 31582 31583 31584 31585 31586 31587 31588 31589 31590 31591 31592 31593 31594 31595 31596 31597 31598 31599 31600 31601 31602 31603 31604 31605 31606 31607 31608 31609 31610 31611 31612 31613 31614 31615 31616 31617 31618 31619 31620 31621 31622 31623 31624 31625 31626 31627 31628 31629 31630 31631 31632 31633 31634 31635 31636 31637 31638 31639 31640 31641 31642 31643 31644 31645 31646 31647 31648 31649 31650 31651 31652 31653 31654 31655 31656 31657 31658 31659 31660 31661 31662 31663 31664 31665 31666 31667 31668 31669 31670 31671 31672 31673 31674 31675 31676 31677 31678 31679 31680 31681 31682 31683 31684 31685 31686 31687 31688 31689 31690 31691 31692 31693 31694 31695 31696 31697 31698 31699 31700 31701 31702 31703 31704 31705 31706 31707 31708 31709 31710 31711 31712 31713 31714 31715 31716 31717 31718 31719 31720 31721 31722 31723 31724 31725 31726 31727 31728 31729 31730 31731 31732 31733 31734 31735 31736 31737 31738 31739 31740 31741 31742 31743 31744 31745 31746 31747 31748 31749 31750 31751 31752 31753 31754 31755 31756 31757 31758 31759 31760 31761 31762 31763 31764 31765 31766 31767 31768 31769 31770 31771 31772 31773 31774 31775 31776 31777 31778 31779 31780 31781 31782 31783 31784 31785 31786 31787 31788 31789 31790 31791 31792 31793 31794 31795 31796 31797 31798 31799 31800 31801 31802 31803 31804 31805 31806 31807 31808 31809 31810 31811 31812 31813 31814 31815 31816 31817 31818 31819 31820 31821 31822 31823 31824 31825 31826 31827 31828 31829 31830 31831 31832 31833 31834 31835 31836 31837 31838 31839 31840 31841 31842 31843 31844 31845 31846 31847 31848 31849 31850 31851 31852 31853 31854 31855 31856 31857 31858 31859 31860 31861 31862 31863 31864 31865 31866 31867 31868 31869 31870 31871 31872 31873 31874 31875 31876 31877 31878 31879 31880 31881 31882 31883 31884 31885 31886 31887 31888 31889 31890 31891 31892 31893 31894 31895 31896 31897 31898 31899 31900 31901 31902 31903 31904 31905 31906 31907 31908 31909 31910 31911 31912 31913 31914 31915 31916 31917 31918 31919 31920 31921 31922 31923 31924 31925 31926 31927 31928 31929 31930 31931 31932 31933 31934 31935 31936 31937 31938 31939 31940 31941 31942 31943 31944 31945 31946 31947 31948 31949 31950 31951 31952 31953 31954 31955 31956 31957 31958 31959 31960 31961 31962 31963 31964 31965 31966 31967 31968 31969 31970 31971 31972 31973 31974 31975 31976 31977 31978 31979 31980 31981 31982 31983 31984 31985 31986 31987 31988 31989 31990 31991 31992 31993 31994 31995 31996 31997 31998 31999 32000 32001 32002 32003 32004 32005 32006 32007 32008 32009 32010 32011 32012 32013 32014 32015 32016 32017 32018 32019 32020 32021 32022 32023 32024 32025 32026 32027 32028 32029 32030 32031 32032 32033 32034 32035 32036 32037 32038 32039 32040 32041 32042 32043 32044 32045 32046 32047 32048 32049 32050 32051 32052 32053 32054 32055 32056 32057 32058 32059 32060 32061 32062 32063 32064 32065 32066 32067 32068 32069 32070 32071 32072 32073 32074 32075 32076 32077 32078 32079 32080 32081 32082 32083 32084 32085 32086 32087 32088 32089 32090 32091 32092 32093 32094 32095 32096 32097 32098 32099 32100 32101 32102 32103 32104 32105 32106 32107 32108 32109 32110 32111 32112 32113 32114 32115 32116 32117 32118 32119 32120 32121 32122 32123 32124 32125 32126 32127 32128 32129 32130 32131 32132 32133 32134 32135 32136 32137 32138 32139 32140 32141 32142 32143 32144 32145 32146 32147 32148 32149 32150 32151 32152 32153 32154 32155 32156 32157 32158 32159 32160 32161 32162 32163 32164 32165 32166 32167 32168 32169 32170 32171 32172 32173 32174 32175 32176 32177 32178 32179 32180 32181 32182 32183 32184 32185 32186 32187 32188 32189 32190 32191 32192 32193 32194 32195 32196 32197 32198 32199 32200 32201 32202 32203 32204 32205 32206 32207 32208 32209 32210 32211 32212 32213 32214 32215 32216 32217 32218 32219 32220 32221 32222 32223 32224 32225 32226 32227 32228 32229 32230 32231 32232 32233 32234 32235 32236 32237 32238 32239 32240 32241 32242 32243 32244 32245 32246 32247 32248 32249 32250 32251 32252 32253 32254 32255 32256 32257 32258 32259 32260 32261 32262 32263 32264 32265 32266 32267 32268 32269 32270 32271 32272 32273 32274 32275 32276 32277 32278 32279 32280 32281 32282 32283 32284 32285 32286 32287 32288 32289 32290 32291 32292 32293 32294 32295 32296 32297 32298 32299 32300 32301 32302 32303 32304 32305 32306 32307 32308 32309 32310 32311 32312 32313 32314 32315 32316 32317 32318 32319 32320 32321 32322 32323 32324 32325 32326 32327 32328 32329 32330 32331 32332 32333 32334 32335 32336 32337 32338 32339 32340 32341 32342 32343 32344 32345 32346 32347 32348 32349 32350 32351 32352 32353 32354 32355 32356 32357 32358 32359 32360 32361 32362 32363 32364 32365 32366 32367 32368 32369 32370 32371 32372 32373 32374 32375 32376 32377 32378 32379 32380 32381 32382 32383 32384 32385 32386 32387 32388 32389 32390 32391 32392 32393 32394 32395 32396 32397 32398 32399 32400 32401 32402 32403 32404 32405 32406 32407 32408 32409 32410 32411 32412 32413 32414 32415 32416 32417 32418 32419 32420 32421 32422 32423 32424 32425 32426 32427 32428 32429 32430 32431 32432 32433 32434 32435 32436 32437 32438 32439 32440 32441 32442 32443 32444 32445 32446 32447 32448 32449 32450 32451 32452 32453 32454 32455 32456 32457 32458 32459 32460 32461 32462 32463 32464 32465 32466 32467 32468 32469 32470 32471 32472 32473 32474 32475 32476 32477 32478 32479 32480 32481 32482 32483 32484 32485 32486 32487 32488 32489 32490 32491 32492 32493 32494 32495 32496 32497 32498 32499 32500 32501 32502 32503 32504 32505 32506 32507 32508 32509 32510 32511 32512 32513 32514 32515 32516 32517 32518 32519 32520 32521 32522 32523 32524 32525 32526 32527 32528 32529 32530 32531 32532 32533 32534 32535 32536 32537 32538 32539 32540 32541 32542 32543 32544 32545 32546 32547 32548 32549 32550 32551 32552 32553 32554 32555 32556 32557 32558 32559 32560 32561 32562 32563 32564 32565 32566 32567 32568 32569 32570 32571 32572 32573 32574 32575 32576 32577 32578 32579 32580 32581 32582 32583 32584 32585 32586 32587 32588 32589 32590 32591 32592 32593 32594 32595 32596 32597 32598 32599 32600 32601 32602 32603 32604 32605 32606 32607 32608 32609 32610 32611 32612 32613 32614 32615 32616 32617 32618 32619 32620 32621 32622 32623 32624 32625 32626 32627 32628 32629 32630 32631 32632 32633 32634 32635 32636 32637 32638 32639 32640 32641 32642 32643 32644 32645 32646 32647 32648 32649 32650 32651 32652 32653 32654 32655 32656 32657 32658 32659 32660 32661 32662 32663 32664 32665 32666 32667 32668 32669 32670 32671 32672 32673 32674 32675 32676 32677 32678 32679 32680 32681 32682 32683 32684 32685 32686 32687 32688 32689 32690 32691 32692 32693 32694 32695 32696 32697 32698 32699 32700 32701 32702 32703 32704 32705 32706 32707 32708 32709 32710 32711 32712 32713 32714 32715 32716 32717 32718 32719 32720 32721 32722 32723 32724 32725 32726 32727 32728 32729 32730 32731 32732 32733 32734 32735 32736 32737 32738 32739 32740 32741 32742 32743 32744 32745 32746 32747 32748 32749 32750 32751 32752 32753 32754 32755 32756 32757 32758 32759 32760 32761 32762 32763 32764 32765 32766 32767 32768 32769 32770 32771 32772 32773 32774 32775 32776 32777 32778 32779 32780 32781 32782 32783 32784 32785 32786 32787 32788 32789 32790 32791 32792 32793 32794 32795 32796 32797 32798 32799 32800 32801 32802 32803 32804 32805 32806 32807 32808 32809 32810 32811 32812 32813 32814 32815 32816 32817 32818 32819 32820 32821 32822 32823 32824 32825 32826 32827 32828 32829 32830 32831 32832 32833 32834 32835 32836 32837 32838 32839 32840 32841 32842 32843 32844 32845 32846 32847 32848 32849 32850 32851 32852 32853 32854 32855 32856 32857 32858 32859 32860 32861 32862 32863 32864 32865 32866 32867 32868 32869 32870 32871 32872 32873 32874 32875 32876 32877 32878 32879 32880 32881 32882 32883 32884 32885 32886 32887 32888 32889 32890 32891 32892 32893 32894 32895 32896 32897 32898 32899 32900 32901 32902 32903 32904 32905 32906 32907 32908 32909 32910 32911 32912 32913 32914 32915 32916 32917 32918 32919 32920 32921 32922 32923 32924 32925 32926 32927 32928 32929 32930 32931 32932 32933 32934 32935 32936 32937 32938 32939 32940 32941 32942 32943 32944 32945 32946 32947 32948 32949 32950 32951 32952 32953 32954 32955 32956 32957 32958 32959 32960 32961 32962 32963 32964 32965 32966 32967 32968 32969 32970 32971 32972 32973 32974 32975 32976 32977 32978 32979 32980 32981 32982 32983 32984 32985 32986 32987 32988 32989 32990 32991 32992 32993 32994 32995 32996 32997 32998 32999 33000 33001 33002 33003 33004 33005 33006 33007 33008 33009 33010 33011 33012 33013 33014 33015 33016 33017 33018 33019 33020 33021 33022 33023 33024 33025 33026 33027 33028 33029 33030 33031 33032 33033 33034 33035 33036 33037 33038 33039 33040 33041 33042 33043 33044 33045 33046 33047 33048 33049 33050 33051 33052 33053 33054 33055 33056 33057 33058 33059 33060 33061 33062 33063 33064 33065 33066 33067 33068 33069 33070 33071 33072 33073 33074 33075 33076 33077 33078 33079 33080 33081 33082 33083 33084 33085 33086 33087 33088 33089 33090 33091 33092 33093 33094 33095 33096 33097 33098 33099 33100 33101 33102 33103 33104 33105 33106 33107 33108 33109 33110 33111 33112 33113 33114 33115 33116 33117 33118 33119 33120 33121 33122 33123 33124 33125 33126 33127 33128 33129 33130 33131 33132 33133 33134 33135 33136 33137 33138 33139 33140 33141 33142 33143 33144 33145 33146 33147 33148 33149 33150 33151 33152 33153 33154 33155 33156 33157 33158 33159 33160 33161 33162 33163 33164 33165 33166 33167 33168 33169 33170 33171 33172 33173 33174 33175 33176 33177 33178 33179 33180 33181 33182 33183 33184 33185 33186 33187 33188 33189 33190 33191 33192 33193 33194 33195 33196 33197 33198 33199 33200 33201 33202 33203 33204 33205 33206 33207 33208 33209 33210 33211 33212 33213 33214 33215 33216 33217 33218 33219 33220 33221 33222 33223 33224 33225 33226 33227 33228 33229 33230 33231 33232 33233 33234 33235 33236 33237 33238 33239 33240 33241 33242 33243 33244 33245 33246 33247 33248 33249 33250 33251 33252 33253 33254 33255 33256 33257 33258 33259 33260 33261 33262 33263 33264 33265 33266 33267 33268 33269 33270 33271 33272 33273 33274 33275 33276 33277 33278 33279 33280 33281 33282 33283 33284 33285 33286 33287 33288 33289 33290 33291 33292 33293 33294 33295 33296 33297 33298 33299 33300 33301 33302 33303 33304 33305 33306 33307 33308 33309 33310 33311 33312 33313 33314 33315 33316 33317 33318 33319 33320 33321 33322 33323 33324 33325 33326 33327 33328 33329 33330 33331 33332 33333 33334 33335 33336 33337 33338 33339 33340 33341 33342 33343 33344 33345 33346 33347 33348 33349 33350 33351 33352 33353 33354 33355 33356 33357 33358 33359 33360 33361 33362 33363 33364 33365 33366 33367 33368 33369 33370 33371 33372 33373 33374 33375 33376 33377 33378 33379 33380 33381 33382 33383 33384 33385 33386 33387 33388 33389 33390 33391 33392 33393 33394 33395 33396 33397 33398 33399 33400 33401 33402 33403 33404 33405 33406 33407 33408 33409 33410 33411 33412 33413 33414 33415 33416 33417 33418 33419 33420 33421 33422 33423 33424 33425 33426 33427 33428 33429 33430 33431 33432 33433 33434 33435 33436 33437 33438 33439 33440 33441 33442 33443 33444 33445 33446 33447 33448 33449 33450 33451 33452 33453 33454 33455 33456 33457 33458 33459 33460 33461 33462 33463 33464 33465 33466 33467 33468 33469 33470 33471 33472 33473 33474 33475 33476 33477 33478 33479 33480 33481 33482 33483 33484 33485 33486 33487 33488 33489 33490 33491 33492 33493 33494 33495 33496 33497 33498 33499 33500 33501 33502 33503 33504 33505 33506 33507 33508 33509 33510 33511 33512 33513 33514 33515 33516 33517 33518 33519 33520 33521 33522 33523 33524 33525 33526 33527 33528 33529 33530 33531 33532 33533 33534 33535 33536 33537 33538 33539 33540 33541 33542 33543 33544 33545 33546 33547 33548 33549 33550 33551 33552 33553 33554 33555 33556 33557 33558 33559 33560 33561 33562 33563 33564 33565 33566 33567 33568 33569 33570 33571 33572 33573 33574 33575 33576 33577 33578 33579 33580 33581 33582 33583 33584 33585 33586 33587 33588 33589 33590 33591 33592 33593 33594 33595 33596 33597 33598 33599 33600 33601 33602 33603 33604 33605 33606 33607 33608 33609 33610 33611 33612 33613 33614 33615 33616 33617 33618 33619 33620 33621 33622 33623 33624 33625 33626 33627 33628 33629 33630 33631 33632 33633 33634 33635 33636 33637 33638 33639 33640 33641 33642 33643 33644 33645 33646 33647 33648 33649 33650 33651 33652 33653 33654 33655 33656 33657 33658 33659 33660 33661 33662 33663 33664 33665 33666 33667 33668 33669 33670 33671 33672 33673 33674 33675 33676 33677 33678 33679 33680 33681 33682 33683 33684 33685 33686 33687 33688 33689 33690 33691 33692 33693 33694 33695 33696 33697 33698 33699 33700 33701 33702 33703 33704 33705 33706 33707 33708 33709 33710 33711 33712 33713 33714 33715 33716 33717 33718 33719 33720 33721 33722 33723 33724 33725 33726 33727 33728 33729 33730 33731 33732 33733 33734 33735 33736 33737 33738 33739 33740 33741 33742 33743 33744 33745 33746 33747 33748 33749 33750 33751 33752 33753 33754 33755 33756 33757 33758 33759 33760 33761 33762 33763 33764 33765 33766 33767 33768 33769 33770 33771 33772 33773 33774 33775 33776 33777 33778 33779 33780 33781 33782 33783 33784 33785 33786 33787 33788 33789 33790 33791 33792 33793 33794 33795 33796 33797 33798 33799 33800 33801 33802 33803 33804 33805 33806 33807 33808 33809 33810 33811 33812 33813 33814 33815 33816 33817 33818 33819 33820 33821 33822 33823 33824 33825 33826 33827 33828 33829 33830 33831 33832 33833 33834 33835 33836 33837 33838 33839 33840 33841 33842 33843 33844 33845 33846 33847 33848 33849 33850 33851 33852 33853 33854 33855 33856 33857 33858 33859 33860 33861 33862 33863 33864 33865 33866 33867 33868 33869 33870 33871 33872 33873 33874 33875 33876 33877 33878 33879 33880 33881 33882 33883 33884 33885 33886 33887 33888 33889 33890 33891 33892 33893 33894 33895 33896 33897 33898 33899 33900 33901 33902 33903 33904 33905 33906 33907 33908 33909 33910 33911 33912 33913 33914 33915 33916 33917 33918 33919 33920 33921 33922 33923 33924 33925 33926 33927 33928 33929 33930 33931 33932 33933 33934 33935 33936 33937 33938 33939 33940 33941 33942 33943 33944 33945 33946 33947 33948 33949 33950 33951 33952 33953 33954 33955 33956 33957 33958 33959 33960 33961 33962 33963 33964 33965 33966 33967 33968 33969 33970 33971 33972 33973 33974 33975 33976 33977 33978 33979 33980 33981 33982 33983 33984 33985 33986 33987 33988 33989 33990 33991 33992 33993 33994 33995 33996 33997 33998 33999 34000 34001 34002 34003 34004 34005 34006 34007 34008 34009 34010 34011 34012 34013 34014 34015 34016 34017 34018 34019 34020 34021 34022 34023 34024 34025 34026 34027 34028 34029 34030 34031 34032 34033 34034 34035 34036 34037 34038 34039 34040 34041 34042 34043 34044 34045 34046 34047 34048 34049 34050 34051 34052 34053 34054 34055 34056 34057 34058 34059 34060 34061 34062 34063 34064 34065 34066 34067 34068 34069 34070 34071 34072 34073 34074 34075 34076 34077 34078 34079 34080 34081 34082 34083 34084 34085 34086 34087 34088 34089 34090 34091 34092 34093 34094 34095 34096 34097 34098 34099 34100 34101 34102 34103 34104 34105 34106 34107 34108 34109 34110 34111 34112 34113 34114 34115 34116 34117 34118 34119 34120 34121 34122 34123 34124 34125 34126 34127 34128 34129 34130 34131 34132 34133 34134 34135 34136 34137 34138 34139 34140 34141 34142 34143 34144 34145 34146 34147 34148 34149 34150 34151 34152 34153 34154 34155 34156 34157 34158 34159 34160 34161 34162 34163 34164 34165 34166 34167 34168 34169 34170 34171 34172 34173 34174 34175 34176 34177 34178 34179 34180 34181 34182 34183 34184 34185 34186 34187 34188 34189 34190 34191 34192 34193 34194 34195 34196 34197 34198 34199 34200 34201 34202 34203 34204 34205 34206 34207 34208 34209 34210 34211 34212 34213 34214 34215 34216 34217 34218 34219 34220 34221 34222 34223 34224 34225 34226 34227 34228 34229 34230 34231 34232 34233 34234 34235 34236 34237 34238 34239 34240 34241 34242 34243 34244 34245 34246 34247 34248 34249 34250 34251 34252 34253 34254 34255 34256 34257 34258 34259 34260 34261 34262 34263 34264 34265 34266 34267 34268 34269 34270 34271 34272 34273 34274 34275 34276 34277 34278 34279 34280 34281 34282 34283 34284 34285 34286 34287 34288 34289 34290 34291 34292 34293 34294 34295 34296 34297 34298 34299 34300 34301 34302 34303 34304 34305 34306 34307 34308 34309 34310 34311 34312 34313 34314 34315 34316 34317 34318 34319 34320 34321 34322 34323 34324 34325 34326 34327 34328 34329 34330 34331 34332 34333 34334 34335 34336 34337 34338 34339 34340 34341 34342 34343 34344 34345 34346 34347 34348 34349 34350 34351 34352 34353 34354 34355 34356 34357 34358 34359 34360 34361 34362 34363 34364 34365 34366 34367 34368 34369 34370 34371 34372 34373 34374 34375 34376 34377 34378 34379 34380 34381 34382 34383 34384 34385 34386 34387 34388 34389 34390 34391 34392 34393 34394 34395 34396 34397 34398 34399 34400 34401 34402 34403 34404 34405 34406 34407 34408 34409 34410 34411 34412 34413 34414 34415 34416 34417 34418 34419 34420 34421 34422 34423 34424 34425 34426 34427 34428 34429 34430 34431 34432 34433 34434 34435 34436 34437 34438 34439 34440 34441 34442 34443 34444 34445 34446 34447 34448 34449 34450 34451 34452 34453 34454 34455 34456 34457 34458 34459 34460 34461 34462 34463 34464 34465 34466 34467 34468 34469 34470 34471 34472 34473 34474 34475 34476 34477 34478 34479 34480 34481 34482 34483 34484 34485 34486 34487 34488 34489 34490 34491 34492 34493 34494 34495 34496 34497 34498 34499 34500 34501 34502 34503 34504 34505 34506 34507 34508 34509 34510 34511 34512 34513 34514 34515 34516 34517 34518 34519 34520 34521 34522 34523 34524 34525 34526 34527 34528 34529 34530 34531 34532 34533 34534 34535 34536 34537 34538 34539 34540 34541 34542 34543 34544 34545 34546 34547 34548 34549 34550 34551 34552 34553 34554 34555 34556 34557 34558 34559 34560 34561 34562 34563 34564 34565 34566 34567 34568 34569 34570 34571 34572 34573 34574 34575 34576 34577 34578 34579 34580 34581 34582 34583 34584 34585 34586 34587 34588 34589 34590 34591 34592 34593 34594 34595 34596 34597 34598 34599 34600 34601 34602 34603 34604 34605 34606 34607 34608 34609 34610 34611 34612 34613 34614 34615 34616 34617 34618 34619 34620 34621 34622 34623 34624 34625 34626 34627 34628 34629 34630 34631 34632 34633 34634 34635 34636 34637 34638 34639 34640 34641 34642 34643 34644 34645 34646 34647 34648 34649 34650 34651 34652 34653 34654 34655 34656 34657 34658 34659 34660 34661 34662 34663 34664 34665 34666 34667 34668 34669 34670 34671 34672 34673 34674 34675 34676 34677 34678 34679 34680 34681 34682 34683 34684 34685 34686 34687 34688 34689 34690 34691 34692 34693 34694 34695 34696 34697 34698 34699 34700 34701 34702 34703 34704 34705 34706 34707 34708 34709 34710 34711 34712 34713 34714 34715 34716 34717 34718 34719 34720 34721 34722 34723 34724 34725 34726 34727 34728 34729 34730 34731 34732 34733 34734 34735 34736 34737 34738 34739 34740 34741 34742 34743 34744 34745 34746 34747 34748 34749 34750 34751 34752 34753 34754 34755 34756 34757 34758 34759 34760 34761 34762 34763 34764 34765 34766 34767 34768 34769 34770 34771 34772 34773 34774 34775 34776 34777 34778 34779 34780 34781 34782 34783 34784 34785 34786 34787 34788 34789 34790 34791 34792 34793 34794 34795 34796 34797 34798 34799 34800 34801 34802 34803 34804 34805 34806 34807 34808 34809 34810 34811 34812 34813 34814 34815 34816 34817 34818 34819 34820 34821 34822 34823 34824 34825 34826 34827 34828 34829 34830 34831 34832 34833 34834 34835 34836 34837 34838 34839 34840 34841 34842 34843 34844 34845 34846 34847 34848 34849 34850 34851 34852 34853 34854 34855 34856 34857 34858 34859 34860 34861 34862 34863 34864 34865 34866 34867 34868 34869 34870 34871 34872 34873 34874 34875 34876 34877 34878 34879 34880 34881 34882 34883 34884 34885 34886 34887 34888 34889 34890 34891 34892 34893 34894 34895 34896 34897 34898 34899 34900 34901 34902 34903 34904 34905 34906 34907 34908 34909 34910 34911 34912 34913 34914 34915 34916 34917 34918 34919 34920 34921 34922 34923 34924 34925 34926 34927 34928 34929 34930 34931 34932 34933 34934 34935 34936 34937 34938 34939 34940 34941 34942 34943 34944 34945 34946 34947 34948 34949 34950 34951 34952 34953 34954 34955 34956 34957 34958 34959 34960 34961 34962 34963 34964 34965 34966 34967 34968 34969 34970 34971 34972 34973 34974 34975 34976 34977 34978 34979 34980 34981 34982 34983 34984 34985 34986 34987 34988 34989 34990 34991 34992 34993 34994 34995 34996 34997 34998 34999 35000 35001 35002 35003 35004 35005 35006 35007 35008 35009 35010 35011 35012 35013 35014 35015 35016 35017 35018 35019 35020 35021 35022 35023 35024 35025 35026 35027 35028 35029 35030 35031 35032 35033 35034 35035 35036 35037 35038 35039 35040 35041 35042 35043 35044 35045 35046 35047 35048 35049 35050 35051 35052 35053 35054 35055 35056 35057 35058 35059 35060 35061 35062 35063 35064 35065 35066 35067 35068 35069 35070 35071 35072 35073 35074 35075 35076 35077 35078 35079 35080 35081 35082 35083 35084 35085 35086 35087 35088 35089 35090 35091 35092 35093 35094 35095 35096 35097 35098 35099 35100 35101 35102 35103 35104 35105 35106 35107 35108 35109 35110 35111 35112 35113 35114 35115 35116 35117 35118 35119 35120 35121 35122 35123 35124 35125 35126 35127 35128 35129 35130 35131 35132 35133 35134 35135 35136 35137 35138 35139 35140 35141 35142 35143 35144 35145 35146 35147 35148 35149 35150 35151 35152 35153 35154 35155 35156 35157 35158 35159 35160 35161 35162 35163 35164 35165 35166 35167 35168 35169 35170 35171 35172 35173 35174 35175 35176 35177 35178 35179 35180 35181 35182 35183 35184 35185 35186 35187 35188 35189 35190 35191 35192 35193 35194 35195 35196 35197 35198 35199 35200 35201 35202 35203 35204 35205 35206 35207 35208 35209 35210 35211 35212 35213 35214 35215 35216 35217 35218 35219 35220 35221 35222 35223 35224 35225 35226 35227 35228 35229 35230 35231 35232 35233 35234 35235 35236 35237 35238 35239 35240 35241 35242 35243 35244 35245 35246 35247 35248 35249 35250 35251 35252 35253 35254 35255 35256 35257 35258 35259 35260 35261 35262 35263 35264 35265 35266 35267 35268 35269 35270 35271 35272 35273 35274 35275 35276 35277 35278 35279 35280 35281 35282 35283 35284 35285 35286 35287 35288 35289 35290 35291 35292 35293 35294 35295 35296 35297 35298 35299 35300 35301 35302 35303 35304 35305 35306 35307 35308 35309 35310 35311 35312 35313 35314 35315 35316 35317 35318 35319 35320 35321 35322 35323 35324 35325 35326 35327 35328 35329 35330 35331 35332 35333 35334 35335 35336 35337 35338 35339 35340 35341 35342 35343 35344 35345 35346 35347 35348 35349 35350 35351 35352 35353 35354 35355 35356 35357 35358 35359 35360 35361 35362 35363 35364 35365 35366 35367 35368 35369 35370 35371 35372 35373 35374 35375 35376 35377 35378 35379 35380 35381 35382 35383 35384 35385 35386 35387 35388 35389 35390 35391 35392 35393 35394 35395 35396 35397 35398 35399 35400 35401 35402 35403 35404 35405 35406 35407 35408 35409 35410 35411 35412 35413 35414 35415 35416 35417 35418 35419 35420 35421 35422 35423 35424 35425 35426 35427 35428 35429 35430 35431 35432 35433 35434 35435 35436 35437 35438 35439 35440 35441 35442 35443 35444 35445 35446 35447 35448 35449 35450 35451 35452 35453 35454 35455 35456 35457 35458 35459 35460 35461 35462 35463 35464 35465 35466 35467 35468 35469 35470 35471 35472 35473 35474 35475 35476 35477 35478 35479 35480 35481 35482 35483 35484 35485 35486 35487 35488 35489 35490 35491 35492 35493 35494 35495 35496 35497 35498 35499 35500 35501 35502 35503 35504 35505 35506 35507 35508 35509 35510 35511 35512 35513 35514 35515 35516 35517 35518 35519 35520 35521 35522 35523 35524 35525 35526 35527 35528 35529 35530 35531 35532 35533 35534 35535 35536 35537 35538 35539 35540 35541 35542 35543 35544 35545 35546 35547 35548 35549 35550 35551 35552 35553 35554 35555 35556 35557 35558 35559 35560 35561 35562 35563 35564 35565 35566 35567 35568 35569 35570 35571 35572 35573 35574 35575 35576 35577 35578 35579 35580 35581 35582 35583 35584 35585 35586 35587 35588 35589 35590 35591 35592 35593 35594 35595 35596 35597 35598 35599 35600 35601 35602 35603 35604 35605 35606 35607 35608 35609 35610 35611 35612 35613 35614 35615 35616 35617 35618 35619 35620 35621 35622 35623 35624 35625 35626 35627 35628 35629 35630 35631 35632 35633 35634 35635 35636 35637 35638 35639 35640 35641 35642 35643 35644 35645 35646 35647 35648 35649 35650 35651 35652 35653 35654 35655 35656 35657 35658 35659 35660 35661 35662 35663 35664 35665 35666 35667 35668 35669 35670 35671 35672 35673 35674 35675 35676 35677 35678 35679 35680 35681 35682 35683 35684 35685 35686 35687 35688 35689 35690 35691 35692 35693 35694 35695 35696 35697 35698 35699 35700 35701 35702 35703 35704 35705 35706 35707 35708 35709 35710 35711 35712 35713 35714 35715 35716 35717 35718 35719 35720 35721 35722 35723 35724 35725 35726 35727 35728 35729 35730 35731 35732 35733 35734 35735 35736 35737 35738 35739 35740 35741 35742 35743 35744 35745 35746 35747 35748 35749 35750 35751 35752 35753 35754 35755 35756 35757 35758 35759 35760 35761 35762 35763 35764 35765 35766 35767 35768 35769 35770 35771 35772 35773 35774 35775 35776 35777 35778 35779 35780 35781 35782 35783 35784 35785 35786 35787 35788 35789 35790 35791 35792 35793 35794 35795 35796 35797 35798 35799 35800 35801 35802 35803 35804 35805 35806 35807 35808 35809 35810 35811 35812 35813 35814 35815 35816 35817 35818 35819 35820 35821 35822 35823 35824 35825 35826 35827 35828 35829 35830 35831 35832 35833 35834 35835 35836 35837 35838 35839 35840 35841 35842 35843 35844 35845 35846 35847 35848 35849 35850 35851 35852 35853 35854 35855 35856 35857 35858 35859 35860 35861 35862 35863 35864 35865 35866 35867 35868 35869 35870 35871 35872 35873 35874 35875 35876 35877 35878 35879 35880 35881 35882 35883 35884 35885 35886 35887 35888 35889 35890 35891 35892 35893 35894 35895 35896 35897 35898 35899 35900 35901 35902 35903 35904 35905 35906 35907 35908 35909 35910 35911 35912 35913 35914 35915 35916 35917 35918 35919 35920 35921 35922 35923 35924 35925 35926 35927 35928 35929 35930 35931 35932 35933 35934 35935 35936 35937 35938 35939 35940 35941 35942 35943 35944 35945 35946 35947 35948 35949 35950 35951 35952 35953 35954 35955 35956 35957 35958 35959 35960 35961 35962 35963 35964 35965 35966 35967 35968 35969 35970 35971 35972 35973 35974 35975 35976 35977 35978 35979 35980 35981 35982 35983 35984 35985 35986 35987 35988 35989 35990 35991 35992 35993 35994 35995 35996 35997 35998 35999 36000 36001 36002 36003 36004 36005 36006 36007 36008 36009 36010 36011 36012 36013 36014 36015 36016 36017 36018 36019 36020 36021 36022 36023 36024 36025 36026 36027 36028 36029 36030 36031 36032 36033 36034 36035 36036 36037 36038 36039 36040 36041 36042 36043 36044 36045 36046 36047 36048 36049 36050 36051 36052 36053 36054 36055 36056 36057 36058 36059 36060 36061 36062 36063 36064 36065 36066 36067 36068 36069 36070 36071 36072 36073 36074 36075 36076 36077 36078 36079 36080 36081 36082 36083 36084 36085 36086 36087 36088 36089 36090 36091 36092 36093 36094 36095 36096 36097 36098 36099 36100 36101 36102 36103 36104 36105 36106 36107 36108 36109 36110 36111 36112 36113 36114 36115 36116 36117 36118 36119 36120 36121 36122 36123 36124 36125 36126 36127 36128 36129 36130 36131 36132 36133 36134 36135 36136 36137 36138 36139 36140 36141 36142 36143 36144 36145 36146 36147 36148 36149 36150 36151 36152 36153 36154 36155 36156 36157 36158 36159 36160 36161 36162 36163 36164 36165 36166 36167 36168 36169 36170 36171 36172 36173 36174 36175 36176 36177 36178 36179 36180 36181 36182 36183 36184 36185 36186 36187 36188 36189 36190 36191 36192 36193 36194 36195 36196 36197 36198 36199 36200 36201 36202 36203 36204 36205 36206 36207 36208 36209 36210 36211 36212 36213 36214 36215 36216 36217 36218 36219 36220 36221 36222 36223 36224 36225 36226 36227 36228 36229 36230 36231 36232 36233 36234 36235 36236 36237 36238 36239 36240 36241 36242 36243 36244 36245 36246 36247 36248 36249 36250 36251 36252 36253 36254 36255 36256 36257 36258 36259 36260 36261 36262 36263 36264 36265 36266 36267 36268 36269 36270 36271 36272 36273 36274 36275 36276 36277 36278 36279 36280 36281 36282 36283 36284 36285 36286 36287 36288 36289 36290 36291 36292 36293 36294 36295 36296 36297 36298 36299 36300 36301 36302 36303 36304 36305 36306 36307 36308 36309 36310 36311 36312 36313 36314 36315 36316 36317 36318 36319 36320 36321 36322 36323 36324 36325 36326 36327 36328 36329 36330 36331 36332 36333 36334 36335 36336 36337 36338 36339 36340 36341 36342 36343 36344 36345 36346 36347 36348 36349 36350 36351 36352 36353 36354 36355 36356 36357 36358 36359 36360 36361 36362 36363 36364 36365 36366 36367 36368 36369 36370 36371 36372 36373 36374 36375 36376 36377 36378 36379 36380 36381 36382 36383 36384 36385 36386 36387 36388 36389 36390 36391 36392 36393 36394 36395 36396 36397 36398 36399 36400 36401 36402 36403 36404 36405 36406 36407 36408 36409 36410 36411 36412 36413 36414 36415 36416 36417 36418 36419 36420 36421 36422 36423 36424 36425 36426 36427 36428 36429 36430 36431 36432 36433 36434 36435 36436 36437 36438 36439 36440 36441 36442 36443 36444 36445 36446 36447 36448 36449 36450 36451 36452 36453 36454 36455 36456 36457 36458 36459 36460 36461 36462 36463 36464 36465 36466 36467 36468 36469 36470 36471 36472 36473 36474 36475 36476 36477 36478 36479 36480 36481 36482 36483 36484 36485 36486 36487 36488 36489 36490 36491 36492 36493 36494 36495 36496 36497 36498 36499 36500 36501 36502 36503 36504 36505 36506 36507 36508 36509 36510 36511 36512 36513 36514 36515 36516 36517 36518 36519 36520 36521 36522 36523 36524 36525 36526 36527 36528 36529 36530 36531 36532 36533 36534 36535 36536 36537 36538 36539 36540 36541 36542 36543 36544 36545 36546 36547 36548 36549 36550 36551 36552 36553 36554 36555 36556 36557 36558 36559 36560 36561 36562 36563 36564 36565 36566 36567 36568 36569 36570 36571 36572 36573 36574 36575 36576 36577 36578 36579 36580 36581 36582 36583 36584 36585 36586 36587 36588 36589 36590 36591 36592 36593 36594 36595 36596 36597 36598 36599 36600 36601 36602 36603 36604 36605 36606 36607 36608 36609 36610 36611 36612 36613 36614 36615 36616 36617 36618 36619 36620 36621 36622 36623 36624 36625 36626 36627 36628 36629 36630 36631 36632 36633 36634 36635 36636 36637 36638 36639 36640 36641 36642 36643 36644 36645 36646 36647 36648 36649 36650 36651 36652 36653 36654 36655 36656 36657 36658 36659 36660 36661 36662 36663 36664 36665 36666 36667 36668 36669 36670 36671 36672 36673 36674 36675 36676 36677 36678 36679 36680 36681 36682 36683 36684 36685 36686 36687 36688 36689 36690 36691 36692 36693 36694 36695 36696 36697 36698 36699 36700 36701 36702 36703 36704 36705 36706 36707 36708 36709 36710 36711 36712 36713 36714 36715 36716 36717 36718 36719 36720 36721 36722 36723 36724 36725 36726 36727 36728 36729 36730 36731 36732 36733 36734 36735 36736 36737 36738 36739 36740 36741 36742 36743 36744 36745 36746 36747 36748 36749 36750 36751 36752 36753 36754 36755 36756 36757 36758 36759 36760 36761 36762 36763 36764 36765 36766 36767 36768 36769 36770 36771 36772 36773 36774 36775 36776 36777 36778 36779 36780 36781 36782 36783 36784 36785 36786 36787 36788 36789 36790 36791 36792 36793 36794 36795 36796 36797 36798 36799 36800 36801 36802 36803 36804 36805 36806 36807 36808 36809 36810 36811 36812 36813 36814 36815 36816 36817 36818 36819 36820 36821 36822 36823 36824 36825 36826 36827 36828 36829 36830 36831 36832 36833 36834 36835 36836 36837 36838 36839 36840 36841 36842 36843 36844 36845 36846 36847 36848 36849 36850 36851 36852 36853 36854 36855 36856 36857 36858 36859 36860 36861 36862 36863 36864 36865 36866 36867 36868 36869 36870 36871 36872 36873 36874 36875 36876 36877 36878 36879 36880 36881 36882 36883 36884 36885 36886 36887 36888 36889 36890 36891 36892 36893 36894 36895 36896 36897 36898 36899 36900 36901 36902 36903 36904 36905 36906 36907 36908 36909 36910 36911 36912 36913 36914 36915 36916 36917 36918 36919 36920 36921 36922 36923 36924 36925 36926 36927 36928 36929 36930 36931 36932 36933 36934 36935 36936 36937 36938 36939 36940 36941 36942 36943 36944 36945 36946 36947 36948 36949 36950 36951 36952 36953 36954 36955 36956 36957 36958 36959 36960 36961 36962 36963 36964 36965 36966 36967 36968 36969 36970 36971 36972 36973 36974 36975 36976 36977 36978 36979 36980 36981 36982 36983 36984 36985 36986 36987 36988 36989 36990 36991 36992 36993 36994 36995 36996 36997 36998 36999 37000 37001 37002 37003 37004 37005 37006 37007 37008 37009 37010 37011 37012 37013 37014 37015 37016 37017 37018 37019 37020 37021 37022 37023 37024 37025 37026 37027 37028 37029 37030 37031 37032 37033 37034 37035 37036 37037 37038 37039 37040 37041 37042 37043 37044 37045 37046 37047 37048 37049 37050 37051 37052 37053 37054 37055 37056 37057 37058 37059 37060 37061 37062 37063 37064 37065 37066 37067 37068 37069 37070 37071 37072 37073 37074 37075 37076 37077 37078 37079 37080 37081 37082 37083 37084 37085 37086 37087 37088 37089 37090 37091 37092 37093 37094 37095 37096 37097 37098 37099 37100 37101 37102 37103 37104 37105 37106 37107 37108 37109 37110 37111 37112 37113 37114 37115 37116 37117 37118 37119 37120 37121 37122 37123 37124 37125 37126 37127 37128 37129 37130 37131 37132 37133 37134 37135 37136 37137 37138 37139 37140 37141 37142 37143 37144 37145 37146 37147 37148 37149 37150 37151 37152 37153 37154 37155 37156 37157 37158 37159 37160 37161 37162 37163 37164 37165 37166 37167 37168 37169 37170 37171 37172 37173 37174 37175 37176 37177 37178 37179 37180 37181 37182 37183 37184 37185 37186 37187 37188 37189 37190 37191 37192 37193 37194 37195 37196 37197 37198 37199 37200 37201 37202 37203 37204 37205 37206 37207 37208 37209 37210 37211 37212 37213 37214 37215 37216 37217 37218 37219 37220 37221 37222 37223 37224 37225 37226 37227 37228 37229 37230 37231 37232 37233 37234 37235 37236 37237 37238 37239 37240 37241 37242 37243 37244 37245 37246 37247 37248 37249 37250 37251 37252 37253 37254 37255 37256 37257 37258 37259 37260 37261 37262 37263 37264 37265 37266 37267 37268 37269 37270 37271 37272 37273 37274 37275 37276 37277 37278 37279 37280 37281 37282 37283 37284 37285 37286 37287 37288 37289 37290 37291 37292 37293 37294 37295 37296 37297 37298 37299 37300 37301 37302 37303 37304 37305 37306 37307 37308 37309 37310 37311 37312 37313 37314 37315 37316 37317 37318 37319 37320 37321 37322 37323 37324 37325 37326 37327 37328 37329 37330 37331 37332 37333 37334 37335 37336 37337 37338 37339 37340 37341 37342 37343 37344 37345 37346 37347 37348 37349 37350 37351 37352 37353 37354 37355 37356 37357 37358 37359 37360 37361 37362 37363 37364 37365 37366 37367 37368 37369 37370 37371 37372 37373 37374 37375 37376 37377 37378 37379 37380 37381 37382 37383 37384 37385 37386 37387 37388 37389 37390 37391 37392 37393 37394 37395 37396 37397 37398 37399 37400 37401 37402 37403 37404 37405 37406 37407 37408 37409 37410 37411 37412 37413 37414 37415 37416 37417 37418 37419 37420 37421 37422 37423 37424 37425 37426 37427 37428 37429 37430 37431 37432 37433 37434 37435 37436 37437 37438 37439 37440 37441 37442 37443 37444 37445 37446 37447 37448 37449 37450 37451 37452 37453 37454 37455 37456 37457 37458 37459 37460 37461 37462 37463 37464 37465 37466 37467 37468 37469 37470 37471 37472 37473 37474 37475 37476 37477 37478 37479 37480 37481 37482 37483 37484 37485 37486 37487 37488 37489 37490 37491 37492 37493 37494 37495 37496 37497 37498 37499 37500 37501 37502 37503 37504 37505 37506 37507 37508 37509 37510 37511 37512 37513 37514 37515 37516 37517 37518 37519 37520 37521 37522 37523 37524 37525 37526 37527 37528 37529 37530 37531 37532 37533 37534 37535 37536 37537 37538 37539 37540 37541 37542 37543 37544 37545 37546 37547 37548 37549 37550 37551 37552 37553 37554 37555 37556 37557 37558 37559 37560 37561 37562 37563 37564 37565 37566 37567 37568 37569 37570 37571 37572 37573 37574 37575 37576 37577 37578 37579 37580 37581 37582 37583 37584 37585 37586 37587 37588 37589 37590 37591 37592 37593 37594 37595 37596 37597 37598 37599 37600 37601 37602 37603 37604 37605 37606 37607 37608 37609 37610 37611 37612 37613 37614 37615 37616 37617 37618 37619 37620 37621 37622 37623 37624 37625 37626 37627 37628 37629 37630 37631 37632 37633 37634 37635 37636 37637 37638 37639 37640 37641 37642 37643 37644 37645 37646 37647 37648 37649 37650 37651 37652 37653 37654 37655 37656 37657 37658 37659 37660 37661 37662 37663 37664 37665 37666 37667 37668 37669 37670 37671 37672 37673 37674 37675 37676 37677 37678 37679 37680 37681 37682 37683 37684 37685 37686 37687 37688 37689 37690 37691 37692 37693 37694 37695 37696 37697 37698 37699 37700 37701 37702 37703 37704 37705 37706 37707 37708 37709 37710 37711 37712 37713 37714 37715 37716 37717 37718 37719 37720 37721 37722 37723 37724 37725 37726 37727 37728 37729 37730 37731 37732 37733 37734 37735 37736 37737 37738 37739 37740 37741 37742 37743 37744 37745 37746 37747 37748 37749 37750 37751 37752 37753 37754 37755 37756 37757 37758 37759 37760 37761 37762 37763 37764 37765 37766 37767 37768 37769 37770 37771 37772 37773 37774 37775 37776 37777 37778 37779 37780 37781 37782 37783 37784 37785 37786 37787 37788 37789 37790 37791 37792 37793 37794 37795 37796 37797 37798 37799 37800 37801 37802 37803 37804 37805 37806 37807 37808 37809 37810 37811 37812 37813 37814 37815 37816 37817 37818 37819 37820 37821 37822 37823 37824 37825 37826 37827 37828 37829 37830 37831 37832 37833 37834 37835 37836 37837 37838 37839 37840 37841 37842 37843 37844 37845 37846 37847 37848 37849 37850 37851 37852 37853 37854 37855 37856 37857 37858 37859 37860 37861 37862 37863 37864 37865 37866 37867 37868 37869 37870 37871 37872 37873 37874 37875 37876 37877 37878 37879 37880 37881 37882 37883 37884 37885 37886 37887 37888 37889 37890 37891 37892 37893 37894 37895 37896 37897 37898 37899 37900 37901 37902 37903 37904 37905 37906 37907 37908 37909 37910 37911 37912 37913 37914 37915 37916 37917 37918 37919 37920 37921 37922 37923 37924 37925 37926 37927 37928 37929 37930 37931 37932 37933 37934 37935 37936 37937 37938 37939 37940 37941 37942 37943 37944 37945 37946 37947 37948 37949 37950 37951 37952 37953 37954 37955 37956 37957 37958 37959 37960 37961 37962 37963 37964 37965 37966 37967 37968 37969 37970 37971 37972 37973 37974 37975 37976 37977 37978 37979 37980 37981 37982 37983 37984 37985 37986 37987 37988 37989 37990 37991 37992 37993 37994 37995 37996 37997 37998 37999 38000 38001 38002 38003 38004 38005 38006 38007 38008 38009 38010 38011 38012 38013 38014 38015 38016 38017 38018 38019 38020 38021 38022 38023 38024 38025 38026 38027 38028 38029 38030 38031 38032 38033 38034 38035 38036 38037 38038 38039 38040 38041 38042 38043 38044 38045 38046 38047 38048 38049 38050 38051 38052 38053 38054 38055 38056 38057 38058 38059 38060 38061 38062 38063 38064 38065 38066 38067 38068 38069 38070 38071 38072 38073 38074 38075 38076 38077 38078 38079 38080 38081 38082 38083 38084 38085 38086 38087 38088 38089 38090 38091 38092 38093 38094 38095 38096 38097 38098 38099 38100 38101 38102 38103 38104 38105 38106 38107 38108 38109 38110 38111 38112 38113 38114 38115 38116 38117 38118 38119 38120 38121 38122 38123 38124 38125 38126 38127 38128 38129 38130 38131 38132 38133 38134 38135 38136 38137 38138 38139 38140 38141 38142 38143 38144 38145 38146 38147 38148 38149 38150 38151 38152 38153 38154 38155 38156 38157 38158 38159 38160 38161 38162 38163 38164 38165 38166 38167 38168 38169 38170 38171 38172 38173 38174 38175 38176 38177 38178 38179 38180 38181 38182 38183 38184 38185 38186 38187 38188 38189 38190 38191 38192 38193 38194 38195 38196 38197 38198 38199 38200 38201 38202 38203 38204 38205 38206 38207 38208 38209 38210 38211 38212 38213 38214 38215 38216 38217 38218 38219 38220 38221 38222 38223 38224 38225 38226 38227 38228 38229 38230 38231 38232 38233 38234 38235 38236 38237 38238 38239 38240 38241 38242 38243 38244 38245 38246 38247 38248 38249 38250 38251 38252 38253 38254 38255 38256 38257 38258 38259 38260 38261 38262 38263 38264 38265 38266 38267 38268 38269 38270 38271 38272 38273 38274 38275 38276 38277 38278 38279 38280 38281 38282 38283 38284 38285 38286 38287 38288 38289 38290 38291 38292 38293 38294 38295 38296 38297 38298 38299 38300 38301 38302 38303 38304 38305 38306 38307 38308 38309 38310 38311 38312 38313 38314 38315 38316 38317 38318 38319 38320 38321 38322 38323 38324 38325 38326 38327 38328 38329 38330 38331 38332 38333 38334 38335 38336 38337 38338 38339 38340 38341 38342 38343 38344 38345 38346 38347 38348 38349 38350 38351 38352 38353 38354 38355 38356 38357 38358 38359 38360 38361 38362 38363 38364 38365 38366 38367 38368 38369 38370 38371 38372 38373 38374 38375 38376 38377 38378 38379 38380 38381 38382 38383 38384 38385 38386 38387 38388 38389 38390 38391 38392 38393 38394 38395 38396 38397 38398 38399 38400 38401 38402 38403 38404 38405 38406 38407 38408 38409 38410 38411 38412 38413 38414 38415 38416 38417 38418 38419 38420 38421 38422 38423 38424 38425 38426 38427 38428 38429 38430 38431 38432 38433 38434 38435 38436 38437 38438 38439 38440 38441 38442 38443 38444 38445 38446 38447 38448 38449 38450 38451 38452 38453 38454 38455 38456 38457 38458 38459 38460 38461 38462 38463 38464 38465 38466 38467 38468 38469 38470 38471 38472 38473 38474 38475 38476 38477 38478 38479 38480 38481 38482 38483 38484 38485 38486 38487 38488 38489 38490 38491 38492 38493 38494 38495 38496 38497 38498 38499 38500 38501 38502 38503 38504 38505 38506 38507 38508 38509 38510 38511 38512 38513 38514 38515 38516 38517 38518 38519 38520 38521 38522 38523 38524 38525 38526 38527 38528 38529 38530 38531 38532 38533 38534 38535 38536 38537 38538 38539 38540 38541 38542 38543 38544 38545 38546 38547 38548 38549 38550 38551 38552 38553 38554 38555 38556 38557 38558 38559 38560 38561 38562 38563 38564 38565 38566 38567 38568 38569 38570 38571 38572 38573 38574 38575 38576 38577 38578 38579 38580 38581 38582 38583 38584 38585 38586 38587 38588 38589 38590 38591 38592 38593 38594 38595 38596 38597 38598 38599 38600 38601 38602 38603 38604 38605 38606 38607 38608 38609 38610 38611 38612 38613 38614 38615 38616 38617 38618 38619 38620 38621 38622 38623 38624 38625 38626 38627 38628 38629 38630 38631 38632 38633 38634 38635 38636 38637 38638 38639 38640 38641 38642 38643 38644 38645 38646 38647 38648 38649 38650 38651 38652 38653 38654 38655 38656 38657 38658 38659 38660 38661 38662 38663 38664 38665 38666 38667 38668 38669 38670 38671 38672 38673 38674 38675 38676 38677 38678 38679 38680 38681 38682 38683 38684 38685 38686 38687 38688 38689 38690 38691 38692 38693 38694 38695 38696 38697 38698 38699 38700 38701 38702 38703 38704 38705 38706 38707 38708 38709 38710 38711 38712 38713 38714 38715 38716 38717 38718 38719 38720 38721 38722 38723 38724 38725 38726 38727 38728 38729 38730 38731 38732 38733 38734 38735 38736 38737 38738 38739 38740 38741 38742 38743 38744 38745 38746 38747 38748 38749 38750 38751 38752 38753 38754 38755 38756 38757 38758 38759 38760 38761 38762 38763 38764 38765 38766 38767 38768 38769 38770 38771 38772 38773 38774 38775 38776 38777 38778 38779 38780 38781 38782 38783 38784 38785 38786 38787 38788 38789 38790 38791 38792 38793 38794 38795 38796 38797 38798 38799 38800 38801 38802 38803 38804 38805 38806 38807 38808 38809 38810 38811 38812 38813 38814 38815 38816 38817 38818 38819 38820 38821 38822 38823 38824 38825 38826 38827 38828 38829 38830 38831 38832 38833 38834 38835 38836 38837 38838 38839 38840 38841 38842 38843 38844 38845 38846 38847 38848 38849 38850 38851 38852 38853 38854 38855 38856 38857 38858 38859 38860 38861 38862 38863 38864 38865 38866 38867 38868 38869 38870 38871 38872 38873 38874 38875 38876 38877 38878 38879 38880 38881 38882 38883 38884 38885 38886 38887 38888 38889 38890 38891 38892 38893 38894 38895 38896 38897 38898 38899 38900 38901 38902 38903 38904 38905 38906 38907 38908 38909 38910 38911 38912 38913 38914 38915 38916 38917 38918 38919 38920 38921 38922 38923 38924 38925 38926 38927 38928 38929 38930 38931 38932 38933 38934 38935 38936 38937 38938 38939 38940 38941 38942 38943 38944 38945 38946 38947 38948 38949 38950 38951 38952 38953 38954 38955 38956 38957 38958 38959 38960 38961 38962 38963 38964 38965 38966 38967 38968 38969 38970 38971 38972 38973 38974 38975 38976 38977 38978 38979 38980 38981 38982 38983 38984 38985 38986 38987 38988 38989 38990 38991 38992 38993 38994 38995 38996 38997 38998 38999 39000 39001 39002 39003 39004 39005 39006 39007 39008 39009 39010 39011 39012 39013 39014 39015 39016 39017 39018 39019 39020 39021 39022 39023 39024 39025 39026 39027 39028 39029 39030 39031 39032 39033 39034 39035 39036 39037 39038 39039 39040 39041 39042 39043 39044 39045 39046 39047 39048 39049 39050 39051 39052 39053 39054 39055 39056 39057 39058 39059 39060 39061 39062 39063 39064 39065 39066 39067 39068 39069 39070 39071 39072 39073 39074 39075 39076 39077 39078 39079 39080 39081 39082 39083 39084 39085 39086 39087 39088 39089 39090 39091 39092 39093 39094 39095 39096 39097 39098 39099 39100 39101 39102 39103 39104 39105 39106 39107 39108 39109 39110 39111 39112 39113 39114 39115 39116 39117 39118 39119 39120 39121 39122 39123 39124 39125 39126 39127 39128 39129 39130 39131 39132 39133 39134 39135 39136 39137 39138 39139 39140 39141 39142 39143 39144 39145 39146 39147 39148 39149 39150 39151 39152 39153 39154 39155 39156 39157 39158 39159 39160 39161 39162 39163 39164 39165 39166 39167 39168 39169 39170 39171 39172 39173 39174 39175 39176 39177 39178 39179 39180 39181 39182 39183 39184 39185 39186 39187 39188 39189 39190 39191 39192 39193 39194 39195 39196 39197 39198 39199 39200 39201 39202 39203 39204 39205 39206 39207 39208 39209 39210 39211 39212 39213 39214 39215 39216 39217 39218 39219 39220 39221 39222 39223 39224 39225 39226 39227 39228 39229 39230 39231 39232 39233 39234 39235 39236 39237 39238 39239 39240 39241 39242 39243 39244 39245 39246 39247 39248 39249 39250 39251 39252 39253 39254 39255 39256 39257 39258 39259 39260 39261 39262 39263 39264 39265 39266 39267 39268 39269 39270 39271 39272 39273 39274 39275 39276 39277 39278 39279 39280 39281 39282 39283 39284 39285 39286 39287 39288 39289 39290 39291 39292 39293 39294 39295 39296 39297 39298 39299 39300 39301 39302 39303 39304 39305 39306 39307 39308 39309 39310 39311 39312 39313 39314 39315 39316 39317 39318 39319 39320 39321 39322 39323 39324 39325 39326 39327 39328 39329 39330 39331 39332 39333 39334 39335 39336 39337 39338 39339 39340 39341 39342 39343 39344 39345 39346 39347 39348 39349 39350 39351 39352 39353 39354 39355 39356 39357 39358 39359 39360 39361 39362 39363 39364 39365 39366 39367 39368 39369 39370 39371 39372 39373 39374 39375 39376 39377 39378 39379 39380 39381 39382 39383 39384 39385 39386 39387 39388 39389 39390 39391 39392 39393 39394 39395 39396 39397 39398 39399 39400 39401 39402 39403 39404 39405 39406 39407 39408 39409 39410 39411 39412 39413 39414 39415 39416 39417 39418 39419 39420 39421 39422 39423 39424 39425 39426 39427 39428 39429 39430 39431 39432 39433 39434 39435 39436 39437 39438 39439 39440 39441 39442 39443 39444 39445 39446 39447 39448 39449 39450 39451 39452 39453 39454 39455 39456 39457 39458 39459 39460 39461 39462 39463 39464 39465 39466 39467 39468 39469 39470 39471 39472 39473 39474 39475 39476 39477 39478 39479 39480 39481 39482 39483 39484 39485 39486 39487 39488 39489 39490 39491 39492 39493 39494 39495 39496 39497 39498 39499 39500 39501 39502 39503 39504 39505 39506 39507 39508 39509 39510 39511 39512 39513 39514 39515 39516 39517 39518 39519 39520 39521 39522 39523 39524 39525 39526 39527 39528 39529 39530 39531 39532 39533 39534 39535 39536 39537 39538 39539 39540 39541 39542 39543 39544 39545 39546 39547 39548 39549 39550 39551 39552 39553 39554 39555 39556 39557 39558 39559 39560 39561 39562 39563 39564 39565 39566 39567 39568 39569 39570 39571 39572 39573 39574 39575 39576 39577 39578 39579 39580 39581 39582 39583 39584 39585 39586 39587 39588 39589 39590 39591 39592 39593 39594 39595 39596 39597 39598 39599 39600 39601 39602 39603 39604 39605 39606 39607 39608 39609 39610 39611 39612 39613 39614 39615 39616 39617 39618 39619 39620 39621 39622 39623 39624 39625 39626 39627 39628 39629 39630 39631 39632 39633 39634 39635 39636 39637 39638 39639 39640 39641 39642 39643 39644 39645 39646 39647 39648 39649 39650 39651 39652 39653 39654 39655 39656 39657 39658 39659 39660 39661 39662 39663 39664 39665 39666 39667 39668 39669 39670 39671 39672 39673 39674 39675 39676 39677 39678 39679 39680 39681 39682 39683 39684 39685 39686 39687 39688 39689 39690 39691 39692 39693 39694 39695 39696 39697 39698 39699 39700 39701 39702 39703 39704 39705 39706 39707 39708 39709 39710 39711 39712 39713 39714 39715 39716 39717 39718 39719 39720 39721 39722 39723 39724 39725 39726 39727 39728 39729 39730 39731 39732 39733 39734 39735 39736 39737 39738 39739 39740 39741 39742 39743 39744 39745 39746 39747 39748 39749 39750 39751 39752 39753 39754 39755 39756 39757 39758 39759 39760 39761 39762 39763 39764 39765 39766 39767 39768 39769 39770 39771 39772 39773 39774 39775 39776 39777 39778 39779 39780 39781 39782 39783 39784 39785 39786 39787 39788 39789 39790 39791 39792 39793 39794 39795 39796 39797 39798 39799 39800 39801 39802 39803 39804 39805 39806 39807 39808 39809 39810 39811 39812 39813 39814 39815 39816 39817 39818 39819 39820 39821 39822 39823 39824 39825 39826 39827 39828 39829 39830 39831 39832 39833 39834 39835 39836 39837 39838 39839 39840 39841 39842 39843 39844 39845 39846 39847 39848 39849 39850 39851 39852 39853 39854 39855 39856 39857 39858 39859 39860 39861 39862 39863 39864 39865 39866 39867 39868 39869 39870 39871 39872 39873 39874 39875 39876 39877 39878 39879 39880 39881 39882 39883 39884 39885 39886 39887 39888 39889 39890 39891 39892 39893 39894 39895 39896 39897 39898 39899 39900 39901 39902 39903 39904 39905 39906 39907 39908 39909 39910 39911 39912 39913 39914 39915 39916 39917 39918 39919 39920 39921 39922 39923 39924 39925 39926 39927 39928 39929 39930 39931 39932 39933 39934 39935 39936 39937 39938 39939 39940 39941 39942 39943 39944 39945 39946 39947 39948 39949 39950 39951 39952 39953 39954 39955 39956 39957 39958 39959 39960 39961 39962 39963 39964 39965 39966 39967 39968 39969 39970 39971 39972 39973 39974 39975 39976 39977 39978 39979 39980 39981 39982 39983 39984 39985 39986 39987 39988 39989 39990 39991 39992 39993 39994 39995 39996 39997 39998 39999 40000 40001 40002 40003 40004 40005 40006 40007 40008 40009 40010 40011 40012 40013 40014 40015 40016 40017 40018 40019 40020 40021 40022 40023 40024 40025 40026 40027 40028 40029 40030 40031 40032 40033 40034 40035 40036 40037 40038 40039 40040 40041 40042 40043 40044 40045 40046 40047 40048 40049 40050 40051 40052 40053 40054 40055 40056 40057 40058 40059 40060 40061 40062 40063 40064 40065 40066 40067 40068 40069 40070 40071 40072 40073 40074 40075 40076 40077 40078 40079 40080 40081 40082 40083 40084 40085 40086 40087 40088 40089 40090 40091 40092 40093 40094 40095 40096 40097 40098 40099 40100 40101 40102 40103 40104 40105 40106 40107 40108 40109 40110 40111 40112 40113 40114 40115 40116 40117 40118 40119 40120 40121 40122 40123 40124 40125 40126 40127 40128 40129 40130 40131 40132 40133 40134 40135 40136 40137 40138 40139 40140 40141 40142 40143 40144 40145 40146 40147 40148 40149 40150 40151 40152 40153 40154 40155 40156 40157 40158 40159 40160 40161 40162 40163 40164 40165 40166 40167 40168 40169 40170 40171 40172 40173 40174 40175 40176 40177 40178 40179 40180 40181 40182 40183 40184 40185 40186 40187 40188 40189 40190 40191 40192 40193 40194 40195 40196 40197 40198 40199 40200 40201 40202 40203 40204 40205 40206 40207 40208 40209 40210 40211 40212 40213 40214 40215 40216 40217 40218 40219 40220 40221 40222 40223 40224 40225 40226 40227 40228 40229 40230 40231 40232 40233 40234 40235 40236 40237 40238 40239 40240 40241 40242 40243 40244 40245 40246 40247 40248 40249 40250 40251 40252 40253 40254 40255 40256 40257 40258 40259 40260 40261 40262 40263 40264 40265 40266 40267 40268 40269 40270 40271 40272 40273 40274 40275 40276 40277 40278 40279 40280 40281 40282 40283 40284 40285 40286 40287 40288 40289 40290 40291 40292 40293 40294 40295 40296 40297 40298 40299 40300 40301 40302 40303 40304 40305 40306 40307 40308 40309 40310 40311 40312 40313 40314 40315 40316 40317 40318 40319 40320 40321 40322 40323 40324 40325 40326 40327 40328 40329 40330 40331 40332 40333 40334 40335 40336 40337 40338 40339 40340 40341 40342 40343 40344 40345 40346 40347 40348 40349 40350 40351 40352 40353 40354 40355 40356 40357 40358 40359 40360 40361 40362 40363 40364 40365 40366 40367 40368 40369 40370 40371 40372 40373 40374 40375 40376 40377 40378 40379 40380 40381 40382 40383 40384 40385 40386 40387 40388 40389 40390 40391 40392 40393 40394 40395 40396 40397 40398 40399 40400 40401 40402 40403 40404 40405 40406 40407 40408 40409 40410 40411 40412 40413 40414 40415 40416 40417 40418 40419 40420 40421 40422 40423 40424 40425 40426 40427 40428 40429 40430 40431 40432 40433 40434 40435 40436 40437 40438 40439 40440 40441 40442 40443 40444 40445 40446 40447 40448 40449 40450 40451 40452 40453 40454 40455 40456 40457 40458 40459 40460 40461 40462 40463 40464 40465 40466 40467 40468 40469 40470 40471 40472 40473 40474 40475 40476 40477 40478 40479 40480 40481 40482 40483 40484 40485 40486 40487 40488 40489 40490 40491 40492 40493 40494 40495 40496 40497 40498 40499 40500 40501 40502 40503 40504 40505 40506 40507 40508 40509 40510 40511 40512 40513 40514 40515 40516 40517 40518 40519 40520 40521 40522 40523 40524 40525 40526 40527 40528 40529 40530 40531 40532 40533 40534 40535 40536 40537 40538 40539 40540 40541 40542 40543 40544 40545 40546 40547 40548 40549 40550 40551 40552 40553 40554 40555 40556 40557 40558 40559 40560 40561 40562 40563 40564 40565 40566 40567 40568 40569 40570 40571 40572 40573 40574 40575 40576 40577 40578 40579 40580 40581 40582 40583 40584 40585 40586 40587 40588 40589 40590 40591 40592 40593 40594 40595 40596 40597 40598 40599 40600 40601 40602 40603 40604 40605 40606 40607 40608 40609 40610 40611 40612 40613 40614 40615 40616 40617 40618 40619 40620 40621 40622 40623 40624 40625 40626 40627 40628 40629 40630 40631 40632 40633 40634 40635 40636 40637 40638 40639 40640 40641 40642 40643 40644 40645 40646 40647 40648 40649 40650 40651 40652 40653 40654 40655 40656 40657 40658 40659 40660 40661 40662 40663 40664 40665 40666 40667 40668 40669 40670 40671 40672 40673 40674 40675 40676 40677 40678 40679 40680 40681 40682 40683 40684 40685 40686 40687 40688 40689 40690 40691 40692 40693 40694 40695 40696 40697 40698 40699 40700 40701 40702 40703 40704 40705 40706 40707 40708 40709 40710 40711 40712 40713 40714 40715 40716 40717 40718 40719 40720 40721 40722 40723 40724 40725 40726 40727 40728 40729 40730 40731 40732 40733 40734 40735 40736 40737 40738 40739 40740 40741 40742 40743 40744 40745 40746 40747 40748 40749 40750 40751 40752 40753 40754 40755 40756 40757 40758 40759 40760 40761 40762 40763 40764 40765 40766 40767 40768 40769 40770 40771 40772 40773 40774 40775 40776 40777 40778 40779 40780 40781 40782 40783 40784 40785 40786 40787 40788 40789 40790 40791 40792 40793 40794 40795 40796 40797 40798 40799 40800 40801 40802 40803 40804 40805 40806 40807 40808 40809 40810 40811 40812 40813 40814 40815 40816 40817 40818 40819 40820 40821 40822 40823 40824 40825 40826 40827 40828 40829 40830 40831 40832 40833 40834 40835 40836 40837 40838 40839 40840 40841 40842 40843 40844 40845 40846 40847 40848 40849 40850 40851 40852 40853 40854 40855 40856 40857 40858 40859 40860 40861 40862 40863 40864 40865 40866 40867 40868 40869 40870 40871 40872 40873 40874 40875 40876 40877 40878 40879 40880 40881 40882 40883 40884 40885 40886 40887 40888 40889 40890 40891 40892 40893 40894 40895 40896 40897 40898 40899 40900 40901 40902 40903 40904 40905 40906 40907 40908 40909 40910 40911 40912 40913 40914 40915 40916 40917 40918 40919 40920 40921 40922 40923 40924 40925 40926 40927 40928 40929 40930 40931 40932 40933 40934 40935 40936 40937 40938 40939 40940 40941 40942 40943 40944 40945 40946 40947 40948 40949 40950 40951 40952 40953 40954 40955 40956 40957 40958 40959 40960 40961 40962 40963 40964 40965 40966 40967 40968 40969 40970 40971 40972 40973 40974 40975 40976 40977 40978 40979 40980 40981 40982 40983 40984 40985 40986 40987 40988 40989 40990 40991 40992 40993 40994 40995 40996 40997 40998 40999 41000 41001 41002 41003 41004 41005 41006 41007 41008 41009 41010 41011 41012 41013 41014 41015 41016 41017 41018 41019 41020 41021 41022 41023 41024 41025 41026 41027 41028 41029 41030 41031 41032 41033 41034 41035 41036 41037 41038 41039 41040 41041 41042 41043 41044 41045 41046 41047 41048 41049 41050 41051 41052 41053 41054 41055 41056 41057 41058 41059 41060 41061 41062 41063 41064 41065 41066 41067 41068 41069 41070 41071 41072 41073 41074 41075 41076 41077 41078 41079 41080 41081 41082 41083 41084 41085 41086 41087 41088 41089 41090 41091 41092 41093 41094 41095 41096 41097 41098 41099 41100 41101 41102 41103 41104 41105 41106 41107 41108 41109 41110 41111 41112 41113 41114 41115 41116 41117 41118 41119 41120 41121 41122 41123 41124 41125 41126 41127 41128 41129 41130 41131 41132 41133 41134 41135 41136 41137 41138 41139 41140 41141 41142 41143 41144 41145 41146 41147 41148 41149 41150 41151 41152 41153 41154 41155 41156 41157 41158 41159 41160 41161 41162 41163 41164 41165 41166 41167 41168 41169 41170 41171 41172 41173 41174 41175 41176 41177 41178 41179 41180 41181 41182 41183 41184 41185 41186 41187 41188 41189 41190 41191 41192 41193 41194 41195 41196 41197 41198 41199 41200 41201 41202 41203 41204 41205 41206 41207 41208 41209 41210 41211 41212 41213 41214 41215 41216 41217 41218 41219 41220 41221 41222 41223 41224 41225 41226 41227 41228 41229 41230 41231 41232 41233 41234 41235 41236 41237 41238 41239 41240 41241 41242 41243 41244 41245 41246 41247 41248 41249 41250 41251 41252 41253 41254 41255 41256 41257 41258 41259 41260 41261 41262 41263 41264 41265 41266 41267 41268 41269 41270 41271 41272 41273 41274 41275 41276 41277 41278 41279 41280 41281 41282 41283 41284 41285 41286 41287 41288 41289 41290 41291 41292 41293 41294 41295 41296 41297 41298 41299 41300 41301 41302 41303 41304 41305 41306 41307 41308 41309 41310 41311 41312 41313 41314 41315 41316 41317 41318 41319 41320 41321 41322 41323 41324 41325 41326 41327 41328 41329 41330 41331 41332 41333 41334 41335 41336 41337 41338 41339 41340 41341 41342 41343 41344 41345 41346 41347 41348 41349 41350 41351 41352 41353 41354 41355 41356 41357 41358 41359 41360 41361 41362 41363 41364 41365 41366 41367 41368 41369 41370 41371 41372 41373 41374 41375 41376 41377 41378 41379 41380 41381 41382 41383 41384 41385 41386 41387 41388 41389 41390 41391 41392 41393 41394 41395 41396 41397 41398 41399 41400 41401 41402 41403 41404 41405 41406 41407 41408 41409 41410 41411 41412 41413 41414 41415 41416 41417 41418 41419 41420 41421 41422 41423 41424 41425 41426 41427 41428 41429 41430 41431 41432 41433 41434 41435 41436 41437 41438 41439 41440 41441 41442 41443 41444 41445 41446 41447 41448 41449 41450 41451 41452 41453 41454 41455 41456 41457 41458 41459 41460 41461 41462 41463 41464 41465 41466 41467 41468 41469 41470 41471 41472 41473 41474 41475 41476 41477 41478 41479 41480 41481 41482 41483 41484 41485 41486 41487 41488 41489 41490 41491 41492 41493 41494 41495 41496 41497 41498 41499 41500 41501 41502 41503 41504 41505 41506 41507 41508 41509 41510 41511 41512 41513 41514 41515 41516 41517 41518 41519 41520 41521 41522 41523 41524 41525 41526 41527 41528 41529 41530 41531 41532 41533 41534 41535 41536 41537 41538 41539 41540 41541 41542 41543 41544 41545 41546 41547 41548 41549 41550 41551 41552 41553 41554 41555 41556 41557 41558 41559 41560 41561 41562 41563 41564 41565 41566 41567 41568 41569 41570 41571 41572 41573 41574 41575 41576 41577 41578 41579 41580 41581 41582 41583 41584 41585 41586 41587 41588 41589 41590 41591 41592 41593 41594 41595 41596 41597 41598 41599 41600 41601 41602 41603 41604 41605 41606 41607 41608 41609 41610 41611 41612 41613 41614 41615 41616 41617 41618 41619 41620 41621 41622 41623 41624 41625 41626 41627 41628 41629 41630 41631 41632 41633 41634 41635 41636 41637 41638 41639 41640 41641 41642 41643 41644 41645 41646 41647 41648 41649 41650 41651 41652 41653 41654 41655 41656 41657 41658 41659 41660 41661 41662 41663 41664 41665 41666 41667 41668 41669 41670 41671 41672 41673 41674 41675 41676 41677 41678 41679 41680 41681 41682 41683 41684 41685 41686 41687 41688 41689 41690 41691 41692 41693 41694 41695 41696 41697 41698 41699 41700 41701 41702 41703 41704 41705 41706 41707 41708 41709 41710 41711 41712 41713 41714 41715 41716 41717 41718 41719 41720 41721 41722 41723 41724 41725 41726 41727 41728 41729 41730 41731 41732 41733 41734 41735 41736 41737 41738 41739 41740 41741 41742 41743 41744 41745 41746 41747 41748 41749 41750 41751 41752 41753 41754 41755 41756 41757 41758 41759 41760 41761 41762 41763 41764 41765 41766 41767 41768 41769 41770 41771 41772 41773 41774 41775 41776 41777 41778 41779 41780 41781 41782 41783 41784 41785 41786 41787 41788 41789 41790 41791 41792 41793 41794 41795 41796 41797 41798 41799 41800 41801 41802 41803 41804 41805 41806 41807 41808 41809 41810 41811 41812 41813 41814 41815 41816 41817 41818 41819 41820 41821 41822 41823 41824 41825 41826 41827 41828 41829 41830 41831 41832 41833 41834 41835 41836 41837 41838 41839 41840 41841 41842 41843 41844 41845 41846 41847 41848 41849 41850 41851 41852 41853 41854 41855 41856 41857 41858 41859 41860 41861 41862 41863 41864 41865 41866 41867 41868 41869 41870 41871 41872 41873 41874 41875 41876 41877 41878 41879 41880 41881 41882 41883 41884 41885 41886 41887 41888 41889 41890 41891 41892 41893 41894 41895 41896 41897 41898 41899 41900 41901 41902 41903 41904 41905 41906 41907 41908 41909 41910 41911 41912 41913 41914 41915 41916 41917 41918 41919 41920 41921 41922 41923 41924 41925 41926 41927 41928 41929 41930 41931 41932 41933 41934 41935 41936 41937 41938 41939 41940 41941 41942 41943 41944 41945 41946 41947 41948 41949 41950 41951 41952 41953 41954 41955 41956 41957 41958 41959 41960 41961 41962 41963 41964 41965 41966 41967 41968 41969 41970 41971 41972 41973 41974 41975 41976 41977 41978 41979 41980 41981 41982 41983 41984 41985 41986 41987 41988 41989 41990 41991 41992 41993 41994 41995 41996 41997 41998 41999 42000 42001 42002 42003 42004 42005 42006 42007 42008 42009 42010 42011 42012 42013 42014 42015 42016 42017 42018 42019 42020 42021 42022 42023 42024 42025 42026 42027 42028 42029 42030 42031 42032 42033 42034 42035 42036 42037 42038 42039 42040 42041 42042 42043 42044 42045 42046 42047 42048 42049 42050 42051 42052 42053 42054 42055 42056 42057 42058 42059 42060 42061 42062 42063 42064 42065 42066 42067 42068 42069 42070 42071 42072 42073 42074 42075 42076 42077 42078 42079 42080 42081 42082 42083 42084 42085 42086 42087 42088 42089 42090 42091 42092 42093 42094 42095 42096 42097 42098 42099 42100 42101 42102 42103 42104 42105 42106 42107 42108 42109 42110 42111 42112 42113 42114 42115 42116 42117 42118 42119 42120 42121 42122 42123 42124 42125 42126 42127 42128 42129 42130 42131 42132 42133 42134 42135 42136 42137 42138 42139 42140 42141 42142 42143 42144 42145 42146 42147 42148 42149 42150 42151 42152 42153 42154 42155 42156 42157 42158 42159 42160 42161 42162 42163 42164 42165 42166 42167 42168 42169 42170 42171 42172 42173 42174 42175 42176 42177 42178 42179 42180 42181 42182 42183 42184 42185 42186 42187 42188 42189 42190 42191 42192 42193 42194 42195 42196 42197 42198 42199 42200 42201 42202 42203 42204 42205 42206 42207 42208 42209 42210 42211 42212 42213 42214 42215 42216 42217 42218 42219 42220 42221 42222 42223 42224 42225 42226 42227 42228 42229 42230 42231 42232 42233 42234 42235 42236 42237 42238 42239 42240 42241 42242 42243 42244 42245 42246 42247 42248 42249 42250 42251 42252 42253 42254 42255 42256 42257 42258 42259 42260 42261 42262 42263 42264 42265 42266 42267 42268 42269 42270 42271 42272 42273 42274 42275 42276 42277 42278 42279 42280 42281 42282 42283 42284 42285 42286 42287 42288 42289 42290 42291 42292 42293 42294 42295 42296 42297 42298 42299 42300 42301 42302 42303 42304 42305 42306 42307 42308 42309 42310 42311 42312 42313 42314 42315 42316 42317 42318 42319 42320 42321 42322 42323 42324 42325 42326 42327 42328 42329 42330 42331 42332 42333 42334 42335 42336 42337 42338 42339 42340 42341 42342 42343 42344 42345 42346 42347 42348 42349 42350 42351 42352 42353 42354 42355 42356 42357 42358 42359 42360 42361 42362 42363 42364 42365 42366 42367 42368 42369 42370 42371 42372 42373 42374 42375 42376 42377 42378 42379 42380 42381 42382 42383 42384 42385 42386 42387 42388 42389 42390 42391 42392 42393 42394 42395 42396 42397 42398 42399 42400 42401 42402 42403 42404 42405 42406 42407 42408 42409 42410 42411 42412 42413 42414 42415 42416 42417 42418 42419 42420 42421 42422 42423 42424 42425 42426 42427 42428 42429 42430 42431 42432 42433 42434 42435 42436 42437 42438 42439 42440 42441 42442 42443 42444 42445 42446 42447 42448 42449 42450 42451 42452 42453 42454 42455 42456 42457 42458 42459 42460 42461 42462 42463 42464 42465 42466 42467 42468 42469 42470 42471 42472 42473 42474 42475 42476 42477 42478 42479 42480 42481 42482 42483 42484 42485 42486 42487 42488 42489 42490 42491 42492 42493 42494 42495 42496 42497 42498 42499 42500 42501 42502 42503 42504 42505 42506 42507 42508 42509 42510 42511 42512 42513 42514 42515 42516 42517 42518 42519 42520 42521 42522 42523 42524 42525 42526 42527 42528 42529 42530 42531 42532 42533 42534 42535 42536 42537 42538 42539 42540 42541 42542 42543 42544 42545 42546 42547 42548 42549 42550 42551 42552 42553 42554 42555 42556 42557 42558 42559 42560 42561 42562 42563 42564 42565 42566 42567 42568 42569 42570 42571 42572 42573 42574 42575 42576 42577 42578 42579 42580 42581 42582 42583 42584 42585 42586 42587 42588 42589 42590 42591 42592 42593 42594 42595 42596 42597 42598 42599 42600 42601 42602 42603 42604 42605 42606 42607 42608 42609 42610 42611 42612 42613 42614 42615 42616 42617 42618 42619 42620 42621 42622 42623 42624 42625 42626 42627 42628 42629 42630 42631 42632 42633 42634 42635 42636 42637 42638 42639 42640 42641 42642 42643 42644 42645 42646 42647 42648 42649 42650 42651 42652 42653 42654 42655 42656 42657 42658 42659 42660 42661 42662 42663 42664 42665 42666 42667 42668 42669 42670 42671 42672 42673 42674 42675 42676 42677 42678 42679 42680 42681 42682 42683 42684 42685 42686 42687 42688 42689 42690 42691 42692 42693 42694 42695 42696 42697 42698 42699 42700 42701 42702 42703 42704 42705 42706 42707 42708 42709 42710 42711 42712 42713 42714 42715 42716 42717 42718 42719 42720 42721 42722 42723 42724 42725 42726 42727 42728 42729 42730 42731 42732 42733 42734 42735 42736 42737 42738 42739 42740 42741 42742 42743 42744 42745 42746 42747 42748 42749 42750 42751 42752 42753 42754 42755 42756 42757 42758 42759 42760 42761 42762 42763 42764 42765 42766 42767 42768 42769 42770 42771 42772 42773 42774 42775 42776 42777 42778 42779 42780 42781 42782 42783 42784 42785 42786 42787 42788 42789 42790 42791 42792 42793 42794 42795 42796 42797 42798 42799 42800 42801 42802 42803 42804 42805 42806 42807 42808 42809 42810 42811 42812 42813 42814 42815 42816 42817 42818 42819 42820 42821 42822 42823 42824 42825 42826 42827 42828 42829 42830 42831 42832 42833 42834 42835 42836 42837 42838 42839 42840 42841 42842 42843 42844 42845 42846 42847 42848 42849 42850 42851 42852 42853 42854 42855 42856 42857 42858 42859 42860 42861 42862 42863 42864 42865 42866 42867 42868 42869 42870 42871 42872 42873 42874 42875 42876 42877 42878 42879 42880 42881 42882 42883 42884 42885 42886 42887 42888 42889 42890 42891 42892 42893 42894 42895 42896 42897 42898 42899 42900 42901 42902 42903 42904 42905 42906 42907 42908 42909 42910 42911 42912 42913 42914 42915 42916 42917 42918 42919 42920 42921 42922 42923 42924 42925 42926 42927 42928 42929 42930 42931 42932 42933 42934 42935 42936 42937 42938 42939 42940 42941 42942 42943 42944 42945 42946 42947 42948 42949 42950 42951 42952 42953 42954 42955 42956 42957 42958 42959 42960 42961 42962 42963 42964 42965 42966 42967 42968 42969 42970 42971 42972 42973 42974 42975 42976 42977 42978 42979 42980 42981 42982 42983 42984 42985 42986 42987 42988 42989 42990 42991 42992 42993 42994 42995 42996 42997 42998 42999 43000 43001 43002 43003 43004 43005 43006 43007 43008 43009 43010 43011 43012 43013 43014 43015 43016 43017 43018 43019 43020 43021 43022 43023 43024 43025 43026 43027 43028 43029 43030 43031 43032 43033 43034 43035 43036 43037 43038 43039 43040 43041 43042 43043 43044 43045 43046 43047 43048 43049 43050 43051 43052 43053 43054 43055 43056 43057 43058 43059 43060 43061 43062 43063 43064 43065 43066 43067 43068 43069 43070 43071 43072 43073 43074 43075 43076 43077 43078 43079 43080 43081 43082 43083 43084 43085 43086 43087 43088 43089 43090 43091 43092 43093 43094 43095 43096 43097 43098 43099 43100 43101 43102 43103 43104 43105 43106 43107 43108 43109 43110 43111 43112 43113 43114 43115 43116 43117 43118 43119 43120 43121 43122 43123 43124 43125 43126 43127 43128 43129 43130 43131 43132 43133 43134 43135 43136 43137 43138 43139 43140 43141 43142 43143 43144 43145 43146 43147 43148 43149 43150 43151 43152 43153 43154 43155 43156 43157 43158 43159 43160 43161 43162 43163 43164 43165 43166 43167 43168 43169 43170 43171 43172 43173 43174 43175 43176 43177 43178 43179 43180 43181 43182 43183 43184 43185 43186 43187 43188 43189 43190 43191 43192 43193 43194 43195 43196 43197 43198 43199 43200 43201 43202 43203 43204 43205 43206 43207 43208 43209 43210 43211 43212 43213 43214 43215 43216 43217 43218 43219 43220 43221 43222 43223 43224 43225 43226 43227 43228 43229 43230 43231 43232 43233 43234 43235 43236 43237 43238 43239 43240 43241 43242 43243 43244 43245 43246 43247 43248 43249 43250 43251 43252 43253 43254 43255 43256 43257 43258 43259 43260 43261 43262 43263 43264 43265 43266 43267 43268 43269 43270 43271 43272 43273 43274 43275 43276 43277 43278 43279 43280 43281 43282 43283 43284 43285 43286 43287 43288 43289 43290 43291 43292 43293 43294 43295 43296 43297 43298 43299 43300 43301 43302 43303 43304 43305 43306 43307 43308 43309 43310 43311 43312 43313 43314 43315 43316 43317 43318 43319 43320 43321 43322 43323 43324 43325 43326 43327 43328 43329 43330 43331 43332 43333 43334 43335 43336 43337 43338 43339 43340 43341 43342 43343 43344 43345 43346 43347 43348 43349 43350 43351 43352 43353 43354 43355 43356 43357 43358 43359 43360 43361 43362 43363 43364 43365 43366 43367 43368 43369 43370 43371 43372 43373 43374 43375 43376 43377 43378 43379 43380 43381 43382 43383 43384 43385 43386 43387 43388 43389 43390 43391 43392 43393 43394 43395 43396 43397 43398 43399 43400 43401 43402 43403 43404 43405 43406 43407 43408 43409 43410 43411 43412 43413 43414 43415 43416 43417 43418 43419 43420 43421 43422 43423 43424 43425 43426 43427 43428 43429 43430 43431 43432 43433 43434 43435 43436 43437 43438 43439 43440 43441 43442 43443 43444 43445 43446 43447 43448 43449 43450 43451 43452 43453 43454 43455 43456 43457 43458 43459 43460 43461 43462 43463 43464 43465 43466 43467 43468 43469 43470 43471 43472 43473 43474 43475 43476 43477 43478 43479 43480 43481 43482 43483 43484 43485 43486 43487 43488 43489 43490 43491 43492 43493 43494 43495 43496 43497 43498 43499 43500 43501 43502 43503 43504 43505 43506 43507 43508 43509 43510 43511 43512 43513 43514 43515 43516 43517 43518 43519 43520 43521 43522 43523 43524 43525 43526 43527 43528 43529 43530 43531 43532 43533 43534 43535 43536 43537 43538 43539 43540 43541 43542 43543 43544 43545 43546 43547 43548 43549 43550 43551 43552 43553 43554 43555 43556 43557 43558 43559 43560 43561 43562 43563 43564 43565 43566 43567 43568 43569 43570 43571 43572 43573 43574 43575 43576 43577 43578 43579 43580 43581 43582 43583 43584 43585 43586 43587 43588 43589 43590 43591 43592 43593 43594 43595 43596 43597 43598 43599 43600 43601 43602 43603 43604 43605 43606 43607 43608 43609 43610 43611 43612 43613 43614 43615 43616 43617 43618 43619 43620 43621 43622 43623 43624 43625 43626 43627 43628 43629 43630 43631 43632 43633 43634 43635 43636 43637 43638 43639 43640 43641 43642 43643 43644 43645 43646 43647 43648 43649 43650 43651 43652 43653 43654 43655 43656 43657 43658 43659 43660 43661 43662 43663 43664 43665 43666 43667 43668 43669 43670 43671 43672 43673 43674 43675 43676 43677 43678 43679 43680 43681 43682 43683 43684 43685 43686 43687 43688 43689 43690 43691 43692 43693 43694 43695 43696 43697 43698 43699 43700 43701 43702 43703 43704 43705 43706 43707 43708 43709 43710 43711 43712 43713 43714 43715 43716 43717 43718 43719 43720 43721 43722 43723 43724 43725 43726 43727 43728 43729 43730 43731 43732 43733 43734 43735 43736 43737 43738 43739 43740 43741 43742 43743 43744 43745 43746 43747 43748 43749 43750 43751 43752 43753 43754 43755 43756 43757 43758 43759 43760 43761 43762 43763 43764 43765 43766 43767 43768 43769 43770 43771 43772 43773 43774 43775 43776 43777 43778 43779 43780 43781 43782 43783 43784 43785 43786 43787 43788 43789 43790 43791 43792 43793 43794 43795 43796 43797 43798 43799 43800 43801 43802 43803 43804 43805 43806 43807 43808 43809 43810 43811 43812 43813 43814 43815 43816 43817 43818 43819 43820 43821 43822 43823 43824 43825 43826 43827 43828 43829 43830 43831 43832 43833 43834 43835 43836 43837 43838 43839 43840 43841 43842 43843 43844 43845 43846 43847 43848 43849 43850 43851 43852 43853 43854 43855 43856 43857 43858 43859 43860 43861 43862 43863 43864 43865 43866 43867 43868 43869 43870 43871 43872 43873 43874 43875 43876 43877 43878 43879 43880 43881 43882 43883 43884 43885 43886 43887 43888 43889 43890 43891 43892 43893 43894 43895 43896 43897 43898 43899 43900 43901 43902 43903 43904 43905 43906 43907 43908 43909 43910 43911 43912 43913 43914 43915 43916 43917 43918 43919 43920 43921 43922 43923 43924 43925 43926 43927 43928 43929 43930 43931 43932 43933 43934 43935 43936 43937 43938 43939 43940 43941 43942 43943 43944 43945 43946 43947 43948 43949 43950 43951 43952 43953 43954 43955 43956 43957 43958 43959 43960 43961 43962 43963 43964 43965 43966 43967 43968 43969 43970 43971 43972 43973 43974 43975 43976 43977 43978 43979 43980 43981 43982 43983 43984 43985 43986 43987 43988 43989 43990 43991 43992 43993 43994 43995 43996 43997 43998 43999 44000 44001 44002 44003 44004 44005 44006 44007 44008 44009 44010 44011 44012 44013 44014 44015 44016 44017 44018 44019 44020 44021 44022 44023 44024 44025 44026 44027 44028 44029 44030 44031 44032 44033 44034 44035 44036 44037 44038 44039 44040 44041 44042 44043 44044 44045 44046 44047 44048 44049 44050 44051 44052 44053 44054 44055 44056 44057 44058 44059 44060 44061 44062 44063 44064 44065 44066 44067 44068 44069 44070 44071 44072 44073 44074 44075 44076 44077 44078 44079 44080 44081 44082 44083 44084 44085 44086 44087 44088 44089 44090 44091 44092 44093 44094 44095 44096 44097 44098 44099 44100 44101 44102 44103 44104 44105 44106 44107 44108 44109 44110 44111 44112 44113 44114 44115 44116 44117 44118 44119 44120 44121 44122 44123 44124 44125 44126 44127 44128 44129 44130 44131 44132 44133 44134 44135 44136 44137 44138 44139 44140 44141 44142 44143 44144 44145 44146 44147 44148 44149 44150 44151 44152 44153 44154 44155 44156 44157 44158 44159 44160 44161 44162 44163 44164 44165 44166 44167 44168 44169 44170 44171 44172 44173 44174 44175 44176 44177 44178 44179 44180 44181 44182 44183 44184 44185 44186 44187 44188 44189 44190 44191 44192 44193 44194 44195 44196 44197 44198 44199 44200 44201 44202 44203 44204 44205 44206 44207 44208 44209 44210 44211 44212 44213 44214 44215 44216 44217 44218 44219 44220 44221 44222 44223 44224 44225 44226 44227 44228 44229 44230 44231 44232 44233 44234 44235 44236 44237 44238 44239 44240 44241 44242 44243 44244 44245 44246 44247 44248 44249 44250 44251 44252 44253 44254 44255 44256 44257 44258 44259 44260 44261 44262 44263 44264 44265 44266 44267 44268 44269 44270 44271 44272 44273 44274 44275 44276 44277 44278 44279 44280 44281 44282 44283 44284 44285 44286 44287 44288 44289 44290 44291 44292 44293 44294 44295 44296 44297 44298 44299 44300 44301 44302 44303 44304 44305 44306 44307 44308 44309 44310 44311 44312 44313 44314 44315 44316 44317 44318 44319 44320 44321 44322 44323 44324 44325 44326 44327 44328 44329 44330 44331 44332 44333 44334 44335 44336 44337 44338 44339 44340 44341 44342 44343 44344 44345 44346 44347 44348 44349 44350 44351 44352 44353 44354 44355 44356 44357 44358 44359 44360 44361 44362 44363 44364 44365 44366 44367 44368 44369 44370 44371 44372 44373 44374 44375 44376 44377 44378 44379 44380 44381 44382 44383 44384 44385 44386 44387 44388 44389 44390 44391 44392 44393 44394 44395 44396 44397 44398 44399 44400 44401 44402 44403 44404 44405 44406 44407 44408 44409 44410 44411 44412 44413 44414 44415 44416 44417 44418 44419 44420 44421 44422 44423 44424 44425 44426 44427 44428 44429 44430 44431 44432 44433 44434 44435 44436 44437 44438 44439 44440 44441 44442 44443 44444 44445 44446 44447 44448 44449 44450 44451 44452 44453 44454 44455 44456 44457 44458 44459 44460 44461 44462 44463 44464 44465 44466 44467 44468 44469 44470 44471 44472 44473 44474 44475 44476 44477 44478 44479 44480 44481 44482 44483 44484 44485 44486 44487 44488 44489 44490 44491 44492 44493 44494 44495 44496 44497 44498 44499 44500 44501 44502 44503 44504 44505 44506 44507 44508 44509 44510 44511 44512 44513 44514 44515 44516 44517 44518 44519 44520 44521 44522 44523 44524 44525 44526 44527 44528 44529 44530 44531 44532 44533 44534 44535 44536 44537 44538 44539 44540 44541 44542 44543 44544 44545 44546 44547 44548 44549 44550 44551 44552 44553 44554 44555 44556 44557 44558 44559 44560 44561 44562 44563 44564 44565 44566 44567 44568 44569 44570 44571 44572 44573 44574 44575 44576 44577 44578 44579 44580 44581 44582 44583 44584 44585 44586 44587 44588 44589 44590 44591 44592 44593 44594 44595 44596 44597 44598 44599 44600 44601 44602 44603 44604 44605 44606 44607 44608 44609 44610 44611 44612 44613 44614 44615 44616 44617 44618 44619 44620 44621 44622 44623 44624 44625 44626 44627 44628 44629 44630 44631 44632 44633 44634 44635 44636 44637 44638 44639 44640 44641 44642 44643 44644 44645 44646 44647 44648 44649 44650 44651 44652 44653 44654 44655 44656 44657 44658 44659 44660 44661 44662 44663 44664 44665 44666 44667 44668 44669 44670 44671 44672 44673 44674 44675 44676 44677 44678 44679 44680 44681 44682 44683 44684 44685 44686 44687 44688 44689 44690 44691 44692 44693 44694 44695 44696 44697 44698 44699 44700 44701 44702 44703 44704 44705 44706 44707 44708 44709 44710 44711 44712 44713 44714 44715 44716 44717 44718 44719 44720 44721 44722 44723 44724 44725 44726 44727 44728 44729 44730 44731 44732 44733 44734 44735 44736 44737 44738 44739 44740 44741 44742 44743 44744 44745 44746 44747 44748 44749 44750 44751 44752 44753 44754 44755 44756 44757 44758 44759 44760 44761 44762 44763 44764 44765 44766 44767 44768 44769 44770 44771 44772 44773 44774 44775 44776 44777 44778 44779 44780 44781 44782 44783 44784 44785 44786 44787 44788 44789 44790 44791 44792 44793 44794 44795 44796 44797 44798 44799 44800 44801 44802 44803 44804 44805 44806 44807 44808 44809 44810 44811 44812 44813 44814 44815 44816 44817 44818 44819 44820 44821 44822 44823 44824 44825 44826 44827 44828 44829 44830 44831 44832 44833 44834 44835 44836 44837 44838 44839 44840 44841 44842 44843 44844 44845 44846 44847 44848 44849 44850 44851 44852 44853 44854 44855 44856 44857 44858 44859 44860 44861 44862 44863 44864 44865 44866 44867 44868 44869 44870 44871 44872 44873 44874 44875 44876 44877 44878 44879 44880 44881 44882 44883 44884 44885 44886 44887 44888 44889 44890 44891 44892 44893 44894 44895 44896 44897 44898 44899 44900 44901 44902 44903 44904 44905 44906 44907 44908 44909 44910 44911 44912 44913 44914 44915 44916 44917 44918 44919 44920 44921 44922 44923 44924 44925 44926 44927 44928 44929 44930 44931 44932 44933 44934 44935 44936 44937 44938 44939 44940 44941 44942 44943 44944 44945 44946 44947 44948 44949 44950 44951 44952 44953 44954 44955 44956 44957 44958 44959 44960 44961 44962 44963 44964 44965 44966 44967 44968 44969 44970 44971 44972 44973 44974 44975 44976 44977 44978 44979 44980 44981 44982 44983 44984 44985 44986 44987 44988 44989 44990 44991 44992 44993 44994 44995 44996 44997 44998 44999 45000 45001 45002 45003 45004 45005 45006 45007 45008 45009 45010 45011 45012 45013 45014 45015 45016 45017 45018 45019 45020 45021 45022 45023 45024 45025 45026 45027 45028 45029 45030 45031 45032 45033 45034 45035 45036 45037 45038 45039 45040 45041 45042 45043 45044 45045 45046 45047 45048 45049 45050 45051 45052 45053 45054 45055 45056 45057 45058 45059 45060 45061 45062 45063 45064 45065 45066 45067 45068 45069 45070 45071 45072 45073 45074 45075 45076 45077 45078 45079 45080 45081 45082 45083 45084 45085 45086 45087 45088 45089 45090 45091 45092 45093 45094 45095 45096 45097 45098 45099 45100 45101 45102 45103 45104 45105 45106 45107 45108 45109 45110 45111 45112 45113 45114 45115 45116 45117 45118 45119 45120 45121 45122 45123 45124 45125 45126 45127 45128 45129 45130 45131 45132 45133 45134 45135 45136 45137 45138 45139 45140 45141 45142 45143 45144 45145 45146 45147 45148 45149 45150 45151 45152 45153 45154 45155 45156 45157 45158 45159 45160 45161 45162 45163 45164 45165 45166 45167 45168 45169 45170 45171 45172 45173 45174 45175 45176 45177 45178 45179 45180 45181 45182 45183 45184 45185 45186 45187 45188 45189 45190 45191 45192 45193 45194 45195 45196 45197 45198 45199 45200 45201 45202 45203 45204 45205 45206 45207 45208 45209 45210 45211 45212 45213 45214 45215 45216 45217 45218 45219 45220 45221 45222 45223 45224 45225 45226 45227 45228 45229 45230 45231 45232 45233 45234 45235 45236 45237 45238 45239 45240 45241 45242 45243 45244 45245 45246 45247 45248 45249 45250 45251 45252 45253 45254 45255 45256 45257 45258 45259 45260 45261 45262 45263 45264 45265 45266 45267 45268 45269 45270 45271 45272 45273 45274 45275 45276 45277 45278 45279 45280 45281 45282 45283 45284 45285 45286 45287 45288 45289 45290 45291 45292 45293 45294 45295 45296 45297 45298 45299 45300 45301 45302 45303 45304 45305 45306 45307 45308 45309 45310 45311 45312 45313 45314 45315 45316 45317 45318 45319 45320 45321 45322 45323 45324 45325 45326 45327 45328 45329 45330 45331 45332 45333 45334 45335 45336 45337 45338 45339 45340 45341 45342 45343 45344 45345 45346 45347 45348 45349 45350 45351 45352 45353 45354 45355 45356 45357 45358 45359 45360 45361 45362 45363 45364 45365 45366 45367 45368 45369 45370 45371 45372 45373 45374 45375 45376 45377 45378 45379 45380 45381 45382 45383 45384 45385 45386 45387 45388 45389 45390 45391 45392 45393 45394 45395 45396 45397 45398 45399 45400 45401 45402 45403 45404 45405 45406 45407 45408 45409 45410 45411 45412 45413 45414 45415 45416 45417 45418 45419 45420 45421 45422 45423 45424 45425 45426 45427 45428 45429 45430 45431 45432 45433 45434 45435 45436 45437 45438 45439 45440 45441 45442 45443 45444 45445 45446 45447 45448 45449 45450 45451 45452 45453 45454 45455 45456 45457 45458 45459 45460 45461 45462 45463 45464 45465 45466 45467 45468 45469 45470 45471 45472 45473 45474 45475 45476 45477 45478 45479 45480 45481 45482 45483 45484 45485 45486 45487 45488 45489 45490 45491 45492 45493 45494 45495 45496 45497 45498 45499 45500 45501 45502 45503 45504 45505 45506 45507 45508 45509 45510 45511 45512 45513 45514 45515 45516 45517 45518 45519 45520 45521 45522 45523 45524 45525 45526 45527 45528 45529 45530 45531 45532 45533 45534 45535 45536 45537 45538 45539 45540 45541 45542 45543 45544 45545 45546 45547 45548 45549 45550 45551 45552 45553 45554 45555 45556 45557 45558 45559 45560 45561 45562 45563 45564 45565 45566 45567 45568 45569 45570 45571 45572 45573 45574 45575 45576 45577 45578 45579 45580 45581 45582 45583 45584 45585 45586 45587 45588 45589 45590 45591 45592 45593 45594 45595 45596 45597 45598 45599 45600 45601 45602 45603 45604 45605 45606 45607 45608 45609 45610 45611 45612 45613 45614 45615 45616 45617 45618 45619 45620 45621 45622 45623 45624 45625 45626 45627 45628 45629 45630 45631 45632 45633 45634 45635 45636 45637 45638 45639 45640 45641 45642 45643 45644 45645 45646 45647 45648 45649 45650 45651 45652 45653 45654 45655 45656 45657 45658 45659 45660 45661 45662 45663 45664 45665 45666 45667 45668 45669 45670 45671 45672 45673 45674 45675 45676 45677 45678 45679 45680 45681 45682 45683 45684 45685 45686 45687 45688 45689 45690 45691 45692 45693 45694 45695 45696 45697 45698 45699 45700 45701 45702 45703 45704 45705 45706 45707 45708 45709 45710 45711 45712 45713 45714 45715 45716 45717 45718 45719 45720 45721 45722 45723 45724 45725 45726 45727 45728 45729 45730 45731 45732 45733 45734 45735 45736 45737 45738 45739 45740 45741 45742 45743 45744 45745 45746 45747 45748 45749 45750 45751 45752 45753 45754 45755 45756 45757 45758 45759 45760 45761 45762 45763 45764 45765 45766 45767 45768 45769 45770 45771 45772 45773 45774 45775 45776 45777 45778 45779 45780 45781 45782 45783 45784 45785 45786 45787 45788 45789 45790 45791 45792 45793 45794 45795 45796 45797 45798 45799 45800 45801 45802 45803 45804 45805 45806 45807 45808 45809 45810 45811 45812 45813 45814 45815 45816 45817 45818 45819 45820 45821 45822 45823 45824 45825 45826 45827 45828 45829 45830 45831 45832 45833 45834 45835 45836 45837 45838 45839 45840 45841 45842 45843 45844 45845 45846 45847 45848 45849 45850 45851 45852 45853 45854 45855 45856 45857 45858 45859 45860 45861 45862 45863 45864 45865 45866 45867 45868 45869 45870 45871 45872 45873 45874 45875 45876 45877 45878 45879 45880 45881 45882 45883 45884 45885 45886 45887 45888 45889 45890 45891 45892 45893 45894 45895 45896 45897 45898 45899 45900 45901 45902 45903 45904 45905 45906 45907 45908 45909 45910 45911 45912 45913 45914 45915 45916 45917 45918 45919 45920 45921 45922 45923 45924 45925 45926 45927 45928 45929 45930 45931 45932 45933 45934 45935 45936 45937 45938 45939 45940 45941 45942 45943 45944 45945 45946 45947 45948 45949 45950 45951 45952 45953 45954 45955 45956 45957 45958 45959 45960 45961 45962 45963 45964 45965 45966 45967 45968 45969 45970 45971 45972 45973 45974 45975 45976 45977 45978 45979 45980 45981 45982 45983 45984 45985 45986 45987 45988 45989 45990 45991 45992 45993 45994 45995 45996 45997 45998 45999 46000 46001 46002 46003 46004 46005 46006 46007 46008 46009 46010 46011 46012 46013 46014 46015 46016 46017 46018 46019 46020 46021 46022 46023 46024 46025 46026 46027 46028 46029 46030 46031 46032 46033 46034 46035 46036 46037 46038 46039 46040 46041 46042 46043 46044 46045 46046 46047 46048 46049 46050 46051 46052 46053 46054 46055 46056 46057 46058 46059 46060 46061 46062 46063 46064 46065 46066 46067 46068 46069 46070 46071 46072 46073 46074 46075 46076 46077 46078 46079 46080 46081 46082 46083 46084 46085 46086 46087 46088 46089 46090 46091 46092 46093 46094 46095 46096 46097 46098 46099 46100 46101 46102 46103 46104 46105 46106 46107 46108 46109 46110 46111 46112 46113 46114 46115 46116 46117 46118 46119 46120 46121 46122 46123 46124 46125 46126 46127 46128 46129 46130 46131 46132 46133 46134 46135 46136 46137 46138 46139 46140 46141 46142 46143 46144 46145 46146 46147 46148 46149 46150 46151 46152 46153 46154 46155 46156 46157 46158 46159 46160 46161 46162 46163 46164 46165 46166 46167 46168 46169 46170 46171 46172 46173 46174 46175 46176 46177 46178 46179 46180 46181 46182 46183 46184 46185 46186 46187 46188 46189 46190 46191 46192 46193 46194 46195 46196 46197 46198 46199 46200 46201 46202 46203 46204 46205 46206 46207 46208 46209 46210 46211 46212 46213 46214 46215 46216 46217 46218 46219 46220 46221 46222 46223 46224 46225 46226 46227 46228 46229 46230 46231 46232 46233 46234 46235 46236 46237 46238 46239 46240 46241 46242 46243 46244 46245 46246 46247 46248 46249 46250 46251 46252 46253 46254 46255 46256 46257 46258 46259 46260 46261 46262 46263 46264 46265 46266 46267 46268 46269 46270 46271 46272 46273 46274 46275 46276 46277 46278 46279 46280 46281 46282 46283 46284 46285 46286 46287 46288 46289 46290 46291 46292 46293 46294 46295 46296 46297 46298 46299 46300 46301 46302 46303 46304 46305 46306 46307 46308 46309 46310 46311 46312 46313 46314 46315 46316 46317 46318 46319 46320 46321 46322 46323 46324 46325 46326 46327 46328 46329 46330 46331 46332 46333 46334 46335 46336 46337 46338 46339 46340 46341 46342 46343 46344 46345 46346 46347 46348 46349 46350 46351 46352 46353 46354 46355 46356 46357 46358 46359 46360 46361 46362 46363 46364 46365 46366 46367 46368 46369 46370 46371 46372 46373 46374 46375 46376 46377 46378 46379 46380 46381 46382 46383 46384 46385 46386 46387 46388 46389 46390 46391 46392 46393 46394 46395 46396 46397 46398 46399 46400 46401 46402 46403 46404 46405 46406 46407 46408 46409 46410 46411 46412 46413 46414 46415 46416 46417 46418 46419 46420 46421 46422 46423 46424 46425 46426 46427 46428 46429 46430 46431 46432 46433 46434 46435 46436 46437 46438 46439 46440 46441 46442 46443 46444 46445 46446 46447 46448 46449 46450 46451 46452 46453 46454 46455 46456 46457 46458 46459 46460 46461 46462 46463 46464 46465 46466 46467 46468 46469 46470 46471 46472 46473 46474 46475 46476 46477 46478 46479 46480 46481 46482 46483 46484 46485 46486 46487 46488 46489 46490 46491 46492 46493 46494 46495 46496 46497 46498 46499 46500 46501 46502 46503 46504 46505 46506 46507 46508 46509 46510 46511 46512 46513 46514 46515 46516 46517 46518 46519 46520 46521 46522 46523 46524 46525 46526 46527 46528 46529 46530 46531 46532 46533 46534 46535 46536 46537 46538 46539 46540 46541 46542 46543 46544 46545 46546 46547 46548 46549 46550 46551 46552 46553 46554 46555 46556 46557 46558 46559 46560 46561 46562 46563 46564 46565 46566 46567 46568 46569 46570 46571 46572 46573 46574 46575 46576 46577 46578 46579 46580 46581 46582 46583 46584 46585 46586 46587 46588 46589 46590 46591 46592 46593 46594 46595 46596 46597 46598 46599 46600 46601 46602 46603 46604 46605 46606 46607 46608 46609 46610 46611 46612 46613 46614 46615 46616 46617 46618 46619 46620 46621 46622 46623 46624 46625 46626 46627 46628 46629 46630 46631 46632 46633 46634 46635 46636 46637 46638 46639 46640 46641 46642 46643 46644 46645 46646 46647 46648 46649 46650 46651 46652 46653 46654 46655 46656 46657 46658 46659 46660 46661 46662 46663 46664 46665 46666 46667 46668 46669 46670 46671 46672 46673 46674 46675 46676 46677 46678 46679 46680 46681 46682 46683 46684 46685 46686 46687 46688 46689 46690 46691 46692 46693 46694 46695 46696 46697 46698 46699 46700 46701 46702 46703 46704 46705 46706 46707 46708 46709 46710 46711 46712 46713 46714 46715 46716 46717 46718 46719 46720 46721 46722 46723 46724 46725 46726 46727 46728 46729 46730 46731 46732 46733 46734 46735 46736 46737 46738 46739 46740 46741 46742 46743 46744 46745 46746 46747 46748 46749 46750 46751 46752 46753 46754 46755 46756 46757 46758 46759 46760 46761 46762 46763 46764 46765 46766 46767 46768 46769 46770 46771 46772 46773 46774 46775 46776 46777 46778 46779 46780 46781 46782 46783 46784 46785 46786 46787 46788 46789 46790 46791 46792 46793 46794 46795 46796 46797 46798 46799 46800 46801 46802 46803 46804 46805 46806 46807 46808 46809 46810 46811 46812 46813 46814 46815 46816 46817 46818 46819 46820 46821 46822 46823 46824 46825 46826 46827 46828 46829 46830 46831 46832 46833 46834 46835 46836 46837 46838 46839 46840 46841 46842 46843 46844 46845 46846 46847 46848 46849 46850 46851 46852 46853 46854 46855 46856 46857 46858 46859 46860 46861 46862 46863 46864 46865 46866 46867 46868 46869 46870 46871 46872 46873 46874 46875 46876 46877 46878 46879 46880 46881 46882 46883 46884 46885 46886 46887 46888 46889 46890 46891 46892 46893 46894 46895 46896 46897 46898 46899 46900 46901 46902 46903 46904 46905 46906 46907 46908 46909 46910 46911 46912 46913 46914 46915 46916 46917 46918 46919 46920 46921 46922 46923 46924 46925 46926 46927 46928 46929 46930 46931 46932 46933 46934 46935 46936 46937 46938 46939 46940 46941 46942 46943 46944 46945 46946 46947 46948 46949 46950 46951 46952 46953 46954 46955 46956 46957 46958 46959 46960 46961 46962 46963 46964 46965 46966 46967 46968 46969 46970 46971 46972 46973 46974 46975 46976 46977 46978 46979 46980 46981 46982 46983 46984 46985 46986 46987 46988 46989 46990 46991 46992 46993 46994 46995 46996 46997 46998 46999 47000 47001 47002 47003 47004 47005 47006 47007 47008 47009 47010 47011 47012 47013 47014 47015 47016 47017 47018 47019 47020 47021 47022 47023 47024 47025 47026 47027 47028 47029 47030 47031 47032 47033 47034 47035 47036 47037 47038 47039 47040 47041 47042 47043 47044 47045 47046 47047 47048 47049 47050 47051 47052 47053 47054 47055 47056 47057 47058 47059 47060 47061 47062 47063 47064 47065 47066 47067 47068 47069 47070 47071 47072 47073 47074 47075 47076 47077 47078 47079 47080 47081 47082 47083 47084 47085 47086 47087 47088 47089 47090 47091 47092 47093 47094 47095 47096 47097 47098 47099 47100 47101 47102 47103 47104 47105 47106 47107 47108 47109 47110 47111 47112 47113 47114 47115 47116 47117 47118 47119 47120 47121 47122 47123 47124 47125 47126 47127 47128 47129 47130 47131 47132 47133 47134 47135 47136 47137 47138 47139 47140 47141 47142 47143 47144 47145 47146 47147 47148 47149 47150 47151 47152 47153 47154 47155 47156 47157 47158 47159 47160 47161 47162 47163 47164 47165 47166 47167 47168 47169 47170 47171 47172 47173 47174 47175 47176 47177 47178 47179 47180 47181 47182 47183 47184 47185 47186 47187 47188 47189 47190 47191 47192 47193 47194 47195 47196 47197 47198 47199 47200 47201 47202 47203 47204 47205 47206 47207 47208 47209 47210 47211 47212 47213 47214 47215 47216 47217 47218 47219 47220 47221 47222 47223 47224 47225 47226 47227 47228 47229 47230 47231 47232 47233 47234 47235 47236 47237 47238 47239 47240 47241 47242 47243 47244 47245 47246 47247 47248 47249 47250 47251 47252 47253 47254 47255 47256 47257 47258 47259 47260 47261 47262 47263 47264 47265 47266 47267 47268 47269 47270 47271 47272 47273 47274 47275 47276 47277 47278 47279 47280 47281 47282 47283 47284 47285 47286 47287 47288 47289 47290 47291 47292 47293 47294 47295 47296 47297 47298 47299 47300 47301 47302 47303 47304 47305 47306 47307 47308 47309 47310 47311 47312 47313 47314 47315 47316 47317 47318 47319 47320 47321 47322 47323 47324 47325 47326 47327 47328 47329 47330 47331 47332 47333 47334 47335 47336 47337 47338 47339 47340 47341 47342 47343 47344 47345 47346 47347 47348 47349 47350 47351 47352 47353 47354 47355 47356 47357 47358 47359 47360 47361 47362 47363 47364 47365 47366 47367 47368 47369 47370 47371 47372 47373 47374 47375 47376 47377 47378 47379 47380 47381 47382 47383 47384 47385 47386 47387 47388 47389 47390 47391 47392 47393 47394 47395 47396 47397 47398 47399 47400 47401 47402 47403 47404 47405 47406 47407 47408 47409 47410 47411 47412 47413 47414 47415 47416 47417 47418 47419 47420 47421 47422 47423 47424 47425 47426 47427 47428 47429 47430 47431 47432 47433 47434 47435 47436 47437 47438 47439 47440 47441 47442 47443 47444 47445 47446 47447 47448 47449 47450 47451 47452 47453 47454 47455 47456 47457 47458 47459 47460 47461 47462 47463 47464 47465 47466 47467 47468 47469 47470 47471 47472 47473 47474 47475 47476 47477 47478 47479 47480 47481 47482 47483 47484 47485 47486 47487 47488 47489 47490 47491 47492 47493 47494 47495 47496 47497 47498 47499 47500 47501 47502 47503 47504 47505 47506 47507 47508 47509 47510 47511 47512 47513 47514 47515 47516 47517 47518 47519 47520 47521 47522 47523 47524 47525 47526 47527 47528 47529 47530 47531 47532 47533 47534 47535 47536 47537 47538 47539 47540 47541 47542 47543 47544 47545 47546 47547 47548 47549 47550 47551 47552 47553 47554 47555 47556 47557 47558 47559 47560 47561 47562 47563 47564 47565 47566 47567 47568 47569 47570 47571 47572 47573 47574 47575 47576 47577 47578 47579 47580 47581 47582 47583 47584 47585 47586 47587 47588 47589 47590 47591 47592 47593 47594 47595 47596 47597 47598 47599 47600 47601 47602 47603 47604 47605 47606 47607 47608 47609 47610 47611 47612 47613 47614 47615 47616 47617 47618 47619 47620 47621 47622 47623 47624 47625 47626 47627 47628 47629 47630 47631 47632 47633 47634 47635 47636 47637 47638 47639 47640 47641 47642 47643 47644 47645 47646 47647 47648 47649 47650 47651 47652 47653 47654 47655 47656 47657 47658 47659 47660 47661 47662 47663 47664 47665 47666 47667 47668 47669 47670 47671 47672 47673 47674 47675 47676 47677 47678 47679 47680 47681 47682 47683 47684 47685 47686 47687 47688 47689 47690 47691 47692 47693 47694 47695 47696 47697 47698 47699 47700 47701 47702 47703 47704 47705 47706 47707 47708 47709 47710 47711 47712 47713 47714 47715 47716 47717 47718 47719 47720 47721 47722 47723 47724 47725 47726 47727 47728 47729 47730 47731 47732 47733 47734 47735 47736 47737 47738 47739 47740 47741 47742 47743 47744 47745 47746 47747 47748 47749 47750 47751 47752 47753 47754 47755 47756 47757 47758 47759 47760 47761 47762 47763 47764 47765 47766 47767 47768 47769 47770 47771 47772 47773 47774 47775 47776 47777 47778 47779 47780 47781 47782 47783 47784 47785 47786 47787 47788 47789 47790 47791 47792 47793 47794 47795 47796 47797 47798 47799 47800 47801 47802 47803 47804 47805 47806 47807 47808 47809 47810 47811 47812 47813 47814 47815 47816 47817 47818 47819 47820 47821 47822 47823 47824 47825 47826 47827 47828 47829 47830 47831 47832 47833 47834 47835 47836 47837 47838 47839 47840 47841 47842 47843 47844 47845 47846 47847 47848 47849 47850 47851 47852 47853 47854 47855 47856 47857 47858 47859 47860 47861 47862 47863 47864 47865 47866 47867 47868 47869 47870 47871 47872 47873 47874 47875 47876 47877 47878 47879 47880 47881 47882 47883 47884 47885 47886 47887 47888 47889 47890 47891 47892 47893 47894 47895 47896 47897 47898 47899 47900 47901 47902 47903 47904 47905 47906 47907 47908 47909 47910 47911 47912 47913 47914 47915 47916 47917 47918 47919 47920 47921 47922 47923 47924 47925 47926 47927 47928 47929 47930 47931 47932 47933 47934 47935 47936 47937 47938 47939 47940 47941 47942 47943 47944 47945 47946 47947 47948 47949 47950 47951 47952 47953 47954 47955 47956 47957 47958 47959 47960 47961 47962 47963 47964 47965 47966 47967 47968 47969 47970 47971 47972 47973 47974 47975 47976 47977 47978 47979 47980 47981 47982 47983 47984 47985 47986 47987 47988 47989 47990 47991 47992 47993 47994 47995 47996 47997 47998 47999 48000 48001 48002 48003 48004 48005 48006 48007 48008 48009 48010 48011 48012 48013 48014 48015 48016 48017 48018 48019 48020 48021 48022 48023 48024 48025 48026 48027 48028 48029 48030 48031 48032 48033 48034 48035 48036 48037 48038 48039 48040 48041 48042 48043 48044 48045 48046 48047 48048 48049 48050 48051 48052 48053 48054 48055 48056 48057 48058 48059 48060 48061 48062 48063 48064 48065 48066 48067 48068 48069 48070 48071 48072 48073 48074 48075 48076 48077 48078 48079 48080 48081 48082 48083 48084 48085 48086 48087 48088 48089 48090 48091 48092 48093 48094 48095 48096 48097 48098 48099 48100 48101 48102 48103 48104 48105 48106 48107 48108 48109 48110 48111 48112 48113 48114 48115 48116 48117 48118 48119 48120 48121 48122 48123 48124 48125 48126 48127 48128 48129 48130 48131 48132 48133 48134 48135 48136 48137 48138 48139 48140 48141 48142 48143 48144 48145 48146 48147 48148 48149 48150 48151 48152 48153 48154 48155 48156 48157 48158 48159 48160 48161 48162 48163 48164 48165 48166 48167 48168 48169 48170 48171 48172 48173 48174 48175 48176 48177 48178 48179 48180 48181 48182 48183 48184 48185 48186 48187 48188 48189 48190 48191 48192 48193 48194 48195 48196 48197 48198 48199 48200 48201 48202 48203 48204 48205 48206 48207 48208 48209 48210 48211 48212 48213 48214 48215 48216 48217 48218 48219 48220 48221 48222 48223 48224 48225 48226 48227 48228 48229 48230 48231 48232 48233 48234 48235 48236 48237 48238 48239 48240 48241 48242 48243 48244 48245 48246 48247 48248 48249 48250 48251 48252 48253 48254 48255 48256 48257 48258 48259 48260 48261 48262 48263 48264 48265 48266 48267 48268 48269 48270 48271 48272 48273 48274 48275 48276 48277 48278 48279 48280 48281 48282 48283 48284 48285 48286 48287 48288 48289 48290 48291 48292 48293 48294 48295 48296 48297 48298 48299 48300 48301 48302 48303 48304 48305 48306 48307 48308 48309 48310 48311 48312 48313 48314 48315 48316 48317 48318 48319 48320 48321 48322 48323 48324 48325 48326 48327 48328 48329 48330 48331 48332 48333 48334 48335 48336 48337 48338 48339 48340 48341 48342 48343 48344 48345 48346 48347 48348 48349 48350 48351 48352 48353 48354 48355 48356 48357 48358 48359 48360 48361 48362 48363 48364 48365 48366 48367 48368 48369 48370 48371 48372 48373 48374 48375 48376 48377 48378 48379 48380 48381 48382 48383 48384 48385 48386 48387 48388 48389 48390 48391 48392 48393 48394 48395 48396 48397 48398 48399 48400 48401 48402 48403 48404 48405 48406 48407 48408 48409 48410 48411 48412 48413 48414 48415 48416 48417 48418 48419 48420 48421 48422 48423 48424 48425 48426 48427 48428 48429 48430 48431 48432 48433 48434 48435 48436 48437 48438 48439 48440 48441 48442 48443 48444 48445 48446 48447 48448 48449 48450 48451 48452 48453 48454 48455 48456 48457 48458 48459 48460 48461 48462 48463 48464 48465 48466 48467 48468 48469 48470 48471 48472 48473 48474 48475 48476 48477 48478 48479 48480 48481 48482 48483 48484 48485 48486 48487 48488 48489 48490 48491 48492 48493 48494 48495 48496 48497 48498 48499 48500 48501 48502 48503 48504 48505 48506 48507 48508 48509 48510 48511 48512 48513 48514 48515 48516 48517 48518 48519 48520 48521 48522 48523 48524 48525 48526 48527 48528 48529 48530 48531 48532 48533 48534 48535 48536 48537 48538 48539 48540 48541 48542 48543 48544 48545 48546 48547 48548 48549 48550 48551 48552 48553 48554 48555 48556 48557 48558 48559 48560 48561 48562 48563 48564 48565 48566 48567 48568 48569 48570 48571 48572 48573 48574 48575 48576 48577 48578 48579 48580 48581 48582 48583 48584 48585 48586 48587 48588 48589 48590 48591 48592 48593 48594 48595 48596 48597 48598 48599 48600 48601 48602 48603 48604 48605 48606 48607 48608 48609 48610 48611 48612 48613 48614 48615 48616 48617 48618 48619 48620 48621 48622 48623 48624 48625 48626 48627 48628 48629 48630 48631 48632 48633 48634 48635 48636 48637 48638 48639 48640 48641 48642 48643 48644 48645 48646 48647 48648 48649 48650 48651 48652 48653 48654 48655 48656 48657 48658 48659 48660 48661 48662 48663 48664 48665 48666 48667 48668 48669 48670 48671 48672 48673 48674 48675 48676 48677 48678 48679 48680 48681 48682 48683 48684 48685 48686 48687 48688 48689 48690 48691 48692 48693 48694 48695 48696 48697 48698 48699 48700 48701 48702 48703 48704 48705 48706 48707 48708 48709 48710 48711 48712 48713 48714 48715 48716 48717 48718 48719 48720 48721 48722 48723 48724 48725 48726 48727 48728 48729 48730 48731 48732 48733 48734 48735 48736 48737 48738 48739 48740 48741 48742 48743 48744 48745 48746 48747 48748 48749 48750 48751 48752 48753 48754 48755 48756 48757 48758 48759 48760 48761 48762 48763 48764 48765 48766 48767 48768 48769 48770 48771 48772 48773 48774 48775 48776 48777 48778 48779 48780 48781 48782 48783 48784 48785 48786 48787 48788 48789 48790 48791 48792 48793 48794 48795 48796 48797 48798 48799 48800 48801 48802 48803 48804 48805 48806 48807 48808 48809 48810 48811 48812 48813 48814 48815 48816 48817 48818 48819 48820 48821 48822 48823 48824 48825 48826 48827 48828 48829 48830 48831 48832 48833 48834 48835 48836 48837 48838 48839 48840 48841 48842 48843 48844 48845 48846 48847 48848 48849 48850 48851 48852 48853 48854 48855 48856 48857 48858 48859 48860 48861 48862 48863 48864 48865 48866 48867 48868 48869 48870 48871 48872 48873 48874 48875 48876 48877 48878 48879 48880 48881 48882 48883 48884 48885 48886 48887 48888 48889 48890 48891 48892 48893 48894 48895 48896 48897 48898 48899 48900 48901 48902 48903 48904 48905 48906 48907 48908 48909 48910 48911 48912 48913 48914 48915 48916 48917 48918 48919 48920 48921 48922 48923 48924 48925 48926 48927 48928 48929 48930 48931 48932 48933 48934 48935 48936 48937 48938 48939 48940 48941 48942 48943 48944 48945 48946 48947 48948 48949 48950 48951 48952 48953 48954 48955 48956 48957 48958 48959 48960 48961 48962 48963 48964 48965 48966 48967 48968 48969 48970 48971 48972 48973 48974 48975 48976 48977 48978 48979 48980 48981 48982 48983 48984 48985 48986 48987 48988 48989 48990 48991 48992 48993 48994 48995 48996 48997 48998 48999 49000 49001 49002 49003 49004 49005 49006 49007 49008 49009 49010 49011 49012 49013 49014 49015 49016 49017 49018 49019 49020 49021 49022 49023 49024 49025 49026 49027 49028 49029 49030 49031 49032 49033 49034 49035 49036 49037 49038 49039 49040 49041 49042 49043 49044 49045 49046 49047 49048 49049 49050 49051 49052 49053 49054 49055 49056 49057 49058 49059 49060 49061 49062 49063 49064 49065 49066 49067 49068 49069 49070 49071 49072 49073 49074 49075 49076 49077 49078 49079 49080 49081 49082 49083 49084 49085 49086 49087 49088 49089 49090 49091 49092 49093 49094 49095 49096 49097 49098 49099 49100 49101 49102 49103 49104 49105 49106 49107 49108 49109 49110 49111 49112 49113 49114 49115 49116 49117 49118 49119 49120 49121 49122 49123 49124 49125 49126 49127 49128 49129 49130 49131 49132 49133 49134 49135 49136 49137 49138 49139 49140 49141 49142 49143 49144 49145 49146 49147 49148 49149 49150 49151 49152 49153 49154 49155 49156 49157 49158 49159 49160 49161 49162 49163 49164 49165 49166 49167 49168 49169 49170 49171 49172 49173 49174 49175 49176 49177 49178 49179 49180 49181 49182 49183 49184 49185 49186 49187 49188 49189 49190 49191 49192 49193 49194 49195 49196 49197 49198 49199 49200 49201 49202 49203 49204 49205 49206 49207 49208 49209 49210 49211 49212 49213 49214 49215 49216 49217 49218 49219 49220 49221 49222 49223 49224 49225 49226 49227 49228 49229 49230 49231 49232 49233 49234 49235 49236 49237 49238 49239 49240 49241 49242 49243 49244 49245 49246 49247 49248 49249 49250 49251 49252 49253 49254 49255 49256 49257 49258 49259 49260 49261 49262 49263 49264 49265 49266 49267 49268 49269 49270 49271 49272 49273 49274 49275 49276 49277 49278 49279 49280 49281 49282 49283 49284 49285 49286 49287 49288 49289 49290 49291 49292 49293 49294 49295 49296 49297 49298 49299 49300 49301 49302 49303 49304 49305 49306 49307 49308 49309 49310 49311 49312 49313 49314 49315 49316 49317 49318 49319 49320 49321 49322 49323 49324 49325 49326 49327 49328 49329 49330 49331 49332 49333 49334 49335 49336 49337 49338 49339 49340 49341 49342 49343 49344 49345 49346 49347 49348 49349 49350 49351 49352 49353 49354 49355 49356 49357 49358 49359 49360 49361 49362 49363 49364 49365 49366 49367 49368 49369 49370 49371 49372 49373 49374 49375 49376 49377 49378 49379 49380 49381 49382 49383 49384 49385 49386 49387 49388 49389 49390 49391 49392 49393 49394 49395 49396 49397 49398 49399 49400 49401 49402 49403 49404 49405 49406 49407 49408 49409 49410 49411 49412 49413 49414 49415 49416 49417 49418 49419 49420 49421 49422 49423 49424 49425 49426 49427 49428 49429 49430 49431 49432 49433 49434 49435 49436 49437 49438 49439 49440 49441 49442 49443 49444 49445 49446 49447 49448 49449 49450 49451 49452 49453 49454 49455 49456 49457 49458 49459 49460 49461 49462 49463 49464 49465 49466 49467 49468 49469 49470 49471 49472 49473 49474 49475 49476 49477 49478 49479 49480 49481 49482 49483 49484 49485 49486 49487 49488 49489 49490 49491 49492 49493 49494 49495 49496 49497 49498 49499 49500 49501 49502 49503 49504 49505 49506 49507 49508 49509 49510 49511 49512 49513 49514 49515 49516 49517 49518 49519 49520 49521 49522 49523 49524 49525 49526 49527 49528 49529 49530 49531 49532 49533 49534 49535 49536 49537 49538 49539 49540 49541 49542 49543 49544 49545 49546 49547 49548 49549 49550 49551 49552 49553 49554 49555 49556 49557 49558 49559 49560 49561 49562 49563 49564 49565 49566 49567 49568 49569 49570 49571 49572 49573 49574 49575 49576 49577 49578 49579 49580 49581 49582 49583 49584 49585 49586 49587 49588 49589 49590 49591 49592 49593 49594 49595 49596 49597 49598 49599 49600 49601 49602 49603 49604 49605 49606 49607 49608 49609 49610 49611 49612 49613 49614 49615 49616 49617 49618 49619 49620 49621 49622 49623 49624 49625 49626 49627 49628 49629 49630 49631 49632 49633 49634 49635 49636 49637 49638 49639 49640 49641 49642 49643 49644 49645 49646 49647 49648 49649 49650 49651 49652 49653 49654 49655 49656 49657 49658 49659 49660 49661 49662 49663 49664 49665 49666 49667 49668 49669 49670 49671 49672 49673 49674 49675 49676 49677 49678 49679 49680 49681 49682 49683 49684 49685 49686 49687 49688 49689 49690 49691 49692 49693 49694 49695 49696 49697 49698 49699 49700 49701 49702 49703 49704 49705 49706 49707 49708 49709 49710 49711 49712 49713 49714 49715 49716 49717 49718 49719 49720 49721 49722 49723 49724 49725 49726 49727 49728 49729 49730 49731 49732 49733 49734 49735 49736 49737 49738 49739 49740 49741 49742 49743 49744 49745 49746 49747 49748 49749 49750 49751 49752 49753 49754 49755 49756 49757 49758 49759 49760 49761 49762 49763 49764 49765 49766 49767 49768 49769 49770 49771 49772 49773 49774 49775 49776 49777 49778 49779 49780 49781 49782 49783 49784 49785 49786 49787 49788 49789 49790 49791 49792 49793 49794 49795 49796 49797 49798 49799 49800 49801 49802 49803 49804 49805 49806 49807 49808 49809 49810 49811 49812 49813 49814 49815 49816 49817 49818 49819 49820 49821 49822 49823 49824 49825 49826 49827 49828 49829 49830 49831 49832 49833 49834 49835 49836 49837 49838 49839 49840 49841 49842 49843 49844 49845 49846 49847 49848 49849 49850 49851 49852 49853 49854 49855 49856 49857 49858 49859 49860 49861 49862 49863 49864 49865 49866 49867 49868 49869 49870 49871 49872 49873 49874 49875 49876 49877 49878 49879 49880 49881 49882 49883 49884 49885 49886 49887 49888 49889 49890 49891 49892 49893 49894 49895 49896 49897 49898 49899 49900 49901 49902 49903 49904 49905 49906 49907 49908 49909 49910 49911 49912 49913 49914 49915 49916 49917 49918 49919 49920 49921 49922 49923 49924 49925 49926 49927 49928 49929 49930 49931 49932 49933 49934 49935 49936 49937 49938 49939 49940 49941 49942 49943 49944 49945 49946 49947 49948 49949 49950 49951 49952 49953 49954 49955 49956 49957 49958 49959 49960 49961 49962 49963 49964 49965 49966 49967 49968 49969 49970 49971 49972 49973 49974 49975 49976 49977 49978 49979 49980 49981 49982 49983 49984 49985 49986 49987 49988 49989 49990 49991 49992 49993 49994 49995 49996 49997 49998 49999 50000 50001 50002 50003 50004 50005 50006 50007 50008 50009 50010 50011 50012 50013 50014 50015 50016 50017 50018 50019 50020 50021 50022 50023 50024 50025 50026 50027 50028 50029 50030 50031 50032 50033 50034 50035 50036 50037 50038 50039 50040 50041 50042 50043 50044 50045 50046 50047 50048 50049 50050 50051 50052 50053 50054 50055 50056 50057 50058 50059 50060 50061 50062 50063 50064 50065 50066 50067 50068 50069 50070 50071 50072 50073 50074 50075 50076 50077 50078 50079 50080 50081 50082 50083 50084 50085 50086 50087 50088 50089 50090 50091 50092 50093 50094 50095 50096 50097 50098 50099 50100 50101 50102 50103 50104 50105 50106 50107 50108 50109 50110 50111 50112 50113 50114 50115 50116 50117 50118 50119 50120 50121 50122 50123 50124 50125 50126 50127 50128 50129 50130 50131 50132 50133 50134 50135 50136 50137 50138 50139 50140 50141 50142 50143 50144 50145 50146 50147 50148 50149 50150 50151 50152 50153 50154 50155 50156 50157 50158 50159 50160 50161 50162 50163 50164 50165 50166 50167 50168 50169 50170 50171 50172 50173 50174 50175 50176 50177 50178 50179 50180 50181 50182 50183 50184 50185 50186 50187 50188 50189 50190 50191 50192 50193 50194 50195 50196 50197 50198 50199 50200 50201 50202 50203 50204 50205 50206 50207 50208 50209 50210 50211 50212 50213 50214 50215 50216 50217 50218 50219 50220 50221 50222 50223 50224 50225 50226 50227 50228 50229 50230 50231 50232 50233 50234 50235 50236 50237 50238 50239 50240 50241 50242 50243 50244 50245 50246 50247 50248 50249 50250 50251 50252 50253 50254 50255 50256 50257 50258 50259 50260 50261 50262 50263 50264 50265 50266 50267 50268 50269 50270 50271 50272 50273 50274 50275 50276 50277 50278 50279 50280 50281 50282 50283 50284 50285 50286 50287 50288 50289 50290 50291 50292 50293 50294 50295 50296 50297 50298 50299 50300 50301 50302 50303 50304 50305 50306 50307 50308 50309 50310 50311 50312 50313 50314 50315 50316 50317 50318 50319 50320 50321 50322 50323 50324 50325 50326 50327 50328 50329 50330 50331 50332 50333 50334 50335 50336 50337 50338 50339 50340 50341 50342 50343 50344 50345 50346 50347 50348 50349 50350 50351 50352 50353 50354 50355 50356 50357 50358 50359 50360 50361 50362 50363 50364 50365 50366 50367 50368 50369 50370 50371 50372 50373 50374 50375 50376 50377 50378 50379 50380 50381 50382 50383 50384 50385 50386 50387 50388 50389 50390 50391 50392 50393 50394 50395 50396 50397 50398 50399 50400 50401 50402 50403 50404 50405 50406 50407 50408 50409 50410 50411 50412 50413 50414 50415 50416 50417 50418 50419 50420 50421 50422 50423 50424 50425 50426 50427 50428 50429 50430 50431 50432 50433 50434 50435 50436 50437 50438 50439 50440 50441 50442 50443 50444 50445 50446 50447 50448 50449 50450 50451 50452 50453 50454 50455 50456 50457 50458 50459 50460 50461 50462 50463 50464 50465 50466 50467 50468 50469 50470 50471 50472 50473 50474 50475 50476 50477 50478 50479 50480 50481 50482 50483 50484 50485 50486 50487 50488 50489 50490 50491 50492 50493 50494 50495 50496 50497 50498 50499 50500 50501 50502 50503 50504 50505 50506 50507 50508 50509 50510 50511 50512 50513 50514 50515 50516 50517 50518 50519 50520 50521 50522 50523 50524 50525 50526 50527 50528 50529 50530 50531 50532 50533 50534 50535 50536 50537 50538 50539 50540 50541 50542 50543 50544 50545 50546 50547 50548 50549 50550 50551 50552 50553 50554 50555 50556 50557 50558 50559 50560 50561 50562 50563 50564 50565 50566 50567 50568 50569 50570 50571 50572 50573 50574 50575 50576 50577 50578 50579 50580 50581 50582 50583 50584 50585 50586 50587 50588 50589 50590 50591 50592 50593 50594 50595 50596 50597 50598 50599 50600 50601 50602 50603 50604 50605 50606 50607 50608 50609 50610 50611 50612 50613 50614 50615 50616 50617 50618 50619 50620 50621 50622 50623 50624 50625 50626 50627 50628 50629 50630 50631 50632 50633 50634 50635 50636 50637 50638 50639 50640 50641 50642 50643 50644 50645 50646 50647 50648 50649 50650 50651 50652 50653 50654 50655 50656 50657 50658 50659 50660 50661 50662 50663 50664 50665 50666 50667 50668 50669 50670 50671 50672 50673 50674 50675 50676 50677 50678 50679 50680 50681 50682 50683 50684 50685 50686 50687 50688 50689 50690 50691 50692 50693 50694 50695 50696 50697 50698 50699 50700 50701 50702 50703 50704 50705 50706 50707 50708 50709 50710 50711 50712 50713 50714 50715 50716 50717 50718 50719 50720 50721 50722 50723 50724 50725 50726 50727 50728 50729 50730 50731 50732 50733 50734 50735 50736 50737 50738 50739 50740 50741 50742 50743 50744 50745 50746 50747 50748 50749 50750 50751 50752 50753 50754 50755 50756 50757 50758 50759 50760 50761 50762 50763 50764 50765 50766 50767 50768 50769 50770 50771 50772 50773 50774 50775 50776 50777 50778 50779 50780 50781 50782 50783 50784 50785 50786 50787 50788 50789 50790 50791 50792 50793 50794 50795 50796 50797 50798 50799 50800 50801 50802 50803 50804 50805 50806 50807 50808 50809 50810 50811 50812 50813 50814 50815 50816 50817 50818 50819 50820 50821 50822 50823 50824 50825 50826 50827 50828 50829 50830 50831 50832 50833 50834 50835 50836 50837 50838 50839 50840 50841 50842 50843 50844 50845 50846 50847 50848 50849 50850 50851 50852 50853 50854 50855 50856 50857 50858 50859 50860 50861 50862 50863 50864 50865 50866 50867 50868 50869 50870 50871 50872 50873 50874 50875 50876 50877 50878 50879 50880 50881 50882 50883 50884 50885 50886 50887 50888 50889 50890 50891 50892 50893 50894 50895 50896 50897 50898 50899 50900 50901 50902 50903 50904 50905 50906 50907 50908 50909 50910 50911 50912 50913 50914 50915 50916 50917 50918 50919 50920 50921 50922 50923 50924 50925 50926 50927 50928 50929 50930 50931 50932 50933 50934 50935 50936 50937 50938 50939 50940 50941 50942 50943 50944 50945 50946 50947 50948 50949 50950 50951 50952 50953 50954 50955 50956 50957 50958 50959 50960 50961 50962 50963 50964 50965 50966 50967 50968 50969 50970 50971 50972 50973 50974 50975 50976 50977 50978 50979 50980 50981 50982 50983 50984 50985 50986 50987 50988 50989 50990 50991 50992 50993 50994 50995 50996 50997 50998 50999 51000 51001 51002 51003 51004 51005 51006 51007 51008 51009 51010 51011 51012 51013 51014 51015 51016 51017 51018 51019 51020 51021 51022 51023 51024 51025 51026 51027 51028 51029 51030 51031 51032 51033 51034 51035 51036 51037 51038 51039 51040 51041 51042 51043 51044 51045 51046 51047 51048 51049 51050 51051 51052 51053 51054 51055 51056 51057 51058 51059 51060 51061 51062 51063 51064 51065 51066 51067 51068 51069 51070 51071 51072 51073 51074 51075 51076 51077 51078 51079 51080 51081 51082 51083 51084 51085 51086 51087 51088 51089 51090 51091 51092 51093 51094 51095 51096 51097 51098 51099 51100 51101 51102 51103 51104 51105 51106 51107 51108 51109 51110 51111 51112 51113 51114 51115 51116 51117 51118 51119 51120 51121 51122 51123 51124 51125 51126 51127 51128 51129 51130 51131 51132 51133 51134 51135 51136 51137 51138 51139 51140 51141 51142 51143 51144 51145 51146 51147 51148 51149 51150 51151 51152 51153 51154 51155 51156 51157 51158 51159 51160 51161 51162 51163 51164 51165 51166 51167 51168 51169 51170 51171 51172 51173 51174 51175 51176 51177 51178 51179 51180 51181 51182 51183 51184 51185 51186 51187 51188 51189 51190 51191 51192 51193 51194 51195 51196 51197 51198 51199 51200 51201 51202 51203 51204 51205 51206 51207 51208 51209 51210 51211 51212 51213 51214 51215 51216 51217 51218 51219 51220 51221 51222 51223 51224 51225 51226 51227 51228 51229 51230 51231 51232 51233 51234 51235 51236 51237 51238 51239 51240 51241 51242 51243 51244 51245 51246 51247 51248 51249 51250 51251 51252 51253 51254 51255 51256 51257 51258 51259 51260 51261 51262 51263 51264 51265 51266 51267 51268 51269 51270 51271 51272 51273 51274 51275 51276 51277 51278 51279 51280 51281 51282 51283 51284 51285 51286 51287 51288 51289 51290 51291 51292 51293 51294 51295 51296 51297 51298 51299 51300 51301 51302 51303 51304 51305 51306 51307 51308 51309 51310 51311 51312 51313 51314 51315 51316 51317 51318 51319 51320 51321 51322 51323 51324 51325 51326 51327 51328 51329 51330 51331 51332 51333 51334 51335 51336 51337 51338 51339 51340 51341 51342 51343 51344 51345 51346 51347 51348 51349 51350 51351 51352 51353 51354 51355 51356 51357 51358 51359 51360 51361 51362 51363 51364 51365 51366 51367 51368 51369 51370 51371 51372 51373 51374 51375 51376 51377 51378 51379 51380 51381 51382 51383 51384 51385 51386 51387 51388 51389 51390 51391 51392 51393 51394 51395 51396 51397 51398 51399 51400 51401 51402 51403 51404 51405 51406 51407 51408 51409 51410 51411 51412 51413 51414 51415 51416 51417 51418 51419 51420 51421 51422 51423 51424 51425 51426 51427 51428 51429 51430 51431 51432 51433 51434 51435 51436 51437 51438 51439 51440 51441 51442 51443 51444 51445 51446 51447 51448 51449 51450 51451 51452 51453 51454 51455 51456 51457 51458 51459 51460 51461 51462 51463 51464 51465 51466 51467 51468 51469 51470 51471 51472 51473 51474 51475 51476 51477 51478 51479 51480 51481 51482 51483 51484 51485 51486 51487 51488 51489 51490 51491 51492 51493 51494 51495 51496 51497 51498 51499 51500 51501 51502 51503 51504 51505 51506 51507 51508 51509 51510 51511 51512 51513 51514 51515 51516 51517 51518 51519 51520 51521 51522 51523 51524 51525 51526 51527 51528 51529 51530 51531 51532 51533 51534 51535 51536 51537 51538 51539 51540 51541 51542 51543 51544 51545 51546 51547 51548 51549 51550 51551 51552 51553 51554 51555 51556 51557 51558 51559 51560 51561 51562 51563 51564 51565 51566 51567 51568 51569 51570 51571 51572 51573 51574 51575 51576 51577 51578 51579 51580 51581 51582 51583 51584 51585 51586 51587 51588 51589 51590 51591 51592 51593 51594 51595 51596 51597 51598 51599 51600 51601 51602 51603 51604 51605 51606 51607 51608 51609 51610 51611 51612 51613 51614 51615 51616 51617 51618 51619 51620 51621 51622 51623 51624 51625 51626 51627 51628 51629 51630 51631 51632 51633 51634 51635 51636 51637 51638 51639 51640 51641 51642 51643 51644 51645 51646 51647 51648 51649 51650 51651 51652 51653 51654 51655 51656 51657 51658 51659 51660 51661 51662 51663 51664 51665 51666 51667 51668 51669 51670 51671 51672 51673 51674 51675 51676 51677 51678 51679 51680 51681 51682 51683 51684 51685 51686 51687 51688 51689 51690 51691 51692 51693 51694 51695 51696 51697 51698 51699 51700 51701 51702 51703 51704 51705 51706 51707 51708 51709 51710 51711 51712 51713 51714 51715 51716 51717 51718 51719 51720 51721 51722 51723 51724 51725 51726 51727 51728 51729 51730 51731 51732 51733 51734 51735 51736 51737 51738 51739 51740 51741 51742 51743 51744 51745 51746 51747 51748 51749 51750 51751 51752 51753 51754 51755 51756 51757 51758 51759 51760 51761 51762 51763 51764 51765 51766 51767 51768 51769 51770 51771 51772 51773 51774 51775 51776 51777 51778 51779 51780 51781 51782 51783 51784 51785 51786 51787 51788 51789 51790 51791 51792 51793 51794 51795 51796 51797 51798 51799 51800 51801 51802 51803 51804 51805 51806 51807 51808 51809 51810 51811 51812 51813 51814 51815 51816 51817 51818 51819 51820 51821 51822 51823 51824 51825 51826 51827 51828 51829 51830 51831 51832 51833 51834 51835 51836 51837 51838 51839 51840 51841 51842 51843 51844 51845 51846 51847 51848 51849 51850 51851 51852 51853 51854 51855 51856 51857 51858 51859 51860 51861 51862 51863 51864 51865 51866 51867 51868 51869 51870 51871 51872 51873 51874 51875 51876 51877 51878 51879 51880 51881 51882 51883 51884 51885 51886 51887 51888 51889 51890 51891 51892 51893 51894 51895 51896 51897 51898 51899 51900 51901 51902 51903 51904 51905 51906 51907 51908 51909 51910 51911 51912 51913 51914 51915 51916 51917 51918 51919 51920 51921 51922 51923 51924 51925 51926 51927 51928 51929 51930 51931 51932 51933 51934 51935 51936 51937 51938 51939 51940 51941 51942 51943 51944 51945 51946 51947 51948 51949 51950 51951 51952 51953 51954 51955 51956 51957 51958 51959 51960 51961 51962 51963 51964 51965 51966 51967 51968 51969 51970 51971 51972 51973 51974 51975 51976 51977 51978 51979 51980 51981 51982 51983 51984 51985 51986 51987 51988 51989 51990 51991 51992 51993 51994 51995 51996 51997 51998 51999 52000 52001 52002 52003 52004 52005 52006 52007 52008 52009 52010 52011 52012 52013 52014 52015 52016 52017 52018 52019 52020 52021 52022 52023 52024 52025 52026 52027 52028 52029 52030 52031 52032 52033 52034 52035 52036 52037 52038 52039 52040 52041 52042 52043 52044 52045 52046 52047 52048 52049 52050 52051 52052 52053 52054 52055 52056 52057 52058 52059 52060 52061 52062 52063 52064 52065 52066 52067 52068 52069 52070 52071 52072 52073 52074 52075 52076 52077 52078 52079 52080 52081 52082 52083 52084 52085 52086 52087 52088 52089 52090 52091 52092 52093 52094 52095 52096 52097 52098 52099 52100 52101 52102 52103 52104 52105 52106 52107 52108 52109 52110 52111 52112 52113 52114 52115 52116 52117 52118 52119 52120 52121 52122 52123 52124 52125 52126 52127 52128 52129 52130 52131 52132 52133 52134 52135 52136 52137 52138 52139 52140 52141 52142 52143 52144 52145 52146 52147 52148 52149 52150 52151 52152 52153 52154 52155 52156 52157 52158 52159 52160 52161 52162 52163 52164 52165 52166 52167 52168 52169 52170 52171 52172 52173 52174 52175 52176 52177 52178 52179 52180 52181 52182 52183 52184 52185 52186 52187 52188 52189 52190 52191 52192 52193 52194 52195 52196 52197 52198 52199 52200 52201 52202 52203 52204 52205 52206 52207 52208 52209 52210 52211 52212 52213 52214 52215 52216 52217 52218 52219 52220 52221 52222 52223 52224 52225 52226 52227 52228 52229 52230 52231 52232 52233 52234 52235 52236 52237 52238 52239 52240 52241 52242 52243 52244 52245 52246 52247 52248 52249 52250 52251 52252 52253 52254 52255 52256 52257 52258 52259 52260 52261 52262 52263 52264 52265 52266 52267 52268 52269 52270 52271 52272 52273 52274 52275 52276 52277 52278 52279 52280 52281 52282 52283 52284 52285 52286 52287 52288 52289 52290 52291 52292 52293 52294 52295 52296 52297 52298 52299 52300 52301 52302 52303 52304 52305 52306 52307 52308 52309 52310 52311 52312 52313 52314 52315 52316 52317 52318 52319 52320 52321 52322 52323 52324 52325 52326 52327 52328 52329 52330 52331 52332 52333 52334 52335 52336 52337 52338 52339 52340 52341 52342 52343 52344 52345 52346 52347 52348 52349 52350 52351 52352 52353 52354 52355 52356 52357 52358 52359 52360 52361 52362 52363 52364 52365 52366 52367 52368 52369 52370 52371 52372 52373 52374 52375 52376 52377 52378 52379 52380 52381 52382 52383 52384 52385 52386 52387 52388 52389 52390 52391 52392 52393 52394 52395 52396 52397 52398 52399 52400 52401 52402 52403 52404 52405 52406 52407 52408 52409 52410 52411 52412 52413 52414 52415 52416 52417 52418 52419 52420 52421 52422 52423 52424 52425 52426 52427 52428 52429 52430 52431 52432 52433 52434 52435 52436 52437 52438 52439 52440 52441 52442 52443 52444 52445 52446 52447 52448 52449 52450 52451 52452 52453 52454 52455 52456 52457 52458 52459 52460 52461 52462 52463 52464 52465 52466 52467 52468 52469 52470 52471 52472 52473 52474 52475 52476 52477 52478 52479 52480 52481 52482 52483 52484 52485 52486 52487 52488 52489 52490 52491 52492 52493 52494 52495 52496 52497 52498 52499 52500 52501 52502 52503 52504 52505 52506 52507 52508 52509 52510 52511 52512 52513 52514 52515 52516 52517 52518 52519 52520 52521 52522 52523 52524 52525 52526 52527 52528 52529 52530 52531 52532 52533 52534 52535 52536 52537 52538 52539 52540 52541 52542 52543 52544 52545 52546 52547 52548 52549 52550 52551 52552 52553 52554 52555 52556 52557 52558 52559 52560 52561 52562 52563 52564 52565 52566 52567 52568 52569 52570 52571 52572 52573 52574 52575 52576 52577 52578 52579 52580 52581 52582 52583 52584 52585 52586 52587 52588 52589 52590 52591 52592 52593 52594 52595 52596 52597 52598 52599 52600 52601 52602 52603 52604 52605 52606 52607 52608 52609 52610 52611 52612 52613 52614 52615 52616 52617 52618 52619 52620 52621 52622 52623 52624 52625 52626 52627 52628 52629 52630 52631 52632 52633 52634 52635 52636 52637 52638 52639 52640 52641 52642 52643 52644 52645 52646 52647 52648 52649 52650 52651 52652 52653 52654 52655 52656 52657 52658 52659 52660 52661 52662 52663 52664 52665 52666 52667 52668 52669 52670 52671 52672 52673 52674 52675 52676 52677 52678 52679 52680 52681 52682 52683 52684 52685 52686 52687 52688 52689 52690 52691 52692 52693 52694 52695 52696 52697 52698 52699 52700 52701 52702 52703 52704 52705 52706 52707 52708 52709 52710 52711 52712 52713 52714 52715 52716 52717 52718 52719 52720 52721 52722 52723 52724 52725 52726 52727 52728 52729 52730 52731 52732 52733 52734 52735 52736 52737 52738 52739 52740 52741 52742 52743 52744 52745 52746 52747 52748 52749 52750 52751 52752 52753 52754 52755 52756 52757 52758 52759 52760 52761 52762 52763 52764 52765 52766 52767 52768 52769 52770 52771 52772 52773 52774 52775 52776 52777 52778 52779 52780 52781 52782 52783 52784 52785 52786 52787 52788 52789 52790 52791 52792 52793 52794 52795 52796 52797 52798 52799 52800 52801 52802 52803 52804 52805 52806 52807 52808 52809 52810 52811 52812 52813 52814 52815 52816 52817 52818 52819 52820 52821 52822 52823 52824 52825 52826 52827 52828 52829 52830 52831 52832 52833 52834 52835 52836 52837 52838 52839 52840 52841 52842 52843 52844 52845 52846 52847 52848 52849 52850 52851 52852 52853 52854 52855 52856 52857 52858 52859 52860 52861 52862 52863 52864 52865 52866 52867 52868 52869 52870 52871 52872 52873 52874 52875 52876 52877 52878 52879 52880 52881 52882 52883 52884 52885 52886 52887 52888 52889 52890 52891 52892 52893 52894 52895 52896 52897 52898 52899 52900 52901 52902 52903 52904 52905 52906 52907 52908 52909 52910 52911 52912 52913 52914 52915 52916 52917 52918 52919 52920 52921 52922 52923 52924 52925 52926 52927 52928 52929 52930 52931 52932 52933 52934 52935 52936 52937 52938 52939 52940 52941 52942 52943 52944 52945 52946 52947 52948 52949 52950 52951 52952 52953 52954 52955 52956 52957 52958 52959 52960 52961 52962 52963 52964 52965 52966 52967 52968 52969 52970 52971 52972 52973 52974 52975 52976 52977 52978 52979 52980 52981 52982 52983 52984 52985 52986 52987 52988 52989 52990 52991 52992 52993 52994 52995 52996 52997 52998 52999 53000 53001 53002 53003 53004 53005 53006 53007 53008 53009 53010 53011 53012 53013 53014 53015 53016 53017 53018 53019 53020 53021 53022 53023 53024 53025 53026 53027 53028 53029 53030 53031 53032 53033 53034 53035 53036 53037 53038 53039 53040 53041 53042 53043 53044 53045 53046 53047 53048 53049 53050 53051 53052 53053 53054 53055 53056 53057 53058 53059 53060 53061 53062 53063 53064 53065 53066 53067 53068 53069 53070 53071 53072 53073 53074 53075 53076 53077 53078 53079 53080 53081 53082 53083 53084 53085 53086 53087 53088 53089 53090 53091 53092 53093 53094 53095 53096 53097 53098 53099 53100 53101 53102 53103 53104 53105 53106 53107 53108 53109 53110 53111 53112 53113 53114 53115 53116 53117 53118 53119 53120 53121 53122 53123 53124 53125 53126 53127 53128 53129 53130 53131 53132 53133 53134 53135 53136 53137 53138 53139 53140 53141 53142 53143 53144 53145 53146 53147 53148 53149 53150 53151 53152 53153 53154 53155 53156 53157 53158 53159 53160 53161 53162 53163 53164 53165 53166 53167 53168 53169 53170 53171 53172 53173 53174 53175 53176 53177 53178 53179 53180 53181 53182 53183 53184 53185 53186 53187 53188 53189 53190 53191 53192 53193 53194 53195 53196 53197 53198 53199 53200 53201 53202 53203 53204 53205 53206 53207 53208 53209 53210 53211 53212 53213 53214 53215 53216 53217 53218 53219 53220 53221 53222 53223 53224 53225 53226 53227 53228 53229 53230 53231 53232 53233 53234 53235 53236 53237 53238 53239 53240 53241 53242 53243 53244 53245 53246 53247 53248 53249 53250 53251 53252 53253 53254 53255 53256 53257 53258 53259 53260 53261 53262 53263 53264 53265 53266 53267 53268 53269 53270 53271 53272 53273 53274 53275 53276 53277 53278 53279 53280 53281 53282 53283 53284 53285 53286 53287 53288 53289 53290 53291 53292 53293 53294 53295 53296 53297 53298 53299 53300 53301 53302 53303 53304 53305 53306 53307 53308 53309 53310 53311 53312 53313 53314 53315 53316 53317 53318 53319 53320 53321 53322 53323 53324 53325 53326 53327 53328 53329 53330 53331 53332 53333 53334 53335 53336 53337 53338 53339 53340 53341 53342 53343 53344 53345 53346 53347 53348 53349 53350 53351 53352 53353 53354 53355 53356 53357 53358 53359 53360 53361 53362 53363 53364 53365 53366 53367 53368 53369 53370 53371 53372 53373 53374 53375 53376 53377 53378 53379 53380 53381 53382 53383 53384 53385 53386 53387 53388 53389 53390 53391 53392 53393 53394 53395 53396 53397 53398 53399 53400 53401 53402 53403 53404 53405 53406 53407 53408 53409 53410 53411 53412 53413 53414 53415 53416 53417 53418 53419 53420 53421 53422 53423 53424 53425 53426 53427 53428 53429 53430 53431 53432 53433 53434 53435 53436 53437 53438 53439 53440 53441 53442 53443 53444 53445 53446 53447 53448 53449 53450 53451 53452 53453 53454 53455 53456 53457 53458 53459 53460 53461 53462 53463 53464 53465 53466 53467 53468 53469 53470 53471 53472 53473 53474 53475 53476 53477 53478 53479 53480 53481 53482 53483 53484 53485 53486 53487 53488 53489 53490 53491 53492 53493 53494 53495 53496 53497 53498 53499 53500 53501 53502 53503 53504 53505 53506 53507 53508 53509 53510 53511 53512 53513 53514 53515 53516 53517 53518 53519 53520 53521 53522 53523 53524 53525 53526 53527 53528 53529 53530 53531 53532 53533 53534 53535 53536 53537 53538 53539 53540 53541 53542 53543 53544 53545 53546 53547 53548 53549 53550 53551 53552 53553 53554 53555 53556 53557 53558 53559 53560 53561 53562 53563 53564 53565 53566 53567 53568 53569 53570 53571 53572 53573 53574 53575 53576 53577 53578 53579 53580 53581 53582 53583 53584 53585 53586 53587 53588 53589 53590 53591 53592 53593 53594 53595 53596 53597 53598 53599 53600 53601 53602 53603 53604 53605 53606 53607 53608 53609 53610 53611 53612 53613 53614 53615 53616 53617 53618 53619 53620 53621 53622 53623 53624 53625 53626 53627 53628 53629 53630 53631 53632 53633 53634 53635 53636 53637 53638 53639 53640 53641 53642 53643 53644 53645 53646 53647 53648 53649 53650 53651 53652 53653 53654 53655 53656 53657 53658 53659 53660 53661 53662 53663 53664 53665 53666 53667 53668 53669 53670 53671 53672 53673 53674 53675 53676 53677 53678 53679 53680 53681 53682 53683 53684 53685 53686 53687 53688 53689 53690 53691 53692 53693 53694 53695 53696 53697 53698 53699 53700 53701 53702 53703 53704 53705 53706 53707 53708 53709 53710 53711 53712 53713 53714 53715 53716 53717 53718 53719 53720 53721 53722 53723 53724 53725 53726 53727 53728 53729 53730 53731 53732 53733 53734 53735 53736 53737 53738 53739 53740 53741 53742 53743 53744 53745 53746 53747 53748 53749 53750 53751 53752 53753 53754 53755 53756 53757 53758 53759 53760 53761 53762 53763 53764 53765 53766 53767 53768 53769 53770 53771 53772 53773 53774 53775 53776 53777 53778 53779 53780 53781 53782 53783 53784 53785 53786 53787 53788 53789 53790 53791 53792 53793 53794 53795 53796 53797 53798 53799 53800 53801 53802 53803 53804 53805 53806 53807 53808 53809 53810 53811 53812 53813 53814 53815 53816 53817 53818 53819 53820 53821 53822 53823 53824 53825 53826 53827 53828 53829 53830 53831 53832 53833 53834 53835 53836 53837 53838 53839 53840 53841 53842 53843 53844 53845 53846 53847 53848 53849 53850 53851 53852 53853 53854 53855 53856 53857 53858 53859 53860 53861 53862 53863 53864 53865 53866 53867 53868 53869 53870 53871 53872 53873 53874 53875 53876 53877 53878 53879 53880 53881 53882 53883 53884 53885 53886 53887 53888 53889 53890 53891 53892 53893 53894 53895 53896 53897 53898 53899 53900 53901 53902 53903 53904 53905 53906 53907 53908 53909 53910 53911 53912 53913 53914 53915 53916 53917 53918 53919 53920 53921 53922 53923 53924 53925 53926 53927 53928 53929 53930 53931 53932 53933 53934 53935 53936 53937 53938 53939 53940 53941 53942 53943 53944 53945 53946 53947 53948 53949 53950 53951 53952 53953 53954 53955 53956 53957 53958 53959 53960 53961 53962 53963 53964 53965 53966 53967 53968 53969 53970 53971 53972 53973 53974 53975 53976 53977 53978 53979 53980 53981 53982 53983 53984 53985 53986 53987 53988 53989 53990 53991 53992 53993 53994 53995 53996 53997 53998 53999 54000 54001 54002 54003 54004 54005 54006 54007 54008 54009 54010 54011 54012 54013 54014 54015 54016 54017 54018 54019 54020 54021 54022 54023 54024 54025 54026 54027 54028 54029 54030 54031 54032 54033 54034 54035 54036 54037 54038 54039 54040 54041 54042 54043 54044 54045 54046 54047 54048 54049 54050 54051 54052 54053 54054 54055 54056 54057 54058 54059 54060 54061 54062 54063 54064 54065 54066 54067 54068 54069 54070 54071 54072 54073 54074 54075 54076 54077 54078 54079 54080 54081 54082 54083 54084 54085 54086 54087 54088 54089 54090 54091 54092 54093 54094 54095 54096 54097 54098 54099 54100 54101 54102 54103 54104 54105 54106 54107 54108 54109 54110 54111 54112 54113 54114 54115 54116 54117 54118 54119 54120 54121 54122 54123 54124 54125 54126 54127 54128 54129 54130 54131 54132 54133 54134 54135 54136 54137 54138 54139 54140 54141 54142 54143 54144 54145 54146 54147 54148 54149 54150 54151 54152 54153 54154 54155 54156 54157 54158 54159 54160 54161 54162 54163 54164 54165 54166 54167 54168 54169 54170 54171 54172 54173 54174 54175 54176 54177 54178 54179 54180 54181 54182 54183 54184 54185 54186 54187 54188 54189 54190 54191 54192 54193 54194 54195 54196 54197 54198 54199 54200 54201 54202 54203 54204 54205 54206 54207 54208 54209 54210 54211 54212 54213 54214 54215 54216 54217 54218 54219 54220 54221 54222 54223 54224 54225 54226 54227 54228 54229 54230 54231 54232 54233 54234 54235 54236 54237 54238 54239 54240 54241 54242 54243 54244 54245 54246 54247 54248 54249 54250 54251 54252 54253 54254 54255 54256 54257 54258 54259 54260 54261 54262 54263 54264 54265 54266 54267 54268 54269 54270 54271 54272 54273 54274 54275 54276 54277 54278 54279 54280 54281 54282 54283 54284 54285 54286 54287 54288 54289 54290 54291 54292 54293 54294 54295 54296 54297 54298 54299 54300 54301 54302 54303 54304 54305 54306 54307 54308 54309 54310 54311 54312 54313 54314 54315 54316 54317 54318 54319 54320 54321 54322 54323 54324 54325 54326 54327 54328 54329 54330 54331 54332 54333 54334 54335 54336 54337 54338 54339 54340 54341 54342 54343 54344 54345 54346 54347 54348 54349 54350 54351 54352 54353 54354 54355 54356 54357 54358 54359 54360 54361 54362 54363 54364 54365 54366 54367 54368 54369 54370 54371 54372 54373 54374 54375 54376 54377 54378 54379 54380 54381 54382 54383 54384 54385 54386 54387 54388 54389 54390 54391 54392 54393 54394 54395 54396 54397 54398 54399 54400 54401 54402 54403 54404 54405 54406 54407 54408 54409 54410 54411 54412 54413 54414 54415 54416 54417 54418 54419 54420 54421 54422 54423 54424 54425 54426 54427 54428 54429 54430 54431 54432 54433 54434 54435 54436 54437 54438 54439 54440 54441 54442 54443 54444 54445 54446 54447 54448 54449 54450 54451 54452 54453 54454 54455 54456 54457 54458 54459 54460 54461 54462 54463 54464 54465 54466 54467 54468 54469 54470 54471 54472 54473 54474 54475 54476 54477 54478 54479 54480 54481 54482 54483 54484 54485 54486 54487 54488 54489 54490 54491 54492 54493 54494 54495 54496 54497 54498 54499 54500 54501 54502 54503 54504 54505 54506 54507 54508 54509 54510 54511 54512 54513 54514 54515 54516 54517 54518 54519 54520 54521 54522 54523 54524 54525 54526 54527 54528 54529 54530 54531 54532 54533 54534 54535 54536 54537 54538 54539 54540 54541 54542 54543 54544 54545 54546 54547 54548 54549 54550 54551 54552 54553 54554 54555 54556 54557 54558 54559 54560 54561 54562 54563 54564 54565 54566 54567 54568 54569 54570 54571 54572 54573 54574 54575 54576 54577 54578 54579 54580 54581 54582 54583 54584 54585 54586 54587 54588 54589 54590 54591 54592 54593 54594 54595 54596 54597 54598 54599 54600 54601 54602 54603 54604 54605 54606 54607 54608 54609 54610 54611 54612 54613 54614 54615 54616 54617 54618 54619 54620 54621 54622 54623 54624 54625 54626 54627 54628 54629 54630 54631 54632 54633 54634 54635 54636 54637 54638 54639 54640 54641 54642 54643 54644 54645 54646 54647 54648 54649 54650 54651 54652 54653 54654 54655 54656 54657 54658 54659 54660 54661 54662 54663 54664 54665 54666 54667 54668 54669 54670 54671 54672 54673 54674 54675 54676 54677 54678 54679 54680 54681 54682 54683 54684 54685 54686 54687 54688 54689 54690 54691 54692 54693 54694 54695 54696 54697 54698 54699 54700 54701 54702 54703 54704 54705 54706 54707 54708 54709 54710 54711 54712 54713 54714 54715 54716 54717 54718 54719 54720 54721 54722 54723 54724 54725 54726 54727 54728 54729 54730 54731 54732 54733 54734 54735 54736 54737 54738 54739 54740 54741 54742 54743 54744 54745 54746 54747 54748 54749 54750 54751 54752 54753 54754 54755 54756 54757 54758 54759 54760 54761 54762 54763 54764 54765 54766 54767 54768 54769 54770 54771 54772 54773 54774 54775 54776 54777 54778 54779 54780 54781 54782 54783 54784 54785 54786 54787 54788 54789 54790 54791 54792 54793 54794 54795 54796 54797 54798 54799 54800 54801 54802 54803 54804 54805 54806 54807 54808 54809 54810 54811 54812 54813 54814 54815 54816 54817 54818 54819 54820 54821 54822 54823 54824 54825 54826 54827 54828 54829 54830 54831 54832 54833 54834 54835 54836 54837 54838 54839 54840 54841 54842 54843 54844 54845 54846 54847 54848 54849 54850 54851 54852 54853 54854 54855 54856 54857 54858 54859 54860 54861 54862 54863 54864 54865 54866 54867 54868 54869 54870 54871 54872 54873 54874 54875 54876 54877 54878 54879 54880 54881 54882 54883 54884 54885 54886 54887 54888 54889 54890 54891 54892 54893 54894 54895 54896 54897 54898 54899 54900 54901 54902 54903 54904 54905 54906 54907 54908 54909 54910 54911 54912 54913 54914 54915 54916 54917 54918 54919 54920 54921 54922 54923 54924 54925 54926 54927 54928 54929 54930 54931 54932 54933 54934 54935 54936 54937 54938 54939 54940 54941 54942 54943 54944 54945 54946 54947 54948 54949 54950 54951 54952 54953 54954 54955 54956 54957 54958 54959 54960 54961 54962 54963 54964 54965 54966 54967 54968 54969 54970 54971 54972 54973 54974 54975 54976 54977 54978 54979 54980 54981 54982 54983 54984 54985 54986 54987 54988 54989 54990 54991 54992 54993 54994 54995 54996 54997 54998 54999 55000 55001 55002 55003 55004 55005 55006 55007 55008 55009 55010 55011 55012 55013 55014 55015 55016 55017 55018 55019 55020 55021 55022 55023 55024 55025 55026 55027 55028 55029 55030 55031 55032 55033 55034 55035 55036 55037 55038 55039 55040 55041 55042 55043 55044 55045 55046 55047 55048 55049 55050 55051 55052 55053 55054 55055 55056 55057 55058 55059 55060 55061 55062 55063 55064 55065 55066 55067 55068 55069 55070 55071 55072 55073 55074 55075 55076 55077 55078 55079 55080 55081 55082 55083 55084 55085 55086 55087 55088 55089 55090 55091 55092 55093 55094 55095 55096 55097 55098 55099 55100 55101 55102 55103 55104 55105 55106 55107 55108 55109 55110 55111 55112 55113 55114 55115 55116 55117 55118 55119 55120 55121 55122 55123 55124 55125 55126 55127 55128 55129 55130 55131 55132 55133 55134 55135 55136 55137 55138 55139 55140 55141 55142 55143 55144 55145 55146 55147 55148 55149 55150 55151 55152 55153 55154 55155 55156 55157 55158 55159 55160 55161 55162 55163 55164 55165 55166 55167 55168 55169 55170 55171 55172 55173 55174 55175 55176 55177 55178 55179 55180 55181 55182 55183 55184 55185 55186 55187 55188 55189 55190 55191 55192 55193 55194 55195 55196 55197 55198 55199 55200 55201 55202 55203 55204 55205 55206 55207 55208 55209 55210 55211 55212 55213 55214 55215 55216 55217 55218 55219 55220 55221 55222 55223 55224 55225 55226 55227 55228 55229 55230 55231 55232 55233 55234 55235 55236 55237 55238 55239 55240 55241 55242 55243 55244 55245 55246 55247 55248 55249 55250 55251 55252 55253 55254 55255 55256 55257 55258 55259 55260 55261 55262 55263 55264 55265 55266 55267 55268 55269 55270 55271 55272 55273 55274 55275 55276 55277 55278 55279 55280 55281 55282 55283 55284 55285 55286 55287 55288 55289 55290 55291 55292 55293 55294 55295 55296 55297 55298 55299 55300 55301 55302 55303 55304 55305 55306 55307 55308 55309 55310 55311 55312 55313 55314 55315 55316 55317 55318 55319 55320 55321 55322 55323 55324 55325 55326 55327 55328 55329 55330 55331 55332 55333 55334 55335 55336 55337 55338 55339 55340 55341 55342 55343 55344 55345 55346 55347 55348 55349 55350 55351 55352 55353 55354 55355 55356 55357 55358 55359 55360 55361 55362 55363 55364 55365 55366 55367 55368 55369 55370 55371 55372 55373 55374 55375 55376 55377 55378 55379 55380 55381 55382 55383 55384 55385 55386 55387 55388 55389 55390 55391 55392 55393 55394 55395 55396 55397 55398 55399 55400 55401 55402 55403 55404 55405 55406 55407 55408 55409 55410 55411 55412 55413 55414 55415 55416 55417 55418 55419 55420 55421 55422 55423 55424 55425 55426 55427 55428 55429 55430 55431 55432 55433 55434 55435 55436 55437 55438 55439 55440 55441 55442 55443 55444 55445 55446 55447 55448 55449 55450 55451 55452 55453 55454 55455 55456 55457 55458 55459 55460 55461 55462 55463 55464 55465 55466 55467 55468 55469 55470 55471 55472 55473 55474 55475 55476 55477 55478 55479 55480 55481 55482 55483 55484 55485 55486 55487 55488 55489 55490 55491 55492 55493 55494 55495 55496 55497 55498 55499 55500 55501 55502 55503 55504 55505 55506 55507 55508 55509 55510 55511 55512 55513 55514 55515 55516 55517 55518 55519 55520 55521 55522 55523 55524 55525 55526 55527 55528 55529 55530 55531 55532 55533 55534 55535 55536 55537 55538 55539 55540 55541 55542 55543 55544 55545 55546 55547 55548 55549 55550 55551 55552 55553 55554 55555 55556 55557 55558 55559 55560 55561 55562 55563 55564 55565 55566 55567 55568 55569 55570 55571 55572 55573 55574 55575 55576 55577 55578 55579 55580 55581 55582 55583 55584 55585 55586 55587 55588 55589 55590 55591 55592 55593 55594 55595 55596 55597 55598 55599 55600 55601 55602 55603 55604 55605 55606 55607 55608 55609 55610 55611 55612 55613 55614 55615 55616 55617 55618 55619 55620 55621 55622 55623 55624 55625 55626 55627 55628 55629 55630 55631 55632 55633 55634 55635 55636 55637 55638 55639 55640 55641 55642 55643 55644 55645 55646 55647 55648 55649 55650 55651 55652 55653 55654 55655 55656 55657 55658 55659 55660 55661 55662 55663 55664 55665 55666 55667 55668 55669 55670 55671 55672 55673 55674 55675 55676 55677 55678 55679 55680 55681 55682 55683 55684 55685 55686 55687 55688 55689 55690 55691 55692 55693 55694 55695 55696 55697 55698 55699 55700 55701 55702 55703 55704 55705 55706 55707 55708 55709 55710 55711 55712 55713 55714 55715 55716 55717 55718 55719 55720 55721 55722 55723 55724 55725 55726 55727 55728 55729 55730 55731 55732 55733 55734 55735 55736 55737 55738 55739 55740 55741 55742 55743 55744 55745 55746 55747 55748 55749 55750 55751 55752 55753 55754 55755 55756 55757 55758 55759 55760 55761 55762 55763 55764 55765 55766 55767 55768 55769 55770 55771 55772 55773 55774 55775 55776 55777 55778 55779 55780 55781 55782 55783 55784 55785 55786 55787 55788 55789 55790 55791 55792 55793 55794 55795 55796 55797 55798 55799 55800 55801 55802 55803 55804 55805 55806 55807 55808 55809 55810 55811 55812 55813 55814 55815 55816 55817 55818 55819 55820 55821 55822 55823 55824 55825 55826 55827 55828 55829 55830 55831 55832 55833 55834 55835 55836 55837 55838 55839 55840 55841 55842 55843 55844 55845 55846 55847 55848 55849 55850 55851 55852 55853 55854 55855 55856 55857 55858 55859 55860 55861 55862 55863 55864 55865 55866 55867 55868 55869 55870 55871 55872 55873 55874 55875 55876 55877 55878 55879 55880 55881 55882 55883 55884 55885 55886 55887 55888 55889 55890 55891 55892 55893 55894 55895 55896 55897 55898 55899 55900 55901 55902 55903 55904 55905 55906 55907 55908 55909 55910 55911 55912 55913 55914 55915 55916 55917 55918 55919 55920 55921 55922 55923 55924 55925 55926 55927 55928 55929 55930 55931 55932 55933 55934 55935 55936 55937 55938 55939 55940 55941 55942 55943 55944 55945 55946 55947 55948 55949 55950 55951 55952 55953 55954 55955 55956 55957 55958 55959 55960 55961 55962 55963 55964 55965 55966 55967 55968 55969 55970 55971 55972 55973 55974 55975 55976 55977 55978 55979 55980 55981 55982 55983 55984 55985 55986 55987 55988 55989 55990 55991 55992 55993 55994 55995 55996 55997 55998 55999 56000 56001 56002 56003 56004 56005 56006 56007 56008 56009 56010 56011 56012 56013 56014 56015 56016 56017 56018 56019 56020 56021 56022 56023 56024 56025 56026 56027 56028 56029 56030 56031 56032 56033 56034 56035 56036 56037 56038 56039 56040 56041 56042 56043 56044 56045 56046 56047 56048 56049 56050 56051 56052 56053 56054 56055 56056 56057 56058 56059 56060 56061 56062 56063 56064 56065 56066 56067 56068 56069 56070 56071 56072 56073 56074 56075 56076 56077 56078 56079 56080 56081 56082 56083 56084 56085 56086 56087 56088 56089 56090 56091 56092 56093 56094 56095 56096 56097 56098 56099 56100 56101 56102 56103 56104 56105 56106 56107 56108 56109 56110 56111 56112 56113 56114 56115 56116 56117 56118 56119 56120 56121 56122 56123 56124 56125 56126 56127 56128 56129 56130 56131 56132 56133 56134 56135 56136 56137 56138 56139 56140 56141 56142 56143 56144 56145 56146 56147 56148 56149 56150 56151 56152 56153 56154 56155 56156 56157 56158 56159 56160 56161 56162 56163 56164 56165 56166 56167 56168 56169 56170 56171 56172 56173 56174 56175 56176 56177 56178 56179 56180 56181 56182 56183 56184 56185 56186 56187 56188 56189 56190 56191 56192 56193 56194 56195 56196 56197 56198 56199 56200 56201 56202 56203 56204 56205 56206 56207 56208 56209 56210 56211 56212 56213 56214 56215 56216 56217 56218 56219 56220 56221 56222 56223 56224 56225 56226 56227 56228 56229 56230 56231 56232 56233 56234 56235 56236 56237 56238 56239 56240 56241 56242 56243 56244 56245 56246 56247 56248 56249 56250 56251 56252 56253 56254 56255 56256 56257 56258 56259 56260 56261 56262 56263 56264 56265 56266 56267 56268 56269 56270 56271 56272 56273 56274 56275 56276 56277 56278 56279 56280 56281 56282 56283 56284 56285 56286 56287 56288 56289 56290 56291 56292 56293 56294 56295 56296 56297 56298 56299 56300 56301 56302 56303 56304 56305 56306 56307 56308 56309 56310 56311 56312 56313 56314 56315 56316 56317 56318 56319 56320 56321 56322 56323 56324 56325 56326 56327 56328 56329 56330 56331 56332 56333 56334 56335 56336 56337 56338 56339 56340 56341 56342 56343 56344 56345 56346 56347 56348 56349 56350 56351 56352 56353 56354 56355 56356 56357 56358 56359 56360 56361 56362 56363 56364 56365 56366 56367 56368 56369 56370 56371 56372 56373 56374 56375 56376 56377 56378 56379 56380 56381 56382 56383 56384 56385 56386 56387 56388 56389 56390 56391 56392 56393 56394 56395 56396 56397 56398 56399 56400 56401 56402 56403 56404 56405 56406 56407 56408 56409 56410 56411 56412 56413 56414 56415 56416 56417 56418 56419 56420 56421 56422 56423 56424 56425 56426 56427 56428 56429 56430 56431 56432 56433 56434 56435 56436 56437 56438 56439 56440 56441 56442 56443 56444 56445 56446 56447 56448 56449 56450 56451 56452 56453 56454 56455 56456 56457 56458 56459 56460 56461 56462 56463 56464 56465 56466 56467 56468 56469 56470 56471 56472 56473 56474 56475 56476 56477 56478 56479 56480 56481 56482 56483 56484 56485 56486 56487 56488 56489 56490 56491 56492 56493 56494 56495 56496 56497 56498 56499 56500 56501 56502 56503 56504 56505 56506 56507 56508 56509 56510 56511 56512 56513 56514 56515 56516 56517 56518 56519 56520 56521 56522 56523 56524 56525 56526 56527 56528 56529 56530 56531 56532 56533 56534 56535 56536 56537 56538 56539 56540 56541 56542 56543 56544 56545 56546 56547 56548 56549 56550 56551 56552 56553 56554 56555 56556 56557 56558 56559 56560 56561 56562 56563 56564 56565 56566 56567 56568 56569 56570 56571 56572 56573 56574 56575 56576 56577 56578 56579 56580 56581 56582 56583 56584 56585 56586 56587 56588 56589 56590 56591 56592 56593 56594 56595 56596 56597 56598 56599 56600 56601 56602 56603 56604 56605 56606 56607 56608 56609 56610 56611 56612 56613 56614 56615 56616 56617 56618 56619 56620 56621 56622 56623 56624 56625 56626 56627 56628 56629 56630 56631 56632 56633 56634 56635 56636 56637 56638 56639 56640 56641 56642 56643 56644 56645 56646 56647 56648 56649 56650 56651 56652 56653 56654 56655 56656 56657 56658 56659 56660 56661 56662 56663 56664 56665 56666 56667 56668 56669 56670 56671 56672 56673 56674 56675 56676 56677 56678 56679 56680 56681 56682 56683 56684 56685 56686 56687 56688 56689 56690 56691 56692 56693 56694 56695 56696 56697 56698 56699 56700 56701 56702 56703 56704 56705 56706 56707 56708 56709 56710 56711 56712 56713 56714 56715 56716 56717 56718 56719 56720 56721 56722 56723 56724 56725 56726 56727 56728 56729 56730 56731 56732 56733 56734 56735 56736 56737 56738 56739 56740 56741 56742 56743 56744 56745 56746 56747 56748 56749 56750 56751 56752 56753 56754 56755 56756 56757 56758 56759 56760 56761 56762 56763 56764 56765 56766 56767 56768 56769 56770 56771 56772 56773 56774 56775 56776 56777 56778 56779 56780 56781 56782 56783 56784 56785 56786 56787 56788 56789 56790 56791 56792 56793 56794 56795 56796 56797 56798 56799 56800 56801 56802 56803 56804 56805 56806 56807 56808 56809 56810 56811 56812 56813 56814 56815 56816 56817 56818 56819 56820 56821 56822 56823 56824 56825 56826 56827 56828 56829 56830 56831 56832 56833 56834 56835 56836 56837 56838 56839 56840 56841 56842 56843 56844 56845 56846 56847 56848 56849 56850 56851 56852 56853 56854 56855 56856 56857 56858 56859 56860 56861 56862 56863 56864 56865 56866 56867 56868 56869 56870 56871 56872 56873 56874 56875 56876 56877 56878 56879 56880 56881 56882 56883 56884 56885 56886 56887 56888 56889 56890 56891 56892 56893 56894 56895 56896 56897 56898 56899 56900 56901 56902 56903 56904 56905 56906 56907 56908 56909 56910 56911 56912 56913 56914 56915 56916 56917 56918 56919 56920 56921 56922 56923 56924 56925 56926 56927 56928 56929 56930 56931 56932 56933 56934 56935 56936 56937 56938 56939 56940 56941 56942 56943 56944 56945 56946 56947 56948 56949 56950 56951 56952 56953 56954 56955 56956 56957 56958 56959 56960 56961 56962 56963 56964 56965 56966 56967 56968 56969 56970 56971 56972 56973 56974 56975 56976 56977 56978 56979 56980 56981 56982 56983 56984 56985 56986 56987 56988 56989 56990 56991 56992 56993 56994 56995 56996 56997 56998 56999 57000 57001 57002 57003 57004 57005 57006 57007 57008 57009 57010 57011 57012 57013 57014 57015 57016 57017 57018 57019 57020 57021 57022 57023 57024 57025 57026 57027 57028 57029 57030 57031 57032 57033 57034 57035 57036 57037 57038 57039 57040 57041 57042 57043 57044 57045 57046 57047 57048 57049 57050 57051 57052 57053 57054 57055 57056 57057 57058 57059 57060 57061 57062 57063 57064 57065 57066 57067 57068 57069 57070 57071 57072 57073 57074 57075 57076 57077 57078 57079 57080 57081 57082 57083 57084 57085 57086 57087 57088 57089 57090 57091 57092 57093 57094 57095 57096 57097 57098 57099 57100 57101 57102 57103 57104 57105 57106 57107 57108 57109 57110 57111 57112 57113 57114 57115 57116 57117 57118 57119 57120 57121 57122 57123 57124 57125 57126 57127 57128 57129 57130 57131 57132 57133 57134 57135 57136 57137 57138 57139 57140 57141 57142 57143 57144 57145 57146 57147 57148 57149 57150 57151 57152 57153 57154 57155 57156 57157 57158 57159 57160 57161 57162 57163 57164 57165 57166 57167 57168 57169 57170 57171 57172 57173 57174 57175 57176 57177 57178 57179 57180 57181 57182 57183 57184 57185 57186 57187 57188 57189 57190 57191 57192 57193 57194 57195 57196 57197 57198 57199 57200 57201 57202 57203 57204 57205 57206 57207 57208 57209 57210 57211 57212 57213 57214 57215 57216 57217 57218 57219 57220 57221 57222 57223 57224 57225 57226 57227 57228 57229 57230 57231 57232 57233 57234 57235 57236 57237 57238 57239 57240 57241 57242 57243 57244 57245 57246 57247 57248 57249 57250 57251 57252 57253 57254 57255 57256 57257 57258 57259 57260 57261 57262 57263 57264 57265 57266 57267 57268 57269 57270 57271 57272 57273 57274 57275 57276 57277 57278 57279 57280 57281 57282 57283 57284 57285 57286 57287 57288 57289 57290 57291 57292 57293 57294 57295 57296 57297 57298 57299 57300 57301 57302 57303 57304 57305 57306 57307 57308 57309 57310 57311 57312 57313 57314 57315 57316 57317 57318 57319 57320 57321 57322 57323 57324 57325 57326 57327 57328 57329 57330 57331 57332 57333 57334 57335 57336 57337 57338 57339 57340 57341 57342 57343 57344 57345 57346 57347 57348 57349 57350 57351 57352 57353 57354 57355 57356 57357 57358 57359 57360 57361 57362 57363 57364 57365 57366 57367 57368 57369 57370 57371 57372 57373 57374 57375 57376 57377 57378 57379 57380 57381 57382 57383 57384 57385 57386 57387 57388 57389 57390 57391 57392 57393 57394 57395 57396 57397 57398 57399 57400 57401 57402 57403 57404 57405 57406 57407 57408 57409 57410 57411 57412 57413 57414 57415 57416 57417 57418 57419 57420 57421 57422 57423 57424 57425 57426 57427 57428 57429 57430 57431 57432 57433 57434 57435 57436 57437 57438 57439 57440 57441 57442 57443 57444 57445 57446 57447 57448 57449 57450 57451 57452 57453 57454 57455 57456 57457 57458 57459 57460 57461 57462 57463 57464 57465 57466 57467 57468 57469 57470 57471 57472 57473 57474 57475 57476 57477 57478 57479 57480 57481 57482 57483 57484 57485 57486 57487 57488 57489 57490 57491 57492 57493 57494 57495 57496 57497 57498 57499 57500 57501 57502 57503 57504 57505 57506 57507 57508 57509 57510 57511 57512 57513 57514 57515 57516 57517 57518 57519 57520 57521 57522 57523 57524 57525 57526 57527 57528 57529 57530 57531 57532 57533 57534 57535 57536 57537 57538 57539 57540 57541 57542 57543 57544 57545 57546 57547 57548 57549 57550 57551 57552 57553 57554 57555 57556 57557 57558 57559 57560 57561 57562 57563 57564 57565 57566 57567 57568 57569 57570 57571 57572 57573 57574 57575 57576 57577 57578 57579 57580 57581 57582 57583 57584 57585 57586 57587 57588 57589 57590 57591 57592 57593 57594 57595 57596 57597 57598 57599 57600 57601 57602 57603 57604 57605 57606 57607 57608 57609 57610 57611 57612 57613 57614 57615 57616 57617 57618 57619 57620 57621 57622 57623 57624 57625 57626 57627 57628 57629 57630 57631 57632 57633 57634 57635 57636 57637 57638 57639 57640 57641 57642 57643 57644 57645 57646 57647 57648 57649 57650 57651 57652 57653 57654 57655 57656 57657 57658 57659 57660 57661 57662 57663 57664 57665 57666 57667 57668 57669 57670 57671 57672 57673 57674 57675 57676 57677 57678 57679 57680 57681 57682 57683 57684 57685 57686 57687 57688 57689 57690 57691 57692 57693 57694 57695 57696 57697 57698 57699 57700 57701 57702 57703 57704 57705 57706 57707 57708 57709 57710 57711 57712 57713 57714 57715 57716 57717 57718 57719 57720 57721 57722 57723 57724 57725 57726 57727 57728 57729 57730 57731 57732 57733 57734 57735 57736 57737 57738 57739 57740 57741 57742 57743 57744 57745 57746 57747 57748 57749 57750 57751 57752 57753 57754 57755 57756 57757 57758 57759 57760 57761 57762 57763 57764 57765 57766 57767 57768 57769 57770 57771 57772 57773 57774 57775 57776 57777 57778 57779 57780 57781 57782 57783 57784 57785 57786 57787 57788 57789 57790 57791 57792 57793 57794 57795 57796 57797 57798 57799 57800 57801 57802 57803 57804 57805 57806 57807 57808 57809 57810 57811 57812 57813 57814 57815 57816 57817 57818 57819 57820 57821 57822 57823 57824 57825 57826 57827 57828 57829 57830 57831 57832 57833 57834 57835 57836 57837 57838 57839 57840 57841 57842 57843 57844 57845 57846 57847 57848 57849 57850 57851 57852 57853 57854 57855 57856 57857 57858 57859 57860 57861 57862 57863 57864 57865 57866 57867 57868 57869 57870 57871 57872 57873 57874 57875 57876 57877 57878 57879 57880 57881 57882 57883 57884 57885 57886 57887 57888 57889 57890 57891 57892 57893 57894 57895 57896 57897 57898 57899 57900 57901 57902 57903 57904 57905 57906 57907 57908 57909 57910 57911 57912 57913 57914 57915 57916 57917 57918 57919 57920 57921 57922 57923 57924 57925 57926 57927 57928 57929 57930 57931 57932 57933 57934 57935 57936 57937 57938 57939 57940 57941 57942 57943 57944 57945 57946 57947 57948 57949 57950 57951 57952 57953 57954 57955 57956 57957 57958 57959 57960 57961 57962 57963 57964 57965 57966 57967 57968 57969 57970 57971 57972 57973 57974 57975 57976 57977 57978 57979 57980 57981 57982 57983 57984 57985 57986 57987 57988 57989 57990 57991 57992 57993 57994 57995 57996 57997 57998 57999 58000 58001 58002 58003 58004 58005 58006 58007 58008 58009 58010 58011 58012 58013 58014 58015 58016 58017 58018 58019 58020 58021 58022 58023 58024 58025 58026 58027 58028 58029 58030 58031 58032 58033 58034 58035 58036 58037 58038 58039 58040 58041 58042 58043 58044 58045 58046 58047 58048 58049 58050 58051 58052 58053 58054 58055 58056 58057 58058 58059 58060 58061 58062 58063 58064 58065 58066 58067 58068 58069 58070 58071 58072 58073 58074 58075 58076 58077 58078 58079 58080 58081 58082 58083 58084 58085 58086 58087 58088 58089 58090 58091 58092 58093 58094 58095 58096 58097 58098 58099 58100 58101 58102 58103 58104 58105 58106 58107 58108 58109 58110 58111 58112 58113 58114 58115 58116 58117 58118 58119 58120 58121 58122 58123 58124 58125 58126 58127 58128 58129 58130 58131 58132 58133 58134 58135 58136 58137 58138 58139 58140 58141 58142 58143 58144 58145 58146 58147 58148 58149 58150 58151 58152 58153 58154 58155 58156 58157 58158 58159 58160 58161 58162 58163 58164 58165 58166 58167 58168 58169 58170 58171 58172 58173 58174 58175 58176 58177 58178 58179 58180 58181 58182 58183 58184 58185 58186 58187 58188 58189 58190 58191 58192 58193 58194 58195 58196 58197 58198 58199 58200 58201 58202 58203 58204 58205 58206 58207 58208 58209 58210 58211 58212 58213 58214 58215 58216 58217 58218 58219 58220 58221 58222 58223 58224 58225 58226 58227 58228 58229 58230 58231 58232 58233 58234 58235 58236 58237 58238 58239 58240 58241 58242 58243 58244 58245 58246 58247 58248 58249 58250 58251 58252 58253 58254 58255 58256 58257 58258 58259 58260 58261 58262 58263 58264 58265 58266 58267 58268 58269 58270 58271 58272 58273 58274 58275 58276 58277 58278 58279 58280 58281 58282 58283 58284 58285 58286 58287 58288 58289 58290 58291 58292 58293 58294 58295 58296 58297 58298 58299 58300 58301 58302 58303 58304 58305 58306 58307 58308 58309 58310 58311 58312 58313 58314 58315 58316 58317 58318 58319 58320 58321 58322 58323 58324 58325 58326 58327 58328 58329 58330 58331 58332 58333 58334 58335 58336 58337 58338 58339 58340 58341 58342 58343 58344 58345 58346 58347 58348 58349 58350 58351 58352 58353 58354 58355 58356 58357 58358 58359 58360 58361 58362 58363 58364 58365 58366 58367 58368 58369 58370 58371 58372 58373 58374 58375 58376 58377 58378 58379 58380 58381 58382 58383 58384 58385 58386 58387 58388 58389 58390 58391 58392 58393 58394 58395 58396 58397 58398 58399 58400 58401 58402 58403 58404 58405 58406 58407 58408 58409 58410 58411 58412 58413 58414 58415 58416 58417 58418 58419 58420 58421 58422 58423 58424 58425 58426 58427 58428 58429 58430 58431 58432 58433 58434 58435 58436 58437 58438 58439 58440 58441 58442 58443 58444 58445 58446 58447 58448 58449 58450 58451 58452 58453 58454 58455 58456 58457 58458 58459 58460 58461 58462 58463 58464 58465 58466 58467 58468 58469 58470 58471 58472 58473 58474 58475 58476 58477 58478 58479 58480 58481 58482 58483 58484 58485 58486 58487 58488 58489 58490 58491 58492 58493 58494 58495 58496 58497 58498 58499 58500 58501 58502 58503 58504 58505 58506 58507 58508 58509 58510 58511 58512 58513 58514 58515 58516 58517 58518 58519 58520 58521 58522 58523 58524 58525 58526 58527 58528 58529 58530 58531 58532 58533 58534 58535 58536 58537 58538 58539 58540 58541 58542 58543 58544 58545 58546 58547 58548 58549 58550 58551 58552 58553 58554 58555 58556 58557 58558 58559 58560 58561 58562 58563 58564 58565 58566 58567 58568 58569 58570 58571 58572 58573 58574 58575 58576 58577 58578 58579 58580 58581 58582 58583 58584 58585 58586 58587 58588 58589 58590 58591 58592 58593 58594 58595 58596 58597 58598 58599 58600 58601 58602 58603 58604 58605 58606 58607 58608 58609 58610 58611 58612 58613 58614 58615 58616 58617 58618 58619 58620 58621 58622 58623 58624 58625 58626 58627 58628 58629 58630 58631 58632 58633 58634 58635 58636 58637 58638 58639 58640 58641 58642 58643 58644 58645 58646 58647 58648 58649 58650 58651 58652 58653 58654 58655 58656 58657 58658 58659 58660 58661 58662 58663 58664 58665 58666 58667 58668 58669 58670 58671 58672 58673 58674 58675 58676 58677 58678 58679 58680 58681 58682 58683 58684 58685 58686 58687 58688 58689 58690 58691 58692 58693 58694 58695 58696 58697 58698 58699 58700 58701 58702 58703 58704 58705 58706 58707 58708 58709 58710 58711 58712 58713 58714 58715 58716 58717 58718 58719 58720 58721 58722 58723 58724 58725 58726 58727 58728 58729 58730 58731 58732 58733 58734 58735 58736 58737 58738 58739 58740 58741 58742 58743 58744 58745 58746 58747 58748 58749 58750 58751 58752 58753 58754 58755 58756 58757 58758 58759 58760 58761 58762 58763 58764 58765 58766 58767 58768 58769 58770 58771 58772 58773 58774 58775 58776 58777 58778 58779 58780 58781 58782 58783 58784 58785 58786 58787 58788 58789 58790 58791 58792 58793 58794 58795 58796 58797 58798 58799 58800 58801 58802 58803 58804 58805 58806 58807 58808 58809 58810 58811 58812 58813 58814 58815 58816 58817 58818 58819 58820 58821 58822 58823 58824 58825 58826 58827 58828 58829 58830 58831 58832 58833 58834 58835 58836 58837 58838 58839 58840 58841 58842 58843 58844 58845 58846 58847 58848 58849 58850 58851 58852 58853 58854 58855 58856 58857 58858 58859 58860 58861 58862 58863 58864 58865 58866 58867 58868 58869 58870 58871 58872 58873 58874 58875 58876 58877 58878 58879 58880 58881 58882 58883 58884 58885 58886 58887 58888 58889 58890 58891 58892 58893 58894 58895 58896 58897 58898 58899 58900 58901 58902 58903 58904 58905 58906 58907 58908 58909 58910 58911 58912 58913 58914 58915 58916 58917 58918 58919 58920 58921 58922 58923 58924 58925 58926 58927 58928 58929 58930 58931 58932 58933 58934 58935 58936 58937 58938 58939 58940 58941 58942 58943 58944 58945 58946 58947 58948 58949 58950 58951 58952 58953 58954 58955 58956 58957 58958 58959 58960 58961 58962 58963 58964 58965 58966 58967 58968 58969 58970 58971 58972 58973 58974 58975 58976 58977 58978 58979 58980 58981 58982 58983 58984 58985 58986 58987 58988 58989 58990 58991 58992 58993 58994 58995 58996 58997 58998 58999 59000 59001 59002 59003 59004 59005 59006 59007 59008 59009 59010 59011 59012 59013 59014 59015 59016 59017 59018 59019 59020 59021 59022 59023 59024 59025 59026 59027 59028 59029 59030 59031 59032 59033 59034 59035 59036 59037 59038 59039 59040 59041 59042 59043 59044 59045 59046 59047 59048 59049 59050 59051 59052 59053 59054 59055 59056 59057 59058 59059 59060 59061 59062 59063 59064 59065 59066 59067 59068 59069 59070 59071 59072 59073 59074 59075 59076 59077 59078 59079 59080 59081 59082 59083 59084 59085 59086 59087 59088 59089 59090 59091 59092 59093 59094 59095 59096 59097 59098 59099 59100 59101 59102 59103 59104 59105 59106 59107 59108 59109 59110 59111 59112 59113 59114 59115 59116 59117 59118 59119 59120 59121 59122 59123 59124 59125 59126 59127 59128 59129 59130 59131 59132 59133 59134 59135 59136 59137 59138 59139 59140 59141 59142 59143 59144 59145 59146 59147 59148 59149 59150 59151 59152 59153 59154 59155 59156 59157 59158 59159 59160 59161 59162 59163 59164 59165 59166 59167 59168 59169 59170 59171 59172 59173 59174 59175 59176 59177 59178 59179 59180 59181 59182 59183 59184 59185 59186 59187 59188 59189 59190 59191 59192 59193 59194 59195 59196 59197 59198 59199 59200 59201 59202 59203 59204 59205 59206 59207 59208 59209 59210 59211 59212 59213 59214 59215 59216 59217 59218 59219 59220 59221 59222 59223 59224 59225 59226 59227 59228 59229 59230 59231 59232 59233 59234 59235 59236 59237 59238 59239 59240 59241 59242 59243 59244 59245 59246 59247 59248 59249 59250 59251 59252 59253 59254 59255 59256 59257 59258 59259 59260 59261 59262 59263 59264 59265 59266 59267 59268 59269 59270 59271 59272 59273 59274 59275 59276 59277 59278 59279 59280 59281 59282 59283 59284 59285 59286 59287 59288 59289 59290 59291 59292 59293 59294 59295 59296 59297 59298 59299 59300 59301 59302 59303 59304 59305 59306 59307 59308 59309 59310 59311 59312 59313 59314 59315 59316 59317 59318 59319 59320 59321 59322 59323 59324 59325 59326 59327 59328 59329 59330 59331 59332 59333 59334 59335 59336 59337 59338 59339 59340 59341 59342 59343 59344 59345 59346 59347 59348 59349 59350 59351 59352 59353 59354 59355 59356 59357 59358 59359 59360 59361 59362 59363 59364 59365 59366 59367 59368 59369 59370 59371 59372 59373 59374 59375 59376 59377 59378 59379 59380 59381 59382 59383 59384 59385 59386 59387 59388 59389 59390 59391 59392 59393 59394 59395 59396 59397 59398 59399 59400 59401 59402 59403 59404 59405 59406 59407 59408 59409 59410 59411 59412 59413 59414 59415 59416 59417 59418 59419 59420 59421 59422 59423 59424 59425 59426 59427 59428 59429 59430 59431 59432 59433 59434 59435 59436 59437 59438 59439 59440 59441 59442 59443 59444 59445 59446 59447 59448 59449 59450 59451 59452 59453 59454 59455 59456 59457 59458 59459 59460 59461 59462 59463 59464 59465 59466 59467 59468 59469 59470 59471 59472 59473 59474 59475 59476 59477 59478 59479 59480 59481 59482 59483 59484 59485 59486 59487 59488 59489 59490 59491 59492 59493 59494 59495 59496 59497 59498 59499 59500 59501 59502 59503 59504 59505 59506 59507 59508 59509 59510 59511 59512 59513 59514 59515 59516 59517 59518 59519 59520 59521 59522 59523 59524 59525 59526 59527 59528 59529 59530 59531 59532 59533 59534 59535 59536 59537 59538 59539 59540 59541 59542 59543 59544 59545 59546 59547 59548 59549 59550 59551 59552 59553 59554 59555 59556 59557 59558 59559 59560 59561 59562 59563 59564 59565 59566 59567 59568 59569 59570 59571 59572 59573 59574 59575 59576 59577 59578 59579 59580 59581 59582 59583 59584 59585 59586 59587 59588 59589 59590 59591 59592 59593 59594 59595 59596 59597 59598 59599 59600 59601 59602 59603 59604 59605 59606 59607 59608 59609 59610 59611 59612 59613 59614 59615 59616 59617 59618 59619 59620 59621 59622 59623 59624 59625 59626 59627 59628 59629 59630 59631 59632 59633 59634 59635 59636 59637 59638 59639 59640 59641 59642 59643 59644 59645 59646 59647 59648 59649 59650 59651 59652 59653 59654 59655 59656 59657 59658 59659 59660 59661 59662 59663 59664 59665 59666 59667 59668 59669 59670 59671 59672 59673 59674 59675 59676 59677 59678 59679 59680 59681 59682 59683 59684 59685 59686 59687 59688 59689 59690 59691 59692 59693 59694 59695 59696 59697 59698 59699 59700 59701 59702 59703 59704 59705 59706 59707 59708 59709 59710 59711 59712 59713 59714 59715 59716 59717 59718 59719 59720 59721 59722 59723 59724 59725 59726 59727 59728 59729 59730 59731 59732 59733 59734 59735 59736 59737 59738 59739 59740 59741 59742 59743 59744 59745 59746 59747 59748 59749 59750 59751 59752 59753 59754 59755 59756 59757 59758 59759 59760 59761 59762 59763 59764 59765 59766 59767 59768 59769 59770 59771 59772 59773 59774 59775 59776 59777 59778 59779 59780 59781 59782 59783 59784 59785 59786 59787 59788 59789 59790 59791 59792 59793 59794 59795 59796 59797 59798 59799 59800 59801 59802 59803 59804 59805 59806 59807 59808 59809 59810 59811 59812 59813 59814 59815 59816 59817 59818 59819 59820 59821 59822 59823 59824 59825 59826 59827 59828 59829 59830 59831 59832 59833 59834 59835 59836 59837 59838 59839 59840 59841 59842 59843 59844 59845 59846 59847 59848 59849 59850 59851 59852 59853 59854 59855 59856 59857 59858 59859 59860 59861 59862 59863 59864 59865 59866 59867 59868 59869 59870 59871 59872 59873 59874 59875 59876 59877 59878 59879 59880 59881 59882 59883 59884 59885 59886 59887 59888 59889 59890 59891 59892 59893 59894 59895 59896 59897 59898 59899 59900 59901 59902 59903 59904 59905 59906 59907 59908 59909 59910 59911 59912 59913 59914 59915 59916 59917 59918 59919 59920 59921 59922 59923 59924 59925 59926 59927 59928 59929 59930 59931 59932 59933 59934 59935 59936 59937 59938 59939 59940 59941 59942 59943 59944 59945 59946 59947 59948 59949 59950 59951 59952 59953 59954 59955 59956 59957 59958 59959 59960 59961 59962 59963 59964 59965 59966 59967 59968 59969 59970 59971 59972 59973 59974 59975 59976 59977 59978 59979 59980 59981 59982 59983 59984 59985 59986 59987 59988 59989 59990 59991 59992 59993 59994 59995 59996 59997 59998 59999 60000 60001 60002 60003 60004 60005 60006 60007 60008 60009 60010 60011 60012 60013 60014 60015 60016 60017 60018 60019 60020 60021 60022 60023 60024 60025 60026 60027 60028 60029 60030 60031 60032 60033 60034 60035 60036 60037 60038 60039 60040 60041 60042 60043 60044 60045 60046 60047 60048 60049 60050 60051 60052 60053 60054 60055 60056 60057 60058 60059 60060 60061 60062 60063 60064 60065 60066 60067 60068 60069 60070 60071 60072 60073 60074 60075 60076 60077 60078 60079 60080 60081 60082 60083 60084 60085 60086 60087 60088 60089 60090 60091 60092 60093 60094 60095 60096 60097 60098 60099 60100 60101 60102 60103 60104 60105 60106 60107 60108 60109 60110 60111 60112 60113 60114 60115 60116 60117 60118 60119 60120 60121 60122 60123 60124 60125 60126 60127 60128 60129 60130 60131 60132 60133 60134 60135 60136 60137 60138 60139 60140 60141 60142 60143 60144 60145 60146 60147 60148 60149 60150 60151 60152 60153 60154 60155 60156 60157 60158 60159 60160 60161 60162 60163 60164 60165 60166 60167 60168 60169 60170 60171 60172 60173 60174 60175 60176 60177 60178 60179 60180 60181 60182 60183 60184 60185 60186 60187 60188 60189 60190 60191 60192 60193 60194 60195 60196 60197 60198 60199 60200 60201 60202 60203 60204 60205 60206 60207 60208 60209 60210 60211 60212 60213 60214 60215 60216 60217 60218 60219 60220 60221 60222 60223 60224 60225 60226 60227 60228 60229 60230 60231 60232 60233 60234 60235 60236 60237 60238 60239 60240 60241 60242 60243 60244 60245 60246 60247 60248 60249 60250 60251 60252 60253 60254 60255 60256 60257 60258 60259 60260 60261 60262 60263 60264 60265 60266 60267 60268 60269 60270 60271 60272 60273 60274 60275 60276 60277 60278 60279 60280 60281 60282 60283 60284 60285 60286 60287 60288 60289 60290 60291 60292 60293 60294 60295 60296 60297 60298 60299 60300 60301 60302 60303 60304 60305 60306 60307 60308 60309 60310 60311 60312 60313 60314 60315 60316 60317 60318 60319 60320 60321 60322 60323 60324 60325 60326 60327 60328 60329 60330 60331 60332 60333 60334 60335 60336 60337 60338 60339 60340 60341 60342 60343 60344 60345 60346 60347 60348 60349 60350 60351 60352 60353 60354 60355 60356 60357 60358 60359 60360 60361 60362 60363 60364 60365 60366 60367 60368 60369 60370 60371 60372 60373 60374 60375 60376 60377 60378 60379 60380 60381 60382 60383 60384 60385 60386 60387 60388 60389 60390 60391 60392 60393 60394 60395 60396 60397 60398 60399 60400 60401 60402 60403 60404 60405 60406 60407 60408 60409 60410 60411 60412 60413 60414 60415 60416 60417 60418 60419 60420 60421 60422 60423 60424 60425 60426 60427 60428 60429 60430 60431 60432 60433 60434 60435 60436 60437 60438 60439 60440 60441 60442 60443 60444 60445 60446 60447 60448 60449 60450 60451 60452 60453 60454 60455 60456 60457 60458 60459 60460 60461 60462 60463 60464 60465 60466 60467 60468 60469 60470 60471 60472 60473 60474 60475 60476 60477 60478 60479 60480 60481 60482 60483 60484 60485 60486 60487 60488 60489 60490 60491 60492 60493 60494 60495 60496 60497 60498 60499 60500 60501 60502 60503 60504 60505 60506 60507 60508 60509 60510 60511 60512 60513 60514 60515 60516 60517 60518 60519 60520 60521 60522 60523 60524 60525 60526 60527 60528 60529 60530 60531 60532 60533 60534 60535 60536 60537 60538 60539 60540 60541 60542 60543 60544 60545 60546 60547 60548 60549 60550 60551 60552 60553 60554 60555 60556 60557 60558 60559 60560 60561 60562 60563 60564 60565 60566 60567 60568 60569 60570 60571 60572 60573 60574 60575 60576 60577 60578 60579 60580 60581 60582 60583 60584 60585 60586 60587 60588 60589 60590 60591 60592 60593 60594 60595 60596 60597 60598 60599 60600 60601 60602 60603 60604 60605 60606 60607 60608 60609 60610 60611 60612 60613 60614 60615 60616 60617 60618 60619 60620 60621 60622 60623 60624 60625 60626 60627 60628 60629 60630 60631 60632 60633 60634 60635 60636 60637 60638 60639 60640 60641 60642 60643 60644 60645 60646 60647 60648 60649 60650 60651 60652 60653 60654 60655 60656 60657 60658 60659 60660 60661 60662 60663 60664 60665 60666 60667 60668 60669 60670 60671 60672 60673 60674 60675 60676 60677 60678 60679 60680 60681 60682 60683 60684 60685 60686 60687 60688 60689 60690 60691 60692 60693 60694 60695 60696 60697 60698 60699 60700 60701 60702 60703 60704 60705 60706 60707 60708 60709 60710 60711 60712 60713 60714 60715 60716 60717 60718 60719 60720 60721 60722 60723 60724 60725 60726 60727 60728 60729 60730 60731 60732 60733 60734 60735 60736 60737 60738 60739 60740 60741 60742 60743 60744 60745 60746 60747 60748 60749 60750 60751 60752 60753 60754 60755 60756 60757 60758 60759 60760 60761 60762 60763 60764 60765 60766 60767 60768 60769 60770 60771 60772 60773 60774 60775 60776 60777 60778 60779 60780 60781 60782 60783 60784 60785 60786 60787 60788 60789 60790 60791 60792 60793 60794 60795 60796 60797 60798 60799 60800 60801 60802 60803 60804 60805 60806 60807 60808 60809 60810 60811 60812 60813 60814 60815 60816 60817 60818 60819 60820 60821 60822 60823 60824 60825 60826 60827 60828 60829 60830 60831 60832 60833 60834 60835 60836 60837 60838 60839 60840 60841 60842 60843 60844 60845 60846 60847 60848 60849 60850 60851 60852 60853 60854 60855 60856 60857 60858 60859 60860 60861 60862 60863 60864 60865 60866 60867 60868 60869 60870 60871 60872 60873 60874 60875 60876 60877 60878 60879 60880 60881 60882 60883 60884 60885 60886 60887 60888 60889 60890 60891 60892 60893 60894 60895 60896 60897 60898 60899 60900 60901 60902 60903 60904 60905 60906 60907 60908 60909 60910 60911 60912 60913 60914 60915 60916 60917 60918 60919 60920 60921 60922 60923 60924 60925 60926 60927 60928 60929 60930 60931 60932 60933 60934 60935 60936 60937 60938 60939 60940 60941 60942 60943 60944 60945 60946 60947 60948 60949 60950 60951 60952 60953 60954 60955 60956 60957 60958 60959 60960 60961 60962 60963 60964 60965 60966 60967 60968 60969 60970 60971 60972 60973 60974 60975 60976 60977 60978 60979 60980 60981 60982 60983 60984 60985 60986 60987 60988 60989 60990 60991 60992 60993 60994 60995 60996 60997 60998 60999 61000 61001 61002 61003 61004 61005 61006 61007 61008 61009 61010 61011 61012 61013 61014 61015 61016 61017 61018 61019 61020 61021 61022 61023 61024 61025 61026 61027 61028 61029 61030 61031 61032 61033 61034 61035 61036 61037 61038 61039 61040 61041 61042 61043 61044 61045 61046 61047 61048 61049 61050 61051 61052 61053 61054 61055 61056 61057 61058 61059 61060 61061 61062 61063 61064 61065 61066 61067 61068 61069 61070 61071 61072 61073 61074 61075 61076 61077 61078 61079 61080 61081 61082 61083 61084 61085 61086 61087 61088 61089 61090 61091 61092 61093 61094 61095 61096 61097 61098 61099 61100 61101 61102 61103 61104 61105 61106 61107 61108 61109 61110 61111 61112 61113 61114 61115 61116 61117 61118 61119 61120 61121 61122 61123 61124 61125 61126 61127 61128 61129 61130 61131 61132 61133 61134 61135 61136 61137 61138 61139 61140 61141 61142 61143 61144 61145 61146 61147 61148 61149 61150 61151 61152 61153 61154 61155 61156 61157 61158 61159 61160 61161 61162 61163 61164 61165 61166 61167 61168 61169 61170 61171 61172 61173 61174 61175 61176 61177 61178 61179 61180 61181 61182 61183 61184 61185 61186 61187 61188 61189 61190 61191 61192 61193 61194 61195 61196 61197 61198 61199 61200 61201 61202 61203 61204 61205 61206 61207 61208 61209 61210 61211 61212 61213 61214 61215 61216 61217 61218 61219 61220 61221 61222 61223 61224 61225 61226 61227 61228 61229 61230 61231 61232 61233 61234 61235 61236 61237 61238 61239 61240 61241 61242 61243 61244 61245 61246 61247 61248 61249 61250 61251 61252 61253 61254 61255 61256 61257 61258 61259 61260 61261 61262 61263 61264 61265 61266 61267 61268 61269 61270 61271 61272 61273 61274 61275 61276 61277 61278 61279 61280 61281 61282 61283 61284 61285 61286 61287 61288 61289 61290 61291 61292 61293 61294 61295 61296 61297 61298 61299 61300 61301 61302 61303 61304 61305 61306 61307 61308 61309 61310 61311 61312 61313 61314 61315 61316 61317 61318 61319 61320 61321 61322 61323 61324 61325 61326 61327 61328 61329 61330 61331 61332 61333 61334 61335 61336 61337 61338 61339 61340 61341 61342 61343 61344 61345 61346 61347 61348 61349 61350 61351 61352 61353 61354 61355 61356 61357 61358 61359 61360 61361 61362 61363 61364 61365 61366 61367 61368 61369 61370 61371 61372 61373 61374 61375 61376 61377 61378 61379 61380 61381 61382 61383 61384 61385 61386 61387 61388 61389 61390 61391 61392 61393 61394 61395 61396 61397 61398 61399 61400 61401 61402 61403 61404 61405 61406 61407 61408 61409 61410 61411 61412 61413 61414 61415 61416 61417 61418 61419 61420 61421 61422 61423 61424 61425 61426 61427 61428 61429 61430 61431 61432 61433 61434 61435 61436 61437 61438 61439 61440 61441 61442 61443 61444 61445 61446 61447 61448 61449 61450 61451 61452 61453 61454 61455 61456 61457 61458 61459 61460 61461 61462 61463 61464 61465 61466 61467 61468 61469 61470 61471 61472 61473 61474 61475 61476 61477 61478 61479 61480 61481 61482 61483 61484 61485 61486 61487 61488 61489 61490 61491 61492 61493 61494 61495 61496 61497 61498 61499 61500 61501 61502 61503 61504 61505 61506 61507 61508 61509 61510 61511 61512 61513 61514 61515 61516 61517 61518 61519 61520 61521 61522 61523 61524 61525 61526 61527 61528 61529 61530 61531 61532 61533 61534 61535 61536 61537 61538 61539 61540 61541 61542 61543 61544 61545 61546 61547 61548 61549 61550 61551 61552 61553 61554 61555 61556 61557 61558 61559 61560 61561 61562 61563 61564 61565 61566 61567 61568 61569 61570 61571 61572 61573 61574 61575 61576 61577 61578 61579 61580 61581 61582 61583 61584 61585 61586 61587 61588 61589 61590 61591 61592 61593 61594 61595 61596 61597 61598 61599 61600 61601 61602 61603 61604 61605 61606 61607 61608 61609 61610 61611 61612 61613 61614 61615 61616 61617 61618 61619 61620 61621 61622 61623 61624 61625 61626 61627 61628 61629 61630 61631 61632 61633 61634 61635 61636 61637 61638 61639 61640 61641 61642 61643 61644 61645 61646 61647 61648 61649 61650 61651 61652 61653 61654 61655 61656 61657 61658 61659 61660 61661 61662 61663 61664 61665 61666 61667 61668 61669 61670 61671 61672 61673 61674 61675 61676 61677 61678 61679 61680 61681 61682 61683 61684 61685 61686 61687 61688 61689 61690 61691 61692 61693 61694 61695 61696 61697 61698 61699 61700 61701 61702 61703 61704 61705 61706 61707 61708 61709 61710 61711 61712 61713 61714 61715 61716 61717 61718 61719 61720 61721 61722 61723 61724 61725 61726 61727 61728 61729 61730 61731 61732 61733 61734 61735 61736 61737 61738 61739 61740 61741 61742 61743 61744 61745 61746 61747 61748 61749 61750 61751 61752 61753 61754 61755 61756 61757 61758 61759 61760 61761 61762 61763 61764 61765 61766 61767 61768 61769 61770 61771 61772 61773 61774 61775 61776 61777 61778 61779 61780 61781 61782 61783 61784 61785 61786 61787 61788 61789 61790 61791 61792 61793 61794 61795 61796 61797 61798 61799 61800 61801 61802 61803 61804 61805 61806 61807 61808 61809 61810 61811 61812 61813 61814 61815 61816 61817 61818 61819 61820 61821 61822 61823 61824 61825 61826 61827 61828 61829 61830 61831 61832 61833 61834 61835 61836 61837 61838 61839 61840 61841 61842 61843 61844 61845 61846 61847 61848 61849 61850 61851 61852 61853 61854 61855 61856 61857 61858 61859 61860 61861 61862 61863 61864 61865 61866 61867 61868 61869 61870 61871 61872 61873 61874 61875 61876 61877 61878 61879 61880 61881 61882 61883 61884 61885 61886 61887 61888 61889 61890 61891 61892 61893 61894 61895 61896 61897 61898 61899 61900 61901 61902 61903 61904 61905 61906 61907 61908 61909 61910 61911 61912 61913 61914 61915 61916 61917 61918 61919 61920 61921 61922 61923 61924 61925 61926 61927 61928 61929 61930 61931 61932 61933 61934 61935 61936 61937 61938 61939 61940 61941 61942 61943 61944 61945 61946 61947 61948 61949 61950 61951 61952 61953 61954 61955 61956 61957 61958 61959 61960 61961 61962 61963 61964 61965 61966 61967 61968 61969 61970 61971 61972 61973 61974 61975 61976 61977 61978 61979 61980 61981 61982 61983 61984 61985 61986 61987 61988 61989 61990 61991 61992 61993 61994 61995 61996 61997 61998 61999 62000 62001 62002 62003 62004 62005 62006 62007 62008 62009 62010 62011 62012 62013 62014 62015 62016 62017 62018 62019 62020 62021 62022 62023 62024 62025 62026 62027 62028 62029 62030 62031 62032 62033 62034 62035 62036 62037 62038 62039 62040 62041 62042 62043 62044 62045 62046 62047 62048 62049 62050 62051 62052 62053 62054 62055 62056 62057 62058 62059 62060 62061 62062 62063 62064 62065 62066 62067 62068 62069 62070 62071 62072 62073 62074 62075 62076 62077 62078 62079 62080 62081 62082 62083 62084 62085 62086 62087 62088 62089 62090 62091 62092 62093 62094 62095 62096 62097 62098 62099 62100 62101 62102 62103 62104 62105 62106 62107 62108 62109 62110 62111 62112 62113 62114 62115 62116 62117 62118 62119 62120 62121 62122 62123 62124 62125 62126 62127 62128 62129 62130 62131 62132 62133 62134 62135 62136 62137 62138 62139 62140 62141 62142 62143 62144 62145 62146 62147 62148 62149 62150 62151 62152 62153 62154 62155 62156 62157 62158 62159 62160 62161 62162 62163 62164 62165 62166 62167 62168 62169 62170 62171 62172 62173 62174 62175 62176 62177 62178 62179 62180 62181 62182 62183 62184 62185 62186 62187 62188 62189 62190 62191 62192 62193 62194 62195 62196 62197 62198 62199 62200 62201 62202 62203 62204 62205 62206 62207 62208 62209 62210 62211 62212 62213 62214 62215 62216 62217 62218 62219 62220 62221 62222 62223 62224 62225 62226 62227 62228 62229 62230 62231 62232 62233 62234 62235 62236 62237 62238 62239 62240 62241 62242 62243 62244 62245 62246 62247 62248 62249 62250 62251 62252 62253 62254 62255 62256 62257 62258 62259 62260 62261 62262 62263 62264 62265 62266 62267 62268 62269 62270 62271 62272 62273 62274 62275 62276 62277 62278 62279 62280 62281 62282 62283 62284 62285 62286 62287 62288 62289 62290 62291 62292 62293 62294 62295 62296 62297 62298 62299 62300 62301 62302 62303 62304 62305 62306 62307 62308 62309 62310 62311 62312 62313 62314 62315 62316 62317 62318 62319 62320 62321 62322 62323 62324 62325 62326 62327 62328 62329 62330 62331 62332 62333 62334 62335 62336 62337 62338 62339 62340 62341 62342 62343 62344 62345 62346 62347 62348 62349 62350 62351 62352 62353 62354 62355 62356 62357 62358 62359 62360 62361 62362 62363 62364 62365 62366 62367 62368 62369 62370 62371 62372 62373 62374 62375 62376 62377 62378 62379 62380 62381 62382 62383 62384 62385 62386 62387 62388 62389 62390 62391 62392 62393 62394 62395 62396 62397 62398 62399 62400 62401 62402 62403 62404 62405 62406 62407 62408 62409 62410 62411 62412 62413 62414 62415 62416 62417 62418 62419 62420 62421 62422 62423 62424 62425 62426 62427 62428 62429 62430 62431 62432 62433 62434 62435 62436 62437 62438 62439 62440 62441 62442 62443 62444 62445 62446 62447 62448 62449 62450 62451 62452 62453 62454 62455 62456 62457 62458 62459 62460 62461 62462 62463 62464 62465 62466 62467 62468 62469 62470 62471 62472 62473 62474 62475 62476 62477 62478 62479 62480 62481 62482 62483 62484 62485 62486 62487 62488 62489 62490 62491 62492 62493 62494 62495 62496 62497 62498 62499 62500 62501 62502 62503 62504 62505 62506 62507 62508 62509 62510 62511 62512 62513 62514 62515 62516 62517 62518 62519 62520 62521 62522 62523 62524 62525 62526 62527 62528 62529 62530 62531 62532 62533 62534 62535 62536 62537 62538 62539 62540 62541 62542 62543 62544 62545 62546 62547 62548 62549 62550 62551 62552 62553 62554 62555 62556 62557 62558 62559 62560 62561 62562 62563 62564 62565 62566 62567 62568 62569 62570 62571 62572 62573 62574 62575 62576 62577 62578 62579 62580 62581 62582 62583 62584 62585 62586 62587 62588 62589 62590 62591 62592 62593 62594 62595 62596 62597 62598 62599 62600 62601 62602 62603 62604 62605 62606 62607 62608 62609 62610 62611 62612 62613 62614 62615 62616 62617 62618 62619 62620 62621 62622 62623 62624 62625 62626 62627 62628 62629 62630 62631 62632 62633 62634 62635 62636 62637 62638 62639 62640 62641 62642 62643 62644 62645 62646 62647 62648 62649 62650 62651 62652 62653 62654 62655 62656 62657 62658 62659 62660 62661 62662 62663 62664 62665 62666 62667 62668 62669 62670 62671 62672 62673 62674 62675 62676 62677 62678 62679 62680 62681 62682 62683 62684 62685 62686 62687 62688 62689 62690 62691 62692 62693 62694 62695 62696 62697 62698 62699 62700 62701 62702 62703 62704 62705 62706 62707 62708 62709 62710 62711 62712 62713 62714 62715 62716 62717 62718 62719 62720 62721 62722 62723 62724 62725 62726 62727 62728 62729 62730 62731 62732 62733 62734 62735 62736 62737 62738 62739 62740 62741 62742 62743 62744 62745 62746 62747 62748 62749 62750 62751 62752 62753 62754 62755 62756 62757 62758 62759 62760 62761 62762 62763 62764 62765 62766 62767 62768 62769 62770 62771 62772 62773 62774 62775 62776 62777 62778 62779 62780 62781 62782 62783 62784 62785 62786 62787 62788 62789 62790 62791 62792 62793 62794 62795 62796 62797 62798 62799 62800 62801 62802 62803 62804 62805 62806 62807 62808 62809 62810 62811 62812 62813 62814 62815 62816 62817 62818 62819 62820 62821 62822 62823 62824 62825 62826 62827 62828 62829 62830 62831 62832 62833 62834 62835 62836 62837 62838 62839 62840 62841 62842 62843 62844 62845 62846 62847 62848 62849 62850 62851 62852 62853 62854 62855 62856 62857 62858 62859 62860 62861 62862 62863 62864 62865 62866 62867 62868 62869 62870 62871 62872 62873 62874 62875 62876 62877 62878 62879 62880 62881 62882 62883 62884 62885 62886 62887 62888 62889 62890 62891 62892 62893 62894 62895 62896 62897 62898 62899 62900 62901 62902 62903 62904 62905 62906 62907 62908 62909 62910 62911 62912 62913 62914 62915 62916 62917 62918 62919 62920 62921 62922 62923 62924 62925 62926 62927 62928 62929 62930 62931 62932 62933 62934 62935 62936 62937 62938 62939 62940 62941 62942 62943 62944 62945 62946 62947 62948 62949 62950 62951 62952 62953 62954 62955 62956 62957 62958 62959 62960 62961 62962 62963 62964 62965 62966 62967 62968 62969 62970 62971 62972 62973 62974 62975 62976 62977 62978 62979 62980 62981 62982 62983 62984 62985 62986 62987 62988 62989 62990 62991 62992 62993 62994 62995 62996 62997 62998 62999 63000 63001 63002 63003 63004 63005 63006 63007 63008 63009 63010 63011 63012 63013 63014 63015 63016 63017 63018 63019 63020 63021 63022 63023 63024 63025 63026 63027 63028 63029 63030 63031 63032 63033 63034 63035 63036 63037 63038 63039 63040 63041 63042 63043 63044 63045 63046 63047 63048 63049 63050 63051 63052 63053 63054 63055 63056 63057 63058 63059 63060 63061 63062 63063 63064 63065 63066 63067 63068 63069 63070 63071 63072 63073 63074 63075 63076 63077 63078 63079 63080 63081 63082 63083 63084 63085 63086 63087 63088 63089 63090 63091 63092 63093 63094 63095 63096 63097 63098 63099 63100 63101 63102 63103 63104 63105 63106 63107 63108 63109 63110 63111 63112 63113 63114 63115 63116 63117 63118 63119 63120 63121 63122 63123 63124 63125 63126 63127 63128 63129 63130 63131 63132 63133 63134 63135 63136 63137 63138 63139 63140 63141 63142 63143 63144 63145 63146 63147 63148 63149 63150 63151 63152 63153 63154 63155 63156 63157 63158 63159 63160 63161 63162 63163 63164 63165 63166 63167 63168 63169 63170 63171 63172 63173 63174 63175 63176 63177 63178 63179 63180 63181 63182 63183 63184 63185 63186 63187 63188 63189 63190 63191 63192 63193 63194 63195 63196 63197 63198 63199 63200 63201 63202 63203 63204 63205 63206 63207 63208 63209 63210 63211 63212 63213 63214 63215 63216 63217 63218 63219 63220 63221 63222 63223 63224 63225 63226 63227 63228 63229 63230 63231 63232 63233 63234 63235 63236 63237 63238 63239 63240 63241 63242 63243 63244 63245 63246 63247 63248 63249 63250 63251 63252 63253 63254 63255 63256 63257 63258 63259 63260 63261 63262 63263 63264 63265 63266 63267 63268 63269 63270 63271 63272 63273 63274 63275 63276 63277 63278 63279 63280 63281 63282 63283 63284 63285 63286 63287 63288 63289 63290 63291 63292 63293 63294 63295 63296 63297 63298 63299 63300 63301 63302 63303 63304 63305 63306 63307 63308 63309 63310 63311 63312 63313 63314 63315 63316 63317 63318 63319 63320 63321 63322 63323 63324 63325 63326 63327 63328 63329 63330 63331 63332 63333 63334 63335 63336 63337 63338 63339 63340 63341 63342 63343 63344 63345 63346 63347 63348 63349 63350 63351 63352 63353 63354 63355 63356 63357 63358 63359 63360 63361 63362 63363 63364 63365 63366 63367 63368 63369 63370 63371 63372 63373 63374 63375 63376 63377 63378 63379 63380 63381 63382 63383 63384 63385 63386 63387 63388 63389 63390 63391 63392 63393 63394 63395 63396 63397 63398 63399 63400 63401 63402 63403 63404 63405 63406 63407 63408 63409 63410 63411 63412 63413 63414 63415 63416 63417 63418 63419 63420 63421 63422 63423 63424 63425 63426 63427 63428 63429 63430 63431 63432 63433 63434 63435 63436 63437 63438 63439 63440 63441 63442 63443 63444 63445 63446 63447 63448 63449 63450 63451 63452 63453 63454 63455 63456 63457 63458 63459 63460 63461 63462 63463 63464 63465 63466 63467 63468 63469 63470 63471 63472 63473 63474 63475 63476 63477 63478 63479 63480 63481 63482 63483 63484 63485 63486 63487 63488 63489 63490 63491 63492 63493 63494 63495 63496 63497 63498 63499 63500 63501 63502 63503 63504 63505 63506 63507 63508 63509 63510 63511 63512 63513 63514 63515 63516 63517 63518 63519 63520 63521 63522 63523 63524 63525 63526 63527 63528 63529 63530 63531 63532 63533 63534 63535 63536 63537 63538 63539 63540 63541 63542 63543 63544 63545 63546 63547 63548 63549 63550 63551 63552 63553 63554 63555 63556 63557 63558 63559 63560 63561 63562 63563 63564 63565 63566 63567 63568 63569 63570 63571 63572 63573 63574 63575 63576 63577 63578 63579 63580 63581 63582 63583 63584 63585 63586 63587 63588 63589 63590 63591 63592 63593 63594 63595 63596 63597 63598 63599 63600 63601 63602 63603 63604 63605 63606 63607 63608 63609 63610 63611 63612 63613 63614 63615 63616 63617 63618 63619 63620 63621 63622 63623 63624 63625 63626 63627 63628 63629 63630 63631 63632 63633 63634 63635 63636 63637 63638 63639 63640 63641 63642 63643 63644 63645 63646 63647 63648 63649 63650 63651 63652 63653 63654 63655 63656 63657 63658 63659 63660 63661 63662 63663 63664 63665 63666 63667 63668 63669 63670 63671 63672 63673 63674 63675 63676 63677 63678 63679 63680 63681 63682 63683 63684 63685 63686 63687 63688 63689 63690 63691 63692 63693 63694 63695 63696 63697 63698 63699 63700 63701 63702 63703 63704 63705 63706 63707 63708 63709 63710 63711 63712 63713 63714 63715 63716 63717 63718 63719 63720 63721 63722 63723 63724 63725 63726 63727 63728 63729 63730 63731 63732 63733 63734 63735 63736 63737 63738 63739 63740 63741 63742 63743 63744 63745 63746 63747 63748 63749 63750 63751 63752 63753 63754 63755 63756 63757 63758 63759 63760 63761 63762 63763 63764 63765 63766 63767 63768 63769 63770 63771 63772 63773 63774 63775 63776 63777 63778 63779 63780 63781 63782 63783 63784 63785 63786 63787 63788 63789 63790 63791 63792 63793 63794 63795 63796 63797 63798 63799 63800 63801 63802 63803 63804 63805 63806 63807 63808 63809 63810 63811 63812 63813 63814 63815 63816 63817 63818 63819 63820 63821 63822 63823 63824 63825 63826 63827 63828 63829 63830 63831 63832 63833 63834 63835 63836 63837 63838 63839 63840 63841 63842 63843 63844 63845 63846 63847 63848 63849 63850 63851 63852 63853 63854 63855 63856 63857 63858 63859 63860 63861 63862 63863 63864 63865 63866 63867 63868 63869 63870 63871 63872 63873 63874 63875 63876 63877 63878 63879 63880 63881 63882 63883 63884 63885 63886 63887 63888 63889 63890 63891 63892 63893 63894 63895 63896 63897 63898 63899 63900 63901 63902 63903 63904 63905 63906 63907 63908 63909 63910 63911 63912 63913 63914 63915 63916 63917 63918 63919 63920 63921 63922 63923 63924 63925 63926 63927 63928 63929 63930 63931 63932 63933 63934 63935 63936 63937 63938 63939 63940 63941 63942 63943 63944 63945 63946 63947 63948 63949 63950 63951 63952 63953 63954 63955 63956 63957 63958 63959 63960 63961 63962 63963 63964 63965 63966 63967 63968 63969 63970 63971 63972 63973 63974 63975 63976 63977 63978 63979 63980 63981 63982 63983 63984 63985 63986 63987 63988 63989 63990 63991 63992 63993 63994 63995 63996 63997 63998 63999 64000 64001 64002 64003 64004 64005 64006 64007 64008 64009 64010 64011 64012 64013 64014 64015 64016 64017 64018 64019 64020 64021 64022 64023 64024 64025 64026 64027 64028 64029 64030 64031 64032 64033 64034 64035 64036 64037 64038 64039 64040 64041 64042 64043 64044 64045 64046 64047 64048 64049 64050 64051 64052 64053 64054 64055 64056 64057 64058 64059 64060 64061 64062 64063 64064 64065 64066 64067 64068 64069 64070 64071 64072 64073 64074 64075 64076 64077 64078 64079 64080 64081 64082 64083 64084 64085 64086 64087 64088 64089 64090 64091 64092 64093 64094 64095 64096 64097 64098 64099 64100 64101 64102 64103 64104 64105 64106 64107 64108 64109 64110 64111 64112 64113 64114 64115 64116 64117 64118 64119 64120 64121 64122 64123 64124 64125 64126 64127 64128 64129 64130 64131 64132 64133 64134 64135 64136 64137 64138 64139 64140 64141 64142 64143 64144 64145 64146 64147 64148 64149 64150 64151 64152 64153 64154 64155 64156 64157 64158 64159 64160 64161 64162 64163 64164 64165 64166 64167 64168 64169 64170 64171 64172 64173 64174 64175 64176 64177 64178 64179 64180 64181 64182 64183 64184 64185 64186 64187 64188 64189 64190 64191 64192 64193 64194 64195 64196 64197 64198 64199 64200 64201 64202 64203 64204 64205 64206 64207 64208 64209 64210 64211 64212 64213 64214 64215 64216 64217 64218 64219 64220 64221 64222 64223 64224 64225 64226 64227 64228 64229 64230 64231 64232 64233 64234 64235 64236 64237 64238 64239 64240 64241 64242 64243 64244 64245 64246 64247 64248 64249 64250 64251 64252 64253 64254 64255 64256 64257 64258 64259 64260 64261 64262 64263 64264 64265 64266 64267 64268 64269 64270 64271 64272 64273 64274 64275 64276 64277 64278 64279 64280 64281 64282 64283 64284 64285 64286 64287 64288 64289 64290 64291 64292 64293 64294 64295 64296 64297 64298 64299 64300 64301 64302 64303 64304 64305 64306 64307 64308 64309 64310 64311 64312 64313 64314 64315 64316 64317 64318 64319 64320 64321 64322 64323 64324 64325 64326 64327 64328 64329 64330 64331 64332 64333 64334 64335 64336 64337 64338 64339 64340 64341 64342 64343 64344 64345 64346 64347 64348 64349 64350 64351 64352 64353 64354 64355 64356 64357 64358 64359 64360 64361 64362 64363 64364 64365 64366 64367 64368 64369 64370 64371 64372 64373 64374 64375 64376 64377 64378 64379 64380 64381 64382 64383 64384 64385 64386 64387 64388 64389 64390 64391 64392 64393 64394 64395 64396 64397 64398 64399 64400 64401 64402 64403 64404 64405 64406 64407 64408 64409 64410 64411 64412 64413 64414 64415 64416 64417 64418 64419 64420 64421 64422 64423 64424 64425 64426 64427 64428 64429 64430 64431 64432 64433 64434 64435 64436 64437 64438 64439 64440 64441 64442 64443 64444 64445 64446 64447 64448 64449 64450 64451 64452 64453 64454 64455 64456 64457 64458 64459 64460 64461 64462 64463 64464 64465 64466 64467 64468 64469 64470 64471 64472 64473 64474 64475 64476 64477 64478 64479 64480 64481 64482 64483 64484 64485 64486 64487 64488 64489 64490 64491 64492 64493 64494 64495 64496 64497 64498 64499 64500 64501 64502 64503 64504 64505 64506 64507 64508 64509 64510 64511 64512 64513 64514 64515 64516 64517 64518 64519 64520 64521 64522 64523 64524 64525 64526 64527 64528 64529 64530 64531 64532 64533 64534 64535 64536 64537 64538 64539 64540 64541 64542 64543 64544 64545 64546 64547 64548 64549 64550 64551 64552 64553 64554 64555 64556 64557 64558 64559 64560 64561 64562 64563 64564 64565 64566 64567 64568 64569 64570 64571 64572 64573 64574 64575 64576 64577 64578 64579 64580 64581 64582 64583 64584 64585 64586 64587 64588 64589 64590 64591 64592 64593 64594 64595 64596 64597 64598 64599 64600 64601 64602 64603 64604 64605 64606 64607 64608 64609 64610 64611 64612 64613 64614 64615 64616 64617 64618 64619 64620 64621 64622 64623 64624 64625 64626 64627 64628 64629 64630 64631 64632 64633 64634 64635 64636 64637 64638 64639 64640 64641 64642 64643 64644 64645 64646 64647 64648 64649 64650 64651 64652 64653 64654 64655 64656 64657 64658 64659 64660 64661 64662 64663 64664 64665 64666 64667 64668 64669 64670 64671 64672 64673 64674 64675 64676 64677 64678 64679 64680 64681 64682 64683 64684 64685 64686 64687 64688 64689 64690 64691 64692 64693 64694 64695 64696 64697 64698 64699 64700 64701 64702 64703 64704 64705 64706 64707 64708 64709 64710 64711 64712 64713 64714 64715 64716 64717 64718 64719 64720 64721 64722 64723 64724 64725 64726 64727 64728 64729 64730 64731 64732 64733 64734 64735 64736 64737 64738 64739 64740 64741 64742 64743 64744 64745 64746 64747 64748 64749 64750 64751 64752 64753 64754 64755 64756 64757 64758 64759 64760 64761 64762 64763 64764 64765 64766 64767 64768 64769 64770 64771 64772 64773 64774 64775 64776 64777 64778 64779 64780 64781 64782 64783 64784 64785 64786 64787 64788 64789 64790 64791 64792 64793 64794 64795 64796 64797 64798 64799 64800 64801 64802 64803 64804 64805 64806 64807 64808 64809 64810 64811 64812 64813 64814 64815 64816 64817 64818 64819 64820 64821 64822 64823 64824 64825 64826 64827 64828 64829 64830 64831 64832 64833 64834 64835 64836 64837 64838 64839 64840 64841 64842 64843 64844 64845 64846 64847 64848 64849 64850 64851 64852 64853 64854 64855 64856 64857 64858 64859 64860 64861 64862 64863 64864 64865 64866 64867 64868 64869 64870 64871 64872 64873 64874 64875 64876 64877 64878 64879 64880 64881 64882 64883 64884 64885 64886 64887 64888 64889 64890 64891 64892 64893 64894 64895 64896 64897 64898 64899 64900 64901 64902 64903 64904 64905 64906 64907 64908 64909 64910 64911 64912 64913 64914 64915 64916 64917 64918 64919 64920 64921 64922 64923 64924 64925 64926 64927 64928 64929 64930 64931 64932 64933 64934 64935 64936 64937 64938 64939 64940 64941 64942 64943 64944 64945 64946 64947 64948 64949 64950 64951 64952 64953 64954 64955 64956 64957 64958 64959 64960 64961 64962 64963 64964 64965 64966 64967 64968 64969 64970 64971 64972 64973 64974 64975 64976 64977 64978 64979 64980 64981 64982 64983 64984 64985 64986 64987 64988 64989 64990 64991 64992 64993 64994 64995 64996 64997 64998 64999 65000 65001 65002 65003 65004 65005 65006 65007 65008 65009 65010 65011 65012 65013 65014 65015 65016 65017 65018 65019 65020 65021 65022 65023 65024 65025 65026 65027 65028 65029 65030 65031 65032 65033 65034 65035 65036 65037 65038 65039 65040 65041 65042 65043 65044 65045 65046 65047 65048 65049 65050 65051 65052 65053 65054 65055 65056 65057 65058 65059 65060 65061 65062 65063 65064 65065 65066 65067 65068 65069 65070 65071 65072 65073 65074 65075 65076 65077 65078 65079 65080 65081 65082 65083 65084 65085 65086 65087 65088 65089 65090 65091 65092 65093 65094 65095 65096 65097 65098 65099 65100 65101 65102 65103 65104 65105 65106 65107 65108 65109 65110 65111 65112 65113 65114 65115 65116 65117 65118 65119 65120 65121 65122 65123 65124 65125 65126 65127 65128 65129 65130 65131 65132 65133 65134 65135 65136 65137 65138 65139 65140 65141 65142 65143 65144 65145 65146 65147 65148 65149 65150 65151 65152 65153 65154 65155 65156 65157 65158 65159 65160 65161 65162 65163 65164 65165 65166 65167 65168 65169 65170 65171 65172 65173 65174 65175 65176 65177 65178 65179 65180 65181 65182 65183 65184 65185 65186 65187 65188 65189 65190 65191 65192 65193 65194 65195 65196 65197 65198 65199 65200 65201 65202 65203 65204 65205 65206 65207 65208 65209 65210 65211 65212 65213 65214 65215 65216 65217 65218 65219 65220 65221 65222 65223 65224 65225 65226 65227 65228 65229 65230 65231 65232 65233 65234 65235 65236 65237 65238 65239 65240 65241 65242 65243 65244 65245 65246 65247 65248 65249 65250 65251 65252 65253 65254 65255 65256 65257 65258 65259 65260 65261 65262 65263 65264 65265 65266 65267 65268 65269 65270 65271 65272 65273 65274 65275 65276 65277 65278 65279 65280 65281 65282 65283 65284 65285 65286 65287 65288 65289 65290 65291 65292 65293 65294 65295 65296 65297 65298 65299 65300 65301 65302 65303 65304 65305 65306 65307 65308 65309 65310 65311 65312 65313 65314 65315 65316 65317 65318 65319 65320 65321 65322 65323 65324 65325 65326 65327 65328 65329 65330 65331 65332 65333 65334 65335 65336 65337 65338 65339 65340 65341 65342 65343 65344 65345 65346 65347 65348 65349 65350 65351 65352 65353 65354 65355 65356 65357 65358 65359 65360 65361 65362 65363 65364 65365 65366 65367 65368 65369 65370 65371 65372 65373 65374 65375 65376 65377 65378 65379 65380 65381 65382 65383 65384 65385 65386 65387 65388 65389 65390 65391 65392 65393 65394 65395 65396 65397 65398 65399 65400 65401 65402 65403 65404 65405 65406 65407 65408 65409 65410 65411 65412 65413 65414 65415 65416 65417 65418 65419 65420 65421 65422 65423 65424 65425 65426 65427 65428 65429 65430 65431 65432 65433 65434 65435 65436 65437 65438 65439 65440 65441 65442 65443 65444 65445 65446 65447 65448 65449 65450 65451 65452 65453 65454 65455 65456 65457 65458 65459 65460 65461 65462 65463 65464 65465 65466 65467 65468 65469 65470 65471 65472 65473 65474 65475 65476 65477 65478 65479 65480 65481 65482 65483 65484 65485 65486 65487 65488 65489 65490 65491 65492 65493 65494 65495 65496 65497 65498 65499 65500 65501 65502 65503 65504 65505 65506 65507 65508 65509 65510 65511 65512 65513 65514 65515 65516 65517 65518 65519 65520 65521 65522 65523 65524 65525 65526 65527 65528 65529 65530 65531 65532 65533 65534 65535 65536 65537 65538 65539 65540 65541 65542 65543 65544 65545 65546 65547 65548 65549 65550 65551 65552 65553 65554 65555 65556 65557 65558 65559 65560 65561 65562 65563 65564 65565 65566 65567 65568 65569 65570 65571 65572 65573 65574 65575 65576 65577 65578 65579 65580 65581 65582 65583 65584 65585 65586 65587 65588 65589 65590 65591 65592 65593 65594 65595 65596 65597 65598 65599 65600 65601 65602 65603 65604 65605 65606 65607 65608 65609 65610 65611 65612 65613 65614 65615 65616 65617 65618 65619 65620 65621 65622 65623 65624 65625 65626 65627 65628 65629 65630 65631 65632 65633 65634 65635 65636 65637 65638 65639 65640 65641 65642 65643 65644 65645 65646 65647 65648 65649 65650 65651 65652 65653 65654 65655 65656 65657 65658 65659 65660 65661 65662 65663 65664 65665 65666 65667 65668 65669 65670 65671 65672 65673 65674 65675 65676 65677 65678 65679 65680 65681 65682 65683 65684 65685 65686 65687 65688 65689 65690 65691 65692 65693 65694 65695 65696 65697 65698 65699 65700 65701 65702 65703 65704 65705 65706 65707 65708 65709 65710 65711 65712 65713 65714 65715 65716 65717 65718 65719 65720 65721 65722 65723 65724 65725 65726 65727 65728 65729 65730 65731 65732 65733 65734 65735 65736 65737 65738 65739 65740 65741 65742 65743 65744 65745 65746 65747 65748 65749 65750 65751 65752 65753 65754 65755 65756 65757 65758 65759 65760 65761 65762 65763 65764 65765 65766 65767 65768 65769 65770 65771 65772 65773 65774 65775 65776 65777 65778 65779 65780 65781 65782 65783 65784 65785 65786 65787 65788 65789 65790 65791 65792 65793 65794 65795 65796 65797 65798 65799 65800 65801 65802 65803 65804 65805 65806 65807 65808 65809 65810 65811 65812 65813 65814 65815 65816 65817 65818 65819 65820 65821 65822 65823 65824 65825 65826 65827 65828 65829 65830 65831 65832 65833 65834 65835 65836 65837 65838 65839 65840 65841 65842 65843 65844 65845 65846 65847 65848 65849 65850 65851 65852 65853 65854 65855 65856 65857 65858 65859 65860 65861 65862 65863 65864 65865 65866 65867 65868 65869 65870 65871 65872 65873 65874 65875 65876 65877 65878 65879 65880 65881 65882 65883 65884 65885 65886 65887 65888 65889 65890 65891 65892 65893 65894 65895 65896 65897 65898 65899 65900 65901 65902 65903 65904 65905 65906 65907 65908 65909 65910 65911 65912 65913 65914 65915 65916 65917 65918 65919 65920 65921 65922 65923 65924 65925 65926 65927 65928 65929 65930 65931 65932 65933 65934 65935 65936 65937 65938 65939 65940 65941 65942 65943 65944 65945 65946 65947 65948 65949 65950 65951 65952 65953 65954 65955 65956 65957 65958 65959 65960 65961 65962 65963 65964 65965 65966 65967 65968 65969 65970 65971 65972 65973 65974 65975 65976 65977 65978 65979 65980 65981 65982 65983 65984 65985 65986 65987 65988 65989 65990 65991 65992 65993 65994 65995 65996 65997 65998 65999 66000 66001 66002 66003 66004 66005 66006 66007 66008 66009 66010 66011 66012 66013 66014 66015 66016 66017 66018 66019 66020 66021 66022 66023 66024 66025 66026 66027 66028 66029 66030 66031 66032 66033 66034 66035 66036 66037 66038 66039 66040 66041 66042 66043 66044 66045 66046 66047 66048 66049 66050 66051 66052 66053 66054 66055 66056 66057 66058 66059 66060 66061 66062 66063 66064 66065 66066 66067 66068 66069 66070 66071 66072 66073 66074 66075 66076 66077 66078 66079 66080 66081 66082 66083 66084 66085 66086 66087 66088 66089 66090 66091 66092 66093 66094 66095 66096 66097 66098 66099 66100 66101 66102 66103 66104 66105 66106 66107 66108 66109 66110 66111 66112 66113 66114 66115 66116 66117 66118 66119 66120 66121 66122 66123 66124 66125 66126 66127 66128 66129 66130 66131 66132 66133 66134 66135 66136 66137 66138 66139 66140 66141 66142 66143 66144 66145 66146 66147 66148 66149 66150 66151 66152 66153 66154 66155 66156 66157 66158 66159 66160 66161 66162 66163 66164 66165 66166 66167 66168 66169 66170 66171 66172 66173 66174 66175 66176 66177 66178 66179 66180 66181 66182 66183 66184 66185 66186 66187 66188 66189 66190 66191 66192 66193 66194 66195 66196 66197 66198 66199 66200 66201 66202 66203 66204 66205 66206 66207 66208 66209 66210 66211 66212 66213 66214 66215 66216 66217 66218 66219 66220 66221 66222 66223 66224 66225 66226 66227 66228 66229 66230 66231 66232 66233 66234 66235 66236 66237 66238 66239 66240 66241 66242 66243 66244 66245 66246 66247 66248 66249 66250 66251 66252 66253 66254 66255 66256 66257 66258 66259 66260 66261 66262 66263 66264 66265 66266 66267 66268 66269 66270 66271 66272 66273 66274 66275 66276 66277 66278 66279 66280 66281 66282 66283 66284 66285 66286 66287 66288 66289 66290 66291 66292 66293 66294 66295 66296 66297 66298 66299 66300 66301 66302 66303 66304 66305 66306 66307 66308 66309 66310 66311 66312 66313 66314 66315 66316 66317 66318 66319 66320 66321 66322 66323 66324 66325 66326 66327 66328 66329 66330 66331 66332 66333 66334 66335 66336 66337 66338 66339 66340 66341 66342 66343 66344 66345 66346 66347 66348 66349 66350 66351 66352 66353 66354 66355 66356 66357 66358 66359 66360 66361 66362 66363 66364 66365 66366 66367 66368 66369 66370 66371 66372 66373 66374 66375 66376 66377 66378 66379 66380 66381 66382 66383 66384 66385 66386 66387 66388 66389 66390 66391 66392 66393 66394 66395 66396 66397 66398 66399 66400 66401 66402 66403 66404 66405 66406 66407 66408 66409 66410 66411 66412 66413 66414 66415 66416 66417 66418 66419 66420 66421 66422 66423 66424 66425 66426 66427 66428 66429 66430 66431 66432 66433 66434 66435 66436 66437 66438 66439 66440 66441 66442 66443 66444 66445 66446 66447 66448 66449 66450 66451 66452 66453 66454 66455 66456 66457 66458 66459 66460 66461 66462 66463 66464 66465 66466 66467 66468 66469 66470 66471 66472 66473 66474 66475 66476 66477 66478 66479 66480 66481 66482 66483 66484 66485 66486 66487 66488 66489 66490 66491 66492 66493 66494 66495 66496 66497 66498 66499 66500 66501 66502 66503 66504 66505 66506 66507 66508 66509 66510 66511 66512 66513 66514 66515 66516 66517 66518 66519 66520 66521 66522 66523 66524 66525 66526 66527 66528 66529 66530 66531 66532 66533 66534 66535 66536 66537 66538 66539 66540 66541 66542 66543 66544 66545 66546 66547 66548 66549 66550 66551 66552 66553 66554 66555 66556 66557 66558 66559 66560 66561 66562 66563 66564 66565 66566 66567 66568 66569 66570 66571 66572 66573 66574 66575 66576 66577 66578 66579 66580 66581 66582 66583 66584 66585 66586 66587 66588 66589 66590 66591 66592 66593 66594 66595 66596 66597 66598 66599 66600 66601 66602 66603 66604 66605 66606 66607 66608 66609 66610 66611 66612 66613 66614 66615 66616 66617 66618 66619 66620 66621 66622 66623 66624 66625 66626 66627 66628 66629 66630 66631 66632 66633 66634 66635 66636 66637 66638 66639 66640 66641 66642 66643 66644 66645 66646 66647 66648 66649 66650 66651 66652 66653 66654 66655 66656 66657 66658 66659 66660 66661 66662 66663 66664 66665 66666 66667 66668 66669 66670 66671 66672 66673 66674 66675 66676 66677 66678 66679 66680 66681 66682 66683 66684 66685 66686 66687 66688 66689 66690 66691 66692 66693 66694 66695 66696 66697 66698 66699 66700 66701 66702 66703 66704 66705 66706 66707 66708 66709 66710 66711 66712 66713 66714 66715 66716 66717 66718 66719 66720 66721 66722 66723 66724 66725 66726 66727 66728 66729 66730 66731 66732 66733 66734 66735 66736 66737 66738 66739 66740 66741 66742 66743 66744 66745 66746 66747 66748 66749 66750 66751 66752 66753 66754 66755 66756 66757 66758 66759 66760 66761 66762 66763 66764 66765 66766 66767 66768 66769 66770 66771 66772 66773 66774 66775 66776 66777 66778 66779 66780 66781 66782 66783 66784 66785 66786 66787 66788 66789 66790 66791 66792 66793 66794 66795 66796 66797 66798 66799 66800 66801 66802 66803 66804 66805 66806 66807 66808 66809 66810 66811 66812 66813 66814 66815 66816 66817 66818 66819 66820 66821 66822 66823 66824 66825 66826 66827 66828 66829 66830 66831 66832 66833 66834 66835 66836 66837 66838 66839 66840 66841 66842 66843 66844 66845 66846 66847 66848 66849 66850 66851 66852 66853 66854 66855 66856 66857 66858 66859 66860 66861 66862 66863 66864 66865 66866 66867 66868 66869 66870 66871 66872 66873 66874 66875 66876 66877 66878 66879 66880 66881 66882 66883 66884 66885 66886 66887 66888 66889 66890 66891 66892 66893 66894 66895 66896 66897 66898 66899 66900 66901 66902 66903 66904 66905 66906 66907 66908 66909 66910 66911 66912 66913 66914 66915 66916 66917 66918 66919 66920 66921 66922 66923 66924 66925 66926 66927 66928 66929 66930 66931 66932 66933 66934 66935 66936 66937 66938 66939 66940 66941 66942 66943 66944 66945 66946 66947 66948 66949 66950 66951 66952 66953 66954 66955 66956 66957 66958 66959 66960 66961 66962 66963 66964 66965 66966 66967 66968 66969 66970 66971 66972 66973 66974 66975 66976 66977 66978 66979 66980 66981 66982 66983 66984 66985 66986 66987 66988 66989 66990 66991 66992 66993 66994 66995 66996 66997 66998 66999 67000 67001 67002 67003 67004 67005 67006 67007 67008 67009 67010 67011 67012 67013 67014 67015 67016 67017 67018 67019 67020 67021 67022 67023 67024 67025 67026 67027 67028 67029 67030 67031 67032 67033 67034 67035 67036 67037 67038 67039 67040 67041 67042 67043 67044 67045 67046 67047 67048 67049 67050 67051 67052 67053 67054 67055 67056 67057 67058 67059 67060 67061 67062 67063 67064 67065 67066 67067 67068 67069 67070 67071 67072 67073 67074 67075 67076 67077 67078 67079 67080 67081 67082 67083 67084 67085 67086 67087 67088 67089 67090 67091 67092 67093 67094 67095 67096 67097 67098 67099 67100 67101 67102 67103 67104 67105 67106 67107 67108 67109 67110 67111 67112 67113 67114 67115 67116 67117 67118 67119 67120 67121 67122 67123 67124 67125 67126 67127 67128 67129 67130 67131 67132 67133 67134 67135 67136 67137 67138 67139 67140 67141 67142 67143 67144 67145 67146 67147 67148 67149 67150 67151 67152 67153 67154 67155 67156 67157 67158 67159 67160 67161 67162 67163 67164 67165 67166 67167 67168 67169 67170 67171 67172 67173 67174 67175 67176 67177 67178 67179 67180 67181 67182 67183 67184 67185 67186 67187 67188 67189 67190 67191 67192 67193 67194 67195 67196 67197 67198 67199 67200 67201 67202 67203 67204 67205 67206 67207 67208 67209 67210 67211 67212 67213 67214 67215 67216 67217 67218 67219 67220 67221 67222 67223 67224 67225 67226 67227 67228 67229 67230 67231 67232 67233 67234 67235 67236 67237 67238 67239 67240 67241 67242 67243 67244 67245 67246 67247 67248 67249 67250 67251 67252 67253 67254 67255 67256 67257 67258 67259 67260 67261 67262 67263 67264 67265 67266 67267 67268 67269 67270 67271 67272 67273 67274 67275 67276 67277 67278 67279 67280 67281 67282 67283 67284 67285 67286 67287 67288 67289 67290 67291 67292 67293 67294 67295 67296 67297 67298 67299 67300 67301 67302 67303 67304 67305 67306 67307 67308 67309 67310 67311 67312 67313 67314 67315 67316 67317 67318 67319 67320 67321 67322 67323 67324 67325 67326 67327 67328 67329 67330 67331 67332 67333 67334 67335 67336 67337 67338 67339 67340 67341 67342 67343 67344 67345 67346 67347 67348 67349 67350 67351 67352 67353 67354 67355 67356 67357 67358 67359 67360 67361 67362 67363 67364 67365 67366 67367 67368 67369 67370 67371 67372 67373 67374 67375 67376 67377 67378 67379 67380 67381 67382 67383 67384 67385 67386 67387 67388 67389 67390 67391 67392 67393 67394 67395 67396 67397 67398 67399 67400 67401 67402 67403 67404 67405 67406 67407 67408 67409 67410 67411 67412 67413 67414 67415 67416 67417 67418 67419 67420 67421 67422 67423 67424 67425 67426 67427 67428 67429 67430 67431 67432 67433 67434 67435 67436 67437 67438 67439 67440 67441 67442 67443 67444 67445 67446 67447 67448 67449 67450 67451 67452 67453 67454 67455 67456 67457 67458 67459 67460 67461 67462 67463 67464 67465 67466 67467 67468 67469 67470 67471 67472 67473 67474 67475 67476 67477 67478 67479 67480 67481 67482 67483 67484 67485 67486 67487 67488 67489 67490 67491 67492 67493 67494 67495 67496 67497 67498 67499 67500 67501 67502 67503 67504 67505 67506 67507 67508 67509 67510 67511 67512 67513 67514 67515 67516 67517 67518 67519 67520 67521 67522 67523 67524 67525 67526 67527 67528 67529 67530 67531 67532 67533 67534 67535 67536 67537 67538 67539 67540 67541 67542 67543 67544 67545 67546 67547 67548 67549 67550 67551 67552 67553 67554 67555 67556 67557 67558 67559 67560 67561 67562 67563 67564 67565 67566 67567 67568 67569 67570 67571 67572 67573 67574 67575 67576 67577 67578 67579 67580 67581 67582 67583 67584 67585 67586 67587 67588 67589 67590 67591 67592 67593 67594 67595 67596 67597 67598 67599 67600 67601 67602 67603 67604 67605 67606 67607 67608 67609 67610 67611 67612 67613 67614 67615 67616 67617 67618 67619 67620 67621 67622 67623 67624 67625 67626 67627 67628 67629 67630 67631 67632 67633 67634 67635 67636 67637 67638 67639 67640 67641 67642 67643 67644 67645 67646 67647 67648 67649 67650 67651 67652 67653 67654 67655 67656 67657 67658 67659 67660 67661 67662 67663 67664 67665 67666 67667 67668 67669 67670 67671 67672 67673 67674 67675 67676 67677 67678 67679 67680 67681 67682 67683 67684 67685 67686 67687 67688 67689 67690 67691 67692 67693 67694 67695 67696 67697 67698 67699 67700 67701 67702 67703 67704 67705 67706 67707 67708 67709 67710 67711 67712 67713 67714 67715 67716 67717 67718 67719 67720 67721 67722 67723 67724 67725 67726 67727 67728 67729 67730 67731 67732 67733 67734 67735 67736 67737 67738 67739 67740 67741 67742 67743 67744 67745 67746 67747 67748 67749 67750 67751 67752 67753 67754 67755 67756 67757 67758 67759 67760 67761 67762 67763 67764 67765 67766 67767 67768 67769 67770 67771 67772 67773 67774 67775 67776 67777 67778 67779 67780 67781 67782 67783 67784 67785 67786 67787 67788 67789 67790 67791 67792 67793 67794 67795 67796 67797 67798 67799 67800 67801 67802 67803 67804 67805 67806 67807 67808 67809 67810 67811 67812 67813 67814 67815 67816 67817 67818 67819 67820 67821 67822 67823 67824 67825 67826 67827 67828 67829 67830 67831 67832 67833 67834 67835 67836 67837 67838 67839 67840 67841 67842 67843 67844 67845 67846 67847 67848 67849 67850 67851 67852 67853 67854 67855 67856 67857 67858 67859 67860 67861 67862 67863 67864 67865 67866 67867 67868 67869 67870 67871 67872 67873 67874 67875 67876 67877 67878 67879 67880 67881 67882 67883 67884 67885 67886 67887 67888 67889 67890 67891 67892 67893 67894 67895 67896 67897 67898 67899 67900 67901 67902 67903 67904 67905 67906 67907 67908 67909 67910 67911 67912 67913 67914 67915 67916 67917 67918 67919 67920 67921 67922 67923 67924 67925 67926 67927 67928 67929 67930 67931 67932 67933 67934 67935 67936 67937 67938 67939 67940 67941 67942 67943 67944 67945 67946 67947 67948 67949 67950 67951 67952 67953 67954 67955 67956 67957 67958 67959 67960 67961 67962 67963 67964 67965 67966 67967 67968 67969 67970 67971 67972 67973 67974 67975 67976 67977 67978 67979 67980 67981 67982 67983 67984 67985 67986 67987 67988 67989 67990 67991 67992 67993 67994 67995 67996 67997 67998 67999 68000 68001 68002 68003 68004 68005 68006 68007 68008 68009 68010 68011 68012 68013 68014 68015 68016 68017 68018 68019 68020 68021 68022 68023 68024 68025 68026 68027 68028 68029 68030 68031 68032 68033 68034 68035 68036 68037 68038 68039 68040 68041 68042 68043 68044 68045 68046 68047 68048 68049 68050 68051 68052 68053 68054 68055 68056 68057 68058 68059 68060 68061 68062 68063 68064 68065 68066 68067 68068 68069 68070 68071 68072 68073 68074 68075 68076 68077 68078 68079 68080 68081 68082 68083 68084 68085 68086 68087 68088 68089 68090 68091 68092 68093 68094 68095 68096 68097 68098 68099 68100 68101 68102 68103 68104 68105 68106 68107 68108 68109 68110 68111 68112 68113 68114 68115 68116 68117 68118 68119 68120 68121 68122 68123 68124 68125 68126 68127 68128 68129 68130 68131 68132 68133 68134 68135 68136 68137 68138 68139 68140 68141 68142 68143 68144 68145 68146 68147 68148 68149 68150 68151 68152 68153 68154 68155 68156 68157 68158 68159 68160 68161 68162 68163 68164 68165 68166 68167 68168 68169 68170 68171 68172 68173 68174 68175 68176 68177 68178 68179 68180 68181 68182 68183 68184 68185 68186 68187 68188 68189 68190 68191 68192 68193 68194 68195 68196 68197 68198 68199 68200 68201 68202 68203 68204 68205 68206 68207 68208 68209 68210 68211 68212 68213 68214 68215 68216 68217 68218 68219 68220 68221 68222 68223 68224 68225 68226 68227 68228 68229 68230 68231 68232 68233 68234 68235 68236 68237 68238 68239 68240 68241 68242 68243 68244 68245 68246 68247 68248 68249 68250 68251 68252 68253 68254 68255 68256 68257 68258 68259 68260 68261 68262 68263 68264 68265 68266 68267 68268 68269 68270 68271 68272 68273 68274 68275 68276 68277 68278 68279 68280 68281 68282 68283 68284 68285 68286 68287 68288 68289 68290 68291 68292 68293 68294 68295 68296 68297 68298 68299 68300 68301 68302 68303 68304 68305 68306 68307 68308 68309 68310 68311 68312 68313 68314 68315 68316 68317 68318 68319 68320 68321 68322 68323 68324 68325 68326 68327 68328 68329 68330 68331 68332 68333 68334 68335 68336 68337 68338 68339 68340 68341 68342 68343 68344 68345 68346 68347 68348 68349 68350 68351 68352 68353 68354 68355 68356 68357 68358 68359 68360 68361 68362 68363 68364 68365 68366 68367 68368 68369 68370 68371 68372 68373 68374 68375 68376 68377 68378 68379 68380 68381 68382 68383 68384 68385 68386 68387 68388 68389 68390 68391 68392 68393 68394 68395 68396 68397 68398 68399 68400 68401 68402 68403 68404 68405 68406 68407 68408 68409 68410 68411 68412 68413 68414 68415 68416 68417 68418 68419 68420 68421 68422 68423 68424 68425 68426 68427 68428 68429 68430 68431 68432 68433 68434 68435 68436 68437 68438 68439 68440 68441 68442 68443 68444 68445 68446 68447 68448 68449 68450 68451 68452 68453 68454 68455 68456 68457 68458 68459 68460 68461 68462 68463 68464 68465 68466 68467 68468 68469 68470 68471 68472 68473 68474 68475 68476 68477 68478 68479 68480 68481 68482 68483 68484 68485 68486 68487 68488 68489 68490 68491 68492 68493 68494 68495 68496 68497 68498 68499 68500 68501 68502 68503 68504 68505 68506 68507 68508 68509 68510 68511 68512 68513 68514 68515 68516 68517 68518 68519 68520 68521 68522 68523 68524 68525 68526 68527 68528 68529 68530 68531 68532 68533 68534 68535 68536 68537 68538 68539 68540 68541 68542 68543 68544 68545 68546 68547 68548 68549 68550 68551 68552 68553 68554 68555 68556 68557 68558 68559 68560 68561 68562 68563 68564 68565 68566 68567 68568 68569 68570 68571 68572 68573 68574 68575 68576 68577 68578 68579 68580 68581 68582 68583 68584 68585 68586 68587 68588 68589 68590 68591 68592 68593 68594 68595 68596 68597 68598 68599 68600 68601 68602 68603 68604 68605 68606 68607 68608 68609 68610 68611 68612 68613 68614 68615 68616 68617 68618 68619 68620 68621 68622 68623 68624 68625 68626 68627 68628 68629 68630 68631 68632 68633 68634 68635 68636 68637 68638 68639 68640 68641 68642 68643 68644 68645 68646 68647 68648 68649 68650 68651 68652 68653 68654 68655 68656 68657 68658 68659 68660 68661 68662 68663 68664 68665 68666 68667 68668 68669 68670 68671 68672 68673 68674 68675 68676 68677 68678 68679 68680 68681 68682 68683 68684 68685 68686 68687 68688 68689 68690 68691 68692 68693 68694 68695 68696 68697 68698 68699 68700 68701 68702 68703 68704 68705 68706 68707 68708 68709 68710 68711 68712 68713 68714 68715 68716 68717 68718 68719 68720 68721 68722 68723 68724 68725 68726 68727 68728 68729 68730 68731 68732 68733 68734 68735 68736 68737 68738 68739 68740 68741 68742 68743 68744 68745 68746 68747 68748 68749 68750 68751 68752 68753 68754 68755 68756 68757 68758 68759 68760 68761 68762 68763 68764 68765 68766 68767 68768 68769 68770 68771 68772 68773 68774 68775 68776 68777 68778 68779 68780 68781 68782 68783 68784 68785 68786 68787 68788 68789 68790 68791 68792 68793 68794 68795 68796 68797 68798 68799 68800 68801 68802 68803 68804 68805 68806 68807 68808 68809 68810 68811 68812 68813 68814 68815 68816 68817 68818 68819 68820 68821 68822 68823 68824 68825 68826 68827 68828 68829 68830 68831 68832 68833 68834 68835 68836 68837 68838 68839 68840 68841 68842 68843 68844 68845 68846 68847 68848 68849 68850 68851 68852 68853 68854 68855 68856 68857 68858 68859 68860 68861 68862 68863 68864 68865 68866 68867 68868 68869 68870 68871 68872 68873 68874 68875 68876 68877 68878 68879 68880 68881 68882 68883 68884 68885 68886 68887 68888 68889 68890 68891 68892 68893 68894 68895 68896 68897 68898 68899 68900 68901 68902 68903 68904 68905 68906 68907 68908 68909 68910 68911 68912 68913 68914 68915 68916 68917 68918 68919 68920 68921 68922 68923 68924 68925 68926 68927 68928 68929 68930 68931 68932 68933 68934 68935 68936 68937 68938 68939 68940 68941 68942 68943 68944 68945 68946 68947 68948 68949 68950 68951 68952 68953 68954 68955 68956 68957 68958 68959 68960 68961 68962 68963 68964 68965 68966 68967 68968 68969 68970 68971 68972 68973 68974 68975 68976 68977 68978 68979 68980 68981 68982 68983 68984 68985 68986 68987 68988 68989 68990 68991 68992 68993 68994 68995 68996 68997 68998 68999 69000 69001 69002 69003 69004 69005 69006 69007 69008 69009 69010 69011 69012 69013 69014 69015 69016 69017 69018 69019 69020 69021 69022 69023 69024 69025 69026 69027 69028 69029 69030 69031 69032 69033 69034 69035 69036 69037 69038 69039 69040 69041 69042 69043 69044 69045 69046 69047 69048 69049 69050 69051 69052 69053 69054 69055 69056 69057 69058 69059 69060 69061 69062 69063 69064 69065 69066 69067 69068 69069 69070 69071 69072 69073 69074 69075 69076 69077 69078 69079 69080 69081 69082 69083 69084 69085 69086 69087 69088 69089 69090 69091 69092 69093 69094 69095 69096 69097 69098 69099 69100 69101 69102 69103 69104 69105 69106 69107 69108 69109 69110 69111 69112 69113 69114 69115 69116 69117 69118 69119 69120 69121 69122 69123 69124 69125 69126 69127 69128 69129 69130 69131 69132 69133 69134 69135 69136 69137 69138 69139 69140 69141 69142 69143 69144 69145 69146 69147 69148 69149 69150 69151 69152 69153 69154 69155 69156 69157 69158 69159 69160 69161 69162 69163 69164 69165 69166 69167 69168 69169 69170 69171 69172 69173 69174 69175 69176 69177 69178 69179 69180 69181 69182 69183 69184 69185 69186 69187 69188 69189 69190 69191 69192 69193 69194 69195 69196 69197 69198 69199 69200 69201 69202 69203 69204 69205 69206 69207 69208 69209 69210 69211 69212 69213 69214 69215 69216 69217 69218 69219 69220 69221 69222 69223 69224 69225 69226 69227 69228 69229 69230 69231 69232 69233 69234 69235 69236 69237 69238 69239 69240 69241 69242 69243 69244 69245 69246 69247 69248 69249 69250 69251 69252 69253 69254 69255 69256 69257 69258 69259 69260 69261 69262 69263 69264 69265 69266 69267 69268 69269 69270 69271 69272 69273 69274 69275 69276 69277 69278 69279 69280 69281 69282 69283 69284 69285 69286 69287 69288 69289 69290 69291 69292 69293 69294 69295 69296 69297 69298 69299 69300 69301 69302 69303 69304 69305 69306 69307 69308 69309 69310 69311 69312 69313 69314 69315 69316 69317 69318 69319 69320 69321 69322 69323 69324 69325 69326 69327 69328 69329 69330 69331 69332 69333 69334 69335 69336 69337 69338 69339 69340 69341 69342 69343 69344 69345 69346 69347 69348 69349 69350 69351 69352 69353 69354 69355 69356 69357 69358 69359 69360 69361 69362 69363 69364 69365 69366 69367 69368 69369 69370 69371 69372 69373 69374 69375 69376 69377 69378 69379 69380 69381 69382 69383 69384 69385 69386 69387 69388 69389 69390 69391 69392 69393 69394 69395 69396 69397 69398 69399 69400 69401 69402 69403 69404 69405 69406 69407 69408 69409 69410 69411 69412 69413 69414 69415 69416 69417 69418 69419 69420 69421 69422 69423 69424 69425 69426 69427 69428 69429 69430 69431 69432 69433 69434 69435 69436 69437 69438 69439 69440 69441 69442 69443 69444 69445 69446 69447 69448 69449 69450 69451 69452 69453 69454 69455 69456 69457 69458 69459 69460 69461 69462 69463 69464 69465 69466 69467 69468 69469 69470 69471 69472 69473 69474 69475 69476 69477 69478 69479 69480 69481 69482 69483 69484 69485 69486 69487 69488 69489 69490 69491 69492 69493 69494 69495 69496 69497 69498 69499 69500 69501 69502 69503 69504 69505 69506 69507 69508 69509 69510 69511 69512 69513 69514 69515 69516 69517 69518 69519 69520 69521 69522 69523 69524 69525 69526 69527 69528 69529 69530 69531 69532 69533 69534 69535 69536 69537 69538 69539 69540 69541 69542 69543 69544 69545 69546 69547 69548 69549 69550 69551 69552 69553 69554 69555 69556 69557 69558 69559 69560 69561 69562 69563 69564 69565 69566 69567 69568 69569 69570 69571 69572 69573 69574 69575 69576 69577 69578 69579 69580 69581 69582 69583 69584 69585 69586 69587 69588 69589 69590 69591 69592 69593 69594 69595 69596 69597 69598 69599 69600 69601 69602 69603 69604 69605 69606 69607 69608 69609 69610 69611 69612 69613 69614 69615 69616 69617 69618 69619 69620 69621 69622 69623 69624 69625 69626 69627 69628 69629 69630 69631 69632 69633 69634 69635 69636 69637 69638 69639 69640 69641 69642 69643 69644 69645 69646 69647 69648 69649 69650 69651 69652 69653 69654 69655 69656 69657 69658 69659 69660 69661 69662 69663 69664 69665 69666 69667 69668 69669 69670 69671 69672 69673 69674 69675 69676 69677 69678 69679 69680 69681 69682 69683 69684 69685 69686 69687 69688 69689 69690 69691 69692 69693 69694 69695 69696 69697 69698 69699 69700 69701 69702 69703 69704 69705 69706 69707 69708 69709 69710 69711 69712 69713 69714 69715 69716 69717 69718 69719 69720 69721 69722 69723 69724 69725 69726 69727 69728 69729 69730 69731 69732 69733 69734 69735 69736 69737 69738 69739 69740 69741 69742 69743 69744 69745 69746 69747 69748 69749 69750 69751 69752 69753 69754 69755 69756 69757 69758 69759 69760 69761 69762 69763 69764 69765 69766 69767 69768 69769 69770 69771 69772 69773 69774 69775 69776 69777 69778 69779 69780 69781 69782 69783 69784 69785 69786 69787 69788 69789 69790 69791 69792 69793 69794 69795 69796 69797 69798 69799 69800 69801 69802 69803 69804 69805 69806 69807 69808 69809 69810 69811 69812 69813 69814 69815 69816 69817 69818 69819 69820 69821 69822 69823 69824 69825 69826 69827 69828 69829 69830 69831 69832 69833 69834 69835 69836 69837 69838 69839 69840 69841 69842 69843 69844 69845 69846 69847 69848 69849 69850 69851 69852 69853 69854 69855 69856 69857 69858 69859 69860 69861 69862 69863 69864 69865 69866 69867 69868 69869 69870 69871 69872 69873 69874 69875 69876 69877 69878 69879 69880 69881 69882 69883 69884 69885 69886 69887 69888 69889 69890 69891 69892 69893 69894 69895 69896 69897 69898 69899 69900 69901 69902 69903 69904 69905 69906 69907 69908 69909 69910 69911 69912 69913 69914 69915 69916 69917 69918 69919 69920 69921 69922 69923 69924 69925 69926 69927 69928 69929 69930 69931 69932 69933 69934 69935 69936 69937 69938 69939 69940 69941 69942 69943 69944 69945 69946 69947 69948 69949 69950 69951 69952 69953 69954 69955 69956 69957 69958 69959 69960 69961 69962 69963 69964 69965 69966 69967 69968 69969 69970 69971 69972 69973 69974 69975 69976 69977 69978 69979 69980 69981 69982 69983 69984 69985 69986 69987 69988 69989 69990 69991 69992 69993 69994 69995 69996 69997 69998 69999 70000 70001 70002 70003 70004 70005 70006 70007 70008 70009 70010 70011 70012 70013 70014 70015 70016 70017 70018 70019 70020 70021 70022 70023 70024 70025 70026 70027 70028 70029 70030 70031 70032 70033 70034 70035 70036 70037 70038 70039 70040 70041 70042 70043 70044 70045 70046 70047 70048 70049 70050 70051 70052 70053 70054 70055 70056 70057 70058 70059 70060 70061 70062 70063 70064 70065 70066 70067 70068 70069 70070 70071 70072 70073 70074 70075 70076 70077 70078 70079 70080 70081 70082 70083 70084 70085 70086 70087 70088 70089 70090 70091 70092 70093 70094 70095 70096 70097 70098 70099 70100 70101 70102 70103 70104 70105 70106 70107 70108 70109 70110 70111 70112 70113 70114 70115 70116 70117 70118 70119 70120 70121 70122 70123 70124 70125 70126 70127 70128 70129 70130 70131 70132 70133 70134 70135 70136 70137 70138 70139 70140 70141 70142 70143 70144 70145 70146 70147 70148 70149 70150 70151 70152 70153 70154 70155 70156 70157 70158 70159 70160 70161 70162 70163 70164 70165 70166 70167 70168 70169 70170 70171 70172 70173 70174 70175 70176 70177 70178 70179 70180 70181 70182 70183 70184 70185 70186 70187 70188 70189 70190 70191 70192 70193 70194 70195 70196 70197 70198 70199 70200 70201 70202 70203 70204 70205 70206 70207 70208 70209 70210 70211 70212 70213 70214 70215 70216 70217 70218 70219 70220 70221 70222 70223 70224 70225 70226 70227 70228 70229 70230 70231 70232 70233 70234 70235 70236 70237 70238 70239 70240 70241 70242 70243 70244 70245 70246 70247 70248 70249 70250 70251 70252 70253 70254 70255 70256 70257 70258 70259 70260 70261 70262 70263 70264 70265 70266 70267 70268 70269 70270 70271 70272 70273 70274 70275 70276 70277 70278 70279 70280 70281 70282 70283 70284 70285 70286 70287 70288 70289 70290 70291 70292 70293 70294 70295 70296 70297 70298 70299 70300 70301 70302 70303 70304 70305 70306 70307 70308 70309 70310 70311 70312 70313 70314 70315 70316 70317 70318 70319 70320 70321 70322 70323 70324 70325 70326 70327 70328 70329 70330 70331 70332 70333 70334 70335 70336 70337 70338 70339 70340 70341 70342 70343 70344 70345 70346 70347 70348 70349 70350 70351 70352 70353 70354 70355 70356 70357 70358 70359 70360 70361 70362 70363 70364 70365 70366 70367 70368 70369 70370 70371 70372 70373 70374 70375 70376 70377 70378 70379 70380 70381 70382 70383 70384 70385 70386 70387 70388 70389 70390 70391 70392 70393 70394 70395 70396 70397 70398 70399 70400 70401 70402 70403 70404 70405 70406 70407 70408 70409 70410 70411 70412 70413 70414 70415 70416 70417 70418 70419 70420 70421 70422 70423 70424 70425 70426 70427 70428 70429 70430 70431 70432 70433 70434 70435 70436 70437 70438 70439 70440 70441 70442 70443 70444 70445 70446 70447 70448 70449 70450 70451 70452 70453 70454 70455 70456 70457 70458 70459 70460 70461 70462 70463 70464 70465 70466 70467 70468 70469 70470 70471 70472 70473 70474 70475 70476 70477 70478 70479 70480 70481 70482 70483 70484 70485 70486 70487 70488 70489 70490 70491 70492 70493 70494 70495 70496 70497 70498 70499 70500 70501 70502 70503 70504 70505 70506 70507 70508 70509 70510 70511 70512 70513 70514 70515 70516 70517 70518 70519 70520 70521 70522 70523 70524 70525 70526 70527 70528 70529 70530 70531 70532 70533 70534 70535 70536 70537 70538 70539 70540 70541 70542 70543 70544 70545 70546 70547 70548 70549 70550 70551 70552 70553 70554 70555 70556 70557 70558 70559 70560 70561 70562 70563 70564 70565 70566 70567 70568 70569 70570 70571 70572 70573 70574 70575 70576 70577 70578 70579 70580 70581 70582 70583 70584 70585 70586 70587 70588 70589 70590 70591 70592 70593 70594 70595 70596 70597 70598 70599 70600 70601 70602 70603 70604 70605 70606 70607 70608 70609 70610 70611 70612 70613 70614 70615 70616 70617 70618 70619 70620 70621 70622 70623 70624 70625 70626 70627 70628 70629 70630 70631 70632 70633 70634 70635 70636 70637 70638 70639 70640 70641 70642 70643 70644 70645 70646 70647 70648 70649 70650 70651 70652 70653 70654 70655 70656 70657 70658 70659 70660 70661 70662 70663 70664 70665 70666 70667 70668 70669 70670 70671 70672 70673 70674 70675 70676 70677 70678 70679 70680 70681 70682 70683 70684 70685 70686 70687 70688 70689 70690 70691 70692 70693 70694 70695 70696 70697 70698 70699 70700 70701 70702 70703 70704 70705 70706 70707 70708 70709 70710 70711 70712 70713 70714 70715 70716 70717 70718 70719 70720 70721 70722 70723 70724 70725 70726 70727 70728 70729 70730 70731 70732 70733 70734 70735 70736 70737 70738 70739 70740 70741 70742 70743 70744 70745 70746 70747 70748 70749 70750 70751 70752 70753 70754 70755 70756 70757 70758 70759 70760 70761 70762 70763 70764 70765 70766 70767 70768 70769 70770 70771 70772 70773 70774 70775 70776 70777 70778 70779 70780 70781 70782 70783 70784 70785 70786 70787 70788 70789 70790 70791 70792 70793 70794 70795 70796 70797 70798 70799 70800 70801 70802 70803 70804 70805 70806 70807 70808 70809 70810 70811 70812 70813 70814 70815 70816 70817 70818 70819 70820 70821 70822 70823 70824 70825 70826 70827 70828 70829 70830 70831 70832 70833 70834 70835 70836 70837 70838 70839 70840 70841 70842 70843 70844 70845 70846 70847 70848 70849 70850 70851 70852 70853 70854 70855 70856 70857 70858 70859 70860 70861 70862 70863 70864 70865 70866 70867 70868 70869 70870 70871 70872 70873 70874 70875 70876 70877 70878 70879 70880 70881 70882 70883 70884 70885 70886 70887 70888 70889 70890 70891 70892 70893 70894 70895 70896 70897 70898 70899 70900 70901 70902 70903 70904 70905 70906 70907 70908 70909 70910 70911 70912 70913 70914 70915 70916 70917 70918 70919 70920 70921 70922 70923 70924 70925 70926 70927 70928 70929 70930 70931 70932 70933 70934 70935 70936 70937 70938 70939 70940 70941 70942 70943 70944 70945 70946 70947 70948 70949 70950 70951 70952 70953 70954 70955 70956 70957 70958 70959 70960 70961 70962 70963 70964 70965 70966 70967 70968 70969 70970 70971 70972 70973 70974 70975 70976 70977 70978 70979 70980 70981 70982 70983 70984 70985 70986 70987 70988 70989 70990 70991 70992 70993 70994 70995 70996 70997 70998 70999 71000 71001 71002 71003 71004 71005 71006 71007 71008 71009 71010 71011 71012 71013 71014 71015 71016 71017 71018 71019 71020 71021 71022 71023 71024 71025 71026 71027 71028 71029 71030 71031 71032 71033 71034 71035 71036 71037 71038 71039 71040 71041 71042 71043 71044 71045 71046 71047 71048 71049 71050 71051 71052 71053 71054 71055 71056 71057 71058 71059 71060 71061 71062 71063 71064 71065 71066 71067 71068 71069 71070 71071 71072 71073 71074 71075 71076 71077 71078 71079 71080 71081 71082 71083 71084 71085 71086 71087 71088 71089 71090 71091 71092 71093 71094 71095 71096 71097 71098 71099 71100 71101 71102 71103 71104 71105 71106 71107 71108 71109 71110 71111 71112 71113 71114 71115 71116 71117 71118 71119 71120 71121 71122 71123 71124 71125 71126 71127 71128 71129 71130 71131 71132 71133 71134 71135 71136 71137 71138 71139 71140 71141 71142 71143 71144 71145 71146 71147 71148 71149 71150 71151 71152 71153 71154 71155 71156 71157 71158 71159 71160 71161 71162 71163 71164 71165 71166 71167 71168 71169 71170 71171 71172 71173 71174 71175 71176 71177 71178 71179 71180 71181 71182 71183 71184 71185 71186 71187 71188 71189 71190 71191 71192 71193 71194 71195 71196 71197 71198 71199 71200 71201 71202 71203 71204 71205 71206 71207 71208 71209 71210 71211 71212 71213 71214 71215 71216 71217 71218 71219 71220 71221 71222 71223 71224 71225 71226 71227 71228 71229 71230 71231 71232 71233 71234 71235 71236 71237 71238 71239 71240 71241 71242 71243 71244 71245 71246 71247 71248 71249 71250 71251 71252 71253 71254 71255 71256 71257 71258 71259 71260 71261 71262 71263 71264 71265 71266 71267 71268 71269 71270 71271 71272 71273 71274 71275 71276 71277 71278 71279 71280 71281 71282 71283 71284 71285 71286 71287 71288 71289 71290 71291 71292 71293 71294 71295 71296 71297 71298 71299 71300 71301 71302 71303 71304 71305 71306 71307 71308 71309 71310 71311 71312 71313 71314 71315 71316 71317 71318 71319 71320 71321 71322 71323 71324 71325 71326 71327 71328 71329 71330 71331 71332 71333 71334 71335 71336 71337 71338 71339 71340 71341 71342 71343 71344 71345 71346 71347 71348 71349 71350 71351 71352 71353 71354 71355 71356 71357 71358 71359 71360 71361 71362 71363 71364 71365 71366 71367 71368 71369 71370 71371 71372 71373 71374 71375 71376 71377 71378 71379 71380 71381 71382 71383 71384 71385 71386 71387 71388 71389 71390 71391 71392 71393 71394 71395 71396 71397 71398 71399 71400 71401 71402 71403 71404 71405 71406 71407 71408 71409 71410 71411 71412 71413 71414 71415 71416 71417 71418 71419 71420 71421 71422 71423 71424 71425 71426 71427 71428 71429 71430 71431 71432 71433 71434 71435 71436 71437 71438 71439 71440 71441 71442 71443 71444 71445 71446 71447 71448 71449 71450 71451 71452 71453 71454 71455 71456 71457 71458 71459 71460 71461 71462 71463 71464 71465 71466 71467 71468 71469 71470 71471 71472 71473 71474 71475 71476 71477 71478 71479 71480 71481 71482 71483 71484 71485 71486 71487 71488 71489 71490 71491 71492 71493 71494 71495 71496 71497 71498 71499 71500 71501 71502 71503 71504 71505 71506 71507 71508 71509 71510 71511 71512 71513 71514 71515 71516 71517 71518 71519 71520 71521 71522 71523 71524 71525 71526 71527 71528 71529 71530 71531 71532 71533 71534 71535 71536 71537 71538 71539 71540 71541 71542 71543 71544 71545 71546 71547 71548 71549 71550 71551 71552 71553 71554 71555 71556 71557 71558 71559 71560 71561 71562 71563 71564 71565 71566 71567 71568 71569 71570 71571 71572 71573 71574 71575 71576 71577 71578 71579 71580 71581 71582 71583 71584 71585 71586 71587 71588 71589 71590 71591 71592 71593 71594 71595 71596 71597 71598 71599 71600 71601 71602 71603 71604 71605 71606 71607 71608 71609 71610 71611 71612 71613 71614 71615 71616 71617 71618 71619 71620 71621 71622 71623 71624 71625 71626 71627 71628 71629 71630 71631 71632 71633 71634 71635 71636 71637 71638 71639 71640 71641 71642 71643 71644 71645 71646 71647 71648 71649 71650 71651 71652 71653 71654 71655 71656 71657 71658 71659 71660 71661 71662 71663 71664 71665 71666 71667 71668 71669 71670 71671 71672 71673 71674 71675 71676 71677 71678 71679 71680 71681 71682 71683 71684 71685 71686 71687 71688 71689 71690 71691 71692 71693 71694 71695 71696 71697 71698 71699 71700 71701 71702 71703 71704 71705 71706 71707 71708 71709 71710 71711 71712 71713 71714 71715 71716 71717 71718 71719 71720 71721 71722 71723 71724 71725 71726 71727 71728 71729 71730 71731 71732 71733 71734 71735 71736 71737 71738 71739 71740 71741 71742 71743 71744 71745 71746 71747 71748 71749 71750 71751 71752 71753 71754 71755 71756 71757 71758 71759 71760 71761 71762 71763 71764 71765 71766 71767 71768 71769 71770 71771 71772 71773 71774 71775 71776 71777 71778 71779 71780 71781 71782 71783 71784 71785 71786 71787 71788 71789 71790 71791 71792 71793 71794 71795 71796 71797 71798 71799 71800 71801 71802 71803 71804 71805 71806 71807 71808 71809 71810 71811 71812 71813 71814 71815 71816 71817 71818 71819 71820 71821 71822 71823 71824 71825 71826 71827 71828 71829 71830 71831 71832 71833 71834 71835 71836 71837 71838 71839 71840 71841 71842 71843 71844 71845 71846 71847 71848 71849 71850 71851 71852 71853 71854 71855 71856 71857 71858 71859 71860 71861 71862 71863 71864 71865 71866 71867 71868 71869 71870 71871 71872 71873 71874 71875 71876 71877 71878 71879 71880 71881 71882 71883 71884 71885 71886 71887 71888 71889 71890 71891 71892 71893 71894 71895 71896 71897 71898 71899 71900 71901 71902 71903 71904 71905 71906 71907 71908 71909 71910 71911 71912 71913 71914 71915 71916 71917 71918 71919 71920 71921 71922 71923 71924 71925 71926 71927 71928 71929 71930 71931 71932 71933 71934 71935 71936 71937 71938 71939 71940 71941 71942 71943 71944 71945 71946 71947 71948 71949 71950 71951 71952 71953 71954 71955 71956 71957 71958 71959 71960 71961 71962 71963 71964 71965 71966 71967 71968 71969 71970 71971 71972 71973 71974 71975 71976 71977 71978 71979 71980 71981 71982 71983 71984 71985 71986 71987 71988 71989 71990 71991 71992 71993 71994 71995 71996 71997 71998 71999 72000 72001 72002 72003 72004 72005 72006 72007 72008 72009 72010 72011 72012 72013 72014 72015 72016 72017 72018 72019 72020 72021 72022 72023 72024 72025 72026 72027 72028 72029 72030 72031 72032 72033 72034 72035 72036 72037 72038 72039 72040 72041 72042 72043 72044 72045 72046 72047 72048 72049 72050 72051 72052 72053 72054 72055 72056 72057 72058 72059 72060 72061 72062 72063 72064 72065 72066 72067 72068 72069 72070 72071 72072 72073 72074 72075 72076 72077 72078 72079 72080 72081 72082 72083 72084 72085 72086 72087 72088 72089 72090 72091 72092 72093 72094 72095 72096 72097 72098 72099 72100 72101 72102 72103 72104 72105 72106 72107 72108 72109 72110 72111 72112 72113 72114 72115 72116 72117 72118 72119 72120 72121 72122 72123 72124 72125 72126 72127 72128 72129 72130 72131 72132 72133 72134 72135 72136 72137 72138 72139 72140 72141 72142 72143 72144 72145 72146 72147 72148 72149 72150 72151 72152 72153 72154 72155 72156 72157 72158 72159 72160 72161 72162 72163 72164 72165 72166 72167 72168 72169 72170 72171 72172 72173 72174 72175 72176 72177 72178 72179 72180 72181 72182 72183 72184 72185 72186 72187 72188 72189 72190 72191 72192 72193 72194 72195 72196 72197 72198 72199 72200 72201 72202 72203 72204 72205 72206 72207 72208 72209 72210 72211 72212 72213 72214 72215 72216 72217 72218 72219 72220 72221 72222 72223 72224 72225 72226 72227 72228 72229 72230 72231 72232 72233 72234 72235 72236 72237 72238 72239 72240 72241 72242 72243 72244 72245 72246 72247 72248 72249 72250 72251 72252 72253 72254 72255 72256 72257 72258 72259 72260 72261 72262 72263 72264 72265 72266 72267 72268 72269 72270 72271 72272 72273 72274 72275 72276 72277 72278 72279 72280 72281 72282 72283 72284 72285 72286 72287 72288 72289 72290 72291 72292 72293 72294 72295 72296 72297 72298 72299 72300 72301 72302 72303 72304 72305 72306 72307 72308 72309 72310 72311 72312 72313 72314 72315 72316 72317 72318 72319 72320 72321 72322 72323 72324 72325 72326 72327 72328 72329 72330 72331 72332 72333 72334 72335 72336 72337 72338 72339 72340 72341 72342 72343 72344 72345 72346 72347 72348 72349 72350 72351 72352 72353 72354 72355 72356 72357 72358 72359 72360 72361 72362 72363 72364 72365 72366 72367 72368 72369 72370 72371 72372 72373 72374 72375 72376 72377 72378 72379 72380 72381 72382 72383 72384 72385 72386 72387 72388 72389 72390 72391 72392 72393 72394 72395 72396 72397 72398 72399 72400 72401 72402 72403 72404 72405 72406 72407 72408 72409 72410 72411 72412 72413 72414 72415 72416 72417 72418 72419 72420 72421 72422 72423 72424 72425 72426 72427 72428 72429 72430 72431 72432 72433 72434 72435 72436 72437 72438 72439 72440 72441 72442 72443 72444 72445 72446 72447 72448 72449 72450 72451 72452 72453 72454 72455 72456 72457 72458 72459 72460 72461 72462 72463 72464 72465 72466 72467 72468 72469 72470 72471 72472 72473 72474 72475 72476 72477 72478 72479 72480 72481 72482 72483 72484 72485 72486 72487 72488 72489 72490 72491 72492 72493 72494 72495 72496 72497 72498 72499 72500 72501 72502 72503 72504 72505 72506 72507 72508 72509 72510 72511 72512 72513 72514 72515 72516 72517 72518 72519 72520 72521 72522 72523 72524 72525 72526 72527 72528 72529 72530 72531 72532 72533 72534 72535 72536 72537 72538 72539 72540 72541 72542 72543 72544 72545 72546 72547 72548 72549 72550 72551 72552 72553 72554 72555 72556 72557 72558 72559 72560 72561 72562 72563 72564 72565 72566 72567 72568 72569 72570 72571 72572 72573 72574 72575 72576 72577 72578 72579 72580 72581 72582 72583 72584 72585 72586 72587 72588 72589 72590 72591 72592 72593 72594 72595 72596 72597 72598 72599 72600 72601 72602 72603 72604 72605 72606 72607 72608 72609 72610 72611 72612 72613 72614 72615 72616 72617 72618 72619 72620 72621 72622 72623 72624 72625 72626 72627 72628 72629 72630 72631 72632 72633 72634 72635 72636 72637 72638 72639 72640 72641 72642 72643 72644 72645 72646 72647 72648 72649 72650 72651 72652 72653 72654 72655 72656 72657 72658 72659 72660 72661 72662 72663 72664 72665 72666 72667 72668 72669 72670 72671 72672 72673 72674 72675 72676 72677 72678 72679 72680 72681 72682 72683 72684 72685 72686 72687 72688 72689 72690 72691 72692 72693 72694 72695 72696 72697 72698 72699 72700 72701 72702 72703 72704 72705 72706 72707 72708 72709 72710 72711 72712 72713 72714 72715 72716 72717 72718 72719 72720 72721 72722 72723 72724 72725 72726 72727 72728 72729 72730 72731 72732 72733 72734 72735 72736 72737 72738 72739 72740 72741 72742 72743 72744 72745 72746 72747 72748 72749 72750 72751 72752 72753 72754 72755 72756 72757 72758 72759 72760 72761 72762 72763 72764 72765 72766 72767 72768 72769 72770 72771 72772 72773 72774 72775 72776 72777 72778 72779 72780 72781 72782 72783 72784 72785 72786 72787 72788 72789 72790 72791 72792 72793 72794 72795 72796 72797 72798 72799 72800 72801 72802 72803 72804 72805 72806 72807 72808 72809 72810 72811 72812 72813 72814 72815 72816 72817 72818 72819 72820 72821 72822 72823 72824 72825 72826 72827 72828 72829 72830 72831 72832 72833 72834 72835 72836 72837 72838 72839 72840 72841 72842 72843 72844 72845 72846 72847 72848 72849 72850 72851 72852 72853 72854 72855 72856 72857 72858 72859 72860 72861 72862 72863 72864 72865 72866 72867 72868 72869 72870 72871 72872 72873 72874 72875 72876 72877 72878 72879 72880 72881 72882 72883 72884 72885 72886 72887 72888 72889 72890 72891 72892 72893 72894 72895 72896 72897 72898 72899 72900 72901 72902 72903 72904 72905 72906 72907 72908 72909 72910 72911 72912 72913 72914 72915 72916 72917 72918 72919 72920 72921 72922 72923 72924 72925 72926 72927 72928 72929 72930 72931 72932 72933 72934 72935 72936 72937 72938 72939 72940 72941 72942 72943 72944 72945 72946 72947 72948 72949 72950 72951 72952 72953 72954 72955 72956 72957 72958 72959 72960 72961 72962 72963 72964 72965 72966 72967 72968 72969 72970 72971 72972 72973 72974 72975 72976 72977 72978 72979 72980 72981 72982 72983 72984 72985 72986 72987 72988 72989 72990 72991 72992 72993 72994 72995 72996 72997 72998 72999 73000 73001 73002 73003 73004 73005 73006 73007 73008 73009 73010 73011 73012 73013 73014 73015 73016 73017 73018 73019 73020 73021 73022 73023 73024 73025 73026 73027 73028 73029 73030 73031 73032 73033 73034 73035 73036 73037 73038 73039 73040 73041 73042 73043 73044 73045 73046 73047 73048 73049 73050 73051 73052 73053 73054 73055 73056 73057 73058 73059 73060 73061 73062 73063 73064 73065 73066 73067 73068 73069 73070 73071 73072 73073 73074 73075 73076 73077 73078 73079 73080 73081 73082 73083 73084 73085 73086 73087 73088 73089 73090 73091 73092 73093 73094 73095 73096 73097 73098 73099 73100 73101 73102 73103 73104 73105 73106 73107 73108 73109 73110 73111 73112 73113 73114 73115 73116 73117 73118 73119 73120 73121 73122 73123 73124 73125 73126 73127 73128 73129 73130 73131 73132 73133 73134 73135 73136 73137 73138 73139 73140 73141 73142 73143 73144 73145 73146 73147 73148 73149 73150 73151 73152 73153 73154 73155 73156 73157 73158 73159 73160 73161 73162 73163 73164 73165 73166 73167 73168 73169 73170 73171 73172 73173 73174 73175 73176 73177 73178 73179 73180 73181 73182 73183 73184 73185 73186 73187 73188 73189 73190 73191 73192 73193 73194 73195 73196 73197 73198 73199 73200 73201 73202 73203 73204 73205 73206 73207 73208 73209 73210 73211 73212 73213 73214 73215 73216 73217 73218 73219 73220 73221 73222 73223 73224 73225 73226 73227 73228 73229 73230 73231 73232 73233 73234 73235 73236 73237 73238 73239 73240 73241 73242 73243 73244 73245 73246 73247 73248 73249 73250 73251 73252 73253 73254 73255 73256 73257 73258 73259 73260 73261 73262 73263 73264 73265 73266 73267 73268 73269 73270 73271 73272 73273 73274 73275 73276 73277 73278 73279 73280 73281 73282 73283 73284 73285 73286 73287 73288 73289 73290 73291 73292 73293 73294 73295 73296 73297 73298 73299 73300 73301 73302 73303 73304 73305 73306 73307 73308 73309 73310 73311 73312 73313 73314 73315 73316 73317 73318 73319 73320 73321 73322 73323 73324 73325 73326 73327 73328 73329 73330 73331 73332 73333 73334 73335 73336 73337 73338 73339 73340 73341 73342 73343 73344 73345 73346 73347 73348 73349 73350 73351 73352 73353 73354 73355 73356 73357 73358 73359 73360 73361 73362 73363 73364 73365 73366 73367 73368 73369 73370 73371 73372 73373 73374 73375 73376 73377 73378 73379 73380 73381 73382 73383 73384 73385 73386 73387 73388 73389 73390 73391 73392 73393 73394 73395 73396 73397 73398 73399 73400 73401 73402 73403 73404 73405 73406 73407 73408 73409 73410 73411 73412 73413 73414 73415 73416 73417 73418 73419 73420 73421 73422 73423 73424 73425 73426 73427 73428 73429 73430 73431 73432 73433 73434 73435 73436 73437 73438 73439 73440 73441 73442 73443 73444 73445 73446 73447 73448 73449 73450 73451 73452 73453 73454 73455 73456 73457 73458 73459 73460 73461 73462 73463 73464 73465 73466 73467 73468 73469 73470 73471 73472 73473 73474 73475 73476 73477 73478 73479 73480 73481 73482 73483 73484 73485 73486 73487 73488 73489 73490 73491 73492 73493 73494 73495 73496 73497 73498 73499 73500 73501 73502 73503 73504 73505 73506 73507 73508 73509 73510 73511 73512 73513 73514 73515 73516 73517 73518 73519 73520 73521 73522 73523 73524 73525 73526 73527 73528 73529 73530 73531 73532 73533 73534 73535 73536 73537 73538 73539 73540 73541 73542 73543 73544 73545 73546 73547 73548 73549 73550 73551 73552 73553 73554 73555 73556 73557 73558 73559 73560 73561 73562 73563 73564 73565 73566 73567 73568 73569 73570 73571 73572 73573 73574 73575 73576 73577 73578 73579 73580 73581 73582 73583 73584 73585 73586 73587 73588 73589 73590 73591 73592 73593 73594 73595 73596 73597 73598 73599 73600 73601 73602 73603 73604 73605 73606 73607 73608 73609 73610 73611 73612 73613 73614 73615 73616 73617 73618 73619 73620 73621 73622 73623 73624 73625 73626 73627 73628 73629 73630 73631 73632 73633 73634 73635 73636 73637 73638 73639 73640 73641 73642 73643 73644 73645 73646 73647 73648 73649 73650 73651 73652 73653 73654 73655 73656 73657 73658 73659 73660 73661 73662 73663 73664 73665 73666 73667 73668 73669 73670 73671 73672 73673 73674 73675 73676 73677 73678 73679 73680 73681 73682 73683 73684 73685 73686 73687 73688 73689 73690 73691 73692 73693 73694 73695 73696 73697 73698 73699 73700 73701 73702 73703 73704 73705 73706 73707 73708 73709 73710 73711 73712 73713 73714 73715 73716 73717 73718 73719 73720 73721 73722 73723 73724 73725 73726 73727 73728 73729 73730 73731 73732 73733 73734 73735 73736 73737 73738 73739 73740 73741 73742 73743 73744 73745 73746 73747 73748 73749 73750 73751 73752 73753 73754 73755 73756 73757 73758 73759 73760 73761 73762 73763 73764 73765 73766 73767 73768 73769 73770 73771 73772 73773 73774 73775 73776 73777 73778 73779 73780 73781 73782 73783 73784 73785 73786 73787 73788 73789 73790 73791 73792 73793 73794 73795 73796 73797 73798 73799 73800 73801 73802 73803 73804 73805 73806 73807 73808 73809 73810 73811 73812 73813 73814 73815 73816 73817 73818 73819 73820 73821 73822 73823 73824 73825 73826 73827 73828 73829 73830 73831 73832 73833 73834 73835 73836 73837 73838 73839 73840 73841 73842 73843 73844 73845 73846 73847 73848 73849 73850 73851 73852 73853 73854 73855 73856 73857 73858 73859 73860 73861 73862 73863 73864 73865 73866 73867 73868 73869 73870 73871 73872 73873 73874 73875 73876 73877 73878 73879 73880 73881 73882 73883 73884 73885 73886 73887 73888 73889 73890 73891 73892 73893 73894 73895 73896 73897 73898 73899 73900 73901 73902 73903 73904 73905 73906 73907 73908 73909 73910 73911 73912 73913 73914 73915 73916 73917 73918 73919 73920 73921 73922 73923 73924 73925 73926 73927 73928 73929 73930 73931 73932 73933 73934 73935 73936 73937 73938 73939 73940 73941 73942 73943 73944 73945 73946 73947 73948 73949 73950 73951 73952 73953 73954 73955 73956 73957 73958 73959 73960 73961 73962 73963 73964 73965 73966 73967 73968 73969 73970 73971 73972 73973 73974 73975 73976 73977 73978 73979 73980 73981 73982 73983 73984 73985 73986 73987 73988 73989 73990 73991 73992 73993 73994 73995 73996 73997 73998 73999 74000 74001 74002 74003 74004 74005 74006 74007 74008 74009 74010 74011 74012 74013 74014 74015 74016 74017 74018 74019 74020 74021 74022 74023 74024 74025 74026 74027 74028 74029 74030 74031 74032 74033 74034 74035 74036 74037 74038 74039 74040 74041 74042 74043 74044 74045 74046 74047 74048 74049 74050 74051 74052 74053 74054 74055 74056 74057 74058 74059 74060 74061 74062 74063 74064 74065 74066 74067 74068 74069 74070 74071 74072 74073 74074 74075 74076 74077 74078 74079 74080 74081 74082 74083 74084 74085 74086 74087 74088 74089 74090 74091 74092 74093 74094 74095 74096 74097 74098 74099 74100 74101 74102 74103 74104 74105 74106 74107 74108 74109 74110 74111 74112 74113 74114 74115 74116 74117 74118 74119 74120 74121 74122 74123 74124 74125 74126 74127 74128 74129 74130 74131 74132 74133 74134 74135 74136 74137 74138 74139 74140 74141 74142 74143 74144 74145 74146 74147 74148 74149 74150 74151 74152 74153 74154 74155 74156 74157 74158 74159 74160 74161 74162 74163 74164 74165 74166 74167 74168 74169 74170 74171 74172 74173 74174 74175 74176 74177 74178 74179 74180 74181 74182 74183 74184 74185 74186 74187 74188 74189 74190 74191 74192 74193 74194 74195 74196 74197 74198 74199 74200 74201 74202 74203 74204 74205 74206 74207 74208 74209 74210 74211 74212 74213 74214 74215 74216 74217 74218 74219 74220 74221 74222 74223 74224 74225 74226 74227 74228 74229 74230 74231 74232 74233 74234 74235 74236 74237 74238 74239 74240 74241 74242 74243 74244 74245 74246 74247 74248 74249 74250 74251 74252 74253 74254 74255 74256 74257 74258 74259 74260 74261 74262 74263 74264 74265 74266 74267 74268 74269 74270 74271 74272 74273 74274 74275 74276 74277 74278 74279 74280 74281 74282 74283 74284 74285 74286 74287 74288 74289 74290 74291 74292 74293 74294 74295 74296 74297 74298 74299 74300 74301 74302 74303 74304 74305 74306 74307 74308 74309 74310 74311 74312 74313 74314 74315 74316 74317 74318 74319 74320 74321 74322 74323 74324 74325 74326 74327 74328 74329 74330 74331 74332 74333 74334 74335 74336 74337 74338 74339 74340 74341 74342 74343 74344 74345 74346 74347 74348 74349 74350 74351 74352 74353 74354 74355 74356 74357 74358 74359 74360 74361 74362 74363 74364 74365 74366 74367 74368 74369 74370 74371 74372 74373 74374 74375 74376 74377 74378 74379 74380 74381 74382 74383 74384 74385 74386 74387 74388 74389 74390 74391 74392 74393 74394 74395 74396 74397 74398 74399 74400 74401 74402 74403 74404 74405 74406 74407 74408 74409 74410 74411 74412 74413 74414 74415 74416 74417 74418 74419 74420 74421 74422 74423 74424 74425 74426 74427 74428 74429 74430 74431 74432 74433 74434 74435 74436 74437 74438 74439 74440 74441 74442 74443 74444 74445 74446 74447 74448 74449 74450 74451 74452 74453 74454 74455 74456 74457 74458 74459 74460 74461 74462 74463 74464 74465 74466 74467 74468 74469 74470 74471 74472 74473 74474 74475 74476 74477 74478 74479 74480 74481 74482 74483 74484 74485 74486 74487 74488 74489 74490 74491 74492 74493 74494 74495 74496 74497 74498 74499 74500 74501 74502 74503 74504 74505 74506 74507 74508 74509 74510 74511 74512 74513 74514 74515 74516 74517 74518 74519 74520 74521 74522 74523 74524 74525 74526 74527 74528 74529 74530 74531 74532 74533 74534 74535 74536 74537 74538 74539 74540 74541 74542 74543 74544 74545 74546 74547 74548 74549 74550 74551 74552 74553 74554 74555 74556 74557 74558 74559 74560 74561 74562 74563 74564 74565 74566 74567 74568 74569 74570 74571 74572 74573 74574 74575 74576 74577 74578 74579 74580 74581 74582 74583 74584 74585 74586 74587 74588 74589 74590 74591 74592 74593 74594 74595 74596 74597 74598 74599 74600 74601 74602 74603 74604 74605 74606 74607 74608 74609 74610 74611 74612 74613 74614 74615 74616 74617 74618 74619 74620 74621 74622 74623 74624 74625 74626 74627 74628 74629 74630 74631 74632 74633 74634 74635 74636 74637 74638 74639 74640 74641 74642 74643 74644 74645 74646 74647 74648 74649 74650 74651 74652 74653 74654 74655 74656 74657 74658 74659 74660 74661 74662 74663 74664 74665 74666 74667 74668 74669 74670 74671 74672 74673 74674 74675 74676 74677 74678 74679 74680 74681 74682 74683 74684 74685 74686 74687 74688 74689 74690 74691 74692 74693 74694 74695 74696 74697 74698 74699 74700 74701 74702 74703 74704 74705 74706 74707 74708 74709 74710 74711 74712 74713 74714 74715 74716 74717 74718 74719 74720 74721 74722 74723 74724 74725 74726 74727 74728 74729 74730 74731 74732 74733 74734 74735 74736 74737 74738 74739 74740 74741 74742 74743 74744 74745 74746 74747 74748 74749 74750 74751 74752 74753 74754 74755 74756 74757 74758 74759 74760 74761 74762 74763 74764 74765 74766 74767 74768 74769 74770 74771 74772 74773 74774 74775 74776 74777 74778 74779 74780 74781 74782 74783 74784 74785 74786 74787 74788 74789 74790 74791 74792 74793 74794 74795 74796 74797 74798 74799 74800 74801 74802 74803 74804 74805 74806 74807 74808 74809 74810 74811 74812 74813 74814 74815 74816 74817 74818 74819 74820 74821 74822 74823 74824 74825 74826 74827 74828 74829 74830 74831 74832 74833 74834 74835 74836 74837 74838 74839 74840 74841 74842 74843 74844 74845 74846 74847 74848 74849 74850 74851 74852 74853 74854 74855 74856 74857 74858 74859 74860 74861 74862 74863 74864 74865 74866 74867 74868 74869 74870 74871 74872 74873 74874 74875 74876 74877 74878 74879 74880 74881 74882 74883 74884 74885 74886 74887 74888 74889 74890 74891 74892 74893 74894 74895 74896 74897 74898 74899 74900 74901 74902 74903 74904 74905 74906 74907 74908 74909 74910 74911 74912 74913 74914 74915 74916 74917 74918 74919 74920 74921 74922 74923 74924 74925 74926 74927 74928 74929 74930 74931 74932 74933 74934 74935 74936 74937 74938 74939 74940 74941 74942 74943 74944 74945 74946 74947 74948 74949 74950 74951 74952 74953 74954 74955 74956 74957 74958 74959 74960 74961 74962 74963 74964 74965 74966 74967 74968 74969 74970 74971 74972 74973 74974 74975 74976 74977 74978 74979 74980 74981 74982 74983 74984 74985 74986 74987 74988 74989 74990 74991 74992 74993 74994 74995 74996 74997 74998 74999 75000 75001 75002 75003 75004 75005 75006 75007 75008 75009 75010 75011 75012 75013 75014 75015 75016 75017 75018 75019 75020 75021 75022 75023 75024 75025 75026 75027 75028 75029 75030 75031 75032 75033 75034 75035 75036 75037 75038 75039 75040 75041 75042 75043 75044 75045 75046 75047 75048 75049 75050 75051 75052 75053 75054 75055 75056 75057 75058 75059 75060 75061 75062 75063 75064 75065 75066 75067 75068 75069 75070 75071 75072 75073 75074 75075 75076 75077 75078 75079 75080 75081 75082 75083 75084 75085 75086 75087 75088 75089 75090 75091 75092 75093 75094 75095 75096 75097 75098 75099 75100 75101 75102 75103 75104 75105 75106 75107 75108 75109 75110 75111 75112 75113 75114 75115 75116 75117 75118 75119 75120 75121 75122 75123 75124 75125 75126 75127 75128 75129 75130 75131 75132 75133 75134 75135 75136 75137 75138 75139 75140 75141 75142 75143 75144 75145 75146 75147 75148 75149 75150 75151 75152 75153 75154 75155 75156 75157 75158 75159 75160 75161 75162 75163 75164 75165 75166 75167 75168 75169 75170 75171 75172 75173 75174 75175 75176 75177 75178 75179 75180 75181 75182 75183 75184 75185 75186 75187 75188 75189 75190 75191 75192 75193 75194 75195 75196 75197 75198 75199 75200 75201 75202 75203 75204 75205 75206 75207 75208 75209 75210 75211 75212 75213 75214 75215 75216 75217 75218 75219 75220 75221 75222 75223 75224 75225 75226 75227 75228 75229 75230 75231 75232 75233 75234 75235 75236 75237 75238 75239 75240 75241 75242 75243 75244 75245 75246 75247 75248 75249 75250 75251 75252 75253 75254 75255 75256 75257 75258 75259 75260 75261 75262 75263 75264 75265 75266 75267 75268 75269 75270 75271 75272 75273 75274 75275 75276 75277 75278 75279 75280 75281 75282 75283 75284 75285 75286 75287 75288 75289 75290 75291 75292 75293 75294 75295 75296 75297 75298 75299 75300 75301 75302 75303 75304 75305 75306 75307 75308 75309 75310 75311 75312 75313 75314 75315 75316 75317 75318 75319 75320 75321 75322 75323 75324 75325 75326 75327 75328 75329 75330 75331 75332 75333 75334 75335 75336 75337 75338 75339 75340 75341 75342 75343 75344 75345 75346 75347 75348 75349 75350 75351 75352 75353 75354 75355 75356 75357 75358 75359 75360 75361 75362 75363 75364 75365 75366 75367 75368 75369 75370 75371 75372 75373 75374 75375 75376 75377 75378 75379 75380 75381 75382 75383 75384 75385 75386 75387 75388 75389 75390 75391 75392 75393 75394 75395 75396 75397 75398 75399 75400 75401 75402 75403 75404 75405 75406 75407 75408 75409 75410 75411 75412 75413 75414 75415 75416 75417 75418 75419 75420 75421 75422 75423 75424 75425 75426 75427 75428 75429 75430 75431 75432 75433 75434 75435 75436 75437 75438 75439 75440 75441 75442 75443 75444 75445 75446 75447 75448 75449 75450 75451 75452 75453 75454 75455 75456 75457 75458 75459 75460 75461 75462 75463 75464 75465 75466 75467 75468 75469 75470 75471 75472 75473 75474 75475 75476 75477 75478 75479 75480 75481 75482 75483 75484 75485 75486 75487 75488 75489 75490 75491 75492 75493 75494 75495 75496 75497 75498 75499 75500 75501 75502 75503 75504 75505 75506 75507 75508 75509 75510 75511 75512 75513 75514 75515 75516 75517 75518 75519 75520 75521 75522 75523 75524 75525 75526 75527 75528 75529 75530 75531 75532 75533 75534 75535 75536 75537 75538 75539 75540 75541 75542 75543 75544 75545 75546 75547 75548 75549 75550 75551 75552 75553 75554 75555 75556 75557 75558 75559 75560 75561 75562 75563 75564 75565 75566 75567 75568 75569 75570 75571 75572 75573 75574 75575 75576 75577 75578 75579 75580 75581 75582 75583 75584 75585 75586 75587 75588 75589 75590 75591 75592 75593 75594 75595 75596 75597 75598 75599 75600 75601 75602 75603 75604 75605 75606 75607 75608 75609 75610 75611 75612 75613 75614 75615 75616 75617 75618 75619 75620 75621 75622 75623 75624 75625 75626 75627 75628 75629 75630 75631 75632 75633 75634 75635 75636 75637 75638 75639 75640 75641 75642 75643 75644 75645 75646 75647 75648 75649 75650 75651 75652 75653 75654 75655 75656 75657 75658 75659 75660 75661 75662 75663 75664 75665 75666 75667 75668 75669 75670 75671 75672 75673 75674 75675 75676 75677 75678 75679 75680 75681 75682 75683 75684 75685 75686 75687 75688 75689 75690 75691 75692 75693 75694 75695 75696 75697 75698 75699 75700 75701 75702 75703 75704 75705 75706 75707 75708 75709 75710 75711 75712 75713 75714 75715 75716 75717 75718 75719 75720 75721 75722 75723 75724 75725 75726 75727 75728 75729 75730 75731 75732 75733 75734 75735 75736 75737 75738 75739 75740 75741 75742 75743 75744 75745 75746 75747 75748 75749 75750 75751 75752 75753 75754 75755 75756 75757 75758 75759 75760 75761 75762 75763 75764 75765 75766 75767 75768 75769 75770 75771 75772 75773 75774 75775 75776 75777 75778 75779 75780 75781 75782 75783 75784 75785 75786 75787 75788 75789 75790 75791 75792 75793 75794 75795 75796 75797 75798 75799 75800 75801 75802 75803 75804 75805 75806 75807 75808 75809 75810 75811 75812 75813 75814 75815 75816 75817 75818 75819 75820 75821 75822 75823 75824 75825 75826 75827 75828 75829 75830 75831 75832 75833 75834 75835 75836 75837 75838 75839 75840 75841 75842 75843 75844 75845 75846 75847 75848 75849 75850 75851 75852 75853 75854 75855 75856 75857 75858 75859 75860 75861 75862 75863 75864 75865 75866 75867 75868 75869 75870 75871 75872 75873 75874 75875 75876 75877 75878 75879 75880 75881 75882 75883 75884 75885 75886 75887 75888 75889 75890 75891 75892 75893 75894 75895 75896 75897 75898 75899 75900 75901 75902 75903 75904 75905 75906 75907 75908 75909 75910 75911 75912 75913 75914 75915 75916 75917 75918 75919 75920 75921 75922 75923 75924 75925 75926 75927 75928 75929 75930 75931 75932 75933 75934 75935 75936 75937 75938 75939 75940 75941 75942 75943 75944 75945 75946 75947 75948 75949 75950 75951 75952 75953 75954 75955 75956 75957 75958 75959 75960 75961 75962 75963 75964 75965 75966 75967 75968 75969 75970 75971 75972 75973 75974 75975 75976 75977 75978 75979 75980 75981 75982 75983 75984 75985 75986 75987 75988 75989 75990 75991 75992 75993 75994 75995 75996 75997 75998 75999 76000 76001 76002 76003 76004 76005 76006 76007 76008 76009 76010 76011 76012 76013 76014 76015 76016 76017 76018 76019 76020 76021 76022 76023 76024 76025 76026 76027 76028 76029 76030 76031 76032 76033 76034 76035 76036 76037 76038 76039 76040 76041 76042 76043 76044 76045 76046 76047 76048 76049 76050 76051 76052 76053 76054 76055 76056 76057 76058 76059 76060 76061 76062 76063 76064 76065 76066 76067 76068 76069 76070 76071 76072 76073 76074 76075 76076 76077 76078 76079 76080 76081 76082 76083 76084 76085 76086 76087 76088 76089 76090 76091 76092 76093 76094 76095 76096 76097 76098 76099 76100 76101 76102 76103 76104 76105 76106 76107 76108 76109 76110 76111 76112 76113 76114 76115 76116 76117 76118 76119 76120 76121 76122 76123 76124 76125 76126 76127 76128 76129 76130 76131 76132 76133 76134 76135 76136 76137 76138 76139 76140 76141 76142 76143 76144 76145 76146 76147 76148 76149 76150 76151 76152 76153 76154 76155 76156 76157 76158 76159 76160 76161 76162 76163 76164 76165 76166 76167 76168 76169 76170 76171 76172 76173 76174 76175 76176 76177 76178 76179 76180 76181 76182 76183 76184 76185 76186 76187 76188 76189 76190 76191 76192 76193 76194 76195 76196 76197 76198 76199 76200 76201 76202 76203 76204 76205 76206 76207 76208 76209 76210 76211 76212 76213 76214 76215 76216 76217 76218 76219 76220 76221 76222 76223 76224 76225 76226 76227 76228 76229 76230 76231 76232 76233 76234 76235 76236 76237 76238 76239 76240 76241 76242 76243 76244 76245 76246 76247 76248 76249 76250 76251 76252 76253 76254 76255 76256 76257 76258 76259 76260 76261 76262 76263 76264 76265 76266 76267 76268 76269 76270 76271 76272 76273 76274 76275 76276 76277 76278 76279 76280 76281 76282 76283 76284 76285 76286 76287 76288 76289 76290 76291 76292 76293 76294 76295 76296 76297 76298 76299 76300 76301 76302 76303 76304 76305 76306 76307 76308 76309 76310 76311 76312 76313 76314 76315 76316 76317 76318 76319 76320 76321 76322 76323 76324 76325 76326 76327 76328 76329 76330 76331 76332 76333 76334 76335 76336 76337 76338 76339 76340 76341 76342 76343 76344 76345 76346 76347 76348 76349 76350 76351 76352 76353 76354 76355 76356 76357 76358 76359 76360 76361 76362 76363 76364 76365 76366 76367 76368 76369 76370 76371 76372 76373 76374 76375 76376 76377 76378 76379 76380 76381 76382 76383 76384 76385 76386 76387 76388 76389 76390 76391 76392 76393 76394 76395 76396 76397 76398 76399 76400 76401 76402 76403 76404 76405 76406 76407 76408 76409 76410 76411 76412 76413 76414 76415 76416 76417 76418 76419 76420 76421 76422 76423 76424 76425 76426 76427 76428 76429 76430 76431 76432 76433 76434 76435 76436 76437 76438 76439 76440 76441 76442 76443 76444 76445 76446 76447 76448 76449 76450 76451 76452 76453 76454 76455 76456 76457 76458 76459 76460 76461 76462 76463 76464 76465 76466 76467 76468 76469 76470 76471 76472 76473 76474 76475 76476 76477 76478 76479 76480 76481 76482 76483 76484 76485 76486 76487 76488 76489 76490 76491 76492 76493 76494 76495 76496 76497 76498 76499 76500 76501 76502 76503 76504 76505 76506 76507 76508 76509 76510 76511 76512 76513 76514 76515 76516 76517 76518 76519 76520 76521 76522 76523 76524 76525 76526 76527 76528 76529 76530 76531 76532 76533 76534 76535 76536 76537 76538 76539 76540 76541 76542 76543 76544 76545 76546 76547 76548 76549 76550 76551 76552 76553 76554 76555 76556 76557 76558 76559 76560 76561 76562 76563 76564 76565 76566 76567 76568 76569 76570 76571 76572 76573 76574 76575 76576 76577 76578 76579 76580 76581 76582 76583 76584 76585 76586 76587 76588 76589 76590 76591 76592 76593 76594 76595 76596 76597 76598 76599 76600 76601 76602 76603 76604 76605 76606 76607 76608 76609 76610 76611 76612 76613 76614 76615 76616 76617 76618 76619 76620 76621 76622 76623 76624 76625 76626 76627 76628 76629 76630 76631 76632 76633 76634 76635 76636 76637 76638 76639 76640 76641 76642 76643 76644 76645 76646 76647 76648 76649 76650 76651 76652 76653 76654 76655 76656 76657 76658 76659 76660 76661 76662 76663 76664 76665 76666 76667 76668 76669 76670 76671 76672 76673 76674 76675 76676 76677 76678 76679 76680 76681 76682 76683 76684 76685 76686 76687 76688 76689 76690 76691 76692 76693 76694 76695 76696 76697 76698 76699 76700 76701 76702 76703 76704 76705 76706 76707 76708 76709 76710 76711 76712 76713 76714 76715 76716 76717 76718 76719 76720 76721 76722 76723 76724 76725 76726 76727 76728 76729 76730 76731 76732 76733 76734 76735 76736 76737 76738 76739 76740 76741 76742 76743 76744 76745 76746 76747 76748 76749 76750 76751 76752 76753 76754 76755 76756 76757 76758 76759 76760 76761 76762 76763 76764 76765 76766 76767 76768 76769 76770 76771 76772 76773 76774 76775 76776 76777 76778 76779 76780 76781 76782 76783 76784 76785 76786 76787 76788 76789 76790 76791 76792 76793 76794 76795 76796 76797 76798 76799 76800 76801 76802 76803 76804 76805 76806 76807 76808 76809 76810 76811 76812 76813 76814 76815 76816 76817 76818 76819 76820 76821 76822 76823 76824 76825 76826 76827 76828 76829 76830 76831 76832 76833 76834 76835 76836 76837 76838 76839 76840 76841 76842 76843 76844 76845 76846 76847 76848 76849 76850 76851 76852 76853 76854 76855 76856 76857 76858 76859 76860 76861 76862 76863 76864 76865 76866 76867 76868 76869 76870 76871 76872 76873 76874 76875 76876 76877 76878 76879 76880 76881 76882 76883 76884 76885 76886 76887 76888 76889 76890 76891 76892 76893 76894 76895 76896 76897 76898 76899 76900 76901 76902 76903 76904 76905 76906 76907 76908 76909 76910 76911 76912 76913 76914 76915 76916 76917 76918 76919 76920 76921 76922 76923 76924 76925 76926 76927 76928 76929 76930 76931 76932 76933 76934 76935 76936 76937 76938 76939 76940 76941 76942 76943
.\" t '\" vim:set syntax=groff:
.\" Copyright (C) 2009-2021 Kaz Kylheku <kaz@kylheku.com>.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice, this
.\"    list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright notice,
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" Useful groff definitions.
.\"
.\" Some constants that depend on troff/nroff mode:
.ie n \{\
.ds vspc 1
.\}
.el \{\
.ds vspc 0.5
.\}
.\" Mount numeric fonts when not running under man2html
.if !\n(M2 \{\
. fp 4 CR
. fp 5 CI
.\}
.\" Base font
.nr fsav 1
.\" start of code block: switch to monospace font and no format
.de verb
.  ft 4
.  nf
..
.\" end of code block: restore font and formatting
.de brev
.  fi
.  ft 1
..
.\" switch to mono font
.de mono
.  ft 4
..
.\" switch back from mon font
.de onom
.  ft 1
..
.\" typeset argument in monospace
.\" .code x  ->  \f[CR]x\f[]
.de code
\f[4]\\$1\f[]
..
.\" like .code typesets meta-syntax
.\" which is done in angle brackets + italic in nroff or oblique
.\" courier in PDF/HTML.
.de meta
.  ie n \{\
\fI<\\$1>\fP
.  \}
.  el \{\
\f[5]\\$1\f[]
.  \}
..
.\" like .meta but tack on second argument with no space.
.de metn
.  ie n \{\
\fI<\\$1>\fP\\$2
.  \}
.  el \{\
\f[5]\\$1\f[]\\$2
.  \}
..
.\" like .code but wraps in quotes
.\" .str x y z ->  \f[CR]"x y z"\f[].
.de str
\f[4]"\\$*"\f[]
..
.\" wrap first argument in quotes, tack no second one with no space
.\" .strn x y ->  \f[CR]"x"\f[]y.
.de strn
\f[4]"\\$1"\f[]\\$2
..
.\" like .IP but use monospace too
.de coIP
.  IP "\\f[4]\\$*\\f[]"
..
.\" Directive heading
.de dir
.  NP* The \f[4]\\$1\f[] directive
..
.\" Multiple directive heading
.de dirs
.  ds s "
.  while (\\n[.$]>2) \{\
.    as s \f[4]\\$1\f[], 
.    shift
.  \}
.  if (\\n[.$]>1) \{\
.    as s \f[4]\\$1\f[] 
.    shift
.  \}
.  if (\\n[.$]>0) \{\
.    as s and \f[4]\\$1\f[]
.  \}
.  NP* The \\*s directives
..
.\" heading with code in position 1
.de c1NP
.  ds s \\f[4]\\$1\\f[]
.  shift
.  as s " \\$*
.  NP* \\*s
..
.\" utility macro for gathering material into "s" string.
.\" a pair of arguments "@ arg" becomes arg set in code
.\" a pair of arguments "@, arg" becomes "arg," where
.\" arg is set in code, followed by comma not in code.
.de gets
.  ds s "
.  while (\\n[.$]>0) \{\
.    ie "\\$1"@" \{\
.      shift
.      as s \f[4]\\$1\f[] 
.      shift
.    \}
.    el \{\
.      ie "\\$1"@," \{\
.        shift
.        as s \f[4]\\$1\f[], 
.        shift
.      \}
.      el \{\
.        as s \\$1 
.        shift
.      \}
.    \}
.  \}
..
.\" a macro for gathering material into "s"
.\" a pair of arguments "< arg" is typeset like
.\" .meta arg. "<< arg arg" is like .metn arg arg.
.ie n \{\
.  de getm
.    ds s "
.    while (\\n[.$]>0) \{\
.      ie "\\$1"<" \{\
.        shift
.        as s \fI<\\$1>\fP 
.        shift
.      \}
.      el \{\
.        ie "\\$1"<<" \{\
.          shift
.          as s \fI<\\$1>\fP\\$2 
.          shift
.          shift
.        \}
.        el \{\
.          ie "\\$1">>" \{\
.            shift
.            as s \\$1\fI<\\$2>\fP 
.            shift
.            shift
.          \}
.          el \{\
.            ie "\\$1"<>" \{\
.              shift
.              as s \\$1\fI<\\$2>\fP\\$3 
.              shift
.              shift
.              shift
.            \}
.            el \{\
.              ie "\\$1"><" \{\
.                shift
.                as s \fI<\\$1>\fP\\$2\fI<\\$3>\fP 
.                shift
.                shift
.                shift
.              \}
.              el \{\
.                as s \\$1 
.                shift
.              \}
.            \}
.          \}
.        \}
.      \}
.    \}
.  .
.\}
.el \{\
.  de getm
.    ds s "
.    while (\\n[.$]>0) \{\
.      ie "\\$1"<" \{\
.        shift
.        as s \\f5\\$1\\f4 
.        shift
.      \}
.      el \{\
.        ie "\\$1"<<" \{\
.          shift
.          as s \\f5\\$1\\f4\\$2 
.          shift
.          shift
.        \}
.        el \{\
.          ie "\\$1">>" \{\
.            shift
.            as s \\$1\\f5\\$2\\f4 
.            shift
.            shift
.          \}
.          el \{\
.            ie "\\$1"<>" \{\
.              shift
.              as s \\$1\\f5\\$2\\f4\\$3 
.              shift
.              shift
.              shift
.            \}
.            el \{\
.              ie "\\$1"><" \{\
.                shift
.                as s \\f5\\$1\\f4\\$2\f5\\$3\\f4 
.                shift
.                shift
.                shift
.              \}
.              el \{\
.                as s \\$1 
.                shift
.              \}
.            \}
.          \}
.        \}
.      \}
.    \}
.  .
.\}
.\" typeset left argument in monospace, then right one
.\" in previous font, with no space between.
.\" .codn x y \f[CR]x\f[]y
.de codn
\f[4]\\$1\f[]\\$2
..
.\" .cod1 a b c ->  abc  where a is typeset as code
.de cod1
\&\\$1\f[4]\\$2\f[]\$3
..
.\" .cod2 a b ->  ab  where b is typeset as code
.de cod2
\&\\$1\f[4]\\$2\f[]
..
.\" .cod3 a b c ->  abc  where a and c are typeset as code
.de cod3
\f[4]\\$1\f[]\\$2\f[4]\\$3\f[]
..
.\" Syntax section markup
.de synb
.  TP* Syntax:
.  mono
..
.de syne
.  onom
..
.\" Used for meta-variables in syntax blocks
.de mets
.  nr fsav \\n[.f]
.  getm \\$*
.  \"workaround for man2html:
.  as s \\f\\n[fsav]
  \\*s
.  ft \\n[fsav]
..
.\" Used for meta-variables in inline blocks
.de meti
.  nr fsav \\n[.f]
.  getm \\$*
.  \"workaround for man2html:
.  as s \\f\\n[fsav]
\&\\*s
.  ft \\n[fsav]
..
.\" Used for meta-variables in .coIP
.de meIP
.  nr fsav \\n[.f]
.  getm \\$*
.  \"workaround for man2html:
.  as s \\f\\n[fsav]
.coIP \\*s
.  ft \\n[fsav]
..
.\" Description section
.de desc
.  TP* Description:
..
.\" Section counters: heading, section, paragraph.
.nr shco 0 1
.nr ssco 0 1
.nr spco 0 1
.\" wrapper for .SH
.de SH*
.  SH \\n+[shco] \\$*
.  rs
.  nr ssco 0
.  nr spco 0
.  sp \*[vspc]
.  ns
..
.\" wrapper for .SS
.de SS*
.  SS \\n[shco].\\n+[ssco] \\$*
.  rs
.  nr spco 0
.  sp \*[vspc]
.  ns
..
.\" wrapper for .TP
.de TP*
.  ds s \\$1
.  shift
.  TP \\$*
\&\\*s
.  sp \*[vspc]
.  ns
..
.\" numbered paragraph
.de NP*
.  ie \n(M2 \{\
.  M2SS 2 h4 "\\n[shco].\\n[ssco].\\n+[spco] \\$*"
.  \}
.  el \{\
.  TP* "\f[B]\\n[shco].\\n[ssco].\\n+[spco] \\$*\f[]"
.  \}
.  PP
..
.\" process arguments using .gets so that some material
.\" is typeset as code. Then pass to .SS* section macro.
.de coSS
.  gets \\$*
.  SS* \\*s
..
.\" like coSS but targeting NP*
.de coNP
.  gets \\$*
.  NP* \\*s
..
.\" like coSS but use monospace IP
.de ccIP
.  gets \\$*
.  IP "\\*s"
..
.\" TXR name
.ds TX \f[B]TXR\f[]
.ds TL \f[B]TXR Lisp\f[]
.\" Start of man page:
.TH TXR 1 2020-12-31 "Utility Commands" "TXR Programming Language" "Kaz Kylheku"
.SH* NAME
\*(TX \- Programming Language (Version 246)

.SH* SYNOPSIS
.mono
.meti txr [ < options ] [ < script-file [ < data-files ... ]]
.onom

.SH* DESCRIPTION
\*(TX is a general-purpose, multi-paradigm programming language.
It comprises two languages integrated into a single tool: a text
scanning and extraction language referred to as the \*(TX Pattern Language
(sometimes just "TXR"), and a general-purpose dialect of Lisp called \*(TL.

\*(TX can be used for everything from "one liner" data transformation tasks at
the command line, to data scanning and extracting scripts, to full
application development in a wide-range of areas.

A script written in the \*(TX Pattern Language, also referred to in this
document as a
.IR query ,
specifies a pattern which matches one or more sources of inputs, such
as text files. Patterns can consist of large chunks of multi-line free-form
text, which is matched literally against material in the input sources. Free
variables occurring in the pattern (denoted by the
.code @
symbol) are bound to the pieces of text occurring in the
corresponding positions.  Patterns can be arbitrarily complex,
and can be broken down into named pattern functions, which may be mutually
recursive.

In addition to embedded variables which implicitly match text, the
\*(TX pattern language supports a number of directives, for matching text using
regular expressions, for continuing a match in another file, for searching
through a file for the place where an entire sub-query matches, for collecting
lists, and for combining sub-queries using logical conjunction, disjunction and
negation, and numerous others.

Patterns can contain actions which transform data and generate output.
These actions can be embedded anywhere within the pattern matching logic.
A common structure for small \*(TX scripts is to perform a complete matching
session in the at the top of the script, and then deal with processing
and reporting at the bottom.

The \*(TL language can be used from within \*(TX scripts as an
embedded language, or completely stand-alone.  It supports functional,
imperative and object-oriented programming, and provides numerous data types
such as symbols, strings, vectors, hash tables with weak reference support,
lazy lists, and arbitrary-precision ("bignum") integers.  It has expressive
foreign function interface (FFI) for calling into libraries and other software
components that support C-language-style calls. 

\*(TL source files as well as individual functions can be optionally compiled
for execution on a virtual machine that is built into \*(TX.  Compiled files
execute and load faster, and resist reverse-engineering.  Stand-alone
application delivery is possible.

\*(TX is free software offered under the two-clause BSD license which
places almost no restrictions on redistribution, and allows every conceivable
use, of the whole software or any constituent part, royalty-free, free of
charge, and free of any restrictions.

.SH* ARGUMENTS AND OPTIONS

If \*(TX is given no arguments, it will enter into an interactive
mode. See the INTERACTIVE LISTENER section for a
description of this mode.  When \*(TX enters interactive mode this
way, it prints a one-line banner is printed announcing the program
name and version, and one line of help text instructing the user
how to exit.

Options which don't take an argument may be combined together.
The
.code -v
and
.code -q
options are mutually exclusive. Of these two, the one which
occurs in the rightmost position in the argument list dominates.
The
.code -c
and
.code -f
options are also mutually exclusive; if both are specified,
it is a fatal error.

.meIP >> -D var=value
Bind the variable
.meta var
to the value
.meta value
prior to processing the query. The name is in scope over the entire
query, so that all occurrence of the variable are substituted and
match the equivalent text.  If the value contains commas, these
are interpreted as separators, which give rise to a list value.
For instance
.code -Da,b,c
creates a list of the strings
.strn "a" ,
.str "b"
and
.strn "c" .
(See Collect Directive bellow). List variables provide a multiple
match. That is to say, if a list variable occurs in a query, a successful
match occurs if any of its values matches the text. If more than one
value matches the text, the first one is taken.

.meIP >> -D var
Binds the variable
.meta var
to an empty string value prior to processing the query.

.coIP -q
Quiet operation during matching. Certain error messages are not reported on the
standard error device (but the if the situations occur, they still fail the
query). This option does not suppress error generation during the parsing
of the query, only during its execution.

.coIP -i
If this option is present, then \*(TX will enter into an interactive
interpretation mode after processing all options, and the input query
if one is present. See the INTERACTIVE LISTENER section for a
description of this mode.

.coIP -d
.coIP --debugger
Invoke the interactive \*(TX debugger. See the DEBUGGER section.
Implies
.codn --backtrace .

.coIP --backtrace
Turns on the establishment of backtrace frames for function calls so that a
backtrace can be produced when an unhandled exception occurs, and in other
situations. Backtraces are helpful in identifying the causes of errors, but
require extra stack space and slow down execution.

.coIP -n
.coIP --noninteractive
This option affects behavior related to \*(TX's
.code *stdin*
stream.  It also has a another, unrelated effect, on the
behavior of the interactive listener; see below.

Normally, if this stream is connected to a terminal device, it is
automatically marked as having the real-time property when \*(TX starts up (see
the functions
.code stream-set-prop
and
.codn real-time-stream-p ).
The
.code -n
option suppresses this behavior; the
.code *stdin*
stream remains ordinary.

The \*(TX pattern language reads standard input via
a lazy list, created by applying the
.code lazy-stream-cons
function to the
.code *stdin*
stream. If that stream is marked real-time, then the lazy list which is
returned by that function has behaviors that are better suited for scanning
interactive input. A more detailed explanation is given under the description
of this function.

If the
.code -n
option is effect and \*(TX enters into the interactive listener,
the listener operates in
.IR "plain mode" .
The listener reads buffered lines
from the operating system without any character-based editing features
or history navigation. In plain mode, no prompts appear and no
terminal control escape sequences are generated. The only output is
the results of evaluation, related diagnostic messages, and any output
generated by the evaluated expressions themselves.

.coIP -v
Verbose operation. Detailed logging is enabled.

.coIP -b
This option binds a Lisp global lexical variable (as if by the
.code defparml
function) to an object described by Lisp syntax. It requires an argument
of the form
.meta sym=value
where
.code sym
must be, syntactically, a token denoting a bindable symbol, and
.meta value
is arbitrary \*(TL syntax. The
.meta sym
syntax is converted to the symbol it denotes, which is bound as a global
lexical variable, if it is not already a variable.
The
.meta value
syntax is parsed to the Lisp object it denotes. This object is not subject
to evaluation; the object itself is stored into the variable binding denoted
by
.metn sym .
Note that if
.meta sym
already exists as a global variable, then it is simply overwritten. If
.meta sym
is marked special, then it stays special.

.coIP -B
If the query is successful, print the variable bindings as a sequence
of assignments in shell syntax that can be
.IR eval -ed
by a POSIX shell.
II the query fails, print the word "false". Evaluation of this word
by the shell has the effect of producing an unsuccessful termination
status from the shell's
.I eval
command.

.coIP "-l or --lisp-bindings"
This option implies
.codn -B .
Print the variable bindings in Lisp syntax instead of
shell syntax.

.meIP -a < num
This option implies
.codn -B .
The decimal integer argument
.meta num
specifies the maximum
number of array dimensions to use for list-valued variable bindings.
The default is 1. Additional dimensions are expressed using numeric suffixes
in the generated variable names.
For instance, consider the three-dimensional list arising out of a triply
nested collect:
.mono
((("a" "b") ("c" "d")) (("e" "f") ("g" "h"))).
.onom
Suppose this is bound to a variable V.  With
.codn "-a 1" ,
this will be
reported as:

.verb
  V_0_0[0]="a"
  V_0_1[0]="b"
  V_1_0[0]="c"
  V_1_1[0]="d"
  V_0_0[1]="e"
  V_0_1[1]="f"
  V_1_0[1]="g"
  V_1_1[1]="h"
.brev

With
.codn "-a 2" ,
it comes out as:

.verb
  V_0[0][0]="a"
  V_1[0][0]="b"
  V_0[0][1]="c"
  V_1[0][1]="d"
  V_0[1][0]="e"
  V_1[1][0]="f"
  V_0[1][1]="g"
  V_1[1][1]="h"
.brev

The leftmost bracketed index is the most major index. That is to say,
the dimension order is:
.codn "NAME_m_m+1_..._n[1][2]...[m-1]" .

.meIP -c < query
Specifies the query in the form of a command line argument. If this option is
used, the
.meta script-file
argument is omitted. The first non-option argument,
if there is one, now specifies the first input source rather than a query.
Unlike queries read from a file, (non-empty) queries specified as arguments
using -c do not have to properly end in a newline. Internally,
\*(TX adds the missing newline before parsing the query. Thus
.code -c
.str @a
is a valid query which matches a line.

Example:

Shell script which uses \*(TX to read two lines
.str 1
and
.str 2
from standard input,
binding them to variables
.code a
and
.codn b .
Standard
input is specified as
.code -
and the data
comes from shell "here document" redirection:
.RS
.IP code:
.mono
\ #!/bin/sh

 txr -B -c "@a
 @b" - <<!
 1
 2
 !
.onom

.IP output:
.mono
\ a=1
 b=2
.onom
.PP

The
.code @;
comment syntax can be used for better formatting:

.verb
  txr -B -c "@;
  @a
  @b"
.brev
.RE

.meIP -f < script-file
Specifies the file from which the query is to be read, instead of the
.meta script-file
argument. This is useful in
.code #!
("hash bang") scripts. (See Hash Bang Support below).

.meIP -e < expression
Evaluates a \*(TL expression for its side effects, without printing
its value. Can be specified more than once. The
.meta script-file
argument becomes optional if
.code -e
is used at least once. If the evaluation of every
.meta expression
evaluated this way terminates normally, and there is no
.meta script-file
argument, then \*(TX terminates with a successful status.

.meIP -p < expression
Just like
.code -e
but prints the value of
.meta expression
using the
.code prinl
function.

.meIP -P < expression
Like
.code -p
but prints using the
.code pprinl
function.

.meIP -t < expression
Like
.code -p
but prints using the
.code tprint
function.

.meIP -C < number
.meIP >> --compat= number

Requests \*(TX to behave in a manner that is compatible with the specified
version of \*(TX. This makes a difference in situations when a release of
\*(TX breaks backward compatibility. If some version N+1 deliberately introduces
a change which is backward incompatible, then
.code "-C N"
can be used to request the old behavior.

The requested value of N can be too low, in which case \*(TX will
complain and exit with an unsuccessful termination status. This indicates
that \*(TX refuses to be compatible with such an old version. Users requiring
the behavior of that version will have to install an older version of \*(TX which
supports that behavior, or even that exact version.

If the option is specified more than once, the behavior is not specified.

Compatibility can also be requested via the
.code TXR_COMPAT
environment variable instead of the
.code -C
option.

For more information, see the COMPATIBILITY section.

.meIP >> --gc-delta= number

The
.meta number
argument to this option must be a decimal integer. It represents
a megabyte value, the "GC delta": one megabyte is 1048576 bytes.  The "GC
delta" controls an aspect of the garbage collector behavior.
See the
.code gc-set-delta
function for a description.

.meIP --debug-autoload
This option turns on debugging, like
.code --debugger
but also requests stepping into the auto-load processing of
\*(TL library code.  Normally, debugging through the evaluations
triggered by auto-loading is suppressed.
Implies
.codn --backtrace .

.meIP --debug-expansion
This option turns on debugging, like
.code --debugger
but also requests stepping into the parse-time macro-expansion
of \*(TL code embedded in \*(TX queries. Normally, this is suppressed.
Implies
.codn --backtrace .

.coIP --help
Prints usage summary on standard output, and terminates successfully.

.coIP --license
Prints the software license. This depends on the software being
installed such that the LICENSE file is in the data directory.
Use of \*(TX implies agreement with the liability disclaimer in the license.

.coIP --version
Prints program version standard output, and terminates successfully.

.coIP --args
The
.code --args
option provides a way to encode multiple arguments as a single
argument, which is useful on some systems which have limitations in
their implementation of the "hash bang" mechanism. For details about
its special syntax, See Hash Bang Support below. It is also useful in
stand-alone application deployment. See the section
STAND-ALONE APPLICATION SUPPORT, in which example uses of
.code --args
are shown.

.coIP --eargs
The
.code --eargs
option (extended
.codn --args )
is like
.code --args
but must be followed by an argument. The argument is removed from
the argument list and substituted in place of occurrences of
.code {}
among the arguments expanded from the
.code --eargs
syntax.

.coIP --lisp
.coIP --compiled
These options influences the treatment of query files which do not have
a suffix indicating their type. The
.code --lisp
option causes an unsuffixed file to be treated as Lisp source; and
.code --compiled
causes it to be treated as a compile file.

Moreover, if
.code --lisp
is specified, and an unsuffixed file does not exist, then \*(TX
will add the
.str .tl
suffix and try the file again; and
.code --compiled
will similarly add the
.str .tlo
suffix and try opening the file again.
In the same situation, if neither
.code --lisp
nor
.code --compiled
has been specified, \*(TX will first try adding the
.str .txr
suffix. If that fails,
then the
.str .tlo
suffix will be tried and finally
.strn .tl .
Note that
.code --lisp
and
.code --compiled
influence how the argument of the
.code -f
option is treated, but only they precedes that option.

.coIP --reexec
On platforms which support the POSIX
.code exec
family of functions, this option causes \*(TX to re-execute itself.
The re-executed image receives the remaining arguments which follow
the
.code --reexec
argument. Note: this option is useful for supporting setuid operation in
"hash hang" scripts. On some platforms, the interpreter designated by
a "hash bang" script runs without altered privilege, even if that
interpreter is installed setuid. If the interpreter is executed directly,
then setuid applies to it, but not if it is executed via "hash bang".
If the
.code --reexec
option is used in the interpreter command line of such a script, the
interpreter will re-execute itself, thereby gaining the setuid privilege.
The re-executed image will then obtain the script name from the arguments
which are passed to it and determine whether that script will run setuid.
See the section SETUID/SETGID OPERATION.

.coIP --gc-debug
This option enables a behavior which stresses the garbage collector with
frequent garbage collection requests. The purpose is to make it more likely
to reproduce certain kinds of bugs. Use of this option severely degrades
the performance of \*(TX.

.coIP --vg-debug
If \*(TX is enabled with Valgrind support, then this option is available.
It enables code which uses the Valgrind API to integrate with the Valgrind
debugger, for more accurate tracking of garbage collected objects. For
example, objects which have been reclaimed by the garbage collector
are marked as inaccessible, and marked as uninitialized when they are
allocated again.

.coIP --dv-regex
If this option is used, then regular expressions are all treated using the
derivative-based back-end.  The NFA-based regex implementation is disabled.
Normally, only regular expressions which require the intersection and
complement operators are handled using the derivative back-end.
This option makes it possible to test that back-end on test cases that it
wouldn't normally receive.

.coIP --
Signifies the end of the option list.

.coIP -
This argument is not interpreted as an option, but treated as a filename
argument. After the first such argument, no more options are recognized. Even
if another argument looks like an option, it is treated as a name.
This special argument
.code -
means "read from standard input" instead of a file.
The
.metn script-file ,
or any of the data files, may be specified using this option.
If two or more files are specified as
.codn - ,
the behavior is system-dependent.
It may be possible to indicate EOF from the interactive terminal, and
then specify more input which is interpreted as the second file, and so forth.

.PP
After the options, the remaining arguments are files. The first file argument
specifies the script file, and is mandatory if the
.code -f
option has not been specified, and \*(TX isn't operating in interactive
mode or evaluating expressions from the command line via
.code -e
or one of the related options.  A file argument consisting of a single
.code -
means to read the standard input instead of opening a file.

Specifying standard input as a source with an explicit
.code -
argument is unnecessary. If no data source arguments are present, then
\*(TX scans standard input by default. This was not true in versions of \*(TX
prior to 171; see the COMPATIBILITY section.

.PP
\*(TX begins by reading the script. In the case of the \*(TX pattern language,
the entire query is scanned, internalized and then begins executing, if it is
free of syntax errors. (\*(TL is processed differently, form by form).  On the
other hand, the pattern language reads data files in a lazy manner. A file
isn't opened until the query demands material from that file, and then the
contents are read on demand, not all at once.

The suffix of the
.meta script-file
is significant. If the name has no suffix, or if it has a
.str .txr
suffix, then it is assumed to be in the \*(TX pattern language. If it has
the
.str .tl
suffix, then it is assumed to be \*(TL.  The
.code --lisp
option changes the treatment of unsuffixed script file names, causing them
to be interpreted as \*(TL .

If an unsuffixed script file name is specified, and cannot be opened, then
\*(TX will add the
.str .txr
suffix and try again. If that fails, it will be tried with the
.str .tl
suffix, and treated as \*(TL .
If the
.code --lisp
option has been specified, then \*(TX tries only the
.str .tl
suffix.

A \*(TL file is processed as if by the
.code load
macro: forms from the file are read and evaluated. If the forms do not terminate
the \*(TX process or throw an exception, and there are no syntax errors, then
\*(TX terminates successfully after evaluating the last form. If syntax errors
are encountered in a form, then \*(TX terminates unsuccessfully.
\*(TL is documented in the section TXR LISP.

If a query file is specified, but no file arguments,
it is up to the query to open a file, pipe or standard input via the
.code @(next)
directive
prior to attempting to make a match. If a query attempts to match text,
but has run out of files to process, the match fails.

.SH* STATUS AND ERROR REPORTING
\*(TX sends errors and verbose logs to the standard error device. The following
paragraphs apply when \*(TX is run without enabling verbose mode with
.codn -v ,
or the printing of variable
bindings with
.code -B
or
.codn -a .

If the command line arguments are incorrect, \*(TX issues an error diagnostic
and terminates with a failed status.

If the
.meta script-file
specifies a query, and the query has a malformed syntax, \*(TX likewise
issues error diagnostics and terminates with a failed status.

If the query fails due to a mismatch, \*(TX terminates
with a failed status. No diagnostics are issued.

If the query is well-formed, and matches, then \*(TX issues
no diagnostics, and terminates with a successful status.

In verbose mode (option
.codn -v ),
\*(TX issues diagnostics on the standard error device even in situations which
are not erroneous.

In bindings-printing mode (options
.code -B
or
.codn -a) ,
\*(TX prints the word
.code false
if the query fails, and exits with a failed
termination status. If the query succeeds, the variable bindings, if any,
are output on standard output.

If the
.meta script-file
is \*(TL, then it is processed form by form. Each top-level Lisp form
is evaluated after it is read. If any form is syntactically malformed,
\*(TX issues diagnostics and terminates unsuccessfully.  This is somewhat
different from how the pattern language is treated: a script in the pattern
language is parsed in its entirety before being executed.

.SH* BASIC TXR SYNTAX
.SS* Comments
A query may contain comments which are delimited by the sequence
.code @;
and extend to the end of the line. Whitespace can occur between the
.code @
and
.codn ; .
A comment which begins on a line swallows that entire line, as well as the
newline which terminates it. In essence, the entire comment line disappears.
If the comment follows some material in a line, then it does not consume
the newline. Thus, the following two queries are equivalent:
.IP 1.
.mono
\ @a@; comment: match whole line against variable @a
 @; this comment disappears entirely
 @b
.onom

.IP 2.
.mono
\ @a
 @b
.onom

.PP

The comment after the
.code @a
does not consume the newline, but the
comment which follows does. Without this intuitive behavior,
line comment would give rise to empty lines that must match empty
lines in the data, leading to spurious mismatches.

Instead of the
.code ;
character, the
.code #
character can be used. This is an obsolescent feature.

.SS* Hash Bang Support
\*(TX has several features which support use of the "hash bang" convention
for creating apparently stand-alone executable programs.

.NP* Basic Hash Bang
Special processing is applied to \*(TX query or \*(TL script files that are
specified on the command line via the
.code -f
option or as the first non-option argument. If the first line of such
a file begins with the characters
.codn #! ,
that entire line is consumed and processed specially.

This removal
for \*(TX queries to be turned into standalone executable programs in the POSIX
environment using the "hash bang" mechanism.  Unlike most interpreters,
\*(TX applies special processing to the
.code #!
line, which is described below, in the section
.BR "Argument Generation with the Null Hack" .

Shell session example: create a simple executable program called
.str "twoline.txr"
and
run it. This assumes \*(TX is installed in
.codn /usr/bin .

.verb
  $ cat > hello.txr
  #!/usr/bin/txr
  @(bind a "Hey")
  @(output)
  Hello, world!
  @(end)
  $ chmod a+x hello.txr
  $ ./hello.txr
  Hello, world!
.brev

When this plain hash bang line is used, \*(TX receives the name of the script
as an argument.  Therefore, it is not possible to pass additional options
to \*(TX.  For instance, if the above script is invoked like this

.verb
  $ ./hello.txr -B
.brev

the -B option isn't processed by \*(TX, but treated as an additional argument,
just as if
.mono
.meti txr < scriptname -B
.onom
had been executed directly.

This behavior is useful if the script author wants not to expose the
\*(TX options to the user of the script.

However, the hash bang line can use the
.code -f
option:

.verb
  #!/usr/bin/txr -f
.brev

Now, the name of the script is passed as an argument to the
.code -f
option, and \*(TX will look for more options after that, so that the resulting
program appears to accept \*(TX options. Now we can run

.verb
  $ ./hello.txr -B
  Hello, world!
  a="Hey"
.brev

The
.code -B
option is honored.

.coNP Argument Generation with @ --args and @ --eargs
On some operating systems, it is not possible to pass more than one
argument through the hash bang mechanism. That is to say, this will
not work.

.verb
  #!/usr/bin/txr -B -f
.brev

To support systems like this, \*(TX supports the special argument
.codn --args ,
as well as as an extended version,
.codn --eargs .
With
.codn --args ,
it is possible to encode multiple arguments
into one argument.  The
.code --args
option must be followed by a separator
character, chosen by the programmer. The characters after that are
split into multiple arguments on the separator character. The
.code --args
option is then removed from the argument list and replaced with these
arguments, which are processed in its place.

Example:

.verb
  #!/usr/bin/txr --args:-B:-f
.brev

The above has the same behavior as

.verb
  #!/usr/bin/txr -B -f
.brev

on a system which supports multiple arguments in hash bang.
The separator character is the colon, and so the remainder
of that argument,
.codn -B:-f ,
is split into the two arguments
.codn "-B -f" .

The
.code --eargs
mechanism allows an additional flexibility. An
.code --eargs
argument must be followed by one more argument.

After
.code --eargs
performs the argument splitting in the same manner as
.codn --args ,
any of the arguments which it produces which are the
two-character sequence
.code {}
are replaced with that following argument. Whether
or not the replacement occurs, that following argument
is then removed.

Example:

.verb
  #!/usr/bin/txr --eargs:-B:{}:--foo:42
.brev

This has an effect which cannot be replicated in any known
implementation of the hash bang mechanism. Suppose
that this hash bang line is placed in a script called
.codn script.txr .
When this script is invoked with arguments, as in:

.verb
  script.txr a b c
.brev

then \*(TX is invoked similarly to:

.verb
  /usr/bin/txr --eargs:-B:{}:--foo:42 script.txr a b c
.brev

Then, when
.code --eargs
processing takes place, firstly the argument sequence

.verb
  -B {} --foo 42
.brev

is produced by splitting into four fields using the
.code :
character as the separator.  Then, within these four fields, all occurrences of
.code {}
are replaced with the following argument
.codn script.txr ,
resulting in:

.verb
  -B script.txr --foo 42
.brev

Furthermore, that
.code script.txr
argument is removed from the remaining argument list.

The four arguments are then substituted in place of the original
.code --eargs:-B:{}:--foo:42
syntax.

The resulting \*(TX invocation is, therefore:

.verb
  /usr/bin/txr -B script.txr --foo 42 a b c
.brev

Thus,
.code --eargs
allows some arguments to be encoded into the interpreter script, such that
script name is inserted anywhere among them, possibly multiple times. Arguments
for the interpreter can be encoded, as well as arguments to be processed by the
script.

.coNP Argument Generation with the Null Hack
The
.code --args
and
.code --eargs
mechanisms do not solve the following problem: the POSIX
.code env
utility is often exploited for its
.code PATH
searching capability, and used to express hash bang scripts in the following
way:

.verb
  #!/usr/bin/env txr
.brev

Here, the
.code env
utility searches for the
.code txr
program in the directories indicated by the
.code PATH
variable, which liberates the script from having encode the exact location
where the program is installed.  However, if the operating system allows only
one argument in the hash bang mechanism, then no arguments can be passed
to the program.

To mitigate this problem,
\*(TX
supports a special feature in its hash bang support. If the hash bang
.code #!
line contains a null byte, then text after the null byte, to the end of the
line, is split into fields using the space character as a separator, and these
fields are inserted into the command line. This manipulation happens during
command line processing, prior to the execution of the file, which happens
after command-line processing. If this processing is applied to a file
that is specified using the
.code -f
option, then the arguments which arise from the special processing
are inserted after that option and its argument.  If this processing is
applied to the file which is the first non-option argument, then the
options are inserted before that argument. However, care is taken not
to process that argument a second time.
In either situation, processing of the command line options continues, and the
arguments which are processed next are the ones which were just inserted.  This
is true even if the options had been inserted as a result of processing the
first non-option argument, which would ordinarily signal the termination of
option processing.

In the following examples, it is assumed that the script is
named, and invoked, as
.codn /home/jenny/foo.txr ,
and is given arguments
.codn "--bar abc" ,
and that
.code txr
resolves to
.codn /usr/bin/txr .
The
.code <NUL>
code indicates a literal ASCII NUL character, or zero bytes.

Basic example:

.verb
  #!/usr/bin/env txr<NUL>-a 3
.brev

Here,
.code env
searches for
.codn txr ,
finding it in
.codn /usr/bin .
Thus, including the executable name, \*(TX receives this full argument list:

.verb
  /usr/bin/txr /home/jenny/foo.txr --bar abc
.brev

The first non-option argument is the name of the script. \*(TX opens
the script, and notices that it begins with a hash bang line.
It consumes the hash bang line and finds the null byte inside it,
retrieving the character string after it, which is
.strn "-a 3" .
This is split into the two arguments
.code -a
and
.codn 3 ,
which are then inserted into the command line ahead of the
the script name. The effective command line then becomes:

.verb
  /usr/bin/txr -a 3 /home/jenny/foo.txr --bar abc
.brev

Command line option processing continues, beginning with the
.code -a
option. After the option is processed,
.code /home/jenny/foo.txr
is encountered again. This time it is not opened a second time;
it signals the end of option processing, exactly as it would immediately
do if it hadn't triggered the insertion of any arguments.

Advanced example: use
.code env
to invoke
.code txr
passing options to interpreter and to the script:

.verb
  #!/usr/bin/env txr<NUL>--eargs:-C:175:{}:--debug
.brev

This example shows how
.code --eargs
can be used in conjunction with the null hack. When
.code txr
begins executing, it receives the arguments

.verb
  /usr/bin/txr /home/jenny/foo.txr
.brev

The script file is opened, and the arguments delimited by the
null character in the hash bang line are inserted, resulting
in the effective command line:

.verb
  /usr/bin/txr --eargs:-C:175:{}:--debug /home/jenny/foo.txr
.brev

Next,
.code --eargs
is processed in the ordinary way, transforming the command line
into:

.verb
  /usr/bin/txr -C 175 /home/jenny/foo.txr --debug
.brev

The name of the script file is encountered, and signals the end
of option processing. Thus
.code txr
receives the
.code -C
option, instructing it to emulate some behaviors from version 175,
and the
.code /home/jenny/foo.txr
script receives
.code --debug
as
.B its
argument: it executes with the
.code *args*
list containing one element, the character string
.strn --debug .

The hash bang null hack feature was introduced in \*(TX 177.
Previous versions ignore the hash bang line, performing no special
processing. Where a risk exists that programs which depend on the
feature might be executed by an older version of \*(TX, care must
be taken to detect and handle that situation, either by means of the
.code txr-version
variable, or else by some logic which infers that the processing of the hash
bang line hadn't been performed.

.coNP Passing Options to \*(TX via Hash Bang Null Hack

It is possible to use the Hash Bang Null Hack, such that the resulting
executable program recognizes \*(TX options. This is made possible by
a special behavior in the processing of the
.code -f
option.

For instance, suppose that the effect of the following familiar hash bang line
is required:

.verb
  #!/path/to/txr -f
.brev

However, suppose there is also a requirement to use the
.code env
utility to find \*(TX. Furthermore, the operation system allows only one hash
bang argument.  Using the Null Hack, this is rewritten as:

.verb
  #!/usr/bin/env txr<NUL>-f
.brev

then if the script is invoked with arguments
.codn "-a b c" ,
the command line will ultimately be transformed into:

.verb
  /path/to/txr -f /path/to/scriptfile -i a b c
.brev

which allows \*(TX to process the
.code -i
option, leaving
.codn a ,
.code b
and
.code c
as arguments for the script.

However, note that there is a subtle issue with the
.code -f
option that has been inserted via the Null Hack: namely, this
insertion happens after
\*(TX has opened the script file and read the hash bang line from it.
This means that when the inserted
.code -f
option is being processed, the script file is already open.
A special behavior occurs. The
.code -f
option processing notices that the argument to
.code -f
is identical to the path name of name of the script file that \*(TX has
already opened for processing. The
.code -f
option and its argument are then skipped.

.NP* Hash Bang and Setuid
\*(TX supports setuid hash bang scripting, even on platforms that do not
support setuid and setgid attributes on hash bang scripts. On such
platforms, \*(TX has to be installed setuid/setgid. See the section
SETUID/SETGID OPERATION. On some platforms, it may also be necessary to
to use the
.code --reexec
option.

.SS* Whitespace
Outside of directives, whitespace is significant in \*(TX queries, and represents
a pattern match for whitespace in the input.  An extent of text consisting of
an undivided mixture of tabs and spaces is a whitespace token.  

Whitespace tokens match a precisely identical piece of whitespace in the input,
with one exception: a whitespace token consisting of precisely one space has a
special meaning. It is equivalent to the regular expression
.codn "@/[ ]+/" :
match an extent of one or more spaces (but not tabs!). Multiple consecutive
spaces do not have this meaning.

Thus, the query line
.str "a b"
(one space between
.code a
and
.codn b )
matches
.str "a b"
with any number of spaces between the two letters.

For matching a single space, the syntax
.code "@\e "
can be used (backslash-escaped space).

It is more often necessary to match multiple spaces than to exactly
match one space, so this rule simplifies many queries and adds inconvenience
to only few.

In output clauses, string and character literals and quasiliterals, a space
token denotes a space.

.SS* Text
Query material which is not escaped by the special character
.code @
is literal text, which matches input character for character. Text which occurs at
the beginning of a line matches the beginning of a line.  Text which starts in
the middle of a line, other than following a variable, must match exactly at
the current position, where the previous match left off. Moreover, if the text
is the last element in the line, its match is anchored to the end of the line.

An empty query line matches an empty line in the input. Note that an
empty input stream does not contain any lines, and therefore is not matched
by an empty line. An empty line in the input is represented by a newline
character which is either the first character of the file, or follows
a previous newline-terminated line.  

Input streams which end without terminating their last line with a newline are
tolerated, and are treated as if they had the terminator.

Text which follows a variable has special semantics, described in the
section Variables below.

A query may not leave a line of input partially matched. If any portion of a
line of input is matched, it must be entirely matched, otherwise a matching
failure results. However, a query may leave unmatched lines. Matching only
four lines of a ten line file is not a matching failure. The
.code eof
directive can be used to explicitly match the end of a file.

In the following example, the query matches the text, even though
the text has an extra line.
.IP code:
.mono
\ Four score and seven
 years ago our
.onom

.IP data:
.mono
\ Four score and seven
 years ago our
 forefathers
.onom
.PP

In the following example, the query
.B fails
to match the text, because the text has extra material on one
line that is not matched:
.IP code:
.mono
\ I can carry nearly eighty gigs
 in my head
.onom

.IP data:
.mono
\ I can carry nearly eighty gigs of data
 in my head
.onom
.PP

Needless to say, if the text has insufficient material relative
to the query, that is a failure also.

To match arbitrary material from the current position to the end
of a line, the "match any sequence of characters, including empty"
regular expression
.code @/.*/
can be used. Example:
.IP code:
.mono
\ I can carry nearly eighty gigs@/.*/
.onom

.IP data:
.mono
\ I can carry nearly eighty gigs of data
.onom
.PP

In this example, the query matches, since the regular expression
matches the string "of data". (See Regular Expressions section below).

Another way to do this is:
.IP code:
.mono
\ I can carry nearly eighty gigs@(skip)
.onom

.SS* Special Characters in Text
Control characters may be embedded directly in a query (with the exception of
newline characters). An alternative to embedding is to use escape syntax.
The following escapes are supported:

.meIP >> @\e  newline
A backslash immediately followed by a newline introduces a physical line
break without breaking up the logical line. Material following this sequence
continues to be interpreted as a continuation of the previous line, so
that indentation can be introduced to show the continuation without appearing
in the data.
.meIP >> @\e  space
A backslash followed by a space encodes a space. This is useful in line
continuations when it is necessary for some or all of the leading spaces to be
preserved.  For instance the two line sequence

.verb
  abcd@\e
    @\e  efg
.brev

is equivalent to the line

.verb
  abcd  efg
.brev

The two spaces before the
.code @\e
in the second line are consumed. The spaces after are preserved.

.coIP @\ea
Alert character (ASCII 7, BEL).
.coIP @\eb
Backspace (ASCII 8, BS).
.coIP @\et
Horizontal tab (ASCII 9, HT).
.coIP @\en
Line feed (ASCII 10, LF). Serves as abstract newline on POSIX systems.
.coIP @\ev
Vertical tab (ASCII 11, VT).
.coIP @\ef
Form feed (ASCII 12, FF). This character clears the screen on many
kinds of terminals, or ejects a page of text from a line printer.
.coIP @\er
Carriage return (ASCII 13, CR).
.coIP @\ee
Escape (ASCII 27, ESC)
.meIP @\ex < hex-digits
A
.code @\ex
immediately followed by a sequence of hex digits is interpreted as a hexadecimal
numeric character code. For instance
.code @\ex41
is the ASCII character A.  If a semicolon character immediately follows the
hex digits, it is consumed, and characters which follow are not considered
part of the hex escape even if they are hex digits.
.meIP @\e < octal-digits

A
.code @\e
immediately followed by a sequence of octal digits (0 through 7) is interpreted
as an octal character code. For instance
.code @\e010
is character 8, same as
.codn @\eb .
If a semicolon character immediately follows the octal digits, it is consumed,
and subsequent characters are not treated as part of the octal escape,
even if they are octal digits.
.PP

Note that if a newline is embedded into a query line with
.code @\en,
this does not split the line into two; it's embedded into the line and thus
cannot match anything. However,
.code @\en
may be useful in the
.code @(cat)
directive and
in
.codn @(output) .

.SS* Character Handling and International Characters

\*(TX represents text internally using wide characters, which are used to
represent Unicode code points. Script source code, as well as all data sources,
are assumed to be in the UTF-8 encoding.  In \*(TX and \*(TL source, extended
characters can be used directly in comments, literal text, string literals,
quasiliterals and regular expressions.  Extended characters can also be
expressed indirectly using hexadecimal or octal escapes.
On some platforms, wide characters may be restricted to 16 bits, so that
\*(TX can only work with characters in the BMP (Basic Multilingual Plane)
subset of Unicode.

\*(TX does not use the localization features of the system library;
its handling of extended characters is not affected by environment variables
like
.code LANG
and
.codn L_CTYPE .
The program reads and writes only the UTF-8 encoding.

If
\*(TX encounters an invalid bytes in the UTF-8 input, what happens depends on
the context in which this occurs. In a query, comments are read without regard
for encoding, so invalid encoding bytes in comments are not detected. A comment
is simply a sequence of bytes terminated by a newline.  In lexical elements
which represent text, such as string literals, invalid or unexpected encoding
bytes are treated as syntax errors. The scanner issues an error message,
then discards a byte and resumes scanning.  Certain sequences pass through the
scanner without triggering an error, namely some UTF-8 overlong sequences.
These are caught when when the lexeme is subject to UTF-8 decoding, and treated
in the same manner as other UTF-8 data, described in the following paragraph.

Invalid bytes in data are treated as follows. When an invalid byte is
encountered in the middle of a multibyte character, or if the input
ends in the middle of a multibyte character, or if a character is extracted
which is encoded as an overlong form, the UTF-8 decoder returns to the starting
byte of the ill-formed multibyte character, and extracts just that byte,
mapping it to the Unicode character range U+DC00 through U+DCFF.  The decoding
resumes afresh at the following byte, expecting that byte to be the start
of a UTF-8 code.

Furthermore, because \*(TX internally uses a null-terminated character
representation of strings which easily interoperates with C language
interfaces, when a null character is read from a stream, \*(TX converts it to
the code U+DC00. On output, this code converts back to a null byte,
as explained in the previous paragraph. By means of this representational
trick, \*(TX can handle textual data containing null bytes.

.SS* Regular Expression Directives

In place of a piece of text (see section Text above), a regular expression
directive may be used, which has the following syntax:

.verb
  @/RE/
.brev

where the RE part enclosed in slashes represents regular expression
syntax (described in the section Regular Expressions below).

Long regular expressions can be broken into multiple lines using a
backslash-newline sequence.  Whitespace before the sequence or after the
sequence is not significant, so the following two are equivalent:

.verb
  @/reg \e
    ular/

  @/regular/
.brev

There may not be whitespace between the backslash and newline.

Whereas literal text simply represents itself, regular expression denotes a
(potentially infinite) set of texts.  The regular expression directive
matches the longest piece of text (possibly empty) which belongs to the set
denoted by the regular expression. The match is anchored to the current
position; thus if the directive is the first element of a line, the match is
anchored to the start of a line. If the regular expression directive is the
last element of a line, it is anchored to the end of the line also: the regular
expression must match the text from the current position to the end of the
line.

Even if the regular expression matches the empty string, the match will fail if
the input is empty, or has run out of data. For instance suppose the third line
of the query is the regular expression
.codn @/.*/ ,
but the input is a file which has
only two lines. This will fail: the data has no line for the regular expression to
match. A line containing no characters is not the same thing as the absence of
a line, even though both abstractions imply an absence of characters.

Like text which follows a variable, a regular expression directive which
follows a variable has special semantics, described in the section Variables
below.

.SS* Variables

Much of the query syntax consists of arbitrary text, which matches file data
character for character. Embedded within the query may be variables and
directives which are introduced by a
.code @
character.  Two consecutive
.code @@
characters encode a literal
.codn @ .

A variable matching or substitution directive is written in one of several
ways:

.mono
.mets >> @ sident
.mets <> @{ bident }
.mets >> @* sident
.mets <> @*{ bident }
.mets >> @{ bident <> / regex /}
.mets >> @{ bident >> ( fun >> [ arg ... ])}
.mets >> @{ bident << number }
.onom

The forms with an
.code *
indicate a long match, see Longest Match below.
The last three forms with the embedded regexp
.mono
.meti <> / regex /
.onom
or
.meta number
or function
have special semantics; see Positive Match below.

The identifier
.code t
cannot be used as a name; it is a reserved symbol which
denotes the value true. An attempt to use the variable
.code @t
will result in an exception.  The symbol
.code nil
can be used where a variable name is required syntactically,
but it has special semantics, described in a section below.

A
.meta sident
is a "simple identifier" form which is not delimited by
braces.

A
.meta sident
consists of any combination of
one or more letters, numbers, and underscores. It may not look like a number,
so that for instance
.code 123
is not a valid
.metn sident ,
but
.code 12A
is valid.  Case is
sensitive, so that
.code FOO
is different from
.codn foo ,
which is different from
.codn Foo .

The braces around an identifier can be used when material which follows would
otherwise be interpreted as being part of the identifier. When a name is
enclosed in braces it is a
.metn bident .

The following additional characters may be used as part of
.meta bident
which are not allowed in a
.metn sident :

.verb
  ! $ % & * + - < = > ? \e ~
.brev

Moreover, most Unicode characters beyond U+007F may appear in a
.metn bident ,
with certain exceptions. A character may not be used if it is any of the
Unicode space characters, a member of the high or low surrogate region,
a member of any Unicode private use area, or is one of the two characters
U+FFFE or U+FFFF.

The rule still holds that a name cannot look like a number so
.code +123
is not a valid
.meta bident
but these are valid:
.codn a->b ,
.codn *xyz* ,
.codn foo-bar .

The syntax
.code @FOO_bar
introduces the name
.codn FOO_bar ,
whereas
.code @{FOO}_bar
means the
variable named
.str FOO
followed by the text
.strn _bar .
There may be whitespace
between the
.code @
and the name, or opening brace. Whitespace is also allowed in the
interior of the braces. It is not significant.

If a variable has no prior binding, then it specifies a match. The
match is determined from some current position in the data: the
character which immediately follows all that has been matched previously.
If a variable occurs at the start of a line, it matches some text
at the start of the line. If it occurs at the end of a line, it matches
everything from the current position to the end of the line.

.SS* Negative Match

If a variable is one of the plain forms

.mono
.mets >> @ sident
.mets <> @{ bident }
.mets >> @* sident
.mets <> @*{ bident }
.onom

then this is a "negative match".  The extent of the matched text (the text
bound to the variable) is determined by looking at what follows the variable,
and ranges from the current position to some position where the following
material finds a match. This is why this is called a "negative match": the
spanned text which ends up bound to the variable is that in which the match for
the trailing material did not occur.

A variable may be followed by a piece of text, a regular expression directive,
a function call, a directive, another variable, or nothing (i.e.  occurs at the
end of a line). These cases are described in detail below.

.NP* Variable Followed by Nothing
If the variable is followed by nothing, the negative match extends from the
current position in the data, to the end of the line.  Example:
.IP code:
.mono
\ a b c @FOO
.onom
.IP data:
.mono
\ a b c defghijk
.onom
.IP result:
.mono
\ FOO="defghijk"
.onom

.NP* Variable Followed by Text
For the purposes of determining the negative match, text is defined as a
sequence of literal text and regular expressions, not divided by a directive.
So for instance in this example:

.verb
  @a:@/foo/bcd e@(maybe)f@(end)
.brev
.PP

the variable @a is considered to be followed by
.strn ":@/foo/bcd e" .

If a variable is followed by text, then the extent of the negative match is
determined by searching for the first occurrence of that text within the line,
starting at the current position.

The variable matches everything between the current position and the matching
position (not including the matching position). Any whitespace which follows
the variable (and is not enclosed inside braces that surround the variable
name) is part of the text. For example:
.IP code:
.mono
\ a b @FOO e f
.onom
.IP data:
.mono
\ a b c d e f
.onom
.IP result:
.mono
\ FOO="c d"
.onom
.PP

In the above example, the pattern text
.str "a b "
matches the
data
.strn "a b " .
So when the
.code @FOO
variable is processed, the data being
matched is the remaining
.strn "c d e f" .
The text which follows
.code @FOO
is
.strn " e f" .
This is found within the data
.str "c d e f"
at position 3 (counting from 0).  So positions 0-2
.mono
("c d")
.onom
constitute the matching text which is bound to FOO.

.NP* Variable Followed by a Function Call or Directive

If the variable is followed by a function call, or a directive, the extent is
determined by scanning the text for the first position where a match occurs
for the entire remainder of the line. (For a description of functions,
see Functions.)

For example:

.verb
  @foo@(bind a "abc")xyz
.brev

Here,
.code foo
will match the text from the current position to where
.str "xyz"
occurs, even though there is a
.code @(bind)
directive. Furthermore, if
more material is added after the xyz, it is part of the search.
Note the difference between the following two:

.verb
  @foo@/abc/@(func)
  @foo@(func)@/abc/
.brev

In the first example, the variable foo matches the text from the current
position until the match for the regular expression abc.
.code @(func)
is not
considered when processing
.codn @foo .
In the second example, the variable foo
matches the text from the current position until the position which matches
the function call, followed by a match for the regular expression.
The entire sequence
.code @(func)@/abc/
is considered.

.NP* Consecutive Variables
If an unbound variable specifies a fixed-width match or a regular expression,
then the issue of consecutive variables does not arise. Such a variable
consumes text regardless of any context which follows it.

However, what if an unbound variable with no modifier is followed by another
variable? The behavior depends on the nature of the other variable.

If the other variable is also unbound, and also has no modifier, this is a
semantic error which will cause the query to fail.  A diagnostic message will
be issued, unless operating in quiet mode via
.codn -q .
The reason is that there is no way to bind two
consecutive variables to an extent of text; this is an ambiguous situation,
since there is no matching criterion for dividing the text between two
variables.  (In theory, a repetition of the same variable, like
.codn @FOO@FOO ,
could find a solution by dividing the match extent in half, which would work
only in the case when it contains an even number of characters.  This behavior
seems to have dubious value).

An unbound variable may be followed by one which is bound. The bound
variable is effectively replaced by the text which it denotes, and the logic
proceeds accordingly.

It is possible for a variable to be bound to a regular expression.
If
.code x
is an unbound variable and
.code y
is bound to a regular expression
.codn RE ,
then
.code @x@y
means
.codn @x@/RE/ .
A variable
.code v
can be bound to a regular expression using, for example,
.codn "@(bind v #/RE/)" .

The
.code @*
syntax for longest match is available. Example:
.IP code:
.mono
\ @FOO:@BAR@FOO
.onom
.IP data:
.mono
\ xyz:defxyz
.onom
.IP result:
.mono
\ FOO=xyz, BAR=def
.onom
.PP

Here,
.code FOO
is matched with
.strn "xyz" ,
based on the delimiting around the
colon. The colon in the pattern then matches the colon in the data,
so that
.code BAR
is considered for matching against
.strn "defxyz" .
.code BAR
is followed by
.codn FOO ,
which is already bound to
.strn "xyz" .
Thus
.str "xyz"
is located in the
.str "defxyz"
data following
.strn "def" ,
and so BAR is bound to
.strn "def" .

If an unbound variable is followed by a variable which is bound to a list, or
nested list, then each character string in the list is tried in turn to produce
a match. The first match is taken.

An unbound variable may be followed by another unbound variable which specifies
a regular expression or function call match. This is a special case called a
"double variable match".  What happens is that the text is searched using the
regular expression or function.  If the search fails, than neither variable is
bound: it is a matching failure.  If the search succeeds, than the first
variable is bound to the text which is skipped by the search.  The second
variable is bound to the text matched by the regular expression or function.
Examples:
.IP code:
.mono
\ @foo@{bar /abc/}
.onom
.IP data:
.mono
\ xyz@#abc
.onom
.IP result:
.mono
\ foo="xyz@#", BAR="abc"
.onom
.PP

.NP* Consecutive Variables Via Directive
Two variables can be
.I de facto
consecutive in a manner shown in the
following example:

.verb
  @var1@(all)@var2@(end)
.brev

This is treated just like the variable followed by directive. No semantic
error is identified, even if both variables are unbound. Here,
.code @var2
matches everything at the current position, and so
.code @var1
ends up bound to the empty string.

Example 1:
.code b
matches at position 0 and
.code a
binds the empty string:
.IP code:
.mono
\ @a@(all)@b@(end)
.onom
.IP data:
.mono
\ abc
.onom
.IP result:
.mono
\ a=""
 b="abc"
.onom
.PP

Example 2:
.code *a
specifies longest match (see Longest Match below), and so it takes
everything:
.IP code:
.mono
\ @*a@(all)@b@(end)
.onom
.IP data:
.mono
\ abc
.onom
.IP result:
.mono
\ a="abc"
 b=""
.onom
.PP

.NP* Longest Match
The closest-match behavior for the negative match can be overridden to longest
match behavior. A special syntax is provided for this: an asterisk between the
.code @
and the variable, e.g:
.IP code:
.mono
\ a @*{FOO}cd
.onom
.IP data:
.mono
\ a b cdcdcdcd
.onom
.IP result:
.mono
\ FOO="b cdcdcd"
.onom
.PP
.IP code:
.mono
\ a @{FOO}cd
.onom
.IP data:
.mono
\ a b cdcdcd
.onom
.IP result:
.mono
\ FOO="b "
 b=""
.onom
.PP

In the former example, the match extends to the rightmost occurrence of
.strn "cd" ,
and so
.code FOO
receives
.strn "b cdcdcd" .
In the latter example, the
.code *
syntax isn't used, and so a leftmost match takes place. The extent
covers only the
.strn "b " ,
stopping at the first
.str "cd"
occurrence.

.SS* Positive Match

There are syntactic variants of variable syntax which have an embedded expression
enclosed with the variable in braces:

.mono
.mets >> @{ bident <> / regex /}
.mets >> @{ bident >> ( fun >> [args ...])}
.mets >> @{ bident << number }
.mets >> @{ bident << bident }
.onom

These specify a variable binding that is driven by a positive match derived
from a regular expression, function or character count, rather than from
trailing material (which is regarded as a "negative" match, since the
variable is bound to material which is
.B skipped
in order to match the trailing material). In the
.mono
.meti <> / regex /
.onom
form, the match
extends over all characters from the current position which match
the regular expression
.metn regex .
(see Regular Expressions section below).
In the
.mono
.meti >> ( fun >> [ args ...])
.onom
form, the match extends over characters which
are matched by the call to the function, if the call
succeeds. Thus
.code "@{x (y z w)}"
is just like
.codn "@(y z w)" ,
except that the region of
text skipped over by
.code "@(y z w)"
is also bound to the variable
.codn x .
See Functions below.

In the
.meta number
form, the match processes a field of text which
consists of the specified number of characters, which must be non-negative
number.  If the data line doesn't have that many characters starting at the
current position, the match fails. A match for zero characters produces an
empty string.  The text which is actually bound to the variable
is all text within the specified field, but excluding leading and
trailing whitespace. If the field contains only spaces, then an empty
string is extracted.

This syntax is processed without consideration of what other
syntax follows.  A positive match may be directly followed by an unbound
variable.

The
.mono
.mets >> @{ bident << bident }
.onom
syntax allows the
.meta number
or
.meta regex
modifier to come from a variable. The variable must be bound and contain
a non-negative integer or regular expression.
For example,
.code "@{x y}"
behaves like
.code "@{x 3}"
if
.code y
is bound to the integer 3. It is an error if
.code y
is unbound.

.coSS Special Symbols @ nil and @ t

Just like in the Common Lisp language, the names
.code nil
and
.code t
are special.

.code nil
symbol stands for the empty
list object, an object which marks the end of a list, and Boolean false. It is
synonymous with the syntax
.code ()
which may be used interchangeably with
.code nil
in most constructs.

In \*(TL,
.code nil
and
.code t
cannot be used as variables. When evaluated, they evaluate to themselves.

In the \*(TX pattern language,
.code nil
can be used in the variable binding syntax, but does not create a binding;
it has a special meaning.  It allows the variable matching syntax to be used to
skip material, in ways similar to the
.code skip
directive.

The
.code nil
symbol is also used as a
.code block
name, both in the \*(TX pattern language and in \*(TL.
A block named
.code nil
is considered to be anonymous.

.SS* Keyword Symbols

Names whose names begin with the
.code :
character are keyword symbols.  These also
may not be used as variables either and stand for themselves. Keywords are
useful for labeling information and situations.

.SS* Regular Expressions
Regular expressions are a language for specifying sets of character strings.
Through the use of pattern matching elements, regular expression is
able to denote an infinite set of texts.
\*(TX contains an original implementation of regular expressions, which
supports the following syntax:
.coIP .
The period is a "wildcard" that matches any character.
.coIP []
Character class: matches a single character, from the set specified by
special syntax written between the square brackets.
This supports basic regexp character class syntax. POSIX
notation like
.code [:digit:]
is not supported.
The regex tokens
.codn \es ,
.code \ed
and
.code \ew
are permitted in character classes, but not their complementing counterparts.
These tokens simply contribute their characters to the class.
The class
.code [a-zA-Z]
means match an uppercase
or lowercase letter; the class
.code [0-9a-f]
means match a digit or
a lowercase letter; the class
.code [^0-9]
means match a non-digit, and so forth.
There are no locale-specific behaviors in \*(TX regular expressions;
.code [A-Z]
denotes an ASCII/Unicode range of characters.
The class
.code [\ed.]
means match a digit or the period character.
A
.code ]
or
.code -
can be used within a character class, but must be escaped
with a backslash. A
.code ^
in the first position denotes a complemented
class, unless it is escaped by backslash. In any other position, it denotes
itself.  Two backslashes code for one backslash. So for instance
.code [\e[\e-]
means match a
.code [
or
.code -
character,
.code [^^]
means match any character other
than
.codn ^ ,
and
.code [\e^\e\e]
means match either a
.code ^
or a backslash. Regex operators
such as
.codn * ,
.code +
and
.code &
appearing in a character class represent ordinary
characters. The characters
.codn - ,
.code ]
and
.code ^
occurring outside of a character class
are ordinary. Unescaped
.code /
characters can appear within a character class. The
empty character class
.code []
matches no character at all, and its complement
.code [^]
matches any character, and is treated as a synonym for the 
.code .
(period) wildcard operator.
.ccIP @, \es @ \ew and @ \ed
These regex tokens each match a single character. 
The
.code \es
regex token matches a wide variety of ASCII whitespace characters
and Unicode spaces. The
.code \ew
token matches alphabetic word characters; it
is equivalent to the character class
.codn [A-Za-z_] .
The
.code \ed
token matches a digit, and is equivalent to
.codn [0-9] .
.ccIP @, \eS @ \eW and @ \eD
These regex tokens are the complemented counterparts of
.codn \es ,
.code \ew
and
.codn \ed .
The
.code \eS
token matches all those characters which
.code \es
does not match,
.code \eW
matches all characters that
.code \ew
does not match and
.code \eD
matches nondigits.
.coIP empty
An empty expression is a regular expression. It represents the set of strings
consisting of the empty string; i.e. it matches just the empty string. The
empty regex can appear alone as a full regular expression (for instance the
\*(TX syntax
.code @//
with nothing between the slashes)
and can also be passed as a subexpression to operators, though this
may require the use of parentheses to make the empty regex explicit.  For
example, the expression
.code a|
means: match either
.codn a ,
or nothing.  The forms
.code *
and
.code (*)
are syntax errors; though not useful, the correct way to match the
empty expression zero or more times is the syntax
.codn ()* .
.coIP nomatch
The nomatch regular expression represents the
empty set: it matches no strings at all, not even the empty string.
There is no dedicated syntax to directly express nomatch in the regex language.
However, the empty character class
.code []
is equivalent to nomatch, and may be
considered to be a notation for it. Other representations of nomatch are
possible: for instance, the regex
.code ~.*
which is the complement of the regex that
denotes the set of all possible strings, and thus denotes the empty set. A
nomatch has uses; for instance, it can be used to temporarily "comment out"
regular expressions. The regex
.code ([]abc|xyz)
is equivalent to
.codn (xyz) ,
since the
.code []abc
branch cannot match anything. Using
.code []
to "block" a subexpression allows
you to leave it in place, then enable it later by removing the "block".
.coIP (R)
If
.code R
is a regular expression, then so is
.code (R).
The contents of parentheses denote one regular expression unit, so that for
instance in
.codn (RE)* ,
the
.code *
operator applies to the entire parenthesized group.
The syntax
.code ()
is valid and equivalent to the empty regular expression.
.coIP R?
Optionally match the preceding regular expression
.codn R .
.coIP R*
Match the expression
.code R
zero or more times. This
operator is sometimes called the "Kleene star", or "Kleene closure".
The Kleene closure favors the longest match. Roughly speaking, if there are two
or more ways in which
.code R1*R2
can match, than that match occurs in which
.code R1*
matches the longest possible text.
.coIP R+
Match the preceding expression
.code R
one or more times.  Like
.codn R* ,
this favors the longest possible match:
.code R+
is equivalent to
.codn RR* .
.coIP R1%R2
Match
.code R1
zero or more times, then match
.codn R2 .
If this match can occur in
more than one way, then it occurs such that
.code R1
is matched the fewest
number of times, which is opposite from the behavior of
.codn R1*R2 .
Repetitions of
.code R1
terminate at the earliest
point in the text where a non-empty match for
.code R2
occurs. Because
it favors shorter matches,
.code %
is termed a non-greedy operator.  If
.code R2
is the empty expression, or equivalent to it, then
.code R1%R2
reduces to
. codn R1* .
So for
instance
.code (R%)
is equivalent to
.codn (R*) ,
since the missing right operand is
interpreted as the empty regex. Note that whereas the expression
.code (R1*R2)
is equivalent to
.codn (R1*)R2 ,
the expression
.code (R1%R2)
is
.B not
equivalent to
.codn (R1%)R2 .
Also note that
.code A(XY%Z)B
is equivalent to
.codn AX(Y%Z)B .
This is because the precedence of
.code %
is higher than that of catenation on its left side; this rule prevents the given
syntax from expressing the
.code XY
catenation. The expression may be understood as:
.code A(X(Y%Z))B
where the inner parentheses clarify how the syntax surrounding the
.code %
operator is being parsed, and the outer parentheses are superfluous.
The correct way to assert catenation of
.code XY
as the left operand of
.code %
is
.codn A(XY)%ZB .
To specify
.code XY
as the left operand, and limit the right operand to just
.codn Z ,
the correct syntax is
.codn A((XY)%Z)B .
By contrast, the expression
.code A(X%YZ)B
is not equivalent to
.code A(X%Y)ZB
because the precedence of
.code %
is lower than that of catenation on its right side. The operator is
effectively "bi-precedential".
.coIP ~R
Match the opposite of the following expression
.codn R ;
that is, match exactly
those texts that
.code R
does not match. This operator is called complement,
or logical not.
.coIP R1R2
Two consecutive regular expressions denote catenation:
the left expression must match, and then the right.
.coIP R1|R2
match either the expression
.code R1
or
.codn R2 .
This operator is known by
a number of names: union, logical or, disjunction, branch, or alternative.
.coIP R1&R2
Match both the expression
.code R1
and
.code R2
simultaneously; i.e. the
matching text must be one of the texts which are in the intersection of the set
of texts matched by
.code R1
and the set matched by
.codn R2 .
This operator is called intersection, logical and, or conjunction.

.PP
Any character which is not a regular expression operator, a backslash escape,
or the slash delimiter, denotes one-position match of that character itself.

Any of the special characters, including the delimiting
.codn / ,
and the backslash, can be escaped with a backslash to suppress its
meaning and denote the character itself.

Furthermore, all of the same escapes as are described in the section Special
Characters in Text above are supported - the difference is that in regular
expressions, the
.code @
character is not required, so for example a tab is coded as
.code \et
rather than
.codn @\et .
Octal and hex character escapes can be optionally
terminated by a semicolon, which is useful if the following characters are
octal or hex digits not intended to be part of the escape.

Only the above escapes are supported. Unlike in some other regular expression
implementations, if a backlash appears before a character which isn't a regex
special character or one of the supported escape sequences, it is an error.
This wasn't true of historic versions of \*(TX. See the COMPATIBILITY section.

.IP "Precedence table, highest to lowest:"
.TS
tab(!);
l l l.
Operators!Class!Associativity
\f[4](R) []\f[]!primary!
\f[4]R? R+ R* R%...\f[]!postfix!left-to-right
\f[4]R1R2\f[]!catenation!left-to-right
\f[4]~R ...%R\f[]\f[]\f[]!unary!right-to-left
\f[4]R1&R2\f[]!intersection!left-to-right
\f[4]R1|R2\f[]!union!left-to-right
.TE
.PP

The
.code %
operator is like a postfix operator with respect to its left
operand, but like a unary operator with respect to its right operand.
Thus
.code a~b%c~d
is
.mono
a(~(b%(c(~d))))
.onom
, demonstrating right-to-left associativity,
where all of
.code b%
may be regarded as a unary operator being applied to
.codn c~d .
Similarly,
.code a?*+%b
means
.codn (((a?)*)+)%b ,
where the trailing
.code %b
behaves like a postfix operator.

In
\*(TX, regular expression matches do not span multiple lines. The regex
language has no feature for multi-line matching. However, the
.code @(freeform)
directive
allows the remaining portion of the input to be treated as one string
in which line terminators appear as explicit characters. Regular expressions
may freely match through this sequence.

It's possible for a regular expression to match an empty string.
For instance, if the next input character is
.codn z ,
facing a
the regular expression
.codn /a?/ ,
there is a zero-character match:
the regular expression's state machine can reach an acceptance
state without consuming any characters. Examples:
.IP code:
.mono
\ @A@/a?/@/.*/
.onom
.IP data:
.mono
\ zzzzz
.onom
.IP result:
.mono
\ A=""
.onom
.PP

.IP code:
.mono
\ @{A /a?/}@B
.onom
.IP data:
.mono
\ zzzzz
.onom
.IP result:
.mono
\ A="", B="zzzz"
.onom
.PP

.IP code:
.mono
\ @*A@/a?/
.onom
.IP data:
.mono
\ zzzzz
.onom
.IP result:
.mono
\ A="zzzzz"
.onom
.PP

In the first example, variable
.code @A
is followed by a regular expression
which can match an empty string. The expression faces the letter
.code "z"
at position 0 in the data line. A zero-character match occurs there,
therefore the variable
.code A
takes on the empty string. The
.code @/.*/
regular expression then consumes the line.

Similarly, in the second example, the
.code /a?/
regular expression faces a
.codn "z" ,
and thus yields an empty string which is bound to
.codn A .
Variable
.code @B
consumes the entire line.

The third example requests the longest match for the variable binding.
Thus, a search takes place for the rightmost position where the
regular expression matches. The regular expression matches anywhere,
including the empty string after the last character, which is
the rightmost place. Thus variable
.code A
fetches the entire line.

For additional information about the advanced regular expression
operators, NOTES ON EXOTIC REGULAR EXPRESSIONS below.

.SS* Compound Expressions
If the
.code @
escape character is followed by an open parenthesis or square bracket,
this is taken to be the start of a \*(TL compound expression.

The \*(TX language has the unusual property that its syntactic elements,
so-called
.IR directives ,
are Lisp compound expressions. These expressions not only enclose syntax, but
expressions which begin with certain symbols
.I de facto
behave as tokens in a phrase structure grammar. For instance, the expression
.code @(collect)
begins a block which must be terminated by the expression
.codn @(end) ,
otherwise there is a syntax error. The
.code collect
expression can contain arguments which modify the behavior of the construct,
for instance
.codn "@(collect :gap 0 :vars (a b))" .
In some ways, this situation might be compared to the HTML language, in which
an element such as
.code <a>
must be terminated by
.code </a>
and can have attributes such as
.codn "<a href=\(dq...\(dq>" .

Compound contain subexpressions: other compound expressions, or literal objects
of various kinds. Among these are: symbols, numbers, string literals, character
literals, quasiliterals and regular expressions. These are described in the
following sections. Additional kinds of literal objects exist, which are
discussed in the TXR LISP section of the manual.

Some examples of compound expressions are:

.verb
  (banana)

  (a b c (d e f))

  (  a (b (c d) (e  ) ))

  ("apple" #\eb #\espace 3)

  (a #/[a-z]*/ b)

  (_ `@file.txt`)
.brev

Symbols occurring in a compound expression follow a slight more permissive
lexical syntax than the
.meta bident
in the syntax
.mono
.meti <> @{ bident }
.onom
introduced earlier. The
.code /
(slash) character may be part of an identifier, or even
constitute an entire identifier. In fact a symbol inside a
directive is a
.metn lident .
This is described in the Symbol Tokens section under TXR LISP.
A symbol must not be a number; tokens that look like numbers are treated as
numbers and not symbols.

.SS* Character Literals

Character literals are introduced by the
.code #\e
syntax, which is either
followed by a character name, the letter
.code x
followed by hex digits,
the letter
.code o
followed by octal digits, or a single character. Valid character
names are:

.verb
  nul                 linefeed            return
  alarm               newline             esc
  backspace           vtab                space
  tab                 page                pnul
.brev

For instance
.code #\eesc
denotes the escape character.

This convention for character literals is similar to that
of the Scheme language.  Note that
.code #\elinefeed
and
.code #\enewline
are the same
character. The
.code #\epnul
character is specific to \*(TX and denotes the
.code U+DC00
code in Unicode; the name stands for "pseudo-null", which is related to
its special function. For more information about this, see the section
"Character Handling and International Characters".

.SS* String Literals

String literals are delimited by double quotes.
A double quote within a string literal is encoded using
.mono
\e"
.onom
and a backslash is encoded as
.codn \e\e .
Backslash escapes like
.code \en
and
.code \et
are recognized, as are hexadecimal escapes like
.code \exFF
or
.code \exxabc
and octal
escapes like
.codn \e123 .
Ambiguity between an escape and subsequent
text can be resolved by using trailing semicolon delimiter:
.str "\exabc;d"
is a string consisting of the character
.code "U+0ABC"
followed by
.strn "d" .
The semicolon
delimiter disappears. To write a literal semicolon immediately after a hex
or octal escape, write two semicolons, the first of which will be interpreted
as a delimiter. Thus,
.str "\ex21;;"
represents
.strn "!;" .

If the line ends in the middle of a literal, it is an error, unless the
last character is a backslash. This backslash is a special escape which does
not denote a character; rather, it indicates that the string literal continues
on the next line.  The backslash is deleted, along with whitespace which
immediately precedes it, as well as leading whitespace in the following line.
The escape sequence
.str "\e "
(backslash space) can be used to encode a significant space.

Example:

.verb
  "foo   \e
   bar"

  "foo   \e
  \e bar"

  "foo\e  \e
   bar"
.brev

The first string literal is the string
.strn "foobar" .
The second two are
.strn "foo bar" .

.SS* Word List Literals

A word list literal (WLL) provides a convenient way to write a list of strings
when such a list can be given as whitespace-delimited words.

There are two flavors of the WLL: the regular WLL which begins with
.mono
#"
.onom
(hash, double-quote) and the splicing list literal which begins with
.mono
#*"
.onom
(hash, star, double-quote).

Both types are terminated by a double quote, which may be escaped
as
.mono
\e"
.onom
in order to include it as a character. All the escaping conventions
used in string literals can be used in word literals.

Unlike in string literals, whitespace (tabs and spaces) is not
significant in word literals: it separates words.  Whitespace may be
escaped with a backslash in order to include it as a literal character.

Just like in string literals, an unescaped newline character is not allowed.
A newline preceded by a backslash is permitted. Such an escaped backslash,
together with any leading and trailing unescaped whitespace, is removed
and replaced with a single space.

Example:

.verb
  #"abc def ghi"   --> notates ("abc" "def" "ghi")

  #"abc   def \e
      ghi"         --> notates ("abc" "def" "ghi")

  #"abc\e def ghi" --> notates ("abc def" "ghi")

  #"abc\e def\e \e
   \e ghi"         --> notates ("abc def " " ghi")
.brev

A splicing word literal differs from a word literal in that it does not
produce a list of string literals, but rather it produces a sequence of string
literals that is merged into the surrounding syntax.  Thus, the following two
notations are equivalent:

.verb
  (1 2 3 #*"abc def" 4 5 #"abc def")

  (1 2 3 "abc" "def" 4 5 ("abc" "def"))
.brev

The regular WLL produced a single list object, but the splicing
WLL expanded into multiple string literal objects.

.SS* String Quasiliterals

Quasiliterals are similar to string literals, except that they may
contain variable references denoted by the usual
.code @
syntax. The quasiliteral
represents a string formed by substituting the values of those variables
into the literal template. If
.code a
is bound to
.str "apple"
and
.code b
to
.strn "banana" ,
the quasiliteral
.code "`one @a and two @{b}s`"
represents the string
.strn "one apple and two bananas" .
A backquote escaped by a backslash represents
itself. Unlike in directive syntax, two consecutive
.code @
characters do not code for a literal
.codn @ ,
but cause a syntax error. The reason for this is that compounding of the
.code @
syntax is meaningful.
Instead, there is a
.code \e@
escape for encoding a literal
.code @
character.  Quasiliterals support the full output variable
syntax. Expressions within variable substitutions follow the evaluation rules
of \*(TL.  This hasn't always been the case: see the COMPATIBILITY section.

Quasiliterals can be split into multiple lines in the same way as ordinary
string literals.

.SS* Quasiword List Literals

The quasiword list literals (QLL-s) are to quasiliterals what WLL-s are to
ordinary literals. (See the above section Word List Literals.)

A QLL combines the convenience of the WLL
with the power of quasistrings.

Just as in the case of WLL-s, there are two flavors of the
QLL: the regular QLL which begins with
.code #`
\ (hash, backquote) and the splicing QLL which begins with
.code #*`
\ (hash, star, backquote).

Both types are terminated by a backquote, which may be escaped
as
.code \e`
\ in order to include it as a character. All the escaping conventions
used in quasiliterals can be used in QLL.

Unlike in quasiliterals, whitespace (tabs and spaces) is not
significant in QLL: it separates words.  Whitespace may be
escaped with a backslash in order to include it as a literal character.

A newline is not permitted unless escaped. An escaped newline works exactly the
same way as it does in word list literals (WLL-s).

Note that the delimiting into words is done before the variable
substitution. If the variable a contains spaces, then
.code #`@a`
nevertheless
expands into a list of one item: the string derived from
.codn a .

Examples:

.verb
  #`abc @a ghi`  --> notates (`abc` `@a` `ghi`)

  #`abc   @d@e@f \e
  ghi`            --> notates (`abc` `@d@e@f` `ghi`)

  #`@a\e @b @c` --> notates (`@a @b` `@c`)
.brev

A splicing QLL differs from an ordinary QLL in that it does not produce a list
of quasiliterals, but rather it produces a sequence of quasiliterals that is
merged into the surrounding syntax.

.SS* Numbers

\*(TX supports integers and floating-point numbers. 

An integer constant is made up of digits
.code 0
through
.codn 9 ,
optionally preceded by a
.code +
or
.code -
sign.

Examples:

.verb
  123
  -34
  +0
  -0
  +234483527304983792384729384723234
.brev

An integer constant can also be specified in hexadecimal using the prefix
.code #x
followed by an optional sign, followed by hexadecimal digits:
.code 0
through
.code 9
and the upper or lower case letters
.code A
through
.codn F :

.verb
  #xFF    ;; 255
  #x-ABC  ;; -2748
.brev

Similarly, octal numbers are supported with the prefix
.code #o
followed by octal digits:

.verb
  #o777   ;; 511
.brev

and binary numbers can be written with a
.code #b
prefix:

.verb
  #b1110  ;; 14
.brev

Note that the
.code #b
prefix is also used for buffer literals.

A floating-point constant is marked by the inclusion of a decimal point, the
exponential "e notation", or both. It is an optional sign, followed
by a mantissa consisting of digits, a decimal point, more digits, and then an
optional exponential notation consisting of the letter
.code "e"
or
.codn "E" ,
an optional
.code +
or
.code -
sign, and then digits indicating the exponent value.
In the mantissa, the digits are not optional. At least one digit must either
precede the decimal point or follow. That is to say, a decimal point by itself
is not a floating-point constant.

Examples:

.verb
  .123
  123.
  1E-3
  20E40
  .9E1
  9.E19
  -.5
  +3E+3
  1.E5
.brev

Examples which are not floating-point constant tokens:

.verb
  .      ;; dot token, not a number
  123E   ;; the symbol 123E
  1.0E-  ;; syntax error: invalid floating point constant
  1.0E   ;; syntax error: invalid floating point constant
  1.E    ;; syntax error: invalid floating point literal
  .e     ;; syntax error: dot token followed by symbol
.brev

In \*(TX there is a special "dotdot" token consisting of two consecutive periods.
An integer constant followed immediately by dotdot is recognized as such; it is
not treated as a floating constant followed by a dot. That is to say,
.code 123..
does not mean
.code "123. ."
(floating point
.code 123.0
value followed by dot token).  It means
.code "123 .."
(integer
.code 123
followed by
.code ..
token).

Dialect note: unlike in Common Lisp,
.code 123.
is not an integer, but the floating-point number
.codn 123.0 .

.SS* Comments

Comments of the form
.code @;
were introduced earlier. Inside compound expressions, another convention for
comments exists: Lisp comments, which are introduced by the
.code ;
(semicolon) character and span to the end of the line.

Example:

.verb
  @(foo  ; this is a comment
    bar  ; this is another comment
    )
.brev

This is equivalent to
.codn "@(foo bar)" .

.SH* DIRECTIVES

.SS* Overview

When a \*(TL compound expressions occurs in \*(TX preceded by a
.codn @ ,
it is a
.IR directive .

Directives which are based on certain symbols are, additionally,
involved in a phrase-structure syntax which uses Lisp expressions
as if they were tokens.

For instance, the directive

.verb
  @(collect)
.brev

not only denotes a compound expression with the
.code collect
symbol in its head position, but it also introduces a syntactic phrase which
requires a matching
.code @(end)
directive. In other words,
.code @(collect)
is not only
an expression, but serves as a kind of token in a higher level phrase structure
grammar.

Effectively,
.code collect
is a reserved symbol in the \*(TX language. A \*(TX program cannot use
this symbol as the name of a pattern function, due to its role in the syntax.
The symbol has no reserved role in \*(TL.

Usually if this type of directive occurs alone in a line, not
preceded or followed by other material, it is involved in a "vertical" (or line
oriented) syntax.

If such a directive is embedded in a line (has preceding or trailing material)
then it is in a horizontal syntactic and semantic context (character-oriented).

There is an exception: the definition of a horizontal function looks like this:

.verb
  @(define name (arg))body material@(end)
.brev

Yet, this is considered one vertical item, which means that it does not match
a line of data. (This is necessary because all horizontal syntax matches
something within a line of data, which is undesirable for definitions.)

Many directives exhibit both horizontal and vertical syntax, with different but
closely related semantics. A few are vertical only, and some are
horizontal only.

A summary of the available directives follows:

.coIP @(eof)
Explicitly match the end of file. Fails if unmatched data remains in
the input stream.

.coIP @(eol)
Explicitly match the end of line. Fails if the current position is not the
end of a line. Also fails if no data remains (there is no current line).

.coIP @(next)
Continue matching in another file or other data source.

.coIP @(block)
Groups together a sequence of directives into a logical name block,
which can be explicitly terminated from within using
the
.code @(accept)
and
.code @(fail)
directives.
Blocks are described in the section Blocks below.

.coIP @(skip)
Treat the remaining query as a subquery unit, and search the lines (or
characters) of the input file until that subquery matches somewhere.  A skip is
also an anonymous block.

.coIP @(trailer)
Treat the remaining query or subquery as a match for a trailing context. That
is to say, if the remainder matches, the data position is not advanced.

.coIP @(freeform)
Treat the remainder of the input as one big string, and apply the following
query line to that string. The newline characters (or custom separators) appear
explicitly in that string.

.coIP @(fuzz)
The
.code fuzz
directive, inspired by the patch utility, specifies a partial
match for some lines.

.ccIP @ @(line) and @ @(chr)
These directives match a variable or expression against the current line
number or character position.

.coIP @(name)
Match a variable against the name of the current data source.

.coIP @(data)
Match a variable against the remaining data (lazy list of strings).

.coIP @(some)
Multiple clauses are each applied to the same input. Succeeds if at least one
of the clauses matches the input. The bindings established by earlier
successful clauses are visible to the later clauses.

.coIP @(all)
Multiple clauses are applied to the same input. Succeeds if and only if each
one of the clauses matches. The clauses are applied in sequence, and evaluation
stops on the first failure. The bindings established by earlier successful
clauses are visible to the later clauses.

.coIP @(none)
Multiple clauses are applied to the same input. Succeeds if and only if none of
them match. The clauses are applied in sequence, and evaluation stops on the
first success. No bindings are ever produced by this construct.

.coIP @(maybe)
Multiple clauses are applied to the same input. No failure occurs if none of
them match.  The bindings established by earlier successful clauses are visible
to the later clauses.

.coIP @(cases)
Multiple clauses are applied to the same input. Evaluation stops on the
first successful clause.

.coIP @(require)
The
.code require
directive is similar to the
.code do
directive in that it evaluates one or more
\*(TL expressions.  If the result of the rightmost expression is nil,
then require triggers a match failure.  See the TXR LISP section far below.

.ccIP @, @(if) @, @(elif) and @ @(else)
The
.code if
directive with optional
.code elif
and
.code else
clauses allows one of multiple bodies of pattern matching directives to be
conditionally selected by testing the values of Lisp expressions. It is
also available inside
.code @(output)
for conditionally selecting output clauses.

.coIP @(choose)
Multiple clauses are applied to the same input. The one whose effect persists
is the one which maximizes or minimizes the length of a particular variable.

.coIP @(empty)
The
.code @(empty)
directive matches the empty string. It is useful in certain
situations, such as expressing an empty match in a directive that doesn't
accept an empty clause. The
.code @(empty)
syntax has another meaning in
.code @(output)
clauses, in conjunction with
.codn @(repeat) .

.meIP @(define < name >> ( args ...))
Introduces a function. Functions are described in the Functions section below.

.meIP @(call < expr << args *)
Performs function indirection.  Evaluates
.metn expr ,
which must produce a symbol that names a pattern function. Then that
pattern function is invoked.

.coIP @(gather)
Searches text for matches for multiple clauses which may occur in arbitrary
order. For convenience, lines of the first clause are treated as separate
clauses.

.coIP @(collect)
Search the data for multiple matches of a clause. Collect the
bindings in the clause into lists, which are output as array variables.
The
.code @(collect)
directive is line oriented. It works with a multi-line
pattern and scans line by line. A similar directive called
.code @(coll)
works within one line.

A collect is an anonymous block.

.coIP @(and)
Separator of clauses for
.codn @(some) ,
.codn @(all) ,
.codn @(none) ,
.code @(maybe)
and
.codn @(cases) .
Equivalent to
.codn @(or) .
The choice is stylistic.

.coIP @(or)
Separator of clauses for
.codn @(some) ,
.codn @(all) ,
.codn @(none) ,
.code @(maybe)
and
.codn @(cases) .
Equivalent to
.codn @(and) .
The choice is stylistic.

.coIP @(end)
Required terminator for
.codn @(some) ,
.codn @(all) ,
.codn @(none) ,
.codn @(maybe) ,
.codn @(cases) ,
.codn @(if) ,
.codn @(collect) ,
.codn @(coll) ,
.codn @(output) ,
.codn @(repeat) ,
.codn @(rep) ,
.codn @(try) ,
.code @(block)
and
.codn @(define) .

.coIP @(fail)
Terminate the processing of a block, as if it were a failed match.
Blocks are described in the section Blocks below.

.coIP @(accept)
Terminate the processing of a block, as if it were a successful match.
What bindings emerge may depend on the kind of block: collect
has special semantics.  Blocks are described in the section Blocks below.

.coIP @(try)
Indicates the start of a try block, which is related to exception
handling, described in the Exceptions section below.

.ccIP @ @(catch) and @ @(finally)
Special clauses within
.codn @(try) .
See Exceptions below.

.ccIP @ @(defex) and @ @(throw)
Define custom exception types; throw an exception.  See Exceptions below.

.coIP @(assert)
The
.code assert
directive requires the following material to match, otherwise
it throws an exception. It is useful for catching mistakes or omissions
in parts of a query that are sure-fire matches.

.coIP @(flatten)
Normalizes a set of specified variables to one-dimensional lists. Those
variables which have scalar value are reduced to lists of that value.
Those which are lists of lists (to an arbitrary level of nesting) are converted
to flat lists of their leaf values.

.coIP @(merge)
Binds a new variable which is the result of merging two or more
other variables. Merging has somewhat complicated semantics.

.coIP @(cat)
Decimates a list (any number of dimensions) to a string, by catenating its
constituent strings, with an optional separator string between all of the
values.

.coIP @(bind)
Binds one or more variables against a value using a structural
pattern match. A limited form of unification takes place which can cause a
match to fail.

.coIP @(set)
Destructively assigns one or more existing variables using a structural
pattern, using syntax similar to bind. Assignment to unbound
variables triggers an error.

.coIP @(rebind)
Evaluates an expression in the current binding environment, and
then creates new bindings for the variables in the structural pattern.
Useful for temporarily overriding variable values in a scope.

.coIP @(forget)
Removes variable bindings.

.coIP @(local)
Synonym of
.codn @(forget) .

.coIP @(output)
A directive which encloses an output clause in the query. An output section
does not match text, but produces text. The directives above are not
understood in an output clause.

.coIP @(repeat)
A directive understood within an
.code @(output)
section, for repeating multi-line
text, with successive substitutions pulled from lists. The directive
.code @(rep)
produces iteration over lists horizontally within one line. These directives
have a different meaning in matching clauses, providing a shorthand
notation for
.code "@(collect :vars nil)"
and
.codn "@(coll :vars nil)" ,
respectively.

.coIP @(deffilter)
The
.code deffilter
directive is used for defining named filters, which are useful
for filtering variable substitutions in output blocks. Filters are useful
when data must be translated between different representations that
have different special characters or other syntax, requiring escaping
or similar treatment. Note that it is also possible to use a function
as a filter. See Function Filters below.

Named filters are stored in the hash table held in the Lisp special variable
.codn *filters* .

.coIP @(filter)
The
.code filter
directive passes one or more variables through a given
filter or chain or filters, updating them with the filtered values.

.ccIP @ @(load) and @ @(include)
The
.code load
and
.code include
directives allow \*(TX programs to be modularized. They bring in
code from a file, in two different ways.

.coIP @(do)
The
.code do
directive is used to evaluate \*(TL expressions, discarding their
result values. See the TXR LISP section far below.

.coIP @(mdo)
The
.code mdo
(macro
.codn do )
directive evaluates \*(TL expressions immediately, during the parsing
of the \*(TX syntax in which it occurs.

.coIP @(in-package)
The
.code in-package
directive is used to switch to a different symbol package.
It mirrors the \*(TL macro of the same name.

.PP

.SS* Subexpression Evaluation

Some directives contain subexpressions which are evaluated. Two distinct
styles of evaluations occur in \*(TX: bind expressions and Lisp expressions.
Which semantics applies to an expression depends on the syntactic
context in which it occurs: which position in which directive.

The evaluation of \*(TL expressions is described in the TXR LISP section of the manual.

Bind expressions are so named because they occur in the
.code @(bind)
directive. \*(TX pattern function invocations also treat argument expressions
as bind expressions.

The
.codn @(rebind) ,
.codn @(set) ,
.codn @(merge) ,
and
.code @(deffilter)
directives also use bind expression evaluation. Bind expression evaluation
also occurs in the argument position of the
.code :tlist
keyword in the
.code @(next)
directive.

Unlike Lisp expressions, bind expressions do not support operators.  If a bind
expression is a nested list structure, it is a template denoting that
structure.  Any symbol in any position of that structure is interpreted as a
variable. When the bind expression is evaluated, those corresponding positions
in the template are replaced by the values of the variables.

Anywhere where a variable can appear in a bind expression's nested list
structure, a Lisp expression can appear preceded by the
.code @
character. That Lisp expression is evaluated and its value is substituted
into the bind expression's template.

Moreover, a Lisp expression preceded by
.code @
can be used as an entire bind expression. The value of that Lisp
expression is then taken as the bind expression value.

Any object in a bind expression which is not a nested list structure containing
Lisp expressions or variables denotes itself literally.

.TP* Examples:

In the following examples, the variables
.code a
and
.code b
are assumed to have the string values
.str foo
and
.strn bar ,
respectively.

The
.code ->
notation indicates the value of each expression.

.verb
  a              ->  "foo"
  (a b)          ->  ("foo" "bar")
  ((a) ((b) b))  ->  (("foo") (("bar") "bar"))
  (list a b)     ->  error: unbound variable list
  @(list a b)    ->  ("foo" "bar") ;; Lisp expression
  (a @[b 1..:])  ->  ("foo" "ar")  ;; Lisp eval of [b 1..:]
  (a @(+ 2 2))   ->  ("foo" 4)     ;; Lisp eval of (+ 2 2)
  #(a b)         ->  (a b)         ;; Vector literal, not list.
  [a b]          ->  error: unbound variable dwim
.brev

The last example above
.code "[a b]"
is a notation equivalent to
.code "(dwim a b)"
and so follows similarly to the example involving
.codn list .

.SS* Input Scanning and Data Manipulation

.dir next

The
.code next
directive indicates that the remaining directives in the current block
are to be applied against a new input source.

It can only occur by itself as the only element in a query line,
and takes various arguments, according to these possibilities:

.mono
.mets @(next)
.mets @(next << source )
.mets @(next < source :nothrow)
.mets @(next :args)
.mets @(next :env)
.mets @(next :list << lisp-expr )
.mets @(next :tlist << bind-expr )
.mets @(next :string << lisp-expr )
.mets @(next :var << var )
.mets @(next nil)
.onom

The lone
.code @(next)
without arguments specifies that subsequent directives
will match inside the next file in the argument list which was passed
to \*(TX on the command line.

If
.meta source
is given, it must be a \*(TL expression which denotes an
input source. Its value may be a string or an input stream.
For instance, if variable
.code A
contains the text
.strn "data" ,
then
.code "@(next A)"
means switch to the file called
.strn "data" ,
and
.code "@(next `@A.txt`)"
means to switch to the file
.strn "data.txt" .
The directive
.code "@(next (open-command `git log`))"
switches to the input stream connected to the output of the
.code "git log"
command.

If the input source cannot be opened for whatever reason,
\*(TX throws an exception (see Exceptions below). An unhandled exception will
terminate the program.  Often, such a drastic measure is inconvenient;
if
.code @(next)
is invoked with the
.code :nothrow
keyword, then if the input
source cannot be opened, the situation is treated as a simple
match failure.

The variant
.code "@(next :args)"
means that the remaining command line arguments are to
be treated as a data source. For this purpose, each argument is considered to
be a line of text. The argument list does include that argument which specifies
the file that is currently being processed or was most recently processed.
As the arguments are matched, they are consumed. This means that if a
.code @(next)
directive without
arguments is executed in the scope of
.codn "@(next :args)" ,
it opens the file named
by the first unconsumed argument.

To process arguments, and then continue with the original file and argument
list, wrap the argument processing in a
.codn @(block) .
When the block terminates, the input source and argument list are restored
to what they were before the block.

The variant
.code "@(next :env)"
means that the list of process environment variables
is treated as a source of data. It looks like a text file stream
consisting of lines of the form
.strn "name=value" .
If this feature is not available
on a given platform, an exception is thrown.

The syntax
.mono
.meti @(next :list << lisp-expr )
.onom
treats \*(TL expression
.meta lisp-expr
as a source of
text. The value of
.meta lisp-expr
is flattened to a simple list in a way similar to the
.code @(flatten)
directive.  The resulting list is treated as if it were the
lines of a text file: each element of the list must be a string,
which represents a line.  If the strings happen contain embedded newline
characters, they are a visible constituent of the line, and do not act as line
separators.

The syntax
.mono
.meti @(next :tlist << bind-expr )
.onom
is similar to
.code "@(next :list ...)"
except that
.meta bind-expr
is not a \*(TL expression, but a \*(TX bind expression.

The syntax
.mono
.meti @(next :var << var )
.onom
requires
.meta var
to be a previously bound variable. The value of the
variable is retrieved and treated like a list, in the
same manner as under
.codn "@(next :list ...)" .
Note that
.code "@(next :var x)"
is not always the same as
.codn "@(next :tlist x)" ,
because
.code ":var x"
strictly requires
.code x
to be a \*(TX variable, whereas the
.code x
in
.code ":tlist x"
is an expression which can potentially refer to Lisp variable.

The syntax
.mono
.meti @(next :string << lisp-expr )
.onom
treats expression
.meta lisp-expr
as a source of text. The value of the expression must be a string. Newlines in
the string are interpreted as line terminators.

A string which is not terminated by a newline is tolerated, so that:

.verb
  @(next :string "abc")
  @a
.brev

binds
.code a
to
.strn "abc" .
Likewise, this is also the case with input files and other
streams whose last line is not terminated by a newline.

However, watch out for empty strings, which are analogous to a correctly formed
empty file which contains no lines:

.verb
  @(next :string "")
  @a
.brev

This will not bind
.code a
to
.strn "" ;
it is a matching failure.  The behavior of
.code :list
is
different. The query

.verb
  @(next :list "")
  @a
.brev

binds
.code a
to
.strn "" .
The reason is that under
.code :list
the string
.str ""
is flattened to
the list
.mono
("")
.onom
which is not an empty input stream, but a stream consisting of
one empty line.

The
.code "@(next nil)"
variant indicates that the following subquery is applied to empty data,
and the list of data sources from the command line is considered empty.
This directive is useful in front of \*(TX code which doesn't process data
sources from the command line, but takes command line arguments.
The
.code "@(next nil)"
incantation absolutely prevents \*(TX from trying to open the
first command line argument as a data source.

Note that the
.code @(next)
directive only redirects the source of input over the scope of subquery in which
the that directive appears.  For
example, the following query looks for the line starting with
.str "xyz"
at the top of the file
.strn "foo.txt" ,
within a
.code some
directive.  After the
.code @(end)
which terminates the
.codn @(some) ,
the
.str "abc"
is matched in the previous input stream which was in effect before
the
.code @(next)
directive:

.verb
  @(some)
  @(next "foo.txt")
  xyz@suffix
  @(end)
  abc
.brev

However, if the
.code @(some)
subquery successfully matched
.str "xyz@suffix"
within the
file
.codn foo.text ,
there is now a binding for the
.code suffix
variable, which
is visible to the remainder of the entire query. The variable bindings
survive beyond the clause, but the data stream does not.

.dir skip

The
.code skip
directive considers the remainder of the query as a search
pattern. The remainder is no longer required to strictly match at the
current line in the current input stream. Rather, the current stream is searched,
starting with the current line, for the first line where the entire remainder
of the query will successfully match. If no such line is found, the
.code skip
directive fails. If a matching position is found, the remainder of
the query is processed from that point.

The remainder of the query can itself contain
.code skip
directives.
Each such directive performs a recursive subsearch.

Skip comes in vertical and horizontal flavors. For instance, skip and match the
last line:

.verb
  @(skip)
  @last
  @(eof)
.brev

Skip and match the last character of the line:

.verb
  @(skip)@{last 1}@(eol)
.brev

The
.code skip
directive has two optional arguments, which are evaluated as \*(TL
expressions. If the first argument evaluates to an integer,
its value limits the range of lines scanned for a match. Judicious use
of this feature can improve the performance of queries.

Example: scan until
.str "size: @SIZE"
matches, which must happen within
the next 15 lines:

.verb
  @(skip 15)
  size: @SIZE
.brev

Without the range limitation skip will keep searching until it consumes
the entire input source.  In a horizontal
.codn skip ,
the range-limiting numeric argument is expressed in characters, so that

.verb
  abc@(skip 5)def
.brev

means: there must be a match for
.str "abc"
at the start of the line, and then within the next five characters,
there must be a match for
.strn "def" .

Sometimes a skip is nested within a
.codn collect ,
or
following another skip. For instance, consider:

.verb
  @(collect)
  begin @BEG_SYMBOL
  @(skip)
  end @BEG_SYMBOL
  @(end)
.brev

The above
.code collect
iterates over the entire input. But, potentially, so does
the embedded
.codn skip .
Suppose that
.str "begin x"
is matched, but the data has no
matching
.strn "end x" .
The skip will search in vain all the way to the end of the
data, and then the collect will try another iteration back at the
beginning, just one line down from the original starting point.  If it is a
reasonable expectation that an
.code "end x"
occurs 15 lines of a
.strn "begin x" ,
this can be specified instead:

.verb
  @(collect)
  begin @BEG_SYMBOL
  @(skip 15)
  end @BEG_SYMBOL
  @(end)
.brev

If the symbol
.code nil
is used in place of a number, it means to scan
an unlimited range of lines; thus,
.code "@(skip nil)"
is equivalent to
.codn @(skip) .

If the symbol
.code :greedy
is used, it changes the semantics of the skip
to longest match semantics.  For instance, match the last three space-separated
tokens of the line:

.verb
  @(skip :greedy) @a @b @c
.brev

Without
.codn :greedy ,
the variable
.code @c
will can match multiple tokens,
and end up with spaces in it, because nothing follows
.code @c
and so it matches from any position which follows a space to the
end of the line.  Also note the space in front of
.codn @a .
Without this
space,
.code @a
will get an empty string.

A line oriented example of greedy skip: match the last line without
using
.codn @eof :

.verb
  @(skip :greedy)
  @last_line
.brev

There may be a second numeric argument. This specifies a minimum
number of lines to skip before looking for a match. For instance,
skip 15 lines and then search indefinitely for
.codn "begin ..." :

.verb
  @(skip nil 15)
  begin @BEG_SYMBOL
.brev

The two arguments may be used together. For instance, the following
matches if, and only if, the 15th line of input starts with
.codn "begin " :

.verb
  @(skip 1 15)
  begin @BEG_SYMBOL
.brev

Essentially,
.mono
.meti @(skip 1 << n )
.onom
means "hard skip by
.meta n
lines".
.code "@(skip 1 0)"
is the same as
.codn "@(skip 1)" ,
which is a noop, because it means: "the remainder of the query must match
starting on the next line", or, more briefly, "skip exactly zero lines",
which is the behavior if the
.code skip
directive is omitted altogether.

Here is one trick for grabbing the fourth line from the bottom of the input:

.verb
  @(skip)
  @fourth_from_bottom
  @(skip 1 3)
  @(eof)
.brev

Or using greedy skip:

.verb
  @(skip :greedy)
  @fourth_from_bottom
  @(skip 1 3)
.brev

Nongreedy skip with the
.code @(eof)
has a slight advantage because the greedy skip
will keep scanning even though it has found the correct match, then backtrack
to the last good match once it runs out of data. The regular skip with explicit
.code @(eof)
will stop when the
.code @(eof)
matches.

.NP* Reducing Backtracking with Blocks

.code skip
can consume considerable CPU time when multiple skips are nested.  Consider:

.verb
  @(skip)
  A
  @(skip)
  B
  @(skip)
  C
.brev

This is actually nesting: the second a third skips occur within the body of the
first one, and thus this creates nested iteration. \*(TX is searching for the
combination of skips which find match the pattern of lines
.codn A ,
.code B
and
.codn C ,
with
backtracking behavior. The outermost skip marches through the data until it
finds
.codn A ,
followed by a pattern match for the second skip. The second skip
iterates within to find
.codn B ,
followed by the third skip, and the third skip
iterates to find
.codn C .
If there is only one line
.codn A ,
and one
.codn B ,
then this is reasonably fast. But suppose there are many lines matching
.code A
and
.codn B ,
giving rise to a large number combinations of skips which match
.code A
and
.codn B ,
and yet do not find a match for
.codn C ,
triggering backtracking. The nested stepping which tries
the combinations of
.code A
and
.code B
can give rise to a considerable running time.

One way to deal with the problem is to unravel the nesting with the help of
blocks. For example:

.verb
  @(block)
  @  (skip)
  A
  @(end)
  @(block)
  @  (skip)
  B
  @(end)
  @(skip)
  C
.brev

Now the scope of each skip is just the remainder of the block in which it
occurs. The first skip finds
.codn A ,
and then the block ends. Control passes to the
next block, and backtracking will not take place to a block which completed
(unless all these blocks are enclosed in some larger construct which
backtracks, causing the blocks to be re-executed.

This rewrite is not equivalent, and cannot be used for instance
in backreferencing situations such as:

.verb
  @;
  @; Find three lines anywhere in the input which are identical.
  @;
  @(skip)
  @line
  @(skip)
  @line
  @(skip)
  @line
.brev

This example depends on the nested search-within-search semantics.

.dir trailer

The
.code trailer
directive introduces a trailing portion of a query or subquery
which matches input material normally, but in the event of a successful match,
does not advance the current position. This can be used, for instance, to
cause
.code @(collect)
to match partially overlapping regions.

Trailer can be used in vertical context:

.mono
.mets @(trailer)
.mets < directives
.mets ...
.onom

or horizontal:

.mono
.mets @(trailer) < directives ...
.onom

A vertical
.code trailer
prevents the vertical input position from
advancing as it is matched by
.metn directives ,
whereas a horizontal
.code trailer
prevents the horizontal position from advancing. In other words,
.code trailer
performs matching without consuming the input, providing a
look-ahead mechanism.

Example:

.verb
  @(collect)
  @line
  @(trailer)
  @(skip)
  @line
  @(end)
.brev

This script collects each line which has a duplicate somewhere later
in the input. Without the
.code @(trailer)
directive, this does not work properly
for inputs like:

.verb
  111
  222
  111
  222
.brev

Without
.codn @(trailer) ,
the first duplicate pair constitutes a match which
spans over the
.codn 222 .
After that pair is found, the matching continues
after the second
.codn 111 .

With the
.code @(trailer)
directive in place, the collect body, on each
iteration, only consumes the lines matched prior to
.codn @(trailer) .

.dir freeform

The
.code freeform
directive provides a useful alternative to
\*(TX's line-oriented matching discipline. The
.code freeform
directive treats all
remaining input from the current input source as one big line. The query line
which immediately follows freeform is applied to that line.

The syntax variations are:

.verb
  @(freeform)
  ... query line ..

.mets @(freeform << number )
  ... query line ..

.mets @(freeform << string )
  ... query line ..

.mets @(freeform < number << string )
  ... query line ..
.brev

where
.meta number
and
.meta string
denote \*(TL expressions which evaluate to an integer or string
value, respectively.

If
.meta number
and
.meta string
are both present, they may be given in either order.

If the
.meta number
argument is given, its value limits the range of lines which are combined
together. For instance
.code "@(freeform 5)"
means to only consider the next five lines
to to be one big line. Without this argument, freeform is "bottomless". It
can match the entire file, which creates the risk of allocating a large amount
of memory.

If the
.meta string
argument is given, it specifies a custom line terminator. The
default terminator is
.strn "\en" .
The terminator does not have to be one character long.

Freeform does not convert the entire remainder of the input into one big line
all at once, but does so in a dynamic, lazy fashion, which takes place as the
data is accessed. So at any time, only some prefix of the data exists as a flat
line in which newlines are replaced by the terminator string, and the remainder
of the data still remains as a list of lines.

After the subquery is applied to the virtual line, the unmatched remainder
of that line is broken up into multiple lines again, by looking for and
removing all occurrences of the terminator string within the flattened portion.

Care must be taken if the terminator is other than the default
.strn "\en" .
All occurrences of the terminator string are treated as line terminators in
the flattened portion of the data, so extra line breaks may be introduced.
Likewise, in the yet unflattened portion, no breaking takes place, even if
the text contains occurrences of the terminator string. The extent of data which
is flattened, and the amount of it which remains, depends entirely on the
query line underneath
.codn @(flatten) .

In the following example, lines of data are flattened using $ as the line
terminator.
.IP code:
.mono
\ @(freeform "$")
 @a$@b:
 @c
 @d
.onom

.IP data:
.mono
\ 1
 2:3
 4
.onom

.IP "output (\f[4]-B\f[]):"
.mono
\ a="1"
 b="2"
 c="3"
 d="4"
.onom
.PP

The data is turned into the virtual line
.codn 1$2:3$4$ .
The
.code @a$@b:
subquery matches
the
.code 1$2:
portion, binding
.code a
to
.strn 1 ,
and
.code b
to
.strn 2 .
The remaining portion
.code 3$4$
is then split into separate lines again according to the line terminator
.codn $i :

.verb
  3
  4
.brev

Thus the remainder of the query

.verb
  @c
  @d
.brev

faces these lines, binding
.code c
to
.code 3
and
.code d
to
.codn 4 .
Note that since the data
does not contain dollar signs, there is no ambiguity; the meaning may be
understood in terms of the entire data being flattened and split again.

In the following example,
.code freeform
is used to solve a tokenizing problem.  The
Unix password file has fields separated by colons. Some fields may be empty.
Using freeform, we can join the password file using
.str ":"
as a terminator.
By restricting freeform to one line, we can obtain each line of the password
file with a terminating
.strn ":" ,
allowing for a simple tokenization, because
now the fields are colon-terminated rather than colon-separated.

Example:

.verb
  @(next "/etc/passwd")
  @(collect)
  @(freeform 1 ":")
  @(coll)@{token /[^:]*/}:@(end)
  @(end)
.brev

.dir fuzz

The
.code fuzz
directive allows for an imperfect match spanning a set number of
lines. It takes two arguments, both of which are \*(TL expressions that should
evaluate to integers:

.mono
.meti @(fuzz m n)
  ...
.onom

This expresses that over the next
.meta n
query lines, the matching strictness
is relaxed a little bit. Only m out of those n lines have to match.
Afterward, the rest of the query follows normal, strict processing.

In the degenerate situation that there are fewer than n query lines following
the
.code fuzz
directive, then m of them must succeed nevertheless. (If there
are fewer than m, then this is impossible.)

.dirs line chr

The
.code line
and
.code chr
directives perform binding between the current input line number or character
position within a line, against an expression or variable:

.verb
  @(line 42)
  @(line x)
  abc@(chr 3)def@(chr y)
.brev

The directive
.code "@(line 42)"
means "match the current input line number against the integer 42". If
the current line is 42, then the directive matches, otherwise it fails.
.code line
is a vertical directive which doesn't consume a line of input. Thus,
the following matches at the beginning of an input stream, and
.code x
ends up bound to the first line of input:

.verb
  @(line 1)
  @(line 1)
  @(line 1)
  @x
.brev

The directive
.code "@(line x)"
binds variable
.code x
to the current input line number, if
.code x
is an unbound variable. If
.code x
is already bound, then the value of
.code x
must match the current line number, otherwise the directive fails.

The
.code chr
directive is similar to
.code line
except that it's a horizontal directive, and matches the character position
rather than the line position. Character positions are measured from zero,
rather than one.
.code chr
does not consume a character. Hence the two occurrences of
.code chr
in the following example both match, and
.code x
takes the entire line of input:

.verb
  @(chr 0)@(chr 0)@x
.brev

The argument of
.code line
or
.code chr
may be a
.codn @ -delimited
Lisp expression. This is useful for matching computed lines or
character positions:

.verb
  @(line @(+ a (* b c)))
.brev

.dir name

The
.code name
directive performs a binding between the name of the current
data source and a variable or bind expression:

.verb
  @(name na)
  @(name "data.txt")
.brev

If
.code na
is an unbound variable, it is bound and takes on the name
of the data source, such as a file name. If
.code na
is bound, then it has to match the name of the data source,
otherwise the directive fails.

The directive
.mono
@(name "data.txt")
.onom
fails unless the current data source has that name.

.dir data

The
.code data
directive performs a binding between the unmatched data
at the current position, and and a variable or bind expression.
The unmatched data takes the form of a list of strings:

.verb
  @(data d)
.brev

The binding is performed on object equality. If
.code d
is already bound, a matching failure occurs unless
.code d
contains the current unmatched data.

Matching the current data has various uses.

For instance, two branches of pattern matching can, at some point, bind the
current data into different variables. When those paths join, the variables can
be bound together to create the assertion that the current data had been the
same at those points:

.verb
  @(all)
  @  (skip)
  foo
  @  (skip)
  bar
  @  (data x)
  @(or)
  @  (skip)
  xyzzy
  @  (skip)
  bar
  @  (data y)
  @(end)
  @(require (eq x y))
.brev

Here, two branches of the
.code @(all)
match some material which ends in the line
.codn "bar" .
However, it is possible that this is a different line. The
.code data
directives are used to create an assertion that the data regions matched
by the two branches are identical. That is to say, the unmatched data
.code x
captured after the first
.code "bar"
and the unmatched data
.code y
captured after the second
.code "bar"
must be the same object in order for
.code "@(require (eq x y))"
to succeed, which implies that the same
.code "bar"
was matched in both branches of the
.codn @(all) .

Another use of
.code data
is simply to gain access to the trailing remainder of the unmatched
input in order to print it, or do some special processing on it.

The
.code tprint
Lisp function is useful for printing the unmatched data as newline-terminated
lines:

.verb
  @(data remainder)
  @(do (tprint remainder))
.brev

.dirs some all none maybe cases choose

These directives, called the parallel directives, combine multiple subqueries,
which are applied at the same input position, rather than to consecutive input.

They come in vertical (line mode) and horizontal (character mode) flavors.

In horizontal mode, the current position is understood to be a character
position in the line being processed. The clauses advance this character
position by moving it to the right.  In vertical mode, the current position is
understood to be a line of text within the stream. A clause advances the
position by some whole number of lines.

The syntax of these parallel directives follows this example:

.verb
  @(some)
  subquery1
  .
  .
  .
  @(and)
  subquery2
  .
  .
  .
  @(and)
  subquery3
  .
  .
  .
  @(end)
.brev

And in horizontal mode:

.verb
  @(some)subquery1...@(and)subquery2...@(and)subquery3...@(end)
.brev

Long horizontal lines can be broken up with line continuations, allowing the
above example to be written like this, which is considered a single logical
line:

.verb
  @(some)@\e
     subquery1...@\e
  @(and)@\e
     subquery2...@\e
  @(and)@\e
     subquery3...@\e
  @(end)
.brev

The
.codn @(some) ,
.codn @(all) ,
.codn @(none) ,
.codn @(maybe) ,
.code @(cases)
or
.code @(choose)
must be followed
by at least one subquery clause, and be terminated by
.codn @(end) .
If there are two
or more subqueries, these additional clauses are indicated by
.code @(and)
or
.codn @(or) ,
which are interchangeable.  The separator and terminator directives also must
appear as the only element in a query line.

The
.code choose
directive requires keyword arguments. See below.

The syntax supports arbitrary nesting. For example:

.verb
  QUERY:            SYNTAX TREE:

  @(all)            all -+
  @  (skip)              +- skip -+
  @  (some)              |        +- some -+
  it                     |        |        +- TEXT
  @  (and)               |        |        +- and
  @    (none)            |        |        +- none -+
  was                    |        |        |        +- TEXT
  @    (end)             |        |        |        +- end
  @  (end)               |        |        +- end
  a dark                 |        +- TEXT
  @(end)                 *- end
.brev

nesting can be indicated using whitespace between
.code @
and the
directive expression. Thus, the above is an
.code @(all)
query containing a
.code @(skip)
clause which applies to a
.code @(some)
that is followed by the text line
.strn "a dark" .
The
.code @(some)
clause combines the text line
.strn it ,
and a
.code @(none)
clause which contains just one clause consisting of the line
.strn was .

The semantics of the parallel directives is:

.coIP @(all)
Each of the clauses is matched at the current position. If any of the
clauses fails to match, the directive fails (and thus does not produce
any variable bindings). Clauses following the failed directive are not
evaluated. Bindings extracted by a successful clause are visible to the clauses
which follow, and if the directive succeeds, all of the combined bindings
emerge.

.meIP @(some [ :resolve >> ( var ...) ])
Each of the clauses is matched at the current position. If any of the clauses
succeed, the directive succeeds, retaining the bindings accumulated by the
successfully matching clauses.  Evaluation does not stop on the first successful
clause. Bindings extracted by a successful clause are visible to the clauses
which follow.

The
.code :resolve
parameter is for situations when the
.code @(some)
directive has
multiple clauses that need to bind some common variables to different
values: for instance, output parameters in functions. Resolve takes
a list of variable name symbols as an argument.  This is called the
resolve set. If the clauses of
.code @(some)
bind variables in the resolve
set, those bindings are not visible to later clauses.  However, those
bindings do emerge out of the
.code @(some)
directive as a whole.
This creates a conflict: what if two or more clauses introduce
different bindings for a variable in the resolve set?
This is why it is called the resolve set: conflicts for variables in the
resolve set are automatically resolved in favor of later directives.

Example:

.verb
  @(some :resolve (x))
  @  (bind a "a")
  @  (bind x "x1")
  @(or)
  @  (bind b "b")
  @  (bind x "x2")
  @(end)
.brev

Here, the two clauses both introduce a binding for
.codn x .
Without the
.code :resolve
parameter, this would mean that the second clause fails, because
.code x
comes in
with the value
.strn x1 ,
which does not bind with
.strn x2 .
But because
.code x
is placed
into the resolve set, the second clause does not see the 
.str x1
binding. Both
clauses establish their bindings independently creating a conflict over
.codn x .
The conflict is resolved in favor of the second clause, and so the bindings
which emerge from the directive are:

.verb
  a="a"
  b="b"
  x="x2"
.brev

.coIP @(none)
Each of the clauses is matched at the current position. The
directive succeeds only if all of the clauses fail. If
any clause succeeds, the directive fails, and subsequent clauses are not
evaluated. Thus, this directive never produces variable bindings, only matching
success or failure.

.coIP @(maybe)
Each of the clauses is matched at the current position.  The directive always
succeeds, even if all of the clauses fail.  Whatever bindings are found in any
of the clauses are retained. Bindings extracted by any successful clause are
visible to the clauses which follow.

.coIP @(cases)
Each of the clauses is matched at the current position.
The clauses are matched, in order, at the current position.
If any clause matches, the matching stops and the bindings
collected from that clause are retained. Any remaining clauses
after that one are not processed. If no clause matches, the
directive fails, and produces no bindings.

.meIP @(choose [ :longest < var | :shortest < var ])
Each of the clauses is matched at the current position in order. In this
construct, bindings established by an earlier clause are not visible to later
clauses.  Although any or all of the clauses can potentially match, the clause
which succeeds is the one which maximizes or minimizes the length of the
text bound to the specified variable. The other clauses have no effect.

For all of the parallel directives other than
.code @(none)
and
.codn @(choose) ,
the query
advances the input position by the greatest number of lines that match in any
of the successfully matching subclauses that are evaluated.  The
.code @(none)
directive does not advance the input position.

For instance if there are two subclauses, and one of them matches three lines,
but the other one matches five lines, then the overall clause is considered to
have made a five line match at its position. If more directives follow, they
begin matching five lines down from that position.

.dir require

The syntax of
.code @(require)
is:

.mono
.mets @(require << lisp-expression )
.onom

The
.code require
directive evaluates a \*(TL expression. (See TXR LISP far
below.) If the expression yields a true value, then it succeeds, and matching
continues with the directives which follow. Otherwise the directive fails.

In the context of the
.code require
directive, the expression should not be introduced by the
.code @
symbol; it is expected to be a Lisp expression.

Example:

.verb
  @; require that 4 is greater than 3
  @; This succeeds; therefore, @a is processed
  @(require (> (+ 2 2) 3))
  @a
.brev

.dir if

The
.code if
directive allows for conditional selection of pattern matching clauses,
based on the Boolean results of Lisp expressions.

A variant of the
.code if
directive is also available for use inside an
.code output
clauses, where it similarly allows for the conditional selection of output
clauses.

The syntax of the
.code if
directive can be exemplified as follows:

.mono
.mets @(if << lisp-expr )
  .
  .
  .
.mets @(elif << lisp-expr )
  .
  .
  .
.mets @(elif << lisp-expr )
  .
  .
  .
  @(else)
  .
  .
  .
  @(end)
.onom

The
.code @(elif)
and
.code @(else)
clauses are all optional. If
.code @(else)
is present, it must be
last, before
.codn @(end) ,
after any
.code @(elif)
clauses. Any of the clauses may be empty.

.TP* "Example:"

.verb
  @(if (> (length str) 42))
  foo: @a @b
  @(else)
  {@c}
  @(end)
.brev

In this example, if the length of the variable
.code str
is greater than
.codn 42 ,
then matching continues with
.strn "foo: @a b" ,
otherwise it proceeds with
.codn {@c} .

More precisely, how the
.code if
directive works is as follows. The Lisp expressions are evaluated in order,
starting with the
.code if
expression, then the
.code elif
expressions if any are present. If any Lisp expression yields a true result
(any value other than
.codn nil )
then evaluation of Lisp expressions stops. The corresponding clause of that
Lisp expression is selected and pattern matching continues
with that clauses. The result of that clause (its success or failure,
and any newly bound variables) is then taken as the result of the
.code if
directive. If none of the Lisp expressions yield true, and an
.code else
clause is present, then that clause is processed and its result determines
the result of the
.code if
directive. If none of the Lisp expressions
yield true, and there is no
.code else
clause, then the
.code if
directive is deemed to have trivially succeeded, allowing matching to continue
with whatever directive follows it.

.coNP The Lisp @ if versus TXR @ if

The
.code @(output)
directive supports the embedding of Lisp expressions, whose values are
interpolated into the output. In particular, Lisp
.code if
expressions are useful. For instance
.code "@(if expr \(dqA\(dq \(dqB\(dq)"
reproduces
.code A
if
.code expr
yields a true value, otherwise
.codn B .
Yet the
.code @(if)
directive is also supported in
.codn @(output) .
How the apparent conflict between the two is resolved is that the two take
different numbers of arguments. An
.code @(if)
which has no arguments at all is a syntax error. One that has one argument
is the head of the
.code if
directive syntax which must be terminated by
.code @(end)
and which takes the optional
.code @(elif)
and
.code @(else)
clauses. An
.code @(if)
which has two or more arguments is parsed as a self-contained Lisp expression.

.dir gather

Sometimes text is structured as items that can appear in an arbitrary order.
When multiple matches need to be extracted, there is a combinatorial explosion
of possible orders, making it impractical to write pattern matches for all
the possible orders.

The
.code gather
directive is for these situations. It specifies multiple clauses
which all have to match somewhere in the data, but in any order.

For further convenience, the lines of the first clause of the
.code gather
directive
are implicitly treated as separate clauses.

The syntax follows this pattern

.verb
  @(gather)
  one-line-query1
  one-line-query2
  .
  .
  .
  one-line-queryN
  @(and)
  multi
  line
  query1
  .
  .
  .
  @(and)
  multi
  line
  query2
  .
  .
  .
  @(end)
.brev

The multi-line clauses are optional.   The
.code gather
directive takes
keyword parameters, see below.

.coNP The @ until / @ last clause in @ gather

Similarly to
.codn collect ,
.code gather
has an optional
.cod3 until / last
clause:

.verb
  @(gather)
  ...
  @(until)
  ...
  @(end)
.brev

How gather works is that the text is searched for matches for the single line
and multi-line queries. The clauses are applied in the order in which they appear.
Whenever one of the clauses matches, any bindings it produces are retained and
it is removed from further consideration. Multiple clauses can match at the
same text position.  The position advances by the longest match from among the
clauses which matched.  If no clauses match, the position advances by one line.
The search stops when all clauses are eliminated, and then the cumulative
bindings are produced.  If the data runs out, but unmatched clauses remain, the
directive fails.

Example: extract several environment variables, which do not appear in a particular
order:

.verb
  @(next :env)
  @(gather)
  USER=@USER
  HOME=@HOME
  SHELL=@SHELL
  @(end)
.brev

If the until or last clause is present and a match occurs, then the matches
from the other clauses are discarded and the gather terminates. The difference
between
.cod3 until / last
is that any bindings bindings established in last are
retained, and the input position is advanced past the matched material.
The
.cod3 until / last
clause has visibility to bindings established in the
previous clauses in that same iteration, even though those bindings
end up thrown away.

For consistency, the
.code :mandatory
keyword is supported in the
.cod3 until / last
clause of
.codn gather .
The semantics of using
.code :mandatory
in this situation is tricky. In particular, if it is in effect, and the
.code gather
terminates successfully by collecting all required matches, it will
trigger a failure. On the other hand, if the
.code until
or
.code last
clause activates before all required matches are gathered, a failure
also occurs, whether or not the clause is
.codn :mandatory .

Meaningful use of
.code :mandatory
requires that the gather be open-ended; it must allow some (or all) variables
not to be required. The presence of the option means that for the gather
to succeed, all required variables must be gathered first, but then termination
must be achieved via the
.cod3 until / last
clause before all gather clauses are satisfied.

.coNP Keyword parameters in @ gather
The
.code gather
directive accepts the keyword parameter
.codn :vars .
The argument to
.code :vars
is a list of required and optional variables. A required variable is specified
as a symbol. An optional variable is specified as a two element list which
pairs a symbol with a Lisp expression. That Lisp expression is evaluated
and specifies the default value for the variable.

Example:

.verb
  @(gather :vars (a b c (d "foo")))
  ...
  @(end)
.brev

Here,
.codn a ,
.code b
and
.code c
are required variables, and
.code d
is optional, with the default value given by the Lisp expression
.strn foo .

The presence of
.code :vars
changes the behavior in three ways.

Firstly, even if all the clauses in the gather match successfully and are
eliminated, the directive will fail if the required variables do not have
bindings. It doesn't matter whether the bindings are existing, or whether they
are established by the gather.

Secondly, if some of the clauses of the gather did not match, but all
of the required variables have bindings, then the directive succeeds.
Without the presence of
.codn :vars ,
it would fail in this situation.

Thirdly, if
.code gather
succeeds (all required variables have bindings),
then all of the optional variables which do not have bindings are given
bindings to their default values.

The expressions which give the default values are evaluated whenever
the
.code gather
directive is evaluated, whether or not their values are used.

.dir collect

The syntax of the
.code collect
directive is:

.verb
  @(collect)
  ... lines of subquery
  @(end)
.brev

or with an until or last clause:

.verb
  @(collect)
  ... lines of subquery: main clause
  @(until)
  ... lines of subquery: until clause
  @(end)

  @(collect)
  ... lines of subquery: main clause
  @(last)
  ... lines of subquery: last clause
  @(end)
.brev

The
.code repeat
symbol may be specified instead of
.codn collect ,
which changes the meaning, see below:

.verb
  @(repeat)
  ... lines of subquery
  @(end)
.brev

The subquery is matched repeatedly, starting at the current line.
If it fails to match, it is tried starting at the subsequent line.
If it matches successfully, it is tried at the line following the
entire extent of matched data, if there is one. Thus, the collected regions do
not overlap. (Overlapping behavior can be obtained: see the
.code @(trailer)
directive).

Unless certain keywords are specified, or unless the collection is explicitly
failed with
.codn @(fail) ,
it always succeeds, even if it collects nothing,
and even if the
.cod3 until / last
clause never finds a match.

If no
.cod3 until / last
last clause is specified, and the collect is not limited
using parameters, the collection is unbounded: it consumes the entire data
file.

.coNP The @ until / @ last clause in @ collect

If an
.cod3 until / last
last clause is specified, the collection stops when that clause
matches at the current position.

If an
.code until
clause terminates collect, no bindings are collected at that
position, even if the main clause matches at that position also. Moreover, the
position is not advanced.  The remainder of the query begins matching at that
position.

If a last clause terminates collect, the behavior is different. Any bindings
captured by the main clause are thrown away, just like with the until clause.
However, the bindings in the last clause itself survive, and the position is
advanced to skip over that material.

Example:
.IP code:
.mono
\ @(collect)
 @a
 @(until)
 42
 @b
 @(end)
 @c
.onom
.IP data:
.mono
\ 1
 2
 3
 42
 5
 6
.onom
.IP result:
.mono
\ a[0]="1"
 a[1]="2"
 a[2]="3"
 c="42"
.onom
.PP

The line
.code 42
is not collected, even though it matches
.codn @a .
Furthermore,
the
.code @(until)
does not advance the position, so variable
.code c
takes
.codn 42 .

If the
.code @(until)
is changed to
.code @(last)
the output will be different:
.IP result:
.mono
\ a[0]="1"
 a[1]="2"
 a[2]="3"
 b="5"
 c="6"
.onom
.PP

The
.code 42
is not collected into the a list, just like before. But now
the binding captured by
.code @b
emerges. Furthermore, the position advances
so variable now takes
.codn 6 .

The binding variables within the clause of a collect are treated specially.
The multiple matches for each variable are collected into lists,
which then appear as array variables in the final output.

Example:
.IP code:
.mono
\ @(collect)
 @a:@b:@c
 @(end)
.onom
.IP data:
.mono
\ John:Doe:101
 Mary:Jane:202
 Bob:Coder:313
.onom
.IP result:
.mono
\ a[0]="John"
 a[1]="Mary"
 a[2]="Bob"
 b[0]="Doe"
 b[1]="Jane"
 b[2]="Coder"
 c[0]="101"
 c[1]="202"
 c[2]="313"
.onom
.PP

The query matches the data in three places, so each variable becomes
a list of three elements, reported as an array.

Variables with list bindings may be referenced in a query. They denote a
multiple match. The
.code -D
command line option can establish a one-dimensional
list binding.

The clauses of
.code collect
may be nested.   Variable matches collated into lists in an
inner collect, are again collated into nested lists in the outer collect.
Thus an unbound variable wrapped in N nestings of
.code @(collect)
will
be an N-dimensional list. A one dimensional list is a list of strings;
a two dimensional list is a list of lists of strings, etc.

It is important to note that the variables which are bound within the main
clause of a collect. That is, the variables which are subject to
collection appear, within the collect, as normal one-value bindings. The
collation into lists happens outside of the collect. So for instance in the
query:

.mono
 @(collect)
 @x=@x
 @(end)
.onom

The left
.code @x
establishes a binding for some material preceding an equal sign.
The right
.code @x
refers to that binding. The value of
.code @x
is different in each
iteration, and these values are collected. What finally comes out of the
collect clause is a single variable called
.code x
which holds a list containing each value that
was ever instantiated under that name within the collect clause.

Also note that the until clause has visibility over the bindings
established in the main clause. This is true even in the terminating
case when the until clause matches, and the bindings of the main clause
are discarded.

.coNP Keyword parameters in @ collect
By default,
.code collect
searches the rest of the input indefinitely,
or until the
.cod3 until / last
clause matches. It skips arbitrary amounts of
nonmatching material before the first match, and between matches.

Within the
.code @(collect)
syntax, it is possible to specify keyword
parameters for additional control of the behavior. A keyword parameter
consist of a keyword symbol followed by an argument, enclosed within
the
.code @(collect)
syntax. The following are the supported keywords.

.meIP :maxgap < n
The
.code :maxgap
keyword takes a numeric argument
.metn n ,
which is a Lisp expression.
It causes the collect to terminate
if it fails to find a match after skipping
.meta n
lines from the starting position,
or more than
.meta n
lines since any successful match. For example,

.verb
  @(collect :maxgap 5)
.brev

specifies that the gap between the current position and the first
match for the body of the collect, or between consecutive matches
can be no longer than five lines. A
.code :maxgap
value of
.code 0
means that the collected regions must be
adjacent and must match right from the starting position. For instance:

.verb
  @(collect :maxgap 0)
  M @a
  @(end)
.brev

means: from here, collect consecutive lines of the form
.strn "M ..." .
This will not
search for the first such line, nor will it skip lines which do not match this
form.

.meIP :mingap < n
The
.code :mingap
keyword complements
.codn :maxgap ,
though not exactly. Its argument
.metn n ,
a Lisp expression, specifies a minimum number
of lines which must separate consecutive matches. However, it has no effect on
the distance from the starting position to the first match.

.meIP :gap < n
The
.code :gap
keyword effectively specifies
.code :mingap
and
.code :maxgap
at the same time, and can only be
used if these other two are not used. Thus:

.verb
  @(collect :gap 1)
  @a
  @(end)
.brev

means: collect every other line starting with the current line.

.meIP :times < n
This shorthand means the same thing as if
.meIP :mintimes < n :maxtimes < n
were specified.  This means that exactly
.meta n
matches must occur. If fewer occur, then the collect fails.
Collect stops once it achieves
.code n
matches.

.meIP :mintimes < n
The argument
.meta n
of the
.code :mintimes
keyword is a Lisp expression which specifies that at least
.meta n
matches must occur, or else the collect fails.

.meIP :mintimes < n
The Lisp argument expression
.meta n
of the
.code :mintimes
keyword specifies that at most
.meta n
matches are collected.

.meIP :lines < n
The argument
.meta n
of the
.code :lines
keyword parameter
is a Lisp expression which specifies the upper bound on how many lines
should be scanned by collect, measuring from the starting position.
The extent of the collect body is not counted. Example:

.verb
  @(collect :lines 2)
  foo: @a
  bar: @b
  baz: @c
  @(end)
.brev

The above
.code collect
will look for a match only twice: at the current position,
and one line down.

.meIP :vars >> ({ variable | >> ( variable << default-value)}*)
The
.code :vars
keyword specifies a restriction on what variables will emanate
from the collect. Its argument is a list of variable
names. An empty list may be specified using empty parentheses
or, equivalently, the symbol
.codn nil .
The
.meta default-value
element of the syntax is a Lisp expression.
The behavior of the
.code :vars
keyword is specified in the following section, "Specifying variables in
.codn collect \(dq.

.meIP :lists <> ( variable *)
The
.code :lists
keyword indicates a list of variables. After the
.code collect
terminates, each
.meta variable
in the list which does not have a binding is bound to the empty
list symbol
.codn nil .
Unlike
.code :vars
the
.code :lists
mechanism doesn't assert that only the listed variables may emanate
from the collect. It also doesn't assert that each iteration of the
collect must bind each of those variables.

.meIP :counter >> { variable | >> ( variable << starting-value )}
The
.code :counter
keyword's argument is a variable name symbol,
or a compound expression consisting of a variable name symbol
and the \*(TL expression
.metn starting-value .
If this keyword argument is specified, then a binding for
.meta variable
is established prior to each repetition of the
.code collect
body, to an integer value representing the repetition count.
By default, repetition counts begin at zero.
If
.meta starting-value
is specified, it must evaluate to a number. This number is
then added to each repetition count, and
.meta variable
takes on the resulting displaced value.

If there is an existing binding for
.meta variable
prior to the processing of the
.codn collect ,
then the variable is shadowed.

The binding is collected in the same way as other bindings
that are established in the
.code collect
body.

The repetition count only increments after a successful match.

The
.code variable
is visible to the
.codn collect 's
.cod3 until / last
clause. If that clause is being processed after a successful match
of the body, then
.meta variable
holds an integer value. If the body fails to match, then the
.cod3 until / last
clause sees a binding for
.code variable
with a value of
.codn nil .
.PP

.coNP Specifying variables in @ collect
Normally, any variable for which a new binding occurs in a
.code collect
block is collected. A collect clause may be "sloppy": it can neglect to collect
some variables on some iterations, or bind some variables which are intended to
behave like local temporaries, but end up collated into lists. Another issue is
that the collect clause might not match anything at all, and then none of the
variables are bound.

The
.code :vars
keyword allows the query writer to add discipline the
.code collect
body.

The argument to
.code :vars
is a list of variable specs. A variable spec is either a
symbol, denoting a required variable, or a
.mono
.meti >> ( symbol << default-value )
.onom
pair, where
.meta default-value
is a Lisp expression whose value specifies a default value
for the variable, which is optional.

When a
.code :vars
list is specified, it means that only the given variables can
emerge from the successful collect. Any newly introduced bindings for other
variables do not propagate. More precisely,  whenever the collect body matches
successfully, the following three rules apply:
.IP 1
If
.code :vars
specifies required variables, the collect body must bind all of them,
or else must not bind any variable at all, whether listed in
.code :vars
or not, otherwise an exception of type
.code query-error
is thrown.
.IP 2
If
.code :vars
specifies required variables, and also specifies default variables,
and the collect body binds no variable at all, then the default variables
are not bound to their default values.
.IP 3
If
.code :vars
specifies optional variables, and all required variables are bound by
the collect body, then all those optional variables that are not bound
by the collect body are bound to their default values. Under this rule, if
.code :vars
specifies no required variables, that is deemed to be
logically equivalent to all required variables being bound.
.PP

In the event that
.code collect
does not match anything, the variables
specified in
.codn :vars ,
whether required or optional, are all bound to
empty lists. These bindings are established after the processing of the
.cod3 until / last
last clause, if present.

Example:

.verb
  @(collect :vars (a b (c "foo")))
  @a @c
  @(end)
.brev

Here, if the body
.str @a @c
matches, an error will be thrown because one of the
mandatory variables is
.codn b ,
and the body neglects to produce a binding for
.codn b .

Example:

.verb
  @(collect :vars (a (c "foo")))
  @a @b
  @(end)
.brev

Here, if
.str @a @b
matches, only
.code a
will be collected, but not
.codn b ,
because
.code b
is not
in the variable list. Furthermore, because there is no binding for
.code c
in the
body, a binding is created with the value
.strn foo ,
exactly as if
.code c
matched
such a piece of text.

In the following example, the assumption is that
.code "THIS NEVER MATCHES"
is not found anywhere in the input but the line
.code "THIS DOES MATCH"
is found and has a successor which is bound to
.codn a .
Because the body did not
match, the
.code :vars
.code a
and
.code b
should be bound to empty lists. But
.code a
is bound by the last clause to some text, so this takes precedence. Only
.code b
is bound to an empty list.

.verb
  @(collect :vars (a b))
  THIS NEVER MATCHES
  @(last)
  THIS DOES MATCH
  @a
  @(end)
.brev

The following means: do not allow any variables to propagate out of any
iteration of the collect and therefore collect nothing:

.verb
  @(collect :vars nil)
  ...
  @(end)
.brev

Instead of writing
.codn "@(collect :vars nil)" ,
it is possible to write
.codn @(repeat) .
.code @(repeat)
takes all collect keywords, except for
.codn :vars .
There is a
.code @(repeat)
directive used in
.code @(output)
clauses; that is a different directive.

.coNP Mandatory @ until and @ last

The
.cod3 until / last
clause supports the option keyword
.codn :mandatory ,
exemplified by the following:

.verb
  @(collect)
  ...
  @(last :mandatory)
  ...
  @(end)
.brev

This means that the collect
.B must
be terminated by a match for the
.cod3 until / last
clause, or else by an explicit
.codn @(accept) .

Specifically, the collect cannot terminate due to simply running out of data,
or exceeding a limit on the number of matches that may be collected. In
those situations, if an
.code until
or
.code last
clause is present with
.codn :mandatory ,
the collect is deemed to have failed.

.dir coll

The
.code coll
directive is the horizontal version of
.codn collect .
Whereas
.code collect
works with multi-line clauses on line-oriented
material,
.code coll
works within a single line. With
.codn coll ,
it is possible to
recognize repeating regularities within a line and collect lists.

Regular-expression based Positive Match variables work well with coll.

Example: collect a comma-separated list, terminated by a space.
.IP code:
.mono
\ @(coll)@{A /[^, ]+/}@(until) @(end)@B
.onom
.IP data:
.mono
\ foo,bar,xyzzy blorch
.onom
.IP result:
.mono
\ A[0]="foo"
 A[1]="bar"
 A[2]="xyzzy"
 B=blorch
.onom
.PP

Here, the variable
.code A
is bound to tokens which match the regular
expression
.codn "/[^, ]+/" :
non-empty sequence of characters other than commas or
spaces.

Like
.codn collect ,
.code coll
searches for matches.  If no match
occurs at the current character position, it tries at the next character
position. Whenever a match occurs, it continues at the character position which
follows the last character of the match, if such a position exists.

If not bounded by an until clause, it will exhaust the entire line.  If the
until clause matches, then the collection stops at that position,
and any bindings from that iteration are discarded.
Like collect, coll also supports an
.cod3 until / last
clause, which propagates variable
bindings and advances the position. The
.code :mandatory
keyword is supported.

.code coll
clauses nest, and variables bound within a coll are available to clauses
within the rest of the
.code coll
clause, including the
.cod3 until / last
clause, and appear as
single values. The final list aggregation is only visible after the
.code coll
clause.

The behavior of
.code coll
leads to difficulties when a delimited variable are used
to match material which is delimiter separated rather than terminated.
For instance, entries in a comma-separated files usually do
not appear as
.str a,b,c,
but rather
.strn a,b,c .

So for instance, the following result is not satisfactory:
.IP code:
.mono
\ @(coll)@a @(end)
.onom
.IP data:
.mono
\ 1 2 3 4 5
.onom
.IP result:
.mono
\ a[0]="1"
 a[1]="2"
 a[2]="3"
 a[3]="4"
.onom
.PP

The
.code 5
is missing because it isn't followed by a space, which the text-delimited
variable match
.str "@a "
looks for.  After matching "4 ", coll continues to look for
matches, and doesn't find any.  It is tempting to try to fix it like this:
.IP code:
.mono
\ @(coll)@a@/ ?/@(end)
.onom
.IP data:
.mono
\ 1 2 3 4 5
.onom
.IP result:
.mono
\ a[0]=""
 a[1]=""
 a[2]=""
 a[3]=""
 a[4]=""
 a[5]=""
 a[6]=""
 a[7]=""
 a[8]=""
.onom
.PP

The problem now is that the regular expression
.code "/ ?/"
(match either a space or nothing), matches at any position.
So when it is used as a variable
delimiter, it matches at the current position, which binds the empty string to
the variable, the extent of the match being zero. In this situation, the
.code coll
directive proceeds character by character. The solution is to use
positive matching: specify the regular expression which matches the item,
rather than a trying to match whatever follows.  The
.code collect
directive will
recognize all items which match the regular expression:
.IP code:
.mono
\ @(coll)@{a /[^ ]+/}@(end)
.onom
.IP data:
.mono
\ 1 2 3 4 5
.onom
.IP result:
.mono
\ a[0]="1"
 a[1]="2"
 a[2]="3"
 a[3]="4"
 a[4]="5"
.onom
.PP

The
.code until
clause can specify a pattern which, when recognized, terminates
the collection. So for instance, suppose that the list of items may
or may not be terminated by a semicolon. We must exclude
the semicolon from being a valid character inside an item, and
add an until clause which recognizes a semicolon:
.IP code:
.mono
\ @(coll)@{a /[^ ;]+/}@(until);@(end);
.onom
.IP data:
.mono
\ 1 2 3 4 5;
.onom
.IP result:
.mono
\ a[0]="1"
 a[1]="2"
 a[2]="3"
 a[3]="4"
 a[4]="5"
.onom
.PP

Whether followed by the semicolon or not, the items are collected properly.

Note that the
.code @(end)
is followed by a semicolon. That's because
when the
.code @(until)
clause meets a match, the matching material
is not consumed.

This repetition can be avoided by using
.code @(last)
instead of
.code @(until)
since
.code @(last)
consumes the terminating material.

Instead of the above regular-expression-based approach, this extraction problem
can also be solved with
.codn cases :
.IP code:
.mono
\ @(coll)@(cases)@a @(or)@a@(end)@(end)
.onom
.IP data:
.mono
\ 1 2 3 4 5
.onom
.IP result:
.mono
\ a[0]="1"
 a[1]="2"
 a[2]="3"
 a[3]="4"
 a[4]="5"
.onom
.PP

.coNP Keyword parameters in @ coll
The
.code @(coll)
directive takes most of the same parameters as
.codn @(collect) .
See the section Keyword parameters in
.code collect
above.
So for instance
.code "@(coll :gap 0)"
means that the collects must be
consecutive, and
.code "@(coll :maxtimes 2)"
means that at most two matches
will be collected.  The
.code :lines
keyword does not exist, but there is
an analogous
.code :chars
keyword.

The
.code @(coll)
directive takes the
.code :vars
keyword.

The shorthand
.code @(rep)
may be used instead of
.codn "@(coll :vars nil)" .
.code @(rep)
takes all keywords, except
.codn :vars .

.dir flatten

The
.code flatten
directive can be used to convert variables to one dimensional
lists. Variables which have a scalar value are converted to lists containing
that value. Variables which are multidimensional lists are flattened to
one-dimensional lists.

Example (without
.codn @(flatten) )
.IP code:
.mono
\ @b
 @(collect)
 @(collect)
 @a
 @(end)
 @(end)
.onom
.IP data:
.mono
\ 0
 1
 2
 3
 4
 5
.onom
.IP result:
.mono
\ b="0"
 a_0[0]="1"
 a_1[0]="2"
 a_2[0]="3"
 a_3[0]="4"
 a_4[0]="5"
.onom
.PP

Example (with
.codn @(flatten) ):
.IP code:
.mono
\ @b
 @(collect)
 @(collect)
 @a
 @(end)
 @(end)
 @(flatten a b)
.onom
.IP data:
.mono
\ 0
 1
 2
 3
 4
 5
.onom
.IP result:
.mono
\ b="0"
 a[0]="1"
 a[1]="2"
 a[2]="3"
 a[3]="4"
 a[4]="5"
.onom
.PP


.dir merge

The syntax of
.code merge
follows the pattern:

.mono
.meti @(merge < destination >> [ sources ...])
.onom

.meta destination
is a variable, which receives a new binding.
.meta sources
are bind expressions.

The
.code merge
directive provides a way of combining collected data from multiple
nested lists in a way which normalizes different nesting levels
among the sources.  This directive is useful for combining the results from
collects at different levels of nesting into a single nested list such that
parallel elements are at equal depth.

A new binding is created for the
.meta destination
variable, which holds the result of the operation.

The
.code merge
directive performs its special function if invoked with at least three
arguments: a destination and two sources.

The one-argument case
.code "@(merge x)"
binds a new variable
.code x
and initializes it with the empty list and is thus equivalent to
.codn "@(bind x)" .
Likewise, the two-argument case
.code "@(merge x y)"
is equivalent to
.codn "@(bind x y)" ,
establishing a binding for
.code x
which is initialized with the value of
.codn y .

To understand what merge does when two sources are given, as in
.codn "@(merge C A B)" ,
we first have
to define a property called depth.  The depth of an atom such as a string is
defined as
.codn 1 .
The depth of an empty
list is
.codn 0 .
The depth of a nonempty list is one plus the depth of its deepest
element. So for instance
.str foo
has depth 1,
.mono
("foo")
.onom
has depth 2, and
.mono
("foo" ("bar"))
.onom
has depth three.

We can now define a binary (two argument) merge(A, B) function as follows.
First, merge(A, B) normalizes the values A and B
to produce a pair of values which have equal depth, as defined above.
If either value is an atom it is first converted
to a one-element list containing that atom. After this step, both
values are lists; and the only way an argument has depth zero is if it is an
empty list.  Next, if either value has a smaller depth than the
other, it is wrapped in a list as many times as needed to give it equal depth.
For instance if A is
.code ("a")
and B is
.code "((((\(dqb\(dq \(dqc\(dq) (\(dqd\(dq \(dqe))))"
then A is converted to
.codn "((((\(dqa\(dq))))" .
Finally, the list values are appended together to produce the merged result.
In the case of the preceding two example values, the result is:
.codn "((((\(dqa\(dq))) (((\(dqb\(dq \(dqc\(dq) (\(dqd\(dq \(dqe))))" .
The result is stored into a the newly bound destination variable
.codn C .

If more than two source arguments are given, these are merged by a left-associative
reduction, which is to say that a three argument
.code "merge(X, Y, Z)"
is defined as
.codn "merge(merge(X, Y), Z)" .
The leftmost two values are merged, and then this result is merged with the third
value, and so on.

.dir cat

The
.code cat
directive converts a list variable into a single
piece of text. The syntax is:

.mono
.mets @(cat < var <> [ sep ])
.onom

The
.meta sep
argument is a Lisp expression whose value specifies a separating piece of text.
If it is omitted, then a single space is used as the separator.

Example:
.IP code:
.mono
\ @(coll)@{a /[^ ]+/}@(end)
 @(cat a ":")
.onom
.IP data:
.mono
\ 1 2 3 4 5
.onom
.IP result:
.mono
\ a="1:2:3:4:5"
.onom
.PP

.dir bind

The syntax of the
.code bind
directive is:

.mono
.mets @(bind < pattern < bind-expression >> { keyword << value }*)
.onom

The
.code bind
directive is a kind of pattern match, which matches one or more
variables given in
.meta pattern
against a value produced by the
.meta bind-expression
on the right.

Variables names occurring in the
.meta pattern
expression may refer to bound variables, or may be unbound.

All variables references occurring in
.meta bind-expression
must have value.

Binding occurs as follows. The tree structure of
.meta pattern
and the value of
.meta bind-expression
are considered to be parallel structures.

Any variables in
.meta pattern
which are unbound receive a new binding, which is initialized with
the structurally corresponding piece of the object produced by
.metn bind-expression .

Any variables in
.meta pattern
which are already bound must match the corresponding part of the
value of
.metn bind-expression ,
or else
the
.code bind
directive fails. Variables which are already bound are not altered,
retaining their current values, even if the matching is inexact.

The simplest bind is of one variable against itself, for instance bind
.code A
against
.codn A :

.verb
  @(bind A A)
.brev

This will throw an exception if
.code A
is not bound. If
.code A
is bound, it
succeeds, since
.code A
matches itself.

The next simplest bind binds one variable to another:

.verb
  @(bind A B)
.brev

Here, if
.code A
is unbound, it takes on the same value as
.codn B .
If
.code A
is bound, it has
to match
.codn B ,
or the bind fails. Matching means that either
.IP -
.code A
and
. code B
are the same text
.IP -
.code A
is text,
.code B
is a list, and
.code A
occurs within
.codn B .
.IP -
.IR "vice versa" :
.code B
is text,
.code A
is a list, and
.code B
occurs within
.codn A .
.IP -
.code A
and
.code B
are lists and are either identical, or one is
found as substructure within the other.
.PP
The right hand side does not have to be a variable. It may be some other
object, like a string, quasiliteral, regexp, or list of strings,
.IR "et cetera" .
For instance

.verb
  @(bind A "ab\etc")
.brev

will bind the string
.str ab\etc
to the variable
.code A
if
.code A
is unbound. If
.code A
is bound, this will fail unless
.code A
already contains an identical string. However, the right hand side of a bind
cannot be an unbound variable, nor a complex expression that contains unbound
variables.

The left hand side of
.code bind
can be a nested list pattern containing variables.
The last item of a list at any nesting level can be preceded by a
.code .
(dot), which means that the variable matches the rest of the list from that
position.

.TP* "Example 1:"

Suppose that the list A contains
.mono
("now" "now" "brown" "cow").
.onom
Then the
directive
.codn "@(bind (H N . C) A)" ,
assuming that
.codn H ,
.code N
and
.code C
are unbound variables,
will bind
.code H
to
.strn how ,
code N
to
.strn now ,
and
.code C
to the remainder of the list
.mono
("brown" "cow").
.onom

Example: suppose that the list
.code A
is nested to two dimensions and  contains
.mono
(("how" "now") ("brown" "cow")).
.onom
Then
.code "@(bind ((H N) (B C)) A)"
binds
.code H
to
.strn how ,
.code N
to
.strn now ,
.code B
to
.str brown
and
.code C
to
.strn cow .

The dot notation may be used at any nesting level. it must be followed
by an item.  The forms
.code (.)
and
.code "(X .)"
are invalid, but
.code "(. X)"
is valid and equivalent to
.codn X .

The number of items in a left pattern match must match the number of items in
the corresponding right side object. So the pattern
.code ()
only matches
an empty list. The notations
.code ()
and
.code nil
mean exactly the same thing.

The symbols
.codn nil ,
.code t
and keyword symbols may be used on either side.
They represent themselves.  For example
.code "@(bind :foo :bar)"
fails,
but
.code "@(bind :foo :foo)"
succeeds since the two sides denote the same
keyword symbol object.

.TP* "Example 2:"
In this example, suppose
.code A
contains
.str foo
and
.code B
contains
bar. Then
.code "@(bind (X (Y Z)) (A (B \(dqhey\(dq)))"
binds
.code X
to
.strn foo ,
.code Y
to
.str bar
and
.code Z
to
.strn hey .
This is because the
.meta bind-expression
produces the object
.mono
("foo" ("bar" "hey"))
.onom
which is then structurally matched against the pattern
.codn "(X (Y Z))" ,
and the variables receive the corresponding pieces.

.coNP Keywords in the @ bind directive
The
.code bind
directive accepts these keywords:

.coIP :lfilt
The argument to
.code :lfilt
is a filter specification. When the left side pattern
contains a binding which is therefore matched against its counterpart from the
right side expression, the left side is filtered through the filter specified
by
.code :lfilt
for the purposes of the comparison. For example:

.verb
  @(bind "a" "A" :lfilt :upcase)
.brev

produces a match, since the left side is the same as the right after
filtering through the :upcase filter.

.coIP :rfilt
The argument to
.code :rfilt
is a filter specification. The specified filter is
applied to the right hand side material prior to matching it against
the left side. The filter is not applied if the left side is a variable
with no binding. It is only applied to determine a match. Binding takes
place the unmodified right hand side object.

For example, the following produces a match:

.verb
  @(bind "A" "a" :rfilt :upcase)
.brev

.coIP :filter
This keyword is a shorthand to specify both filters to the same value.
For instance
.code ":filter :upcase"
is equivalent to
.codn ":lfilt :upcase :rfilt :upcase" .

For a description of filters, see Output Filtering below.

Compound filters like
.code "(:fromhtml :upcase)"
are supported with all these keywords. The filters apply across arbitrary
patterns and nested data.

Example:

.verb
  @(bind (a b c) ("A" "B" "C"))
  @(bind (a b c) (("z" "a") "b" "c") :rfilt :upcase)
.brev

Here, the first bind establishes the values for
.codn a ,
.code b
and
.codn c ,
and the second bind
succeeds, because the value of a matches the second element of the list
.mono
("z" "a")
.onom
if it is upcased, and likewise
.code b
matches
.str "b"
and
.code c
matches
.str c
if these are upcased.

.coNP Lisp forms in the @ bind directive

\*(TL forms, introduced by
.code @
may be used in the
.meta bind-expression
argument of
.codn bind ,
or as the entire form. This is consistent with the rules for bind expressions.

\*(TL forms can be used in the
.meta pattern
expression also.

Example:

.verb
  @(bind a @(+ 2 2))
  @(bind @(+ 2 2) @(* 2 2))
.brev

Here,
.code a
is bound to the integer
.codn 4 .
The second
.code bind
then succeeds because the forms
.code "(+ 2 2)"
and
.code "(* 2 2)"
produce equal values.

.dir set

The
.code set
directive syntactically resembles
.codn bind ,
but is not a pattern match. It overwrites
the previous values of variables with new values from the right hand side.
Each variable that is assigned must have an existing binding:
.code set
will not induce binding.

Examples follow.

Store the value of
.code A
back into
.codn A ,
an operation with no effect:

.verb
  @(set A A)
.brev

Exchange the values of
.code A
and
.codn B :

.verb
  @(set (A B) (B A))
.brev

Store a string into
.codn A :

.verb
  @(set A "text")
.brev

Store a list into
.codn A :

.verb
  @(set A ("line1" "line2"))
.brev

Destructuring assignment.
.code A
ends up with
.strn A ,
.code B
ends up with
.mono
("B1" "B2")
.onom
and
.code C
binds to
.mono
("C1" "C2").
.onom

.verb
  @(bind D ("A" ("B1" "B2") "C1" "C2"))
  @(bind (A B C) (() () ()))
  @(set (A B . C) D)
.brev

Note that
.code set
does not support a \*(TL expression on the left side, so the following
are invalid syntax:

.verb
  @(set @(+ 1 1) @(* 2 2))
  @(set @b @(list "a"))
.brev

The second one is erroneous even though there is a variable on the left.
Because it is preceded by the
.code @
escape, it is a Lisp variable, and not a pattern variable.

.dir rebind

The
.code rebind
directive resembles
.code set
but it is not an assignment.
It combines the semantics of
.codn local ,
.code bind
and
.codn set .
The expression on the right hand side is evaluated in the current
environment. Then the variables in the pattern on the left are introduced
as new bindings, whose values come from the pattern.

.code rebind
makes it easy to create temporary bindings based on existing bindings.

.verb
  @(define pattern-function (arg))
  @;; inside a pattern function:
  @(rebind recursion-level @(+ recursion-level 1))
  @;; ...
  @(end)
.brev

When the function terminates, the previous value of recursion-level
is restored. The effect is like the following, but much easier
to write and faster to execute:

.verb
  @(define pattern-function (arg))
  @;; inside a pattern function:
  @(local temp)
  @(set temp recursion-level)
  @(local recursion-level)
  @(set recursion-level @(+ temp 1))
  @;; ...
  @(end)
.brev

.dir forget

The
.code forget
has two spellings:
.code @(forget)
and
.codn @(local) .

The arguments are one or more symbols, for example:

.verb
  @(forget a)
  @(local a b c)
.brev

this can be written

.verb
  @(local a)
  @(local a b c)
.brev

Directives which follow the
.code forget
or
.code local
directive no longer see
any bindings for the symbols mentioned in that directive, and
can establish new bindings.

It is not an error if the bindings do not exist.

It is strongly recommended to use the
.code @(local)
spelling in functions,
because the forgetting action simulates local variables:
for the given symbols, the machine forgets any earlier variables
from outside of the function, and consequently, any new bindings
for those variables belong to the function. (Furthermore,
functions suppress the propagation of variables that are not
in their parameter list, so these locals will be automatically
forgotten when the function terminates.)

.dir do

The syntax of
.code @(do)
is:

.mono
.mets @(do << lisp-expression *)
.onom

The
.code do
directive evaluates zero or more \*(TL expressions. (See TXR LISP far
below.) The value of the expression is ignored, and matching
continues with the directives which follow the
.code do
directive, if any.

In the context of the
.code do
directive, the expression should not be introduced by the
.code @
symbol; it is expected to be a Lisp expression.

Example:

.verb
  @; match text into variables a and b, then insert into hash table h
  @(bind h (hash))
  @a:@b
  @(do (set [h a] b))
.brev

.dir mdo

The syntax of
.code @(mdo)
is:

.mono
.mets @(mdo << lisp-expression *)
.onom

Like the
.code do
directive,
.code mdo
(macro-time
.codn do )
evaluates zero or more \*(TL expressions. Unlike
.codn do ,
.code mdo
performs this evaluation immediately upon being parsed.
Then it disappears from the syntax.

The effect of
.code "@(mdo e0 e1 e2 ...)"
is exactly like
.code "@(do (macro-time e0 e1 e2 ...))"
except that
.code do
doesn't disappear from the syntax.

Another difference is that
.code do
can be used as a horizontal or vertical directive, whereas
.code mdo
is only vertical.

.dir in-package

The
.code in-package
directive shares the same syntax and semantics as the \*(TL macro
of the same name:

.mono
.mets (in-package << name )
.onom

The
.code in-package
directive is evaluated immediately upon being parsed,
leaving no trace in the syntax tree of the surrounding \*(TX
query.

It causes the
.code *package*
special variable to take on the package denoted by
.metn name .

The directive that
.meta name
is either a string or symbol. An error exception is thrown if
this isn't the case.  Otherwise it searches for the package.
If the package is not found, an error exception is thrown.

.SS* Blocks

.NP* Overview
Blocks are sections of a query which are either denoted by a name,
or are anonymous. They may nest: blocks can occur within blocks
and other constructs.

Blocks are useful for terminating parts of a pattern matching search
prematurely, and escaping to a higher level. This makes blocks not only
useful for simplifying the semantics of certain pattern matches,
but also an optimization tool.

Judicious use of blocks and escapes can reduce or eliminate the amount of
backtracking that \*(TX performs.

.dir block

The
.mono
.meti @(block << name )
.onom
directive introduces a named block, except when
.meta name
is the symbol
.codn nil .
The
.code @(block)
directive introduces an unnamed block, equivalent
to
.codn "@(block nil)" .

The
.code @(skip)
and
.code @(collect)
directives introduce implicit anonymous blocks,
as do function bodies.

Blocks must be terminated by
.code "@(end)"
and can be vertical:

.mono
.mets @(block <> [ name ])
  ...
.mets @(end)
.onom

or horizontal:

.mono
.mets @(block <> [ name ])...@(end)
.onom

.NP* Block Scope

The names of blocks are in a distinct namespace from the variable binding
space. So
.code "@(block foo)"
is unrelated to the variable
.codn @foo .

A block extends from the
.code "@(block ...)"
directive which introduces it,
until the matching
.codn @(end) ,
and may be empty.  For instance:

.verb
  @(some)
  abc
  @(block foo)
  xyz
  @(end)
  @(end)
.brev

Here, the block foo occurs in a
.code @(some)
clause, and so it extends to the
.code @(end)
which terminates the block.  After that
.codn @(end) ,
the name foo is not
associated with a block (is not "in scope"). The second
.code @(end)
terminates
the
.code @(some)
block.

The implicit anonymous block introduced by
.code @(skip)
has the same scope
as the
.codn @(skip) :
it extends over all of the material which follows the skip,
to the end of the containing subquery.

.NP* Block Nesting

Blocks may nest, and nested blocks may have the same names as blocks in
which they are nested. For instance:

.verb
  @(block)
  @(block)
  ...
  @(end)
  @(end)
.brev

is a nesting of two anonymous blocks, and

.verb
  @(block foo)
  @(block foo)
  @(end)
  @(end)
.brev

is a nesting of two named blocks which happen to have the same name.
When a nested block has the same name as an outer block, it creates
a block scope in which the outer block is "shadowed"; that is to say,
directives which refer to that block name within the nested block refer to the
inner block, and not to the outer one.

.NP* Block Semantics

A block normally does nothing. The query material in the block is evaluated
normally. However, a block serves as a termination point for
.code @(fail)
and
.code @(accept)
directives which are in scope of that block and refer to it.

The precise meaning of these directives is:

.meIP @(fail << name )
Immediately terminate the enclosing query block called
.metn name ,
as if that block
failed to match anything. If more than one block by that name encloses
the directive, the inner-most block is terminated. No bindings emerge from
a failed block.

.coIP @(fail)
Immediately terminate the innermost enclosing anonymous block, as if
that block failed to match.

The
.code @(fail)
directive has a vertical and horizontal form.

If the implicit block introduced by
.code @(skip)
is terminated in this manner,
this has the effect of causing
.code skip
itself to fail. I.e. the behavior
is as if skip search did not find a match for the trailing material,
except that it takes place prematurely (before the end of the available
data source is reached).

If the implicit block associated with a
.code @(collect)
is terminated this way,
then the entire
.code collect
fails. This is a special behavior, because a
collect normally does not fail, even if it matches nothing and collects nothing!

To prematurely terminate a collect by means of its anonymous block, without
failing it, use
.codn @(accept) .

.meIP @(accept << name )
Immediately terminate the enclosing query block called
.metn name ,
as if that block
successfully matched. If more than one block by that name encloses the
directive, the inner-most block is terminated.

.coIP @(accept)
Immediately terminate the innermost enclosing anonymous block, as if
that block successfully matched.

.code @(accept)
communicates the current bindings and input position to the terminated
block. These bindings and current position may be altered by special
interactions between certain directives and
.codn @(accept) ,
described in the following section. Communicating the current bindings
and input position means that the block which is terminated by
.code @(accept)
exhibits the bindings which were collected just prior to the execution
of that
.code @(accept)
and the input position which was in effect at that time.

.code @(accept)
has a vertical and horizontal form. In the horizontal form,
it communicates a horizontal input position. A horizontal input
position thus communicated will only take effect if the block being
terminated had been suspended on the same line of input.

If the implicit block introduced by
.code @(skip)
is terminated by
.codn @(accept) ,
this has the effect of causing the skip itself to succeed, as if
all of the trailing material had successfully matched.

If the implicit block associated with a
.code @(collect)
is terminated by
.codn @(accept) ,
then the collection stops. All bindings collected in the current iteration of
the collect are discarded. Bindings collected in previous iterations are
retained, and collated into lists in accordance with the semantics of collect.

Example: alternative way to achieve
.code @(until)
termination:

.verb
  @(collect)
  @  (maybe)
  ---
  @  (accept)
  @  (end)
  @LINE
  @(end)
.brev

This query will collect entire lines into a list called
.codn LINE .
However,
if the line
.code ---
is matched (by the embedded
.codn @(maybe) ),
the collection
is terminated. Only the lines up to, and not including the
.code ---
line, are collected. The effect is identical to:

.verb
  @(collect)
  @LINE
  @(until)
  ---
  @(end)
.brev

The difference (not relevant in these examples) is that the until clause has
visibility into the bindings set up by the main clause.

However, the following example has a different meaning:

.verb
  @(collect)
  @LINE
  @  (maybe)
  ---
  @  (accept)
  @  (end)
  @(end)
.brev

Now, lines are collected until the end of the data source, or until a line is
found which is followed by a
.code ---
line. If such a line is found,
the collection stops, and that line is not included in the collection!
The
.code @(accept)
terminates the process of the collect body, and so the
action of collecting the last
.code @LINE
binding into the list is not performed.
.PP

Example: communication of bindings and input position:

.IP code:
.mono
\ @(some)
 @(block foo)
 @first
 @(accept foo)
 @ignored
 @(end)
 @second
.onom
.IP data:
.mono
\ 1
 2
 3
.onom
.IP result:
.mono
\ first="1"
 second="2"
.onom
.PP

At the point where the
.code accept
occurs, the foo block has matched the first line,
bound the text
.str 1
to the variable
.codn @first .
The block is then terminated.
Not only does the
.code @first
binding emerge from this terminated block, but
what also emerges is that the block advanced the data past the first line to
the second line. Next, the
.code @(some)
directive ends, and propagates the
bindings and position. Thus the
.code @second
which follows then matches the second
line and takes the text
.strn 2 .

Example: abandonment of
.code @(some)
clause by
.codn @(accept) :

In the following query, the foo block occurs inside a maybe clause.
Inside the foo block there is a
.code @(some)
clause. Its first subclause
matches variable
.code @first
and then terminates block foo. Since block foo is
outside of the
.code @(some)
directive, this has the effect of terminating the
.code @(some)
clause:
.IP code:
.mono
\ @(maybe)
 @(block foo)
 @  (some)
 @first
 @  (accept foo)
 @  (or)
 @one
 @two
 @three
 @four
 @  (end)
 @(end)
 @second
.onom
.IP data:
.mono
\ 1
 2
 3
 4
 5
.onom
.IP result:
.mono
\ first="1"
 second="2"
.onom
.PP

The second clause of the
.code @(some)
directive, namely:

.verb
  @one
  @two
  @three
  @four
.brev

is never processed. The reason is that subclauses are processed in top
to bottom order, but the processing was aborted within the
first clause the
.codn "@(accept foo)" .
The
.code @(some)
construct never gets the
opportunity to match four lines.

If the
.code "@(accept foo)"
line is removed from the above query, the output
is different:
.IP code:
.mono
\ @(maybe)
 @(block foo)
 @  (some)
 @first
 @#          <--  @(accept foo) removed from here!!!
 @  (or)
 @one
 @two
 @three
 @four
 @  (end)
 @(end)
 @second
.onom
.IP data:
.mono
\ 1
 2
 3
 4
 5
.onom
.IP result:
.mono
\ first="1"
 one="1"
 two="2"
 three="3"
 four="4"
 second="5"
.onom
.PP

Now, all clauses of the
.code @(some)
directive have the opportunity to match.
The second clause grabs four lines, which is the longest match.
And so, the next line of input available for matching is
.codn 5 ,
which goes
to the
.code @second
variable.

.coNP Interaction Between the @ trailer and @ accept Directives

If one of the clauses which follow a
.code @(trailer)
requests a successful
termination to an outer block via
.codn @(accept) ,
then
.code @(trailer)
intercepts the escape and adjusts the data extent to the position
that it was given.

Example:
.IP code:
.mono
\ @(block)
 @(trailer)
 @line1
 @line2
 @(accept)
 @(end)
 @line3
.onom
.IP data:
.mono
\ 1
 2
 3
.onom
.IP result:
.mono
\ line1="1"
 line2="2"
 line3="1"
.onom
.PP

The variable
.code line3
is bound to
.str 1
because although
.code @(accept)
yields a data
position which has advanced to the third line, this is intercepted by
.code @(trailer)
and adjusted back to the first line. Neglecting to do this adjustment
would violate the semantics of
.codn trailer .

.coNP Interaction Between the @ next and @ accept Directives

When the clauses under a
.code next
directive are terminated by an
.codn accept ,
such that control passes to a block which surrounds that
.codn next ,
the
.code accept
is intercepted by
.codn next .

The input position being communicated by the
.code accept
is replaced with the original input position in the original
stream which is in effect prior to the
.code next
directive. The
.code accept
transfer is then resumed.

In other words,
.code accept
cannot be used to "leak" the new stream out of a
.code next
scope.

However,
.code next
has no effect on the bindings being communicated.

Example:

.mono
\ @(next "file-x")
 @(block b)
 @(next "file-y")
 @line
 @(accept b)
 @(end)
.onom

Here, the variable
.code line
matches the first line of the file
.strn file-y ,
after which an
.code accept
transfer is initiated, targeting block
.codn b .
This transfer communicates the
.code line
binding, as well as the position within
.codn file-y ,
pointing at the second line.
However, the
.code accept
traverses the
.code next
directive, causing it to be abandoned. The special unwinding
action within that directive detects this transfer and rewrites
the input position to be the original one within the stream
associated with
.strn file-x .
Note that this special handling exists in order for the behavior to be
consistent with what would happen if the
.code "@(accept b)"
were removed, and the block
.code b
terminated normally: because the inner
.code next
is nested within that block, \*(TX would backtrack to the
previous input position within
.strn file-x .

.coNP Interaction Between Functions and the @ accept directive
If a pattern function is terminated due to
.codn accept ,
the function return mechanism intercepts the
.codn accept .
The bindings being communicated by that
.code accept
are then subject to the special resolution with respect to the
function parameters, exactly as if the bindings were being
returned normally out of the function. The resolved bindings
then replace those being communicated by the
.code accept
and the
.code accept
transfer is resumed.

Example:

.mono
\ @(define fun (a))
 @  (bind a "a")
 @  (bind b "b")
 @  (accept blk)
 @(end)
 @(block blk)
 @(fun x)
 this line is skipped by accept
 @(end)
.onom

Here, the
.code accept
initiates a control transfer which communicates the
.code a
and
.code b
variable bindings which are visible in that scope. This transfer is
intercepted by the function, and the treatment of the bindings follows
to the same rules as a normal return (which, in the given function, would
readily take place if the
.code accept
directive were removed). The
.code b
variable is suppressed, because
.code b
isn't a parameter of the function. Because
.code a
.B is
a parameter, and the argument to that parameter is the unbound
variable
.codn x ,
the effect is that
.code x
is bound to the value of
.codn a .
When the accept transfer reaches block
.code blk
and terminates it, all that emerges is the
.code x
binding carrying
.strn a .

If the
.code accept
invocation is removed from
.codn fun ,
then the function returns normally, producing the
.code x
binding. In that case, the line
.code "this line is skipped by accept"
isn't skipped since the block isn't being terminated; that
line must match something.

.coNP Interaction Between @ finally and the @ accept directive
If the exception handling
.code try
directive protected body is terminated by an
.code accept
transfer, and if that
.code try
has a
.code finally
block, then there is a special interaction between the
.code finally
block and the
.code accept
transfer.

The processing of the
.code finally
block detects that it has been triggered by an
.code accept
transfer. Consequently, it retrieves the current input position
and bindings from that transfer, and uses that position and those
bindings for the processing of the
.code finally
clauses.

If the
.code finally
clauses succeed, then the new input position and new bindings
are installed into the
.code accept
control transfer and that transfer resumes.

If the
.code finally
clauses fail, then the
.code accept
transfer is converted to a
.codn fail ,
with exactly the same block as its destination.

.coNP Vertical-Horizontal Mismatch Between @ block and @ accept
The
.codn block ,
.code accept
and
.code fail
directives comes in horizontal and vertical forms.

This creates the possibility than an
.code accept
in horizontal context targets a vertical
.code block
or
.IR "vice versa" ,
raising the question of how the input position
is treated.  The semantics of this is defined.

If a horizontal-context
.code accept
targets a vertical block, the current position at the target block will be the
following line. That is to say, when the horizontal
.code accept
occurs, there is a current input line which may have unconsumed
material past the current position. If the
.code accept
communicates its input position to a vertical context, that unconsumed
material is skipped, as if it had been matched and the vertical position
is advanced to the next line.

If a horizontal block catches a vertical accept, it rejects that
.codn accept 's
position and stays at the current backtracking position for that block.
Only the bindings from the
.code accept
are retained.

.coNP Horizontal-Horizontal Mismatch between @ block and @ accept
It is possible for a horizontal
.code accept
to terminate in a horizontal block which is processing
a different line of input (or even a different input stream).
This situation is treated the same way as vertical accept terminating
in a horizontal block: the position communicated by
.code accept
is ignored, and only the bindings are taken.

.SS* Functions

.NP* Overview
\*(TX functions allow a query to be structured to avoid repetition.
On a theoretical note, because
\*(TX functions support recursion, functions enable \*(TX to match some
kinds of patterns which exhibit self-embedding, or nesting,
and thus cannot be matched by a regular language.

Functions in \*(TX are not exactly like functions in mathematics or functional
languages, and are not like procedures in imperative programming languages.
They are not exactly like macros either. What it means for a
\*(TX function to take arguments and produce a result is different from
the conventional notion of a function.

A \*(TX function may have one or more parameters. When such a function is
invoked, an argument must be specified for each parameter.  However, a special
behavior is at play here. Namely, some or all of the argument expressions may
be unbound variables.  In that case, the corresponding parameters behave like
unbound variables also.  Thus \*(TX function calls can transmit the "unbound"
state from argument to parameter.

It should be mentioned that functions have access to all bindings that are
visible in the caller; functions may refer to variables which are not
mentioned in their parameter list.

With regard to returning, \*(TX functions are also unconventional. If the
function fails, then the function call is considered to have failed. The
function call behaves like a kind of match; if the function fails, then the
call is like a failed match.

When a function call succeeds, then the bindings emanating from that function
are processed specially. Firstly, any bindings for variables which do not
correspond to one of the function's parameters are thrown away. Functions may
internally bind arbitrary variables in order to get their job done, but only
those variables which are named in the function argument list may propagate out
of the function call.  Thus, a function with no arguments can only indicate
matching success or failure, but not produce any bindings. Secondly,
variables do not propagate out of the function directly, but undergo
a renaming. For each parameter which went into the function as an unbound
variable (because its corresponding argument was an unbound variable),
if that parameter now has a value, that value is bound onto the corresponding
argument.

Example:

.verb
  @(define collect-words (list))
  @(coll)@{list /[^ \et]+/}@(end)
  @(end)
.brev

The above function
.code collect-words
contains a query which collects words from a
line (sequences of characters other than space or tab), into the list variable
called
.codn list .
This variable is named in the parameter list of the function,
therefore, its value, if it has one, is permitted to escape from the function
call.

Suppose the input data is:

.verb
  Fine summer day
.brev

and the function is called like this:

.verb
  @(collect-words wordlist)
.brev

The result (with
.codn "txr -B" )
is:

.verb
  wordlist[0]=Fine
  wordlist[1]=summer
  wordlist[1]=day
.brev

How it works is that in the function call
.codn "@(collect-words wordlist)" ,
.code wordlist
is an unbound variable. The parameter corresponding to that
unbound variable is the parameter
.codn list .
Therefore, that parameter
is unbound over the body of the function.  The function body collects the
words of
.str Fine summer day
into the variable
.codn list ,
and then
yields the that binding.   Then the function call completes by
noticing that the function parameter
.code list
now has a binding, and
that the corresponding argument
.code wordlist
has no binding. The binding
is thus transferred to the
.code wordlist
variable.  After that, the
bindings produced by the function are thrown away. The only enduring
effects are:
.IP -
the function matched and consumed some input; and
.IP -
the function succeeded; and
.IP -
the
.code wordlist
variable now has a binding.
.PP
Another way to understand the parameter behavior is that function
parameters behave like proxies which represent their arguments.  If an argument
is an established value, such as a character string or bound variable, the
parameter is a proxy for that value and behaves just like that value. If an
argument is an unbound variable, the function parameter acts as a proxy
representing that unbound variable. The effect of binding the proxy is
that the variable becomes bound, an effect which is settled when the
function goes out of scope.

Within the function, both the original variable and the proxy are
visible simultaneously, and are independent.  What if a function binds both of
them? Suppose a function has a parameter called
.codn P ,
which is called with an argument
.codn A ,
which is an unbound variable, and then, in the function, both
.code A
and
.code P
bound.  This is
permitted, and they can even be bound to different values.  However, when the
function terminates, the local binding of A simply disappears (because
the symbol
.code A
is not among the parameters of the function).
Only the value bound to
.code P
emerges, and is bound to
.codn A ,
which still appears unbound at that point. The
.code P
binding disappears also, and the net effect is that
.code A
is now bound. The "proxy" binding of
.code A
through the parameter
.code P
"wins" the conflict with the direct binding.

.NP* Definition Syntax

Function definition syntax comes in two flavors: vertical and horizontal.
Horizontal definitions actually come in two forms, the distinction
between which is hardly noticeable, and the need for which is
made clear below.

A function definition begins with a
.code "@(define ...)"
directive. For vertical
functions, this is the only element in a line.

The
.code define
symbol must be followed by a symbol, which is the name of the
function being defined. After the symbol, there is a parenthesized optional
argument list. If there is no such list, or if the list is specified as
.code ()
or
the symbol
.code nil
then the function has no parameters. Examples of valid
.code define
syntax are:

.verb
  @(define foo)
  @(define bar ())
  @(define match (a b c))
.brev

If the
.code define
directive is followed by more material on the same line, then
it defines a horizontal function:

.verb
  @(define match-x)x@(end)
.brev

If the define is the sole element in a line, then it
is a vertical function, and the function definition continues below:

.verb
  @(define match-x)
  x
  @(end)
.brev

The difference between the two is that a horizontal function matches
characters within a line, whereas a vertical function matches lines
within a stream. The former
.code match-x
matches the character
.codn x ,
advancing
to the next character position.  The latter
.code match-x
matches a line consisting
of the character
.codn x ,
advancing to the next line.

Material between
.code @(define)
and
.code @(end)
is the function body.  The define
directive may be followed directly by the
.code @(end)
directive, in which case the
function has an empty body.

Functions may be nested within function bodies. Such local functions have
dynamic scope. They are visible in the function body in which they are defined,
and in any functions invoked from that body.

The body of a function is an anonymous block. (See Blocks above).

.NP* Two Forms of The Horizontal Function

If a horizontal function is defined as the only element of a line,
it may not be followed by additional material. The following
construct is erroneous:

.verb
  @(define horiz (x))@foo:@bar@(end)lalala
.brev

This kind of definition is actually considered to be in the vertical context,
and like other directives that have special effects and that do not match
anything, it does not consume a line of input. If the above syntax were
allowed, it would mean that the line would not only define a function but also
match
.codn "lalala" .
This would, in turn, would mean that the
.code @(define)...@(end)
is
actually in horizontal mode, and so it matches a span of zero characters within
a line (which means that is would require a line of input to match: a
surprising behavior for a non-matching directive!)

A horizontal function can be defined in an actual horizontal context. This
occurs if its is in a line where it is preceded by other material.
For instance:

.verb
  X@(define fun)...@(end)Y
.brev

This is a query line which must match the text
.codn XY .
It also defines the function
.codn fun .
The main use of this form is for nested horizontal functions:

.verb
  @(define fun)@(define local_fun)...@(end)@(end)
.brev

.NP* Vertical-Horizontal Overloading

A function of the same name may be defined as both vertical and horizontal.
Both functions are available at the same time. Which one is used by
a call is resolved by context. See the section Vertical Versus Horizontal Calls
below.

.NP* Call Syntax

A function is invoked by compound directive whose first symbol is the name of
that function. Additional elements in the directive are the arguments.
Arguments may be symbols, or other objects like string and character
literals, quasiliterals ore regular expressions.

Example:
.IP code:
.mono
\ @(define pair (a b))
 @a @b
 @(end)
 @(pair first second)
 @(pair "ice" cream)
.onom
.IP data:
.mono
\ one two
 ice milk
.onom
.IP result:
.mono
\ first="one"
 second="two"
 cream="milk"
.onom
.PP

The first call to the function takes the line
.strn "one two" .
The parameter
.code a
takes
.str one
and parameter
.code b
takes
.strn two .
These are rebound to the arguments
.code first
and
.codn second .
The second call to the function binds the a parameter to the word
.strn "ice" ,
and the
.code b
is unbound, because the
corresponding argument
.code cream
is unbound. Thus inside the function,
.code a
is forced to match
.codn "ice" .
Then a space is matched and
.code b
collects the text
.strn milk .
When the function returns, the unbound
.str cream
variable gets this value.

If a symbol occurs multiple times in the argument list, it constrains
both parameters to bind to the same value. That is to say, all parameters
which, in the body of the function, bind a value, and which are all derived
from the same argument symbol must bind to the same value. This is settled when
the function terminates, not while it is matching. Example:
.IP code:
.mono
\ @(define pair (a b))
 @a @b
 @(end)
 @(pair same same)
.onom
.IP data:
.mono
\ one two
.onom
.IP result:
.mono
\ [query fails]
.onom
.PP

Here the query fails because
.code a
and
.code b
are effectively proxies for the same unbound variable
.code same
and are bound to different values, creating a conflict which
constitutes a match failure.

.NP* Vertical Versus Horizontal Calls

A function call which is the only element of the query line in
which it occurs is ambiguous. It can go either to a vertical
function or to the horizontal one. If both are defined, then
it goes to the vertical one.

Example:
.IP code:
.mono
\ @(define which (x))@(bind x "horizontal")@(end)
 @(define which (x))
 @(bind x "vertical")
 @(end)
 @(which fun)
.onom
.IP result:
.mono
\ fun="vertical"
.onom
.PP

Not only does this call go to the vertical function, but
it is in a vertical context.

If only a horizontal function is defined, then that is the one which is called,
even if the call is the only element in the line. This takes place in a
horizontal character-matching context, which requires a line of input which can
be traversed:

Example:
.IP code:
.mono
\ @(define which (x))@(bind x "horizontal")@(end)
 @(which fun)
.onom
.IP data:
.mono
\ ABC
.onom
.IP result:
.mono
\ [query fails]
.onom
.PP

The query fails because since
.code "@(which fun)"
is in horizontal mode,
it matches characters in a line. Since the function body consists
only of
.code "@(bind ...)"
which doesn't match any characters, the function
call requires an empty line to match. The line
.code ABC
is not empty,
and so there is a matching failure. The following
example corrects this:

Example:
.IP code:
.mono
\ @(define which (x))@(bind x "horizontal")@(end)
 @(which fun)
.onom
.IP data:
.mono
\ [empty line]
.onom
.IP result:
.mono
\ fun="horizontal"
.onom
.PP

A call made in a clearly horizontal context will prefer the
horizontal function, and only fall back on the vertical one
if the horizontal one doesn't exist. (In this fall-back case,
the vertical function is called with empty data; it is useful
for calling vertical functions which process arguments and
produce values.)

In the next example, the call is followed by trailing material,
placing it in a horizontal context. Leading material will
do the same thing:

Example:
.IP code:
.mono
\ @(define which (x))@(bind x "horizontal")@(end)
 @(define which (x))
 @(bind x "vertical")
 @(end)
 @(which fun)B
.onom
.IP data:
.mono
\ B
.onom
.IP result:
.mono
\ fun="horizontal"
.onom
.PP

.NP* Local Variables

As described earlier, variables bound in a function body which are not
parameters of the function are discarded when the function returns. However,
that, by itself, doesn't make these variables local, because pattern functions
have visibility to all variables in their calling environment. If a variable
.code x
exists already when a function is called, then an attempt to bind it inside a
function may result in a failure.  The
.code local
directive must be used in a
pattern function to list which variables are local. 

Example:

.verb
  @(define path (path))@\e
    @(local x y)@\e
    @(cases)@\e
      (@(path x))@(path y)@(bind path `(@x)@y`)@\e
    @(or)@\e
      @{x /[.,;'!?][^ \et\ef\ev]/}@(path y)@(bind path `@x@y`)@\e
    @(or)@\e
      @{x /[^ .,;'!?()\et\ef\ev]/}@(path y)@(bind path `@x@y`)@\e
    @(or)@\e
      @(bind path "")@\e
    @(end)@\e
  @(end)
.brev

This is a horizontal function which matches a path, which lands into four
recursive cases. A path can be parenthesized path followed by a path; it can be
a certain character followed by a path, or it can be empty

This function ensures that the variables it uses internally,
.code x
and
.codn y ,
do not have anything to do with any inherited bindings for
.code x
and
.codn y .

Note that the function is recursive, which cannot work without
.code x
and
.code y
being local, even if no such bindings exist prior to the top-level invocation of the
function. The invocation
.code "@(path x)"
causes
.code x
to be bound, which is
visible inside the invocation
.codn "@(path y)" ,
but that invocation needs to have its own binding of
.code x
for local use.

.NP* Nested Functions

Function definitions may appear in a function. Such definitions
are visible in all functions which are invoked from the body
(and not necessarily enclosed in the body). In other words, the
scope is dynamic, not lexical.  Inner definitions shadow outer
definitions. This means that a caller can redirect the function
calls that take place in a callee, by defining local functions
which capture the references.

Example:
.IP code:
.mono
\ @(define which)
 @  (fun)
 @(end)
 @(define fun)
 @  (output)
 top-level fun!
 @  (end)
 @(end)
 @(define callee)
 @  (define fun)
 @    (output)
 local fun!
 @    (end)
 @  (end)
 @  (which)
 @(end)
 @(callee)
 @(which)
.onom
.IP output:
.mono
\ local fun!
 top-level fun!
.onom
.PP

Here, the function
.code which
is defined which calls
.codn fun .
A top-level definition of
.code fun
is introduced which
outputs
.strn "top-level fun!" .
The function
.code callee
provides its own local
definition of
.code fun
which outputs
.str "local fun!"
before calling
.codn which .
When
.code callee
is invoked, it calls
.codn which ,
whose
.code @(fun)
call is routed to callee's
local definition.  When
.code which
is called directly from the top level, its
.code fun
call goes to the top-level definition.

.NP* Indirect Calls

Function indirection may be performed using the
.code call
directive. If
.meta fun-expr
is an expression which evaluates to a symbol, and
that symbol names a function which takes no arguments, then
.verb
  @(call fun-expr)
.brev
may be used to invoke the function. Additional
expressions may be supplied which specify arguments.

Example 1:

.mono
\ @(define foo (arg))
  @(bind arg "abc")
  @(end)
  @(call @'foo b)
.onom

In this example, the effect is that
.code foo
is invoked, and
.code b
ends up bound to
.strn abc .

The
.code call
directive here uses the
.code @'foo
expression to calculate the name of the function to be invoked.
The
.code @
symbol indicates that the expression which follows is \*(TL ,
and
.code 'foo
is the \*(TL syntax for quoting a symbol. (See the
.code quote
operator).

This particular
.code call
expression can just be replaced by the direct invocation
syntax
.codn "@(foo b)" .

The power of
.code call
lies in being able to specify the function as a value which
comes from elsewhere in the program, as in the following example.

.mono
\ @(define foo (arg))
  @(bind arg "abc")
  @(end)
  @(bind f @'foo)
  @(call f b)
.onom

Here the
.code call
directive obtains the name of the function from the
.code f
variable.

Note that function names are resolved to functions in the environment
that is apparent at the point in execution where the
.code call
takes place. The directive
.code "@(call f args ...)"
is precisely equivalent to
.code "@(s args ...)"
if, at the point of the call,
.code f
is a variable which holds the symbol
.code s
and symbol
.code s
is defined as a function. Otherwise it is erroneous.

.SS* Modularization

.dirs load include

The syntax of the
.code load
and
.code include
directives is:

.mono
.mets @(load << expr )
.mets @(include << expr )
.onom

Where
.meta expr
is a Lisp expression that
evaluates to a string giving the path of the file to load.

Firstly, the path given by
.meta expr
is converted to an effective path, as follows.

If the value of the
.code *load-path*
variable has a current value which is not
.code nil
and the path given in
.meta expr
is pure relative according to the
.code pure-rel-path-p
function, then the effective path is interpreted taken relative
to the directory portion of the path which is stored in
.codn *load-path* .

If
.code *load-path*
is nil, or the load path is not pure relative, then the
path is taken as-is as the effective path.

Next, an attempt is made to open the file for processing, in
almost exactly the same manner as by the \*(TL function
.codn load .
The difference is that if the effective path is unsuffixed,
then the
.code .txr
suffix is added to it, and that resulting path is tried first,
and if it succeeds, then the file is treated as \*(TX Pattern
Language syntax.
If that fails, then the suffix
.code .tlo
is tried, and so forth, as described for the
.code load
function.

Both the
.code load
and
.code include
directives bind the
.code *load-path*
variable to the path of the loaded file just before parsing syntax from it,
The
.code *package*
variable is also given a new dynamic binding, whose value is the
same as the existing binding. These bindings are removed when the
load operation completes, restoring the prior values of these
variables.

If the file opened for processing is \*(TL source, or
a compiled \*(TL file, then it is processed in the manner
described for the
.code load
function.

Different requirements apply to the processing of the file under the
.code load
and
.code include
directives.

The
.code include
directive performs the processing of the file at parse time. If the
file being processed is \*(TX Pattern Language, then it is parsed,
and then its syntax replaces the
.code include
directive, as if it had originally appeared in its place.
If a \*(TL source or a compiled \*(TL file is processed by
.code include
then the
.code include
directive is removed from the syntax.

The
.code load
directive performs the processing of the file at evaluation time.
Evaluation time
occurs after a \*(TX program is read from beginning to end and parsed.
That is to say, when a \*(TX query is parsed, any embedded
.code "@(load ...)"
forms in it are parsed and constitute part of its syntax tree.
They are executed when that query is executed, whenever its execution
reaches those
.code load
directives. When the
.code load
directive processes \*(TX Pattern Language syntax, it parses
the file in its entirety and then executes that file's directives
against the current input position. Repeated executions of the
same
.code load
directive result in repeated processing of the file.

Note: the
.code include
directive is useful for loading \*(TX files which contain Lisp macros
which are needed by the parent program. The parent program cannot use
.code load
to bring in macros because macros are required during expansion, which
takes place prior to evaluation time, whereas
.code load
doesn't execute until evaluation time.

See also: the
.codn self-path ,
.code stdlib
and
.code *load-path*
variables in \*(TL.

.SS* Output

.NP* Introduction

A \*(TX query may perform custom output. Output is performed by
.code output
clauses,
which may be embedded anywhere in the query, or placed at the end.  Output
occurs as a side effect of producing a part of a query which contains an
.code @(output)
directive, and is executed even if that part of the query ultimately
fails to find a match. Thus output can be useful for debugging.
An
.code output
clause specifies that its output goes to a file, pipe, or (by
default) standard output. If any output clause is executed whose destination is
standard output, \*(TX makes a note of this, and later, just prior to
termination, suppresses the usual printing of the variable bindings or the word
false.

.dir output

The syntax of the
.code @(output)
directive is:

.mono
.mets @(output [ < destination ] { < bool-keyword | < keyword < value }* )
  .
  . one or more output directives or lines
  .
  @(end)
.onom

If the directive has arguments, then the first one is evaluated.
If it is an object other than a keyword symbol, then it specifies
the optional
.metn destination .
Any remaining arguments after the optional destination are
the keyword list. If the destination is missing, then the
entire argument list is a keyword list.

The
.meta destination
argument,
if present,
is treated as a \*(TL expression and evaluated.
The resulting value is taken as the output destination. The value may be a
string which gives the path name of a file to open for output. Otherwise,
the destination must be a stream object.

The keyword list consists of a mixture of Boolean keywords which
do not have an argument, or keywords with arguments.

The following Boolean keywords are supported:

.coIP :nothrow
The
.code output
directive throws an exception if the output destination
cannot be opened, unless the
.code :nothrow
keyword is present, in which
case the situation is treated as a match failure.

Note that since command pipes are processes that report errors
asynchronously, a failing command will not throw an immediate exception that
can be suppressed with
.codn :nothrow .
This is for synchronous errors, like
trying to open a destination file, but not having permissions, etc.

.coIP :append
This keyword is meaningful for files, specifying append mode: the output is to
be added to the end of the file rather than overwriting the file.

The following value keywords are supported:

.coIP :filter
The argument can be a symbol, which specifies a filter to be applied to
the variable substitutions occurring within the
.code output
clause.
The argument can also be a list of filter symbols, which specifies
that multiple filters are to be applied, in left to right order.

See the later sections Output Filtering below, and The Deffilter Directive.

.coIP :into
The argument of
.code :into
is a symbol which denotes a variable.
The output will go into that variable.  If the variable is unbound,
it will be created. Otherwise, its contents are overwritten
unless the
.code :append
keyword is used. If
.code :append
is used, then
the new content will be appended to the previous content of
the variable, after flattening the content to a list,
as if by the
.code flatten
directive.

.coIP :named
The argument of
.code :named
is a symbol which denotes a variable.
The file or pipe stream which is opened for the output is
stored in this variable, and is not closed at the end of the
output block. This allows a subsequent output block to continue
output on the same stream, which is possible using the
next two keywords,
.code :continue
or
.codn :finish .
A new binding is established for the variable, even if it
already has an existing binding.

.coIP :continue
A destination should not be specified if
.code :continue
is used.  The argument of
.code :continue
is an expression, such as a variable name, that evaluates to a
stream object. That stream object is used for the output block.
At the end of the output block, the stream is flushed, but not
closed.  A usage example is given in the documentation for the Close Directive
below.

.coIP :finish
A destination should not be specified if
.code :finish
is used.  The argument of
.code :finish
is an expression, such as a variable name, that evaluates to a
stream object. That stream object is used for the output block.
At the end of the output block, the stream is closed.
An example is given in the documentation for the Close Directive
below.

.NP* Output Text

Text in an output clause is not matched against anything, but is output
verbatim to the destination file, device or command pipe.

.NP* Output Variables

Variables occurring in an output clause do not match anything; instead
their contents are output.

A variable being output can be any object. If it is of a type other
than a list or string, it will be converted to a string as if by the
.code tostring
function in \*(TL.

A list is converted to a string in a special way: the elements are
individually converted to a string and then they are catenated together.
The default separator string is a single space: an alternate separation
can be specified as an argument in the brace substitution syntax.
Empty lists turn into an empty string.

Lists may be output within
.code @(repeat)
or
.code @(rep)
clauses. Each nesting of
these constructs removes one level of nesting from the list variables
that it contains.

In an output clause, the
.mono
.meti >> @{ name << number }
.onom
variable syntax generates fixed-width
field, which contains the variable's text.  The absolute value of the
number specifies the field width. For instance
.code -20
and
.code 20
both specify a field
width of twenty.  If the text is longer than the field, then it overflows the
field. If the text is shorter than the field, then it is left-adjusted within
that field, if the width is specified as a positive number, and right-adjusted
if the width is specified as negative.

An output variable may specify a filter which overrides any filter established
for the output clause. The syntax for this is
.mono
.meti @{NAME :filter << filterspec }.
.onom
The filter specification syntax is the same as in the output clause.
See Output Filtering below.

.NP* Output Variables: Indexing

Additional syntax is supported in output variables that does not appear
in pattern matching variables.

A square bracket index notation may be used to extract elements or
ranges from a variable, which works with strings, vectors and lists.  Elements
are indexed from zero. This notation is only available in brace-enclosed
syntax, and looks like this:

.meIP <> @{name[ expr ]}
Extract the element at the position given by
.metn expr .

.meIP <> @{name[ expr1..expr2 ]}
Extract a range of elements from the position given by
.metn expr1 ,
up to
one position less than the position given by
.metn expr2 .

If the variable is a list, it is treated as a list substitution,
exactly as if it were the value of an unsubscripted list variable.
The elements of the list are converted to strings and catenated
together wit ha separator string between them, the default one being
a single space.

An alternate character may be given as a string argument in the brace
notation.
.PP

Example:

.verb
  @(bind a ("a" "b" "c" "d"))
  @(output)
  @{a[1..3] "," 10}
  @(end)
.brev

The above produces the text
.str b,c
in a field
.code 10
spaces wide. The
.code [1..3]
argument extracts a range of
.codn a ;
the
.str ","
argument specifies an alternate
separator string, and
.code 10
specifies the field width.

.NP* Output Substitutions

The brace syntax has another syntactic and semantic extension in
.code output
clauses. In place
of the symbol, an expression may appear. The value of that expression
is substituted.

Example:

.mono
 @(bind a "foo")
 @(output)
 @{`@a:` -10}
.onom

Here, the quasiliteral expression
.code `@a:`
is evaluated, producing the string
.strn foo: .
This string is printed right-adjusted in a
.code 10
character field.

.dir repeat

The
.code repeat
directive generates repeated text from a "boilerplate",
by taking successive elements from lists. The syntax of repeat is
like this:

.verb
  @(repeat)
  .
  .
  main clause material, required
  .
  .
  special clauses, optional
  .
  .
  @(end)
.brev

.code repeat
has four types of special clauses, any of which may be
specified with empty contents, or omitted entirely. They are described
below.

.code repeat
takes arguments, also described below.

All of the material in the main clause and optional clauses
is examined for the presence of variables.  If none of the variables
hold lists which contain at least one item, then no output is performed,
(unless the repeat specifies an
.code @(empty)
clause, see below).
Otherwise, among those variables which contain non-empty lists, repeat finds
the length of the longest list. This length of this list determines the number
of repetitions, R.

If the
.code repeat
contains only a main clause, then the lines of this clause is
output R times. Over the first repetition, all of the variables which, outside
of the repeat, contain lists are locally rebound to just their first item. Over
the second repetition, all of the list variables are bound to their second
item, and so forth. Any variables which hold shorter lists than the longest
list eventually end up with empty values over some repetitions.

Example: if the list
.code A
holds
.strn 1 ,
.str 2
and
.strn 3 ;
the list
.code B
holds
.strn A ,
.strn B ;
and the variable
.code C
holds
.strn X ,
then

.verb
  @(repeat)
  >> @C
  >> @A @B
  @(end)
.brev

will produce three repetitions (since there are two lists, the longest
of which has three items). The output is:

.verb
  >> X
  >> 1 A
  >> X
  >> 2 B
  >> X
  >> 3
.brev

The last line has a trailing space, since it is produced by
.strn "@A @B" ,
where
.code B
has an empty value. Since
.code C
is not a list variable, it
produces the same value in each repetition.

The special clauses are:

.coIP @(single)
If the
.code repeat
produces exactly one repetition, then the contents of this clause
are processed for that one and only repetition, instead of the main clause
or any other clause which would otherwise be processed.

.coIP @(first)
The body of this clause specifies an alternative body to be used for the first
repetition, instead of the material from the main clause.

.coIP @(last)
The body of this clause is used instead of the main clause for the last
repetition.

.coIP @(empty)
If the repeat produces no repetitions, then the body of this clause is output.
If this clause is absent or empty, the repeat produces no output.

.coIP "@(mod n m)"
The forms
.code n
and
.code m
are Lisp expressions that evaluate to integers. The value of
.code m
should be nonzero. The clause denoted this way is active if the repetition
modulo
.code m
is equal to
.codn n .
The first repetition is numbered zero.
For instance the clause headed by
.code "@(mod 0 2)"
will be used on repetitions 
0, 2, 4, 6, ...  and
.code "@(mod 1 2)"
will be used on repetitions 1, 3, 5, 7, ...

.coIP "@(modlast n m)"
The meaning of
.code n
and
.code m
is the same as in
.codn "@(mod n m)" ,
but one more condition
is imposed. This clause is used if the repetition modulo
.code m
is equal to
.codn n ,
and if it is the last repetition.
.PP

The precedence among the clauses which take an iteration is:
.codn "single > first > mod > modlast > last > main" .
That is if two or more of these
clauses can apply to a repetition, then the leftmost one in this precedence
list applies. For instance, if there is just a single repetition, then any of
these special clause types can apply to that repetition, since it is the only
repetition, as well as the first and last one. In this situation, if there is a
.code @(single)
clause present, then the repetition is processed using that clause.
Otherwise, if there is a
.code @(first)
clause present, that clause is used. Failing
that,
.code @(mod)
is used if there is such a clause and its numeric conditions
are satisfied. If there isn't, then
.code @(modlast)
clauses are considered, and if there
are none, or none of them activate, then
.code @(last)
is considered. Finally if none
of all these clauses are present or apply, then the repetition is processed
using the main clause.

Repeat supports arguments.

.mono
.mets @(repeat
.mets \ \ \  [:counter >> { symbol | >> ( symbol << expr )}]
.mets \ \ \  [:vars >> ({ symbol | >> ( symbol << expr )}*)])
.onom

The
.code :counter
argument designates a symbol which will behave as an integer
variable over the scope of the clauses inside the repeat. The variable provides
access to the repetition count, starting at zero, incrementing with each
repetition. If the the argument is given as
.mono
.meti >> ( symbol << expr )
.onom
then
.meta expr
is a Lisp expression whose value is taken as a displacement value which
is added to each iteration of the counter. For instance
.code ":counter (c 1)"
specifies a counter
.code c
which counts from 1.

The
.code :vars
argument specifies a list of variable name symbols
.meta symbol
or else pairs of the form
.mono
.meti >> ( symbol << init-form )
.onom
consisting of a variable name and Lisp expression. Historically, the former
syntax informed
.code repeat
about references to variables contained in Lisp code. This usage is no
longer necessary as of \*(TX 243, since the
.code repeat
construct walks Lisp code, identifying all free variables.
The latter syntax introduces a new pattern variable binding for
.meta symbol
over the scope of the
.code repeat
construct. The
.meta init-form
specifies a Lisp expression which is evaluated to produce the
binding's value.

The
.code repeat
directive then processes the list of variables, selecting from it
those which have a binding, either a previously existing binding or the
one just introduced. For each selected variable, repeat
will assume that the variable occurs in the repeat block and contains
a list to be iterated.

The variable binding syntax supported by
.code :vars
of the form
.mono
.meti >> ( symbol << init-form )
.onom
provides a solution for situations when it is necessary to iterate
over some list, but that list is the result of an expression, and not stored in
any variable. A repeat block iterates only over lists emanating from variables;
it does not iterate over lists pulled from arbitrary expressions.

Example: output all file names matching the
.code *.txr
pattern in the current directory:

.verb
  @(output)
  @(repeat :vars ((name (glob "*.txr"))))
  @name
  @(end)
  @(end)
.brev

Prior to \*(TX 243, the simple variable binding syntax supported by
.code :vars
of the form
.meta symbol
binding was needed for situations in which \*(TL expressions which
reference variables were embedded in
.code @(repeat)
blocks.  Variables references embedded in Lisp code were not identified
.codn @(repeat) .
For instance, the following produced no output, because no variables
were found in the
.code repeat
body:

.verb
  @(bind trigraph ("abc" "def" "ghi"))
  @(output)
  @(repeat)
  @(reverse trigraph)
  @(end)
  @(end)
.brev

There is a reference to
.meta list
but it's inside a Lisp
.code "(reverse lisp)"
expression that was not processed by
.codn repeat .
The solution was to mention
.meta list
via the
.code :vars
construct:

.verb
  @(bind trigraph ("abc" "def" "ghi"))
  @(output)
  @(repeat :vars (trigraph))
  @(reverse trigraph)
  @(end)
  @(end)
.brev

Then the repeat block would iterates over list, producing the output:

.verb
  cba
  fed
  igh
.brev

This workaround is no longer required as of \*(TX 243; the output
is produced by the first example, without
.codn :vars .

.coNP Nested @ repeat directives

If a
.code repeat
clause encloses variables which hold multidimensional lists,
those lists require additional nesting levels of repeat (or rep).
It is an error to attempt to output a list variable which has not been
decimated into primary elements via a repeat construct.

Suppose that a variable
.code X
is two-dimensional (contains a list of lists).
.code X
must be twice nested in a
.codn repeat .
The outer repeat will traverse the lists
contained in
.codn X .
The inner repeat will traverse the elements of each of these
lists.

A nested repeat may be embedded in any of the clauses of a repeat,
not only the main clause.

.dir rep

The
.code rep
directive is similar to
.codn repeat .
Whereas
.code repeat
is line oriented,
.code rep
generates material within a line. It has all the same clauses,
but everything is specified within one line:

.verb
  @(rep)... main material ... .... special clauses ...@(end)
.brev

More than one
.code @(rep)
can occur within a line, mixed with other material.
A
.code @(rep)
can be nested within a
.code @(repeat)
or within another
.codn @(rep) .

Also,
.code @(rep)
accepts the same
.code :counter
and
.code :vars
arguments.

.coNP @ repeat and @ rep Examples

Example 1: show the list
.code L
in parentheses, with spaces between
the elements, or the word
.code EMPTY
if the list is empty:

.verb
  @(output)
  @(rep)@L @(single)(@L)@(first)(@L @(last)@L)@(empty)EMPTY@(end)
  @(end)
.brev

Here, the
.code @(empty)
clause specifies
.codn EMPTY .
So if there are no repetitions,
the text
.code EMPTY
is produced. If there is a single item in the list
.codn L ,
then
.code @(single)(@L)
produces that item between parentheses.  Otherwise
if there are two or more items, the first item is produced with
a leading parenthesis followed by a space by
.code @(first)(@L
and the last item is produced with a closing parenthesis:
.codn @(last)@L) .
All items in between are emitted with a trailing space by
the main clause:
.codn @(rep)@L .

Example 2: show the list L like Example 1 above, but the empty list is
.codn () .

.verb
  @(output)
  (@(rep)@L @(last)@L@(end))
  @(end)
.brev

This is simpler. The parentheses are part of the text which
surrounds the
.code @(rep)
construct, produced unconditionally.
If the list
.code L
is empty, then
.code @(rep)
produces no output, resulting in
.codn () .
If the list
.code L
has one or more items, then they are produced with
spaces each one, except the last which has no space.
If the list has exactly one item, then the
.code @(last)
applies to it
instead of the main clause: it is produced with no trailing space.

.dir close

The syntax of the
.code close
directive is:

.mono
.mets @(close << expr )
.onom

Where
.meta expr
evaluates to a stream. The
.code close
directive can be
used to explicitly close streams created using
.mono
.meti @(output ... :named << var )
.onom
syntax, as an alternative to
.mono
.meti @(output :finish << expr ).
.onom

Examples:

Write two lines to
.str foo.txt
over two output blocks using
a single stream:

.verb
  @(output "foo.txt" :named foo)
  Hello,
  @(end)
  @(output :continue foo)
  world!
  @(end)
  @(close foo)
.brev

The same as above, using
.code :finish
rather than
.code :continue
so that the stream is closed at the end of the second block:

.verb
  @(output "foo.txt" :named foo)
  Hello,
  @(end)
  @(output :finish foo)
  world!
  @(end)
.brev

.NP* Output Filtering

Often it is necessary to transform the output to preserve its meaning
under the convention of a given data format. For instance, if a piece of
text contains the characters
.code <
or
.codn > ,
then if that text is being
substituted into HTML, these should be replaced by
.code &lt;
and
.codn &gt; .
This is what filtering is for.  Filtering is applied to the contents of output
variables, not to any template text.
\*(TX implements named filters.  Built-in filters are named by keywords, given
below. User-defined filters are possible, however.  See notes on the deffilter
directive below.

Instead of a filter name, the syntax
.mono
.meti (fun << name )
.onom
can be used. This
denotes that the function called
.meta name
is to be used as a filter.
This is described in the next section Function Filters below.

Built-in filters named by keywords:

.coIP :tohtml
Filter text to HTML, representing special characters using HTML
ampersand sequences. For instance
.code >
is replaced by
.codn &gt; .

.coIP :tohtml*
Filter text to HTML, representing special characters using HTML
ampersand sequences. Unlike
.codn :tohtml ,
this filter doesn't treat the single and double quote characters.
It is not suitable for preparing HTML fragments which end up
inserted into HTML tag attributes.

.coIP :fromhtml
Filter text with HTML codes into text in which the codes are replaced by the
corresponding characters. For instance
.code &gt;
is replaced by
.codn > .

.coIP :upcase
Convert the 26 lower case letters of the English alphabet to upper case.

.coIP :downcase
Convert the 26 upper case letters of the English alphabet to lower case.

.coIP :frompercent
Decode percent-encoded text. Character triplets consisting
of the
.code %
character followed by a pair of hexadecimal digits (case insensitive)
are are converted to bytes having the value represented by the hexadecimal
digits (most significant nybble first). Sequences of one or more such bytes are
treated as UTF-8 data  and decoded to characters.

.coIP :topercent
Convert to percent encoding according to RFC 3986. The text is first converted
to UTF-8 bytes. The bytes are then converted back to text as follows.
Bytes in the range 0 to 32, and 127 to 255 (note: including the ASCII DEL), 
bytes whose values correspond to ASCII characters which are listed by RFC 3986 
as being in the "reserved set", and the byte value corresponding to the
ASCII
.code %
character are encoded as a three-character sequence consisting
of the
.code %
character followed by two hexadecimal digits derived from the
byte value (most significant nybble first, upper case). All other bytes
are converted directly to characters of the same value without any such
encoding.

.coIP :fromurl
Decode from URL encoding, which is like percent encoding, except that
if the unencoded
.code +
character occurs, it is decoded to a space character. The
.code %20
sequence still decodes to space, and
.code %2B
to the
.code +
character.

.coIP :tourl
Encode to URL encoding, which is like percent encoding except that
a space maps to
.code +
rather than
.codn %20 .
The
.code +
character, being in the
reserved set, encodes to
.codn %2B .

.coIP :frombase64
Decode from the Base 64 encoding described in RFC 4648, section 5.

.coIP :tobase64
Encode to the Base 64 encoding described in RFC 4648, section 5.

.coIP :frombase64url
Decode from the Base64 encoding described in RFC 4648, section 6.
This uses the URL and filename safe alphabet, in which the
.code +
(plus) and
.code /
(slash) characters used in regular Base 64 are respectively replaced with
.code -
(minus) and
.code _
(underscore).

.coIP :tobase64url
Encode to the Base 64 encoding described in RFC 4648, section 6.  See
.code :frombase64url
above.

.coIP :tonumber
Converts strings to numbers. Strings that contain a period,
.code e
or
.code E
are converted to floating point as if by the Lisp function
.codn flo-str .
Otherwise they are converted to integer as if using
.code int-str
with a radix of 10.
Non-numeric junk results in the object
.codn nil .

.coIP :toint
Converts strings to integers as if using
.code int-str
with a radix of 10.
Non-numeric junk results in the object
.codn nil .

.coIP :tofloat
Converts strings to floating-point values as if using the function
.codn flo-str .
Non-numeric junk results in the object
.codn nil .

.coIP :hextoint
Converts strings to integers as if using
.code int-str
with a radix of 16.
Non-numeric junk results in the object
.codn nil .

.PP

Examples:

To escape HTML characters in all variable substitutions occurring in an
output clause, specify
.code ":filter :tohtml"
in the directive:

.verb
  @(output :filter :tohtml)
  ...
  @(end)
.brev

To filter an individual variable, add the syntax to the variable spec:

.verb
  @(output)
  @{x :filter :tohtml}
  @(end)
.brev

Multiple filters can be applied at the same time. For instance:

.verb
  @(output)
  @{x :filter (:upcase :tohtml)}
  @(end)
.brev

This will fold the contents of
.code x
to upper case, and then encode any special
characters into HTML. Beware of combinations that do not make sense.
For instance, suppose the original text is HTML, containing codes
like
.codn &quot; .
The compound filter
.code "(:upcase :fromhtml)"
will not work
because
.code &quot;
will turn to
.code &QUOT;
which no longer be recognized by the
.code :fromhtml
filter, since the entity names in HTML codes
are case-sensitive.

Capture some numeric variables and convert to numbers:

.verb
  @date @time @temperature @pressure
  @(filter :tofloat temperature pressure)
  @;; temperature and pressure can now be used in calculations
.brev

.NP* Function Filters

A function can be used as a filter. For this to be possible, the function must
conform to certain rules:
.IP 1.
The function must take two special arguments, which may be followed
by additional arguments.
.IP 2.
When the function is called, the first argument will be bound to a string,
and the second argument will be unbound. The function must produce a 
value by binding it to the second argument. If the filter is to be used
as the final filter in a chain, it must produce a string.
.PP

For instance, the following is a valid filter function:

.verb
  @(define foo_to_bar (in out))
  @  (next :string in)
  @  (cases)
  foo
  @    (bind out "bar")
  @  (or)
  @    (bind out in)
  @  (end)
  @(end)
.brev

This function binds the
.code out
parameter to
.str bar
if the in parameter
is
.strn foo ,
otherwise it binds the
.code out
parameter to a copy of the
.code in
parameter.
This is a simple filter.

To use the filter, use the syntax
.code "(:fun foo_to_bar)"
in place of a filter name.
For instance in the
.code bind
directive:

.verb
  @(bind "foo" "bar" :lfilt (:fun foo_to_bar))
.brev

The above should succeed since the left side is filtered from
.str foo
to
.strn bar ,
so that there is a match.

Function filters can be used in a chain:

.verb
  @(output :filter (:downcase (:fun foo_to_bar) :upcase))
  ...
  @(end)
.brev

Here is a split function which takes an extra argument
which specifies the separator:

.verb
  @(define split (in out sep))
  @  (next :list in)
  @  (coll)@(maybe)@token@sep@(or)@token@(end)@(end)
  @  (bind out token)
  @(end)
.brev

Furthermore, note that it produces a list rather than a string.
This function separates the argument in into tokens according to the
separator text carried in the variable
.codn sep .

Here is another function,
.codn join ,
which catenates a list:

.verb
  @(define join (in out sep))
  @  (output :into out)
  @  (rep)@in@sep@(last)@in@(end)
  @  (end)
  @(end)
.brev

Now here is these two being used in a chain:

.verb
  @(bind text "how,are,you")
  @(output :filter (:fun split ",") (:fun join "-"))
  @text
  @(end)
.brev

Output:

.verb
  how-are-you
.brev

When the filter invokes a function, it generates the first two arguments
internally to pass in the input value and capture the output. The remaining
arguments from the
.code "(:fun ...)"
construct are also passed to the function.
Thus the string objects
.str ","
and
.str "-"
are passed as the
.code sep
argument to
.code split
and
.codn join .

Note that
.code split
puts out a list, which
.code join
accepts. So the overall filter
chain operates on a string: a string goes into split, and a string comes out of
join.

.dir deffilter

The
.code deffilter
directive allows a query to define a custom filter, which
can then be used in
.code output
clauses to transform substituted data.

The syntax of
.code deffilter
is illustrated in this example:
.IP code:
.mono
\ @(deffilter rot13
    ("a" "n")
    ("b" "o")
    ("c" "p")
    ("d" "q")
    ("e" "r")
    ("f" "s")
    ("g" "t")
    ("h" "u")
    ("i" "v")
    ("j" "w")
    ("k" "x")
    ("l" "y")
    ("m" "z")
    ("n" "a")
    ("o" "b")
    ("p" "c")
    ("q" "d")
    ("r" "e")
    ("s" "f")
    ("t" "g")
    ("u" "h")
    ("v" "i")
    ("w" "j")
    ("x" "k")
    ("y" "l")
    ("z" "m"))
 @(collect)
 @line
 @(end)
 @(output :filter rot13)
 @(repeat)
 @line
 @(end)
 @(end)
.onom
.IP data:
.mono
\ hey there!
.onom
.IP output:
.mono
\ url gurer!
.onom
.PP

The
.code deffilter
symbol must be followed by the name of the filter to be defined,
followed by bind expressions which evaluate to lists of strings. Each list must
be at least two elements long and specifies one or more texts which are mapped
to a replacement text. For instance, the following specifies a telephone keypad
mapping from upper case letters to digits.

.verb
  @(deffilter alpha_to_phone ("E" "0")
                             ("J" "N" "Q" "1")
                             ("R" "W" "X" "2")
                             ("D" "S" "Y" "3")
                             ("F" "T" "4")
                             ("A" "M" "5")
                             ("C" "I" "V" "6")
                             ("B" "K" "U" "7")
                             ("L" "O" "P" "8")
                             ("G" "H" "Z" "9"))

  @(deffilter foo (`@a` `@b`) ("c" `->@d`))

  @(bind x ("from" "to"))
  @(bind y ("---" "+++"))
  @(deffilter sub x y)
.brev

The last deffilter has the same effect as the
.mono
@(deffilter sub ("from" "to") ("---" "+++"))
.onom
directive.

Filtering works using a longest match algorithm. The input is scanned from left
to right, and the longest piece of text is identified at every character
position which matches a string on the left hand side, and that text is
replaced with its associated replacement text. The scanning then continues
at the first character after the matched text.

If none of the strings matches at a given character position, then that
character is passed through the filter untranslated, and the scan continues at
the next character in the input.

Filtering is not in-place but rather instantiates a new text, and so
replacement text is not re-scanned for more replacements.

If a filter definition accidentally contains two or more repetitions of the
same left hand string with different right hand translations, the later ones
take precedence. No warning is issued.


.dir filter

The syntax of the
.code filter
directive is:

.verb
  @(filter FILTER { VAR }+ )
.brev

A filter is specified, followed by one or more variables whose values
are filtered and stored back into each variable.

Example: convert
.codn a ,
.codn b ,
and
.code c
to upper case and HTML encode:

.verb
  @(filter (:upcase :tohtml) a b c)
.brev

.SS* Exceptions

.NP* Introduction

The exceptions mechanism in \*(TX is another
disciplined form of non-local transfer, in addition to the blocks
mechanism (see Blocks above).  Like blocks, exceptions provide a construct
which serves as the target for a dynamic exit.  Both blocks and exceptions
can be used to bail out of deep nesting when some condition occurs.
However, exceptions provide more complexity. Exceptions are useful for
error handling, and \*(TX in fact maps certain error situations to exception
control transfers. However, exceptions are not inherently an error-handling
mechanism; they are a structured dynamic control transfer mechanism, one
of whose applications is error handling.

An exception control transfer (simply called an exception) is always identified
by a symbol, which is its type. Types are organized in a subtype-supertype
hierarchy.  For instance, the
.code file-error
exception type is a subtype of the
.code error
type. This means that a file error is a kind of error. An exception
handling block which catches exceptions of type
.code error
will catch exceptions of
type
.codn file-error ,
but a block which catches
.code file-error
will not catch all
exceptions of type
.codn error .
A
.code query-error
is a kind of error, but not a kind of
.codn file-error .
The symbol
.code t
is the supertype of every type: every exception type
is considered to be a kind of
.codn t .
(Mnemonic:
.code t
stands for type, as in any type).

Exceptions are handled using
.code @(catch)
clauses within a
.code @(try)
directive.

In addition to being useful for exception handling, the
.code @(try)
directive
also provides unwind protection by means of a
.code @(finally)
clause,
which specifies query material to be executed unconditionally when
the try clause terminates, no matter how it terminates.

.dir try

The general syntax of the
.code try
directive is

.verb
  @(try)
  ... main clause, required ...
  ... optional catch clauses ...
  ... optional finally clause
  @(end)
.brev

A
.code catch
clause looks like:

.verb
  @(catch TYPE [ PARAMETERS ])
  .
  .
  .
.brev

and also this simple form:

.verb
  @(catch)
  .
  .
  .
.brev

which catches all exceptions, and is equivalent
to
.codn "@(catch t)" .

A
.code finally
clause looks like:

.verb
  @(finally)
  ...
  .
  .
.brev

The main clause may not be empty, but the catch and finally may be.

A try clause is surrounded by an implicit anonymous block (see Blocks section
above). So for instance, the following is a no-op (an operation with no effect,
other than successful execution):

.verb
  @(try)
  @(accept)
  @(end)
.brev

The
.code @(accept)
causes a successful termination of the implicit anonymous block.
Execution resumes with query lines or directives which follow, if any.

.code try
clauses and blocks interact. For instance, an
.code accept
from within
a try clause invokes a
.codn finally .
.IP code:
.mono
\ @(block foo)
 @  (try)
 @    (accept foo)
 @  (finally)
 @     (output)
 bye!
 @     (end)
 @  (end)
.onom
.IP output:
.mono
\ bye!
.onom
.PP

How this works: the
.code try
block's main clause is
.codn "@(accept foo)" .
This causes
the enclosing block named
.code foo
to terminate, as a successful match.
Since the
.code try
is nested within this block, it too must terminate
in order for the block to terminate. But the try has a
.code finally
clause,
which executes unconditionally, no matter how the try block
terminates. The
.code finally
clause performs some output, which is seen.

Note that
.code finally
interacts with
.code accept
in subtle ways not revealed in this example; they are documented in
the description of
.code accept
under the
.code block
directive documentation.

.coNP The @ finally clause

A
.code try
directive can terminate in one of three ways. The main clause
may match successfully, and possibly yield some new variable bindings.
The main clause may fail to match. Or the main clause may be terminated
by a non-local control transfer, like an exception being thrown or a block
return (like the block foo example in the previous section).

No matter how the
.code try
clause terminates, the
.code finally
clause is processed.

The
.code finally
clause is itself a query which binds variables, which leads to
questions: what happens to such variables? What if the
.code finally
block fails
as a query? As well as: what if a
.code finally
clause itself initiates a
control transfer?  Answers follow.

Firstly, a
.code finally
clause will contribute variable bindings only if the main
clause terminates normally (either as a successful or failed match).
If the main clause of the
.code try
block successfully matches, then the
.code finally
block continues
matching at the next position in the data, and contributes bindings.
If the main clause fails, then the
.code finally
block tries to match at the same position where the main clause failed.

The overall
.code try
directive succeeds as a match if either the main clause
or the
.code finally
clause succeed. If both fail, then the
.code try
directive is a failed match.

Example:
.IP code:
.mono
\ @(try)
 @a
 @(finally)
 @b
 @(end)
 @c
.onom
.IP data:
.mono
\ 1
 2
 3
.onom
.IP result:
.mono
\ a="1"
 b="2"
 c="3"
.onom
.PP

In this example, the main clause of the
.code try
captures line
.str 1
of the data as
variable
.codn a ,
then the finally clause captures
.str 2
as
.codn b ,
and then the query continues with the
.code @c
line after try block, so that
.code c
captures
.strn "3" .

Example:
.IP code:
.mono
\ @(try)
 hello @a
 @(finally)
 @b
 @(end)
 @c
.onom
.IP data:
.mono
\ 1
 2
.onom
.IP result:
.mono
\ b="1"
 c="2"
.onom
.PP

In this example, the main clause of the
.code try
fails to match, because
the input is not prefixed with
.strn "hello " .
However, the
.code finally
clause
matches, binding
.code b
to
.strn "1" .
This means that the try block is a successful
match, and so processing continues with
.code @c
which captures
.strn "2" .

When
.code finally
clauses are processed during a non-local return,
they have no externally visible effect if they do not bind variables.
However, their execution makes itself known if they perform side effects,
such as output.

A
.code finally
clause guards only the main clause and the
.code catch
clauses. It does not
guard itself.   Once the finally clause is executing, the
.code try
block is no
longer guarded.  This means if a nonlocal transfer, such as a block accept
or exception, is initiated within the finally clause, it will not re-execute
the
.code finally
clause. The
.code finally
clause is simply abandoned.

The disestablishment of blocks and
.code try
clauses is properly interleaved
with the execution of
.code finally
clauses. This means that all surrounding
exit points are visible in a
.code finally
clause, even if the
.code finally
clause
is being invoked as part of a transfer to a distant exit point.
The finally clause can make a control transfer to an exit point which
is more near than the original one, thereby "hijacking" the control
transfer. Also, the anonymous block established by the
.code try
directive
is visible in the
.code finally
clause.

Example:

.verb
  @(try)
  @  (try)
  @    (next "nonexistent-file")
  @  (finally)
  @    (accept)
  @  (end)
  @(catch file-error)
  @  (output)
  file error caught
  @  (end)
  @(end)
.brev

In this example, the
.code @(next)
directive throws an exception of type
.codn file-error ,
because the given file does not exist. The exit point for this exception is the
.code "@(catch file-error)"
clause in the outer-most
.code try
block. The inner block is
not eligible because it contains no catch clauses at all. However, the inner
try block has a finally clause, and so during the processing of this
exception which is headed for
.codn "@(catch file-error)" ,
the
.code finally
clause performs an anonymous
.codn accept .
The exit point for that
.code accept
is the anonymous block
surrounding the inner
.codn try .
So the original
transfer to the
.code catch
clause is thereby abandoned. The inner
.code try
terminates
successfully due to the
.codn accept ,
and since it constitutes the main clause of the outer try,
that also terminates successfully. The
.str "file error caught"
message is never printed.

.c1NP catch clauses

.code catch
clauses establish their associated
.code try
blocks as potential exit points for
exception-induced control transfers (called "throws").

A
.code catch
clause specifies an optional list of symbols which represent
the exception types which it catches. The
.code catch
clause will catch
exceptions which are a subtype of any one of those exception types.

If a
.code try
block has more than one
.code catch
clause which can match a given
exception, the first one will be invoked.

When a
.code catch
is invoked, it is understood that the main clause did
not terminate normally, and so the main clause could not have produced any
bindings.

.code catch
clauses are processed prior to
.codn finally .

If a
.code catch
clause itself throws an exception, that exception cannot
be caught by that same clause or its siblings in the same try block.
The
.code catch
clauses of that block are no longer visible at that point.
Nevertheless, the
.code catch
clauses are still protected by the finally block.
If a catch clause throws, or otherwise terminates, the
.code finally
block is still processed.

If a
.code finally
block throws an exception, then it is simply aborted;
the remaining directives in that block are not processed.

So the success or failure of the
.code try
block depends on the behavior of the
.code catch
clause or the
.code finally
clause, if there is one. If either of them succeed, then the try
block is considered a successful match.

Example:
.IP code:
.mono
\ @(try)
 @  (next "nonexistent-file")
 @  x
 @  (catch file-error)
 @a
 @(finally)
 @b
 @(end)
 @c
.onom
.IP data:
.mono
\ 1
 2
 3
.onom
.IP result:
.mono
\ a="1"
 b="2"
 c="3"
.onom
.PP

Here, the
.code try
block's main clause is terminated abruptly by a
.code file-error
exception from the
.code @(next)
directive.   This is handled by the
.code catch
clause, which binds variable
.code a
to the input line
.strn 1 .
Then the
.code finally
clause executes, binding
.code b
to
.strn  2 .
The
.code try
block then terminates successfully, and so
.code @c
takes
.strn "3" .

.coNP @ catch Clauses with Parameters

A
.code catch
clause may have parameters following the type name, like this:

.verb
  @(catch pair (a b))
.brev

To write a catch-all with parameters, explicitly write the
master supertype t:

.verb
  @(catch t (arg ...))
.brev

Parameters are useful in conjunction with
.codn throw .
The built-in
.code error
exceptions carry one argument, which is a string containing
the error message. Using
.codn throw ,
arbitrary parameters can be passed
from the throw site to the catch site.

.dir throw

The
.code throw
directive generates an exception. A type must be specified,
followed by optional arguments, which are bind expressions. For example,

.verb
  @(throw pair "a" `@file.txt`)
.brev

throws an exception of type
.codn pair ,
with two arguments, being
.str a
and the expansion of the quasiliteral
.codn `@file.txt` .

The selection of the target
.code catch
is performed purely using the type
name; the parameters are not involved in the selection.

Binding takes place between the arguments given in
.code throw
and the target
.codn catch .

If any
.code catch
parameter, for which a
.code throw
argument is given, is a bound
variable, it has to be identical to the argument, otherwise the catch fails.
(Control still passes to the
.codn catch ,
but the catch is a failed match).

.IP code:
.mono
\ @(bind a "apple")
 @(try)
 @(throw e "banana")
 @(catch e (a))
 @(end)
.onom
.IP result:
.mono
\ [query fails]
.onom
.PP

If any argument is an unbound variable, the corresponding parameter
in the
.code catch
is left alone: if it is an unbound variable, it remains
unbound, and if it is bound, it stays as is.
.IP code:
.mono
\ @(try)
 @(trow e "honda" unbound)
 @(catch e (car1 car2))
 @car1 @car2
 @(end)
.onom
.IP data:
.mono
\ honda toyota
.onom
.IP result:
.mono
\ car1="honda"
 car2="toyota"
.onom
.PP

If a
.code catch
has fewer parameters than there are throw arguments,
the excess arguments are ignored:
.IP code:
.mono
\ @(try)
 @(throw e "banana" "apple" "pear")
 @(catch e (fruit))
 @(end)
.onom
.IP result:
.mono
\ fruit="banana"
.onom
.PP

If a
.code catch
has more parameters than there are throw arguments, the excess
parameters are left alone. They may be bound or unbound variables.
.IP code:
.mono
\ @(try)
 @(trow e "honda")
 @(catch e (car1 car2))
 @car1 @car2
 @(end)
.onom
.IP data:
.mono
\ honda toyota
.onom
.IP result:
.mono
\ car1="honda"
 car2="toyota"
.onom
.PP

A
.code throw
argument passing a value to a
.code catch
parameter which is unbound causes
that parameter to be bound to that value.

.code throw
arguments are evaluated in the context of the
.codn throw ,
and the bindings
which are available there. Consideration of what parameters are bound
is done in the context of the catch.
.IP code:
.mono
\ @(bind c "c")
 @(try)
 @(forget c)
 @(bind (a c) ("a" "lc"))
 @(throw e a c)
 @(catch e (b a))
 @(end)
.onom
.IP result:
.mono
\ c="c"
 b="a"
 a="lc"
.onom
.PP

In the above example,
.code c
has a top-level binding to the string
.strn "c" ,
but then becomes unbound
via
.code forget
within the
.code try
construct, and rebound to the value
.strn lc .
Since the
.code try
construct is terminated by a
.codn throw ,
these modifications of the
binding environment are discarded. Hence, at the end of the query, variable
.code c
ends up bound to the original value
.strn c .
The
.code throw
still takes place
within the scope of the bindings set up by the
.code try
clause, so the values of
.code a
and
.code c
that are thrown are
.str a
and
.strn lc .
However, at the
.code catch
site, variable
.code a
does not have a binding.  At that point, the binding to
.str a
established in
the
.code try
has disappeared already. Being unbound, the
.code catch
parameter
.code a
can take
whatever value the corresponding throw argument provides, so it ends up with
.strn lc .

There is a horizontal form of
.codn throw .
For instance:

.verb
  abc@(throw e 1)
.brev

throws exception
.code e
if
.code abc
matches.

If
.code throw
is used to generate an exception derived from type
.code error
and that exception is not handled, \*(TX will issue diagnostics on the
.code *stderr*
stream and terminate. If an exception derived from
.code warning
is not handled, \*(TX will generate diagnostics on the
.code *stderr*
stream, after which control returns to the
.code throw
directive, and proceeds with the next directive.
If an exception not derived from
.code error
is thrown, control returns to the
.code throw
directive and proceeds with the next directive.

.dir defex

The
.code defex
directive allows the query writer to invent custom exception types,
which are arranged in a type hierarchy (meaning that some exception types are
considered subtypes of other types).

Subtyping means that if an exception type
.code B
is a subtype of
.codn A ,
then every
exception of type
.code B
is also considered to be of type
.codn A .
So a catch for type
.code A
will also catch exceptions of type
.codn B .
Every type is a supertype of itself: an
.code A
is a kind of
.codn A .
This implies that every type is a subtype of itself
also.  Furthermore, every type is a subtype of the type
.codn t ,
which has no
supertype other than itself. Type
.code nil
is is a subtype of every type, including
itself.  The subtyping relationship is transitive also. If
.code A
is a subtype
of
.codn B ,
and
.code B
is a subtype of
.codn C ,
then
.code A
is a subtype of
.codn C .

.code defex
may be invoked with no arguments, in which case it does nothing:

.verb
  @(defex)
.brev

It may be invoked with one argument, which must be a symbol. This introduces a
new exception type. Strictly speaking, such an introduction is not necessary;
any symbol may be used as an exception type without being introduced by
.codn @(defex) :

.verb
  @(defex a)
.brev

Therefore, this also does nothing, other than document the intent to use
a as an exception.

If two or more argument symbols are given, the symbols are all introduced as
types, engaged in a subtype-supertype relationship from left to right.
That is to say, the first (leftmost) symbol is a subtype of the next one,
which is a subtype of the next one and so on. The last symbol, if it
had not been already defined as a subtype of some type, becomes a
direct subtype of the master supertype
.codn t .
Example:

.verb
  @(defex d e)
  @(defex a b c d)
.brev

The first directive defines
.code d
as a subtype of
.codn e ,
and
.code e
as a subtype of
.codn t .
The second defines
.code a
as a subtype of
.codn b ,
.code b
as a subtype of
.codn c ,
and
.code c
as a subtype of
.codn d ,
which is already defined as a subtype of
.codn e .
Thus
.code a
is now a subtype of
.codn e .
The the above can be condensed to:

.verb
  @(defex a b c d e)
.brev

Example:
.IP code:
.mono
\ @(defex gorilla ape primate)
 @(defex monkey primate)
 @(defex human primate)
 @(collect)
 @(try)
 @(skip)
 @(cases)
 gorilla @name
 @(throw gorilla name)
 @(or)
 monkey @name
 @(throw monkey name)
 @(or)
 human @name
 @(throw human name)
 @(end)@#cases
 @(catch primate (name))
 @kind @name
 @(output)
 we have a primate @name of kind @kind
 @(end)@#output
 @(end)@#try
 @(end)@#collect
.onom
.IP data:
.mono
\ gorilla joe
 human bob
 monkey alice
.onom
.IP output:
.mono
\ we have a primate joe of kind gorilla
 we have a primate bob of kind human
 we have a primate alice of kind monkey
.onom
.PP

Exception types have a pervasive scope. Once a type relationship is introduced,
it is visible everywhere. Moreover, the
.code defex
directive is destructive,
meaning that the supertype of a type can be redefined. This is necessary so
that something like the following works right:

.verb
  @(defex gorilla ape)
  @(defex ape primate)
.brev

These directives are evaluated in sequence. So after the first one, the
.code ape
type has the type
.code t
as its immediate supertype.  But in the second directive,
.code ape
appears again, and is assigned the
.code primate
supertype, while retaining
.code gorilla
as a subtype.  This situation could be diagnosed as an
error, forcing the programmer to reorder the statements, but instead
\*(TX obliges. However, there are limitations.  It is an error to define a
subtype-supertype relationship between two types if they are already connected
by such a relationship, directly or transitively. So the following
definitions are in error:

.verb
  @(defex a b)
  @(defex b c)
  @(defex a c)@# error: a is already a subtype of c, through b

  @(defex x y)
  @(defex y x)@# error: circularity; y is already a supertype of x.
.brev

.dir assert

The
.code assert
directive requires the remaining query or sub-query which follows it
to match. If the remainder fails to match, the
.code assert
directive throws an exception. If the directive is simply

.verb
  @(assert)
.brev

Then it throws an assertion of type assert, which is a subtype of error.
The
.code assert
directive also takes arguments similar to the
.code throw
directive: an exception symbol and additional arguments which are bind
expressions, and may be unbound variables. The following assert directive, if
it triggers, will throw an exception of type
.codn foo ,
with arguments
.code 1
and
.strn 2 :

.verb
  @(assert foo 1 "2")
.brev

Example:

.verb
  @(collect)
  Important Header
  ----------------
  @(assert)
  Foo: @a, @b
  @(end)
.brev

Without the assertion in places, if the
.code "Foo: @a, @b"
part does not
match, then the entire interior of the
.code @(collect)
clause fails,
and the collect continues searching for another match.

With the assertion in place, if the text
.str "Important Header"
and its
underline match, then the remainder of the collect body must
match, otherwise an exception is thrown. Now the program will not
silently skip over any Important Header sections due to a problem
in its matching logic. This is particularly useful when the matching is varied
with numerous cases, and they must all be handled.

There is a horizontal
.code assert
directive also. For instance:

.verb
  abc@(assert)d@x
.brev

asserts that if the prefix
.str abc
is matched, then it must be
followed by a successful match for
.strn "d@x" ,
or else an exception is thrown.

If the exception is not handled, and is derived from
.code error
then \*(TX issues diagnostics on the
.code *stderr*
stream and terminates. If the exception is derived from
.code warning
and not handled, \*(TX issues a diagnostic on
.code *stderr*
after which control returns to the
.code assert
directive. Control silently returns to the
.code assert
directive if an exception of any other kind is not handled.

When control returns to
.code assert
due to an unhandled exception, it behaves like a failed match,
similarly to the require directive.

.SH* TXR LISP
The \*(TX language contains an embedded Lisp dialect called \*(TL.

This language is exposed in \*(TX in a number of ways.

In any situation that calls for an expression, a Lisp
expression can be used, if it is preceded by the
.code @
character. The Lisp expression
is evaluated and its value  becomes the value of that expression.
Thus, \*(TX directives are embedded in literal text using
.codn @ ,
and Lisp expressions
are embedded in directives using
.code @
also.

Furthermore, certain directives evaluate Lisp expressions without
requiring
.codn @ .
These are
.codn @(do) ,
.codn @(require) ,
.codn @(assert) ,
.code @(if)
and
.codn @(next) .

\*(TL code can be placed into files. On the command
line, \*(TX treats files with a
.str ".tl"
suffix as \*(TL code, and the
.code @(load)
directive does also.

\*(TX also provides an interactive listener for Lisp evaluation.

Lastly, \*(TL expressions can be evaluated via the
command line, using the
.code -e
and
.code -p
options.

.B
Examples:

Bind variable
.code a
to the integer 4:

.verb
  @(bind a @(+ 2 2))
.brev

Bind variable
.code b
to the standard input stream. Note that
.code @
is not required on a Lisp variable:

.verb
  @(bind a *stdin*)
.brev

Define several Lisp functions inside
.codn @(do) :

.verb
  @(do
    (defun add (x y) (+ x y))

    (defun occurs (item list)
      (cond ((null list) nil)
            ((atom list) (eql item list))
            (t (or (eq (first list) item)
                   (occurs item (rest list)))))))
.brev

Trigger a failure unless previously bound variable
.code answer
is greater than 42:

.verb
  @(require (> (int-str answer) 42)
.brev

.SS* Overview

\*(TL is a small and simple dialect, like Scheme, but much more similar to
Common Lisp than Scheme. It has separate value and function binding namespaces,
like Common Lisp (and thus is a Lisp-2 type dialect), and represents Boolean
.B true
and
.B false
with the symbols
.code t
and
.code nil
(note the case sensitivity of
identifiers denoting symbols!) Furthermore, the symbol
.code nil
is also the empty list, which terminates nonempty lists.

\*(TL has lexically scoped local variables and dynamic global variables,
similarly to Common Lisp, including the convention that
.code defvar
marks symbols for dynamic binding in local scopes. Lexical closures
are supported. \*(TL also supports global lexical variables via
.codn defvarl .

Functions are lexically scoped in \*(TL; they can be
defined in pervasive global environment using
.code defun
or in local scopes using
.code flet
and
.codn labels .

.SS* Additional Syntax

Much of the \*(TL syntax has been introduced in the previous sections of the
manual, since directive forms are based on it. There is some additional syntax
that is useful in \*(TL programming.

.NP* Symbol Tokens

The symbol tokens in \*(TL,
called a
.meta lident
(Lisp identifier) has a similar syntax to the
.meta bident
(braced identifier) in the \*(TX pattern language. It may consist of
all the same characters, as well as the
.code /
(slash) character which may not be used in a
.metn bident .
Thus a
.meta lident
may consist of these characters, in addition to letters, numbers and
underscores:

.mono
 ! $ % & * + - < = > ? \e ~ /
.onom

and may not look like a number.

A
.meta lident
may also include all of the Unicode characters which are permitted in a
.metn bident .

The one character which is allowed in a
.meta lident
but not in a
.meta bident
is
.code /
(forward slash).

A lone
.code /
is a valid
.meta lident
and consequently a symbol token in \*(TL. The token
.code /abc/
is also a symbol, and, unlike in a braced expression, is not a regular
expression. In \*(TL expressions, regular expressions are written with
a leading
.codn # .

.NP* Package Prefixes

If a symbol name contains a colon, the
.I lident
characters, if any, before that colon constitute the package prefix.

For example, the syntax
.code foo:bar
denotes
.code bar
symbol in the
.code foo
package.

It is a syntax error to read a symbol whose package doesn't exist.

If the package exists, but the symbol name doesn't exist in that package,
then the symbol is interned in that package.

If the package name is an empty string (the colon is preceded by nothing), the
package is understood to be the
.code keyword
package. The symbol is interned in that package.

The syntax
.code :test
denotes the symbol
.code test
in the
.code keyword
package, the same as
.codn keyword:test .

Symbols in the keyword package are self-evaluating. This means that
when a keyword symbol is evaluated as a form, the value of that form
is the keyword symbol itself. Exactly two non-keyword symbols also
have this special self-evaluating behavior:
the symbols
.code t
and
.code nil
in the user package, whose fully qualified names are
.code usr:t
and
.codn usr:nil .

The syntax
.code @foo:bar
denotes the meta prefix
.code @
being applied to the
.code foo:bar
symbol, not to a symbol in the
.code @foo
package.

The syntax
.code #:bar
denotes an uninterned symbol named
.codn bar ,
described in the next section.

.TP* "Dialect note:"
In ANSI Common Lisp, the
.code foo:bar
syntax does not intern the symbol
.code bar
in the
.code foo
package; the symbol must exist and be an exported symbol, or else the syntax is
erroneous. In ANSI Common Lisp, the syntax
.code foo::bar
does intern
.code foo
in the
.code bar
package. \*(TX's package system has no double-colon syntax, and lacks the concept of exported symbols.

.NP* Uninterned Symbols

Uninterned symbols are written with the
.code #:
prefix, followed by zero or more
.I lident
characters.
When an uninterned symbol is read, a new, unique symbol is constructed,
with the specified name. Even if two uninterned symbols have the same name,
they are different objects. The
.code make-sym
and
.code gensym
functions produce uninterned symbols.

"Uninterned" means "not entered into a package". Interning refers to a
process which combines package lookup with symbol creation, which ensures
that multiple occurrences of a symbol name in written syntax are all converted
to the same object: the first occurrence creates the symbol and associates it
with its name in a package. Subsequent occurrences do not create a new symbol,
but retrieve the existing one.

.NP* Consing Dot

Unlike other major Lisp dialects, \*(TL allows a consing dot with no forms
preceding it. This construct simply denotes the form which follows the dot.
That is to say, the parser implements the following transformation:

.verb
  (. expr) -> expr
.brev

This is convenient in writing function argument lists that only take
variable arguments. Instead of the syntax:

.verb
  (defun fun args ...)
.brev

the following syntax can be used:

.verb
  (defun fun (. args) ...)
.brev

When a
.code lambda
form is printed, it is printed in the following style.

.verb
  (lambda nil ...) -> (lambda () ...)
  (lambda sym ...) -> (lambda (. sym) ...)
  (lambda (sym) ...) -> (lambda (sym) ...)
.brev

In no other circumstances is
.code nil
printed as
.codn () ,
or an atom
.code sym
as
.codn "(. sym)" .

.NP* Referencing Dot

A dot token which is flanked by expressions on both sides, without any
intervening whitespace, is the referencing dot, and not the consing dot.
The referencing dot is a syntactic sugar which translated to the
.code qref
syntax ("quoted ref"). When evaluated as a form, this syntax denotes structure
access; see Structures. However, it is possible to put this syntax to use for
other purposes, in other contexts.

.verb
  ;; a.b may be almost any expressions
  a.b           <-->  (qref a b)
  a.b.c         <-->  (qref a b c)
  a.(qref b c)  <-->  (qref a b c)
  (qref a b).c  <-->  (qref (qref a b) c)
.brev

That is to say, this dot operator constructs a
.code qref
expression out of its left and right arguments. If the right argument
of the dot is already a qref expression (whether produced by another instance
of the dot operator, or expressed directly) it is merged. This requires
the qref dot operator to be right-to-left associative, so that
.code a.b.c
works by first translating
.code b.c
to
.codn "(qref b c)" ,
and then adjoining
.code a
to produce
.codn "(qref a b c)" .

If the referencing dot is immediately followed by a question mark, it forms
a single token, which produces the following syntactic variation:

.verb
  a.?b     <-->  (t a).b         <--> (qref (t a) b)
  a.?b.?c  <-->  (t a).(t b).c   <--> (qref (t a) (t b) c)
.brev

This syntax denotes
.I null-safe
access to structure slots.
.code a.?b
means that
.code a
may evaluate to
.codn nil ,
in which case the expression yields
.codn nil ;
otherwise,
.code a
must evaluate to a
.code struct
which has a slot
.codn b .

Integer tokens cannot be involved in this syntax, because they
form floating-point constants when juxtaposed with a dot.
Such ambiguous uses of floating-point tokens are diagnosed as syntax errors:

.verb
  (a.4)   ;; error: cramped floating-point literal
  (a .4)  ;; good: a followed by 0.4
.brev

.NP* Unbound Referencing Dot

Closely related to the referencing dot syntax is the unbound
referencing dot. This is a dot which is flanked by an expression on the right,
without any intervening whitespace, but is not preceded by an expression
Rather, it is preceded by whitespace,
or some punctuation such as
.codn [ ,
.code (
or
.codn ' .
This is a syntactic sugar which translates to
.code uref
syntax:

.verb
  .a       <--> (uref a)
  .a.b     <--> (uref a b)
  .a.?b    <--> (uref (t a) b)
.brev

If the unbound referencing dot is itself combined with a question
mark to form the
.code .?
token, then the translation to
.code uref
is as follows:

.verb
  .?a      <--> (uref t a)
  .?a.b    <--> (uref t a b)
  .?a.?b    <--> (uref t a (t b))
.brev

When the unbound referencing dot is applied to a dotted expression,
this can be understood as a conversion of
.code qref
to
.codn uref .

Indeed, this is exactly what happens if the unbound dot is applied to an
explicit
.code qref
expression:

.verb
  .(qref a b)   <--> (uref a b)
.brev

The unbound referencing dot takes its name from the semantics of the
.code uref
macro, which produces a function that implements late binding of an
object to a method slot. Whereas the expression
.code obj.a.b
denotes accessing object
.code obj
to retrieve slot
.code a
and then accessing slot
.code b
of the object from that slot, the expression
.code .a.b.
represents a "disembodied" reference: it produces a function which takes an
object as an argument and then performs the implied slot referencing on that
argument. When the function is called, it is said to bind the referencing to
the object. Hence that referencing is "unbound".

Whereas the expression
.code .a
produces a function whose argument must be an object,
.code .?a
produces a function whose argument may be
.codn nil .
The function detects this case and returns
.codn nil .

.NP* Quote and Quasiquote

.meIP >> ' expr

The quote character in front of an expression is used for suppressing evaluation,
which is useful for forms that evaluate to something other than themselves.
For instance if
.code "'(+ 2 2)"
is evaluated, the value is the three-element list
.codn "(+ 2 2)" ,
whereas if
.code "(+ 2 2)"
is evaluated, the value is
.codn 4 .
Similarly, the value of
.code 'a
is the symbol
.code a
itself, whereas the value of
.code a
is the contents of the variable
.codn a .

.meIP >> ^ qq-template

The caret in front of an expression is a quasiquote. A quasiquote is like
a quote, but with the possibility of substitution of material.

Under a quasiquote, form is considered to be a quasiquote template. The template
is considered to be a literal structure, except that it may contain
the notations
.mono
.meti >> , expr
.onom
and
.mono
.meti >> ,* expr
.onom
which denote non-constant parts.

A quasiquote gets translated into code which, when evaluated, constructs
the structure implied by
.metn qq-template ,
taking into account the unquotes and splices.

A quasiquote also processes nested quasiquotes specially.

If
.meta qq-template
does not contain any unquotes or splices (which match its
level of nesting), or is simply an atom, then
.mono
.meti >> ^ qq-template
.onom
is equivalent to
.mono
.meti >> ' qq-template .
.onom
in other words, it is like an ordinary quote.  For instance
.code "^(a b ^(c ,d))"
is equivalent to
.codn "'(a b ^(c ,d))" .
Although there is an unquote ,d it
belongs to the inner quasiquote
.codn "^(c ,d)" ,
and the outer quasiquote does not have
any unquotes of its own, making it equivalent to a quote.

Dialect note: in Common Lisp and Scheme,
.code ^form
is written
.codn `form ,
and
quasiquotes are also informally known as backquotes.  In \*(TX, the backquote
character
.code `
used for quasi string literals.

.meIP >> , expr

The comma character is used within a
.meta qq-template
to denote an unquote.  Whereas the quasiquote suppresses evaluation,
similarly to the quote, the comma introduces an exception: an element
of a form which is evaluated. For example, list
.code "^(a b c ,(+ 2 2) (+ 2 2))"
is the list
.codn "(a b c 4 (+ 2 2))" .
Everything
in the quasiquote stands for itself, except for the
.code ",(+ 2 2)"
which is evaluated.

Note: if a variable is called
.codn *x* ,
then the syntax
.code ,*x*
means
.codn ",* x*" :
splice
the value of
.codn x* .
In this situation, whitespace between the comma and the
variable name must be used:
.codn ", *x*" .

.meIP >> ,* expr

The comma-star operator is used within quasiquote list to denote a splicing
unquote.  The form which follows
.code ,*
must evaluate to a list. That list is spliced into
the structure which the quasiquote denotes. For example:
.code "'(a b c ,*(list (+ 3 3) (+ 4 4) d))"
evaluates to
.codn "(a b c 6 8 d)" .
The expression
.code "(list (+ 3 3) (+ 4 4))"
is evaluated to produce the list
.codn "(6 8)" ,
and this list is spliced into the quoted template.

.TP* "Dialect Notes:"

In other Lisp dialects, like Scheme and ANSI Common Lisp, the equivalent syntax
is usually
.code ,@
(comma at). The
.code @
character already has an assigned meaning in \*(TX, so
.code *
is used.

However,
.code *
is also a character that may appear in a symbol name, which creates
a potential for ambiguity. The syntax
.code ,*abc
denotes the application of the
.code ,*
splicing operator to the symbolic expression
.codn abc ;
to apply the ordinary non-splicing unquote to the symbol
.codn *abc ,
whitespace must be used:
.codn ", *abc" .

In \*(TX, the unquoting and splicing forms may freely appear outside of
a quasiquote template. If they are evaluated as forms, however, they
throw an exception:

.verb
   ,(+ 2 2) ;; error!

   ',(+ 2 2) --> ,(+ 2 2)
.brev

In other Lisp dialects, a comma not enclosed by backquote syntax is
treated as a syntax error by the reader.

.NP* Quasiquoting non-List Objects
Quasiquoting is supported over hash table and vector literals (see Vectors
and Hashes below).  A hash table or vector literal can be quoted, like any
object, for instance:

.verb
  '#(1 2 3)
.brev

The
.code "#(1 2 3)"
literal is turned into a vector atom right in the \*(TX parser,
and this atom is being quoted: this is
.mono
.meti (quote << atom )
.onom
syntactically, which evaluates to
.metn atom .

When a vector is quasi-quoted, this is a case of
.mono
.meti >> ^ atom
.onom
which evaluates to
.metn atom .

A vector can be quasiquoted, for example:

.verb
  ^#(1 2 3)
.brev

Unquotes can occur within a quasiquoted vector:

.verb
  (let ((a 42))
    ^#(1 ,a 3)) ; value is #(1 42 3)
.brev

In this situation, the
.code ^#(...)
notation produces code which constructs a vector.

The vector in the following example is also a quasivector. It contains
unquotes, and though the quasiquote is not directly applied to it,
it is embedded in a quasiquote:

.verb
  (let ((a 42))
    ^(a b c #(d ,a))) ; value is (a b c #(d 42))
.brev

Hash table literals have two parts: the list of hash construction
arguments and the key-value pairs. For instance:

.verb
   #H((:eql-based) (a 1) (b 2))
.brev

where
.code (:eql-based)
indicates that this hash table's keys are treated using
.code eql
equality, and
.code "(a 1)"
and
.code "(b 2)"
are the key/value entries. Hash literals may be quasiquoted.  In
quasiquoting, the arguments and pairs are treated as separate syntax; it is not
one big list.  So the following is not a possible way to express the above
hash:

.verb
  ;; not supported: splicing across the entire syntax
  (let ((hash-syntax '((:eql-based) (a 1) (b 2))))
    ^#H(,*hash-syntax))
.brev

This is correct:

.verb
  ;; fine: splicing hash arguments and contents separately
  (let ((hash-args '(:eql-based))
        (hash-contents '((a 1) (b 2))))
    ^#H(,hash-args ,*hash-contents))
.brev

.NP* Quasiquoting combined with Quasiliterals
When a quasiliteral is embedded in a quasiquote, it is possible to use
splicing to insert material into the quasiliteral.

Example:

.verb
  (eval (let ((a 3)) ^`abc @,a @{,a} @{(list 1 2 ,a)}`))

  -> "abc 3 3 1 2 3"
.brev

.NP* Vector Literals

.coIP "#(...)"

A hash token followed by a list denotes a vector. For example
.code "#(1 2 a)"
is a three-element vector containing the numbers
.code 1
and
.codn 2 ,
and the symbol
.codn a .

.NP* Struct Literals

.meIP >> #S( name >> { slot << value }*)

The notation
.code #S
followed by a nested list syntax denotes a struct literal.
The first item in the syntax is a symbol denoting the struct type
name. This must be the name of a struct type, otherwise the
literal is erroneous.  Followed by the struct type are slot names
interleaved with their values. The values are literal expressions,
not subject to evaluation.
Each slot name which is present in the
literal must name a slot in the struct type, though not
all slots in the struct type must be present in the literal.

When a struct literal is read, the denoted struct type is
constructed as if by a call to
.code make-struct
with an empty
.meta plist
argument, followed by a sequence of assignments which store into each
.meta slot
the corresponding
.meta value
expression.

.NP* Hash Literals

.meIP <> #H(( hash-argument *) >> ( key << value )*)

The notation
.code #H
followed by list syntax denotes a hash table literal.
The first item in the syntax is a list of keywords. These are the same
keywords as are used when calling the function hash to construct
a hash table. Allowed keywords are:
.codn :equal-based ,
.codn :eql-based ,
.codn :eq-based ,
.codn :weak-keys ,
.codn :weak-values ,
and
.codn :userdata .
If the
.code :userdata
keyword is present,
it must be followed by an object; that object
specifies the hash table's user data, which
can be retrieved using the
.code hash-userdata
function.
The
.codn :equal-based ,
.code :eql-based
and
.code :eq-based
keywords are mutually exclusive.

An empty list can be specified as
.code nil
or
.codn () ,
which defaults to a
hash table based on the
.code eql
function, with no weak semantics or user data.

The entire syntax following
.code #H
may be an empty list; however, that empty list may not
be specified as
.codn nil ;
the empty parentheses notation is required.

The hash table key-value contents are specified as zero or more
two-element lists, whose first element specifies the
.meta key
and whose second specifies the
.metn value .
Both expressions are literal objects, not subject to evaluation.

.NP* Range Literals

.meIP >> #R( from << to )

The notation
.code #R
followed by a two-element list syntax denotes a range literal.
It combines
.meta from
and
.meta to
expressions, themselves literals not subject to
evaluation, producing the range object whose corresponding
.code to
and
.code from
fields are the objects denoted by these expressions.

.NP* Buffer Literals

.meIP <> #b' hex-data '

The notation
.code #b'
introduces a buffer object: a data representation for a
block of bytes. This
.code #b'
prefix must be followed
by a data section and a closing quote.
The data section consists of hexadecimal digits, among which
may be interspersed whitespace: tabs, spaces and newlines.
There must be an even number of digits, or else the
notation is ill-formed. The whitespace is ignored, and
pairs of successive hex digits specify bytes.
If there are no hex digits, then a zero length buffer
is specified.

Buffers may be constructed by the
.code make-buf
function, and other means such as the
.code ffi-get
function.

Note that the
.code #b
prefix is also used for binary numbers. In that syntax, it
is followed by an optional sign, and then a mixture of one
or more of the digits
.code 0
or
.codn 1 .

.NP* Tree Node Literals

.meIP >> #N([ key >> [ left <> [ right ]]])

The notation
.code #N
followed by list syntax denotes a tree node literal. The list syntax must be a
proper list that has up to three elements. If the list is empty, it may not
be written as
.codn nil .

A tree node is an object of type
.codn tnode .
Every
.code tnode
has three elements: a
.metn key ,
a
.meta left
link and a
.meta right
link.  They may be objects of any type.
If the tree node literal syntax omits any of these, they default to
.codn nil .

.NP* Tree Literals

.meIP >> #T([([ keyfun >> [ lessfun <> [ equalfun ]]]) << item *])

The notation
.code #T
followed by list syntax denotes a tree literal, which specifies an
object of type
.codn tree .
Objects of type
.code tree
are search trees.

The list syntax which follows
.code #T
may be empty. If so, it cannot be written as
.codn nil .

The first element of the
.code #T
syntax, if present, must be a list of zero to three elements.
These elements are symbols giving the names of the
.code tree
object's
.IR "key abstraction functions" .
.meta keyfun
specifies the key function which is applied to each element to
retrieve its key. If it is omitted, the object shall use the
.code identity
function as its key.
The
.meta lessfun
specifies the name of the comparison function by which keys are compared
for inequality. It defaults to
.codn less .
The
.meta equalfun
specifies the function by which keys are compared for equality. It
defaults to
.codn equal .
A symbol which is specified as the name of any of these three special
functions must be an element of the list stored in the special variable
.codn *tree-fun-whitelist* ,
otherwise the string literal is diagnosed as erroneous.
Note: this is due to security considerations, since these three
functions are executed during the processing of tree syntax.

A tree object is constructed from a tree literal by first creating an empty
tree endowed with the three key abstraction functions that are indicated in the
syntax, either explicitly or as defaults. Then, every
.meta element
object is constructed from its respective literal syntax and inserted into
the tree.

.coNP The @ .. notation
In \*(TL, there is a special "dotdot" notation consisting of a pair of dots.
This can be written between successive atoms or compound expressions, and is a
shorthand for
.codn rcons .

That is to say,
.code "A .. B"
translates to
.codn "(rcons A B)" ,
and so for instance
.code "(a b .. (c d) e .. f . g)"
means
.codn "(a (rcons b (c d)) (rcons e f) . g)" .

The
.code rcons
function constructs a range object, which denotes a pair of values.
Range objects are most commonly used for referencing subranges of
sequences.

For instance, if
.code L
is a list, then
.code "[L 1 .. 3]"
computes a sublist of
.code L
consisting of
elements 1 through 2 (counting from zero).

Note that if this notation is used in the dot position of an improper
list, the transformation still applies. That is, the syntax
.code "(a . b .. c)"
is valid and produces the object
.code "(a . (rcons b c))"
which is another way of writing
.codn "(a rcons b c)" ,
which is quite probably nonsense.

The notation's
.code ..
operator associates right to left, so that
.code a..b..c
denotes
.codn "(rcons a (rcons b c))" .

Note that range objects are not printed using the dotdot notation.
A range literal has the syntax of a two-element list, prefixed by
.codn #R .
(See Range Literals above).

In any context where the dotdot notation may be used, and where
it is evaluated to its value, a range literal may also be specified.
If an evaluated dotdot notation specifies two constant expressions, then
an equivalent range literal can replace it. For instance the
form
.code "[L 1 .. 3]"
can also be written
.codn "[L #R(1 3)]" .
The two are syntactically different, and so if these expressions are being
considered for their syntax rather than value, they are not the same.

.NP* The DWIM Brackets
\*(TL has a square bracket notation. The syntax
.code [...]
is a shorthand
way of writing
.codn "(dwim ...)" .
The
.code []
syntax is useful for situations
where the expressive style of a Lisp-1 dialect is useful.

For instance if
.code foo
is a variable which holds a function object, then
.code "[foo 3]"
can be used to call it, instead of
.codn "(call foo 3)" .
If foo is a vector, then
.code "[foo 3]"
retrieves the fourth element, like
.codn "(vecref foo 3)" .
Indexing over lists,
strings and hash tables is possible, and the notation is assignable.

Furthermore, any arguments enclosed in
.code []
which are symbols are treated
according to a modified namespace lookup rule.

More details are given in the documentation for the
.code dwim
operator.

.NP* Compound Forms
In \*(TL, there are two types of compound forms: the Lisp-2 style
compound forms, denoted by ordinary lists that are expressed with parentheses.
There are Lisp-1 style compound forms denoted by the DWIM Brackets, described
in the previous section.

The first position of an ordinary Lisp-2 style compound form, is expected to
have a function or operator name.  Then arguments follow. There may
also be an expression in the dotted position, if the form is a function call.

If the form is a function call then the arguments are evaluated. If any of the
arguments are symbols, they are treated according to Lisp-2 namespacing rules.

A function name may be a symbol, or else any of the syntactic forms given in the
description of the function
.codn func-get-name .

.NP* Dot Position in Function Calls

If there is an expression in the dotted position of a function call
expression, it is also evaluated, and the resulting value is involved in the
function call in a special way.

Firstly, note that a compound form cannot be used in the dot position,
for obvious reasons, namely that
.code "(a b c . (foo z))"
does not mean that there is
a compound form in the dot position, but denotes an alternate spelling for
.codn "(a b c foo z)" ,
where foo behaves as a variable.

If the dot position of a compound form is an atom, then the behavior
may be understood according to the following transformations:

.verb
  (f a b c ... . x)  -->  (apply (fun f) a b c ... x)
  [f a b c ... . x]  -->  [apply f a b c ... x]
.brev

In addition to atoms, meta-expressions and meta-variables can appear in the dot
position, even though their underlying syntax is comprised of a compound
expression. This appears to work according to a transformation pattern
which superficially appears to be the same as that for atoms:

.verb
  (f a b c ... . @x)  -->  (apply (fun f) a b c ... @x)
.brev

However, in this situation, the
.code @x
is actually the form
.code "(sys:var x)"
and the dotted form is actually a proper list. The transformation is
in fact taking place over a proper list, like this:

.verb
  (f a b c ... sys:var x)  -->  (apply (fun f) a b c ... (sys:var @x))
.brev

That is to say, the \*(TL form expander reacts to the presence of a
.code sys:var
or
.code sys:expr
atom in embedded in the form. That symbol and the items which follow it
are wrapped in an additional level of nesting, converted into a single
compound form element.

Effectively, in all these cases, the dot notation constitutes a shorthand for
.codn apply .

Examples:

.verb
  ;; a contains 3
  ;; b contains 4
  ;; c contains #(5 6 7)
  ;; s contains "xyz"

  (foo a b . c)  ;; calls (foo 3 4 5 6 7)
  (foo a)        ;; calls (foo 3)
  (foo . s)      ;; calls (foo #\ex #\ey #\ez)

  (list . a)     ;; yields 3
  (list a . b)   ;; yields (3 . 4)
  (list a . c)   ;; yields (3 5 6 7)
  (list* a c)    ;; yields (3 . #(5 6 7))

  (cons a . b)   ;; error: cons isn't variadic.
  (cons a b . c) ;; error: cons requires exactly two arguments.

  [foo a b . c]  ;; calls (foo 3 4 5 6 7)

  [c 1]          ;; indexes into vector #(5 6 7) to yield 6

  (call (op list 1 . @1) 2) ;; yields (1 . 2)
.brev

Note that the atom in the dot position of a function call may
be a symbol macro. Since the semantics works as if by
transformation to an apply form in which the original dot
position atom is an ordinary argument, the symbol macro
may produce a compound form.

Thus:

.verb
  (symacrolet ((x 2))
    (list 1 . x))  ;; yields (1 . 2)

  (symacrolet ((x (list 1 2)))
    (list 1 . x))  ;; yields (1 1 2)
.brev

That is to say, the expansion of
.code x
is not substituted into the form
.code "(list 1 . x)"
but rather the transformation to
.code apply
syntax takes place first, and
so the substitution of
.code x
takes place in a form resembling
.codn "(apply (fun list) 1 x)" .

Dialect Note:

In some other Lisp dialects like ANSI Common Lisp, the improper list syntax may
not be used as a function call; a function called apply (or similar) must be
used for application even if the expression which gives the trailing arguments
is a symbol. Moreover, applying sequences other than lists is not supported.

.NP* Improper Lists as Macro Calls

\*(TL allows macros to be called using forms which are improper lists.
These forms are simply destructured by the usual macro parameter list
destructuring. To be callable this way, the macro must have an argument
list which specifies a parameter match in the dot position. This dot position
must either match the terminating atom of the improper list form,
or else match the trailing portion of the improper list form.

For instance if a macro mac is defined as

.verb
  (defmacro mac (a b . c) ...)
.brev

then it may not be invoked as
.code "(mac 1 . 2)"
because the required argument
.code b
is not satisfied, and so the
.code 2
argument cannot match the dot position
.code c
as required. The macro may be called as
.code "(mac 1 2 . 3)"
in which case
.code c
receives the form
.codn 3 .
If it is called as
.code "(mac 1 2 3 . 4)"
then
.code c
receives the improper list form
.codn "3 . 4" .

.NP* Regular Expression Literals
In \*(TL, the
.code /
character can occur in symbol names, and the
.code /
token
is a symbol. Therefore the
.code /regex/
syntax is not used for denoting regular expressions; rather, the
.code #/regex/
syntax is used.

.NP* Notation for Circular and Shared Structure

\*(TL supports a printed notation called
.I "circle notation"
which accurately articulates
the representation of objects which contain shared substructures as well
as circular references. The notation is supported as a means of
input, and is also optionally produced as output, controlled by the
.code *print-circle*
variable.

Ordinarily, shared substructure in printed objects is not
evident, except in the case of multiple occurrences of interned symbols,
in whose semantics it is implicit that they refer to the same object.
Other shared structure is printed as separate copies which look like
distinct objects. For instance, the object produced by
.code "(let ((shared '(1 2))) (list shared shared))"
is printed as
.codn "((1 2) (1 2))" ,
where it is not clear that the two occurrences of
.code "(1 2)"
are actually the same object. Under the circle notation, this object
can be represented as
.codn "(#5=(1 2) #5#)" .
The
.code #5=
part introduces a reference label, associating the arbitrarily
chosen non-negative integer 5 with the object which follows.
The subsequent notation
.code #5#
simply refers to the object labeled by 5, reproducing that object
by reference. The result is a two-element list which has the same
.code "(1 2)"
in two places.

Circular structure presents a greater challenge to printing: namely, if it is
printed by a naive recursive descent, it results in infinite output, and
possibly stack exhaustion due to recursion. The circle notation detects
and handles circular references. For instance, the object produced by
.code "(let ((c (list 1))) (rplacd c c))"
produces a circular list which looks like an infinite list of 1's:
.codn "(1 1 1 1 ...)" .
This cannot be printed. However, under the circle notation, it can
be represented as
.codn "#1=(1 . #1#)" .
The entire object itself is labeled by the integer 1. Then, enclosed
within the syntax of that labeled object itself, a reference occurs
to the label. This circular label reference represents the corresponding
circular reference in the object.

A detailed description of the notational elements follows:

.meIP <> # digits = < object

The
.code #=
syntax introduces an object label which denotes the
object whose printed representation follows. The label is identified by
the integer value arising from digits
.meta digits
which are one or more decimal digits. Note: the value zero is permitted;
even though when the notation is produced by the \*(TL printer, labeling
begins at 1. Negative values are not possible because a leading sign
is not part of the syntax.

There may be no more than one definition for a given label within the syntactic
scope being parsed, otherwise a syntax error occurs.
In \*(TX pattern language code,
an entire source file is parsed as one unit, and so scope for the circular
notation's references is the entire source file. Files processed by
.code @(include)
have their own scope. The scope for labels in \*(TL source code is the
top-level expression in which they appear.  Consequently, references
in one \*(TL top-level expression cannot reach definitions in another.

.meIP <> # digits #

The
.code ##
syntax denotes a label reference: the repetition of an object that was
previously labeled by the integer given by
.metn digits .
If no such label had been introduced in the syntactic scope,
a syntax error occurs.
An object was previously labeled by
.meta digits
if a
.code #=
definition occurs in the same syntactic scope as the reference,
and is applied to an object which either encloses the reference,
or lexically precedes the reference.  Forward references such as
.code "(#1# #1=(1 2))"
are not supported.

.TP* "Note:"
Circular notation can span hash table literals. The syntax
.code "#1=#H((:eql-based) (#1# #1#))"
denotes an
.codn eql -based
hash table which contains one entry, in which that
same table itself is both the key and value. This kind of
circularity is not supported for
.codn equal -based
hash tables. The analogous syntax
.code "#1=#H(() (#1# #1#))"
produces a hash table in an inconsistent state.

.TP* "Dialect note:"
Circle notation is taken from Common Lisp, 
intended to be unsurprising to users familiar with that
language.
The implementation is based on descriptions in the ANSI Common Lisp
document, judiciously taking into account the content of the X3J13 Cleanup
Issues named PRINT-CIRCLE-STRUCTURE:USER-FUNCTIONS-WORK and
PRINT-CIRCLE-SHARED:RESPECT-PRINT-CIRCLE.

.NP* Notation for Erasing Objects

.meIP #; < expr

The \*(TL notation
.code #;
in TXR Lisp indicates that the expression
.meta expr
is to be read and then discarded, as if it were replaced by whitespace.

This is useful for temporarily "commenting out" an expression.

.TP* Notes:
Whereas it is valid for a \*(TL source file to be empty, it is
a syntax error if a \*(TL source file contains nothing but one or more
objects which are each suppressed by a preceding
.codn #; .
In the interactive listener, an input line consisting of nothing but
commented-out objects is similarly a syntax error.

The notation does not cascade; consecutive occurrences of
.code #;
trigger a syntax error.

The notation interacts with the circle notation. Firstly, if an object
which is erased by
.code #;
contains circular-referencing instances of the label notation,
those instances refer to
.codn nil .
Secondly, commented-out objects may introduce labels
which are subsequently referenced in
.metn expr .
An example of the first situation occurs in:

.verb
  #;(#1=(#1#))
.brev

Here the
.code #1#
label is a circular reference because it refers to an object which
is a parent of the object which contains that reference. Such a reference
is only satisfied by a "backpatching" process once the entire surrounding syntax
is processed to the top level. The erasure perpetrated by
.code #;
causes the
.code #1#
label reference to be replaced by
.codn nil ,
and therefore the labeled object is the object
.codn (nil) .

An example of the second situation is

.verb
  #;(#2=(a b c)) #2#
.brev

Here, even though the expression
.code "(#2=(a b c))"
is suppressed, the label definition which it has introduced persists into the
following object, where the label reference
.code #2#
resolves to
.codn "(a b c)" .

A combination of the two situations occurs in

.verb
  #;(#1=(#1#)) #1#
.brev

which yields
.codn "(nil)" .
This is because the
.code #1=
label is available; but the earlier
.code #1#
reference, being a circular reference inside an erased object, had lapsed to
.codn nil .

.SS* Generalization of List Accessors
In ancient Lisp in the 1960's, it was not possible to apply the operations
.code car
and
.code cdr
to the
.code nil
symbol (empty list), because it is not a
.code cons
cell. In
the InterLisp dialect, this restriction was lifted: these operations were
extended to accept
.code nil
(and return
.codn nil ).
The convention was adopted in
other Lisp dialects such as MacLisp and eventually in Common Lisp. Thus there
exists an object which is not a cons, yet which takes
.code car
and
.codn cdr .

In \*(TL, this relaxation is extended further. For the sake of convenience,
the operations
.code car
and
.codn cdr ,
are made to work with strings and vectors:

.verb
  (cdr "") -> nil
  (car "") -> nil

  (car "abc") -> #\ea
  (cdr "abc") -> "bc"

  (cdr #(1 2 3)) -> #(2 3)
  (car #(1 2 3)) -> 1
.brev

Moreover, structure types which define the methods
.codn car ,
.code cdr
and
.code nullify
can also be treated in the same way.

The
.code ldiff
function is also extended in a special way. When the right parameter
a non-list sequence, then it uses the equal equality test rather than eq for
detecting the tail of the list.

.verb
  (ldiff "abcd" "cd") -> (#\ea #\eb)
.brev

The
.code ldiff
operation starts with
.str "abcd"
and repeatedly applies
.code cdr
to produce
.str "bcd"
and
.strn "cd" ,
until the suffix is equal to the second argument:
.mono
(equal "cd" "cd")
.onom
yields true.

Operations based on
.codn car ,
.code cdr
and
.codn ldiff ,
such as
.code keep-if
and
.code remq
extend to
strings and vectors.

Most derived list processing operations such as
.code remq
or
.code mapcar
obey the following
rule: the returned object follows the type of the leftmost input list object.
For instance, if one or more sequences are processed by
.codn mapcar ,
and the
leftmost one is a character string, the function is expected to return
characters, which are converted to a character string. However, in the
event that the objects produced cannot be assembled into that type of
sequence, a list is returned instead.

For example
.mono
[mapcar list "ab" "12"]
.onom
returns
.codn "((#\ea #\eb) (#\e1 #\e2))" ,
because a string cannot hold lists of characters. However
.mono
[mappend list "ab" "12"]
.onom
returns
.strn "a1b2" .

The lazy versions of these functions such as
.code mapcar*
do not have this behavior;
they produce lazy lists.

.SS* Generalization of Iteration

\*(TL implements a unified paradigm for iterating over sequence-like
container structures and abstract spaces such as bounded and unbounded ranges
of integers. This concept is based around an iterator abstraction which is
directly compatible with Lisp cons cell traversal in the sense that when
iteration takes place over lists, the iterator instance is nothing but a cons
cell.

An iterator is created using the constructor function
.code iter-begin
which takes a single argument. The argument denotes a space to be traversed;
the iterator provides the means for that traversal.

When the
.code iter-begin
function is applied to a list (a
.code cons
cell or the
.code nil
object), the return value is that object itself. The remaining functions
in the iterator API then behave like aliases for list processing functions.
The
.code iter-more
function behaves like
.codn identity ,
.code iter-item
behaves like
.code car
and
.code iter-step
behaves like
.codn cdr .

For example, the following loops not only produce identical behavior,
but the
.code iter
variable steps through the
.code cons
cells in the same manner in both:

.verb
  ;; print all symbols in the list (a b c d):

  (let ((iter '(a b c d)))
    (while iter
      (prinl (car iter))
      (set iter (cdr iter))))

  ;; likewise:

  (let ((iter (iter-begin '(a b c d))))
    (while (iter-more iter)
      (prinl (iter-item iter))
      (set iter (iter-step iter))))
.brev

There are three important differences.

Firstly, both examples will still work
if the list
.code "(a b c d)"
is replaced by a different kind of sequence, such as the string
.str abcd
or the vector
.codn "#(a b c d)" .
However, the former example will not execute efficiently on these objects.
The reason is that the
.code cdr
function will construct successive suffixes of the string and list object.
That requires not only the allocation of memory, but changes the running time
complexity of the loop from linear to quadratic.

Secondly, the former example with
.cod3 car / cdr
will not work correctly if the sequence is an empty non-list sequence, like
the null string or empty vector. Rectifying this problem requires the
.code nullify
function to be used:

.verb
  ;; print all symbols in the list (a b c d):

  (let ((iter (nullify "abcd")))
    (while iter
      (prinl (car iter))
      (set iter (cdr iter))))
.brev

The
.code nullify
function converts empty sequences of all kinds into the empty list
.codn nil .

Thirdly, the second
example will work even if the input list is replaced with certain objects
which are not sequences at all:

.verb
  ;; Print the integers from 0 to 3

  (let ((iter (iter-begin 0..4)))
    (while (iter-more iter)
      (prinl (iter-item iter))
      (set iter (iter-step iter))))

  ;; Print incrementing integers starting at 1,
  ;; breaking out of the loop after 100.

  (let ((iter (iter-begin 1)))
    (while (iter-more iter)
      (if (eql 100 (prinl (iter-item iter)))
        (return))
      (set iter (iter-step iter))))
.brev

In \*(TL, numerous functions that appear as list processing functions in other
contemporary Lisp dialects, and historically, are actually sequence processing
functions based on the above iterator paradigm.

.SS* Callable Objects

In \*(TL, sequences (strings, vectors and lists) as well as hashes and
regular expressions can be used as functions everywhere, not just with the DWIM
brackets.

Sequences work as one or two-argument functions. With a single argument, an
element is selected by position and returned. With two arguments, a range is
extracted and returned.

Moreover, when a sequence is used as a function of one argument, and the
argument is a range object rather than an integer, then the call is equivalent
to the two-argument form.  This is the basis for array slice syntax like
.mono
["abc" 0..1] .
.onom

Hashes also work as one or two argument functions, corresponding to the
arguments of the gethash function.

A regular expression behaves as a one, two, or three argument function, which
operates on a string argument.
It returns the leftmost matching substring, or else
.codn nil .

.B Example 1:

.verb
  (mapcar "abc" '(2 0 1)) -> (#\ec #\ea #\eb)
.brev

Here,
.code mapcar
treats the string
.str abc
as a function of one argument (since there
is one list argument). This function maps the indices
.codn 0 ,
.code 1
and
.code 2
to the
corresponding characters of string
.strn abc .
Through this function, the list of integer indices
.code "(2 0 1)"
is taken to the list of characters
.codn "(#\ec #\ea #\eb)" .

.B Example 2:

.verb
  (call '(1 2 3 4) 1..3) -> (2 3)
.brev

Here, the shorthand
.code "1 .. 3"
denotes
.codn "(rcons 1 3)" .
A range used as an argument
to a sequence performs range extraction: taking a slice starting at
index 1, up to and not including index 3, as if by the call
.codn "(sub '(1 2 3 4) 1 3)" .

.B Example 3:

.verb
  (call '(1 2 3 4) '(0 2)) -> (1 2)
.brev

A list of indices applied to a sequence is equivalent to using the
select function, as if
.code "(select '(1 2 3 4) '(0 2))"
were called.

.B Example 4:

.verb
  (call #/b./ "abcd") -> "bc"
.brev

Here, the regular expression, called as a function, finds the matching
substring
.str bc
within the argument
.strn abcd .

.SS* Special Variables
Similarly to Common Lisp, \*(TL is lexically scoped by default, but
also has dynamically scoped (a.k.a "special") variables.

When a variable is defined with
.code defvar
or
.codn defparm ,
a binding for the symbol is
introduced in the global name space, regardless of in what scope the
.code defvar
form occurs.

Furthermore, at the time the defvar form is evaluated, the symbol which
names the variable is tagged as special.

When a symbol is tagged as special, it behaves differently when it is used
in a lexical binding construct like
.codn let ,
and all other such constructs
such as function parameter lists. Such a binding is not the usual lexical
binding, but a "rebinding" of the global variable. Over the dynamic scope
of the form, the global variable takes on the value given to it by the
rebinding. When the form terminates, the prior value of the variable
is restored. (This is true no matter how the form terminates; even if by
an exception.)

Because of this "pervasive special" behavior of a symbol that has been
used as the name of a global variable, a good practice is to make global
variables have visually distinct names via the "earmuffs" convention:
beginning and ending the name with an asterisk.

.TP* "Example:"

.verb
  (defvar *x* 42)     ;; *x* has a value of 42

  (defun print-x ()
    (format t "~a\en" *x*))

  (let ((*x* "abc"))  ;; this overrides *x*
    (print-x))        ;; *x* is now "abc" and so that is printed

  (print-x)           ;; *x* is 42 again and so "42" is printed
.brev

.TP* "Dialect Note 1:"

The terms
.I bind
and
.I binding
are used differently in \*(TL compared to ANSI Common Lisp.
In \*(TL binding is an association between a symbol and an abstract storage
location. The association is registered in some namespace, such as the global
namespace or a lexical scope.  That storage location, in turn, contains a
value. In ANSI Lisp, a binding of a dynamic variable is the association between
the symbol and a value.  It is possible for a dynamic variable to exist, and
not have a value.  A value can be assigned, which creates a binding.
In \*(TL, an assignment is an operation which transfers a value into
a binding, not one which creates a binding.

In ANSI Lisp, a dynamic variable can exist which has no value. Accessing
the value signals a condition, but storing a value is permitted; doing so
creates a binding. By contrast, in \*(TL a global variable cannot exist without
a value. If a
.code defvar
form doesn't specify a value, and the variable doesn't exist, it is
created with a value of
.codn nil .

.TP* "Dialect Note 2:"

Unlike ANSI Common Lisp, \*(TL has global lexical variables in addition to
special variables. These are defined using
.code defvarl
and
.codn defparml .
The only difference is that when variables are introduced by these macros,
the symbols are not marked special, so their binding in lexical scopes
is not altered to dynamic binding.

Many variables in \*(TL's standard library are global lexicals.
Those which are special variables obey the "earmuffs" convention
in their naming. For instance
.codn s-ifmt ,
.code log-emerg
and
.code sig-hup
are global lexicals, because they provide constant values
for which overriding doesn't make sense. On the other hand the standard
output stream variable
.code *stdout*
is special. Overriding it over a dynamic scope is useful, as a means of
redirecting the output of functions which write to the
.code *stdout*
stream.

.TP* "Dialect Note 3:"

In Common Lisp,
.code defparm
is known as
.codn defparameter .

.SS* Syntactic Places and Accessors

The \*(TL feature known as
.I syntactic places
allows programs to use
the syntax of a form which is used to
.I access
a value from an environment or
object, as an expression which denotes a
.I place
where a value may be
.I stored.

They are almost exactly the
same concept as "generalized references" in Common Lisp, and are related to
"lvalues" in languages in the C family, or "designators" in Pascal.

.NP* Symbolic Places

A symbol is a is a syntactic place if it names a variable. If
.code a
is a variable, then it may be assigned using the
.code set
operator: the form
.code "(set a 42)"
causes
.code a
to have the integer value 42.

.NP* Compound Places

A compound expression can be a syntactic place, if its leftmost constituent is
as symbol which is specially registered, and if the form has the correct syntax
for that kind of place, and suitable semantics. Such an expression is a compound
place.

An example of a compound place is a
.code car
form. If
.code c
is an expression denoting a
.code cons
cell, then
.code "(car c)"
is not only an expression which retrieves the value of the
.code car
field of the cell. It is also a syntactic place which denotes that field as
a storage location. Consequently, the expression
.mono
(set (car c) "abc")
.onom
stores the character string
.str "abc"
in that location.  Although the same effect can be obtained with
.mono
(rplaca c "abc")
.onom
the syntactic place frees the programmer from having to remember
different update functions for different kinds of places.
There are
various other advantages. \*(TL provides a plethora of operators
for modifying a place in addition to
.codn set .
Subject to certain usage restrictions, these operators work uniformly on all
places. For instance, the expression
.code "(rotate (car x) [str 3] y)"
causes three different kinds of places to exchange contents,
while the three expressions denoting those places
are evaluated only once. New kinds of place update macros like
.code rotate
are quite easily defined, as are new kinds of compound places.

.NP* Accessor Functions

When a function call form such as the above
.code "(car x)"
is a syntactic place, then the function is called an
.IR accessor .
This term is used throughout this document to denote functions
which have associated syntactic places.

.NP* Macro Call Syntactic Places

Syntactic places can be macros (global and lexical), including symbol macros.
So for instance in
.code "(set x 42)"
the
.code x
place can actually be a symbolic macro which expands to, say,
.codn "(cdr y)" .
This means that the assignment is effectively
.codn "(set (cdr y) 42)" .

.NP* User-Defined Syntactic Places and Place Operators

Syntactic places, as well as operators upon syntactic places,
are both open-ended. Code can be written quite easily in \*(TL to introduce
new kinds of places, as well as new place-mutating operators.
New places can be introduced with the help of the
.codn defplace ,
.code define-accessor
or
.code defset
macros, or possibly the
.code define-place-macro
macro in simple cases when a new syntactic place can be expressed as a
transformation to the syntax of an existing place.
Three ways exist for developing new place update macros (place operators).
They can be written using the ordinary macro definer
ordinary macro definer
.codn defmacro ,
with the help of special utility macros called
.codn with-update-expander ,
.codn with-clobber-expander ,
and
.codn with-delete-expander .
They can also be written using
.code defmacro
in conjunction with the operators
.code placelet
or
.codn placelet* .
Simple update macros similar to
.code inc
and
.code push
can be written compactly using
.codn define-modify-macro .

.NP* Deletable Places

Unlike generalized references in Common Lisp, \*(TL syntactic
places support the concept of deletion. Some kinds of places
can be deleted, which is an action distinct from (but does not preclude) being
overwritten with a value. What exactly it means for a place to be deleted,
or whether that is even permitted, depends on the kind of place.
For instance a place which denotes a lexical variable may not be deleted,
whereas a global variable may be.
A place which denotes a hash table entry may be deleted, and results in the
entry being removed from the hash table. Deleting a place in a list
causes the trailing items, if any, or else the terminating atom, to
move in to close the gap. Users may define new kinds of places
which support deletion semantics.

.NP* Evaluation of Places

To bring about their effect, place operators must evaluate one or
more places. Moreover, some of them evaluate additional forms which are not
places. Which arguments of a place operator form are places and which are
ordinary forms depends on its specific syntax. For all the built-in place
operators, the position of an argument in the syntax determines whether it is
treated as (and consequently required to be) a syntactic place, or whether it is
an ordinary form.

All built-in place operators perform the evaluation of place and non-place
argument forms in strict left to right order.

Place forms are evaluated not in order to compute a value, but in order to
determine the storage location.  In addition to determining a storage location,
the evaluation of a place form may possibly give rise to side effects.
Once a place is fully evaluated, the storage location can then be accessed.
Access to the storage location is not considered part of the evaluation of a
place.  To determine a storage location means to compute some hidden referential
object which provides subsequent access to that location without the need for a
re-evaluation of the original place form.  (The subsequent access to the
place through this referential object may still require a multi-step traversal
of a data structure; minimizing such steps is a matter of optimization.)

Place forms may themselves be compounds, which contain subexpressions that must
be evaluated. All such evaluation for the built-in places takes place in left
to right order.

Certain place operators, such as
.code shift
and
.codn rotate ,
exhibit an unspecified behavior with regard to the timing of the access
of the prior value of a place, relative to the evaluation of places
which occur later in the same place operator form. Access to the prior values
may be delayed until the entire form is evaluated, or it may be interleaved
into the evaluation of the form. For example, in the form
.codn "(shift a b c 1)" ,
the prior value of
.code a
can be accessed and saved as soon as
.code a
is evaluated, prior to the evaluation of
.codn b .
Alternatively,
.code a
may be accessed and saved later, after the evaluation of
.code b
or after the evaluation of all the forms.  This issue affects the behavior of
place-modifying forms whose subforms contain side effects. It is recommended
that such forms not be used in programs.

.NP* Nested Places

Certain place forms are required to have one or more arguments which
are themselves places. The prime example of this, and the only example from
among built-in syntactic places, are DWIM forms. A DWIM form has the syntax

.mono
.mets (dwim < obj-place < index <> [ alt ])
.onom

and the square-bracket-notation equivalent:

.mono
.mets >> [ obj-place < index <> [ alt ]]
.onom

Note that not only is the entire form a place, denoting some element or element
range of
.metn obj-place ,
but there is the added constraint that
.meta obj-place
must also itself be a syntactic place.

This requirement is necessary, because it supports the behavior that
when the element or element range is updated, then
.meta obj-place
is also potentially updated.

After the assignment
.mono
(set [obj 0..3] '("forty" "two"))
.onom
not only is the range of places denoted by
.code "[obj 0..3]"
replaced by the list of strings
.mono
("forty" "two")
.onom
but
.code obj
may also be overwritten with a new value.

This behavior is necessary because the DWIM brackets notation maintains
the illusion of an encapsulated array-like container over several dis-similar
types, including Lisp lists.  But Lisp lists do not behave as fully
encapsulated containers.  Some mutations on Lisp lists return new objects,
which then have to stored (or otherwise accepted) in place of the original
objects in order to maintain the array-like container illusion.

.NP* Built-In Syntactic Places

The following is a summary of the built-in place forms, in addition to symbolic
places denoting variables. New syntactic place forms can be
defined by \*(TX programs.

.mono
.mets (car << object )
.mets (first << object )
.mets (rest << object )
.mets (second << object )
.mets (third << object )
.mets ...
.mets (tenth << object )
.mets (last < object <> [ num ])
.mets (butlast < object <> [ num ])
.mets (cdr << object )
.mets (caar << object )
.mets (cadr << object )
.mets (cdar << object )
.mets (cddr << object )
.mets ...
.mets (cdddddr << object )
.mets (nthcdr < index << obj )
.mets (nthlast < index << obj )
.mets (butlastn < num << obj )
.mets (last < num << obj )
.mets (nth < index << obj )
.mets (ref < seq << idx )
.mets (sub < sequence >> [ from <> [ to ]])
.mets (vecref < vec << idx )
.mets (chr-str < str << idx )
.mets (gethash < hash < key <> [ alt ])
.mets (hash-userdata << hash )
.mets (dwim < obj-place < index <> [ alt ])
.mets (sub-list < obj >> [ from <> [ to ]])
.mets (sub-vec < obj >> [ from <> [ to ]])
.mets (sub-str < str >> [ from <> [ to ]])
.mets >> [ obj-place < index <> [ alt ]] ;; equivalent to dwim
.mets (symbol-value << symbol-valued-form )
.mets (symbol-function << function-name-valued-form )
.mets (symbol-macro << symbol-valued-form )
.mets (fun << function-name )
.mets (force << promise )
.mets (errno)
.mets (slot < struct-obj << slot-name-valued-form )
.mets (qref < struct-obj << slot-name ) ;; by macro-expansion to (slot ...)
.mets >< struct-obj . slot-name ;; equivalent to qref
.mets (sock-peer << socket )
.mets (carray-sub < carray >> [ from <> [ to ]])
.mets (sub-buf < buf >> [ from <> [ to ]])
.mets (left << node )
.mets (right << node )
.mets (key << node )
.onom

.NP* Built-In Place-Mutating Operators

The following is a summary of the built-in place mutating macros.
They are described in detail in their own sections.

.meIP (set >> { place << new-value }*)
Assigns the values of expressions to places, performing assignments in left to right order,
returning the value assigned to the rightmost place.

.meIP (pset >> { place << new-value }*)
Assigns the values of expressions to places, performing the determination of
places and evaluation of the expressions left to right, but the assignment
in parallel. Returns the value assigned to the rightmost place.

.meIP (zap < place <> [ new-value ])
Assigns
.meta new-value
to place, defaulting to
.codn nil ,
and returns the prior value.

.meIP (flip << place )
Logically toggles the Boolean value of
.metn place ,
and returns the new value.

.meIP (test-set << place )
If
.meta place
contains
.codn nil ,
stores
.code t
into the place and returns
.code t
to indicate that the store took place.
Otherwise does nothing and returns
.codn nil .

.meIP (test-clear << place )
If
.meta place
contains a Boolean true value, stores
.code nil
into the place and returns
.code t
to indicate that the store took place.
Otherwise does nothing and returns
.codn nil .

.meIP (compare-swap < place < cmp-fun < cmp-val << store-val )
Examines the value of
.meta place
and compares it to
.meta cmp-val
using the comparison function given by the function name
.metn cmp-fun .
If the comparison is false, returns
.codn nil .
Otherwise, stores the
.meta store-val
value into
.meta place
and returns
.codn t .

.meIP (inc < place <> [ delta ])
Increments
.meta place
by
.metn delta ,
which defaults to 1, and returns the new value.

.meIP (dec < place <> [ delta ])
Decrements
.meta place
by
.metn delta ,
which defaults to 1, and returns the new value.

.meIP (pinc < place <> [ delta ])
Increments
.meta place
by
.metn delta ,
which defaults to 1, and returns the old value.

.meIP (pdec < place <> [ delta ])
Decrements
.meta place
by
.metn delta ,
which defaults to 1, and returns the old value.

.meIP (test-inc < place >> [ delta <> [ from-val ]])
Increments
.meta place
by
.meta delta
and returns
.code t
if the previous value was
.code eql
to
.metn from-val ,
where
.meta delta
defaults to 1
and
.meta from-val
defaults to zero.

.meIP (test-dec < place >> [ delta <> [ to-val ]])
Decrements
.meta place
by
.meta delta
and returns
.code t
if the new value is
.code eql
to
.metn to-val ,
where
.meta delta
defaults to 1
and
.meta to-val
defaults to 0.

.meIP (swap < left-place << right-place )
Exchanges the values of
.meta left-place
and
.metn right-place .

.meIP (push < item << place )
Pushes
.meta item
into the list stored in
.code place
and returns
.codn item .

.meIP (pop << place )
Pop the list stored in
.meta place
and returns the popped value.

.meIP (shift << place + << shift-in-value)
Treats one or more places as a "multi-place shift register".
Values are shifted to the left among the places. The
rightmost place receives
.metn shift-in-value ,
and the value of the leftmost place emerges as the return value.

.meIP (rotate << place *)
Treats zero or more places as a "multi-place rotate register".
The places exchange values among themselves, by a rotation
by one place to the left. The value of the leftmost place
goes to the rightmost place, and that value is returned.

.meIP (del << place )
Deletes a place which supports deletion, and returns
the value which existed in that place prior to deletion.

.meIP (lset <> { place }+ << list-expr )
Sets multiple places to values obtained from successive
elements of
.metn sequence .

.meIP (upd < place << opip-arg *)
Applies an
.codn opip -style
operational pipeline to the value of
.meta place
and stores the result back into
.metn place .

.PP

.SS* Namespaces and Environments

\*(TL is a Lisp-2 dialect: it features separate namespaces for
functions and variables.

.NP* Global Functions and Operator Macros

In \*(TL, global functions and operator macros co-exist, meaning that the same
symbol can be defined as both a macro and a function.

There is a global namespace for functions,
into which functions can be introduced with the
.code defun
macro.  The global function environment can be inspected and modified using the
.code symbol-function
accessor.

There is a global namespace for macros, into which
macros are introduced with the
.code defmacro
macro. The global function environment can be inspected and modified using the
.code symbol-macro
accessor.

If a name
.code x
is defined as both a function and a macro, then an expression of the form
.code "(x ...)"
is expanded by the macro, whereas an expression of the form
.code "[x ...]"
refers to the function. Moreover, the macro can produce a call to the
function.  The expression
.code "(fun x)"
will retrieve the function object.

.NP* Global and Dynamic Variables

There is a global namespace for variables also.
The operators
.code defvar
and
.code defparm
introduce bindings into this namespace. These operators have the
side effect of marking a symbol as a special variable,
of the symbol are treated as dynamic variables, subject to
rebinding.  The global variable namespace together with the special dynamic
rebinding is called the dynamic environment.
The dynamic environment can be inspected and modified using the
.code symbol-value
accessor.

The operators
.code defvarl
and
.code defparml
introduce bindings into the global namespace without marking
symbols as special variables. Such bindings are called global lexical
variables.

.NP* Global Symbol Macros

Symbol macros may be defined over the global variable namespace
using
.codn defsymacro .

Note that whereas a symbol may simultaneously have both a function and macro
binding in the global namespace, a symbol may not simultaneously have
a variable and symbol macro binding.

.NP* Lexical Environments

In addition to global and dynamic namespaces, \*(TL provides lexically scoped
binding for functions, variables, macros, and symbol macros.
Lexical variable binding are introduced with
.codn let ,
.code let*
or various binding macros derived from these. Lexical functions are bound
with
.code flet
and
.codn labels .
Lexical macros are established with
.code macrolet
and lexical symbol macros with
.codn symacrolet .

Macros receive an environment parameter with which they may expand
forms in their correct environment, and perform some limited introspection
over that environment in order to determine the nature of bindings,
or the classification of forms in those environments. This introspection
is provided by
.codn lexical-var-p ,
.codn lexical-fun-p ,
and
.codn lexical-lisp1-binding .

Lexical operator macros and lexical functions can also co-exist in the
following way.  A lexical function shadows a global or lexical macro
completely. However, the reverse is not the case. A lexical macro shadows
only those uses of a function which look like macro calls. This is
succinctly demonstrated by the following form:

.verb
  (flet ((foo () 43))
    (macrolet ((foo () 44))
      (list (fun foo) (foo) [foo])))

  -> (#<interpreted fun: lambda nil> 44 43)
.brev

The
.code "(fun foo)"
and
.code [fun]
expressions are oblivious to the macro; the macro expansion process
process the symbol
.code foo
in those contexts. However the form
.code (foo)
is subject to macro-expansion and replaced with
.codn 44 .

If the
.code flet
and
.code macrolet
are reversed, the behavior is different:

.verb
  (macrolet ((foo () 44))
    (flet ((foo () 43))
      (list (fun foo) (foo) [foo])))

  -> (#<interpreted fun: lambda nil> 43 43)
.brev

All three forms refer to the function, which lexically shadows the macro.

.NP* Pattern Language and Lisp Scope Nesting

\*(TL expressions can be embedded in the \*(TX pattern language in various
ways. Likewise, the pattern language can be invoked from \*(TL. This
brings about the possibility that Lisp code attempts to access
pattern variables bound in the pattern language. The \*(TX pattern language
can also attempt to access \*(TL variables.

The rules are as follows, but they have undergone historic changes.  See the
COMPATIBILITY section, in particular notes under 138 and 121, and also 124.

A Lisp expression evaluated from the \*(TX pattern language executes
in a null lexical environment. The current set of pattern variables captured
up to that point by the pattern language are installed as dynamic variables.
They shadow any Lisp global variables (whether those are defined
by
.code defvar
or
.codn defvarl ).

In the reverse direction, a variable reference from the \*(TX pattern
language searches the pattern variable space first. If a variable doesn't
exist there, then the lookup refers to the \*(TL global variable space.
The pattern language doesn't see Lisp lexical variables.

When Lisp code is evaluated from the pattern language, the pattern variable
bindings are not only installed as dynamic variables for the sake of their
visibility from Lisp, but they are also specially stored in a dynamic
environment frame.  When \*(TX pattern code is re-entered from Lisp, these
bindings are picked up from the closest such environment frame, allowing the
nested invocation of pattern code to continue with the bindings captured by
outer pattern code.

Concisely, in any context in which a symbol has both a binding as a Lisp global
variable as well as a pattern variable, that symbol refers to the pattern
variable. Pattern variables are propagated through Lisp evaluation into
nested invocations of the pattern language.

The pattern language can also reference
Lisp variables using the
.code @
prefix, which is a consequence of that prefix introducing an expression that is
evaluated as Lisp, the name of a variable being such an expression.

.SH* LISP OPERATOR, FUNCTION AND MACRO REFERENCE

.SS* Conventions
The following sections list all of the special operators, macros
and functions in \*(TL.

In these sections, syntax is indicated using these conventions:

.meIP < word
.ie n \{\
A symbol in angle brackets
.\}
.el \{\
A symbol in
.meta fixed-width-italic
font
.\}
denotes some syntactic unit: it
may be a symbol or compound form. The syntactic unit is explained
in the corresponding Description section.

.meIP {syntax}* << word *
This indicates a repetition of zero or more of the given
syntax enclosed in the braces or syntactic unit.
The curly braces may be omitted if the scope of the
.code *
is clear.

.meIP {syntax}+ << word +
This indicates a repetition of one or more of the given
syntax enclosed in the braces or syntactic unit.
The curly braces may be omitted if the scope of the
.code +
is clear.

.coIP {syntax | syntax | ...}
This indicates a choice among alternatives.
May be combined with
.code +
or
.code *
repetition.

.meIP [syntax] <> [ word ]
Square brackets indicate optional syntax.

.coIP '[' ']'
The quoted square brackets indicate literal brackets which appear
in the syntax, which they do without quotes. For instance
.code "'['foo [ bar ]']'"
is a pattern denotes the two possible expressions
.code "[foo]"
and
.codn "[foo bar]" .

.meIP syntax -> < result
The arrow notation is used in examples to indicate that the evaluation
of the given syntax produces a value, whose printed representation is
.metn result .

.SS* Form Evaluation
A compound expression with a symbol as its first element, if
intended to be evaluated, denotes either an operator invocation or a function
call. This depends on whether the symbol names an operator or a function.

When the form is an operator invocation, the interpretation of the meaning of
that form is under the complete control of that operator.

If the compound form is a function call, the remaining forms, if any, denote
argument expressions to the function.  They are evaluated in left to right
order to produce the argument values, which are passed to the function.  An
exception is thrown if there are not enough arguments, or too many.  Programs
can define named functions with the defun operator

Some operators are macros. There exist predefined macros in the library, and
macro operators can also be user-defined using the macro-defining operator
.codn defmacro .
Operators that are not macros are called special operators.

Macro operators work as functions which are given the source code of the form.
They analyze the form, and translate it to another form which is substituted in
their place.   This happens during a code walking phase called the expansion
phase, which is applied to each top-level expression prior to evaluation. All
macros occurring in a form are expanded in the expansion phase, and subsequent
evaluation takes place on a structure which is devoid of macros. All that
remains are the executable forms of special operators, function calls,
symbols denoting either variables or themselves, and atoms such as numeric
and string literals.

Special operators can also perform code transformations during the expansion
phase, but that is not considered macroexpansion, but rather an adjustment
of the representation of the operator into an required executable form.
In effect, it is post-macro compilation phase.

Note that Lisp forms occurring in \*(TX pattern language are not individual
top-level forms. Rather, the entire \*(TX query is parsed at the same time, and
the macros occurring in its Lisp forms are expanded at that time.

.coNP Operator @ quote
.synb
.mets (quote << form )
.syne
.desc
The
.code quote
operator, when evaluated, suppresses the evaluation of
.metn form ,
and instead returns
.meta form
itself as an object. For example, if
.meta form
is a symbol, then
.meta form
is not evaluated to the symbol's value; rather
the symbol itself is returned.

Note: the quote syntax
.mono
.meti >> ' form
.onom
is translated to
.mono
.meti (quote << form ).
.onom

.TP* Example:

.verb
  ;; yields symbol a itself, not value of variable a
  (quote a) -> a

  ;; yields three-element list (+ 2 2), not 4.
  (quote (+ 2 2)) -> (+ 2 2)
.brev

.SS* Variable Binding

Variables are associations between symbols and storage locations
which hold values. These associations are called
.IR bindings .

Bindings are held in a context called an
.IR environment .

.I Lexical
environments hold local variables, and nest according to the syntactic
structure of the program. Lexical bindings are always introduced by a
some form known as a
.IR "binding construct" ,
and the corresponding environment is instantiated during the evaluation
of that construct. There also exist bindings outside of any binding
construct, in the so-called
.I global environment .
Bindings in the global environment can be temporarily shadowed by
lexically-established binding in the
.I dynamic environment .
See the Special Variables section above.

Certain special symbols cannot be used as variable names, namely the
symbols
.code t
and
.codn nil ,
and all of the keyword symbols (symbols in the keyword package), which are
denoted by a leading colon. When any of these symbols is evaluated as
a form, the resulting value is that symbol itself. It is said that these
special symbols are self-evaluating or self-quoting, similarly to all
other atom objects such as numbers or strings.

When a form consisting of a symbol, other than the above special symbols, is
evaluated, it is treated as a variable, and yields the value of
the variable's storage location. If the variable doesn't exist,
an exception is thrown.

Note: symbol forms may also denote invocations of symbol macros. (See the
operators
.code defsymacro
and
.codn symacrolet ).
All macros, including symbol macros, which occur inside
a form are fully expanded prior to the evaluation of a form, therefore
evaluation does not consider the possibility of a symbol being
a symbol macro.

.coNP Operator @ defvar and macro @ defparm
.synb
.mets (defvar < sym <> [ value ])
.mets (defparm < sym << value )
.syne
.desc
The
.code defvar
operator binds a name in the variable namespace of the global environment.
Binding a name means creating a binding: recording, in some namespace of some
environment, an association between a name and some named entity. In the
case of a variable binding, that entity is a storage location for a value.
The value of a variable is that which has most recently been written into the
storage location, and is also said to be a value of the binding, or stored
in the binding.

If the variable named
.meta sym
already exists in the global environment, the
form has no effect; the
.meta value
form is not evaluated, and the value of the
variable is unchanged.

If the variable does not exist, then a new binding is introduced, with a value
given by evaluating the
.meta value
form. If the form is absent, the variable is initialized
to
.codn nil .

The
.meta value
form is evaluated in the environment
in which the
.code defvar
form occurs, not necessarily in the global environment.

The symbols
.code t
and
.code nil
may not be used as variables, and neither
can be keyword symbols: symbols denoted by a leading colon.

In addition to creating a binding, the
.code defvar
operator also marks
.meta sym
as the name of a special variable. This changes what it means to bind
that symbol in a lexical binding construct such as the
.code let
operator, or a function parameter list. See the section "Special Variables" far
above.

The
.code defparm
macro behaves like
.code defvar
when a variable named
.meta sym
doesn't already exist.

If
.meta sym
already denotes a variable binding in the global namespace,
.code defparm
evaluates the
.meta value
form and assigns the resulting value to the variable.

The following equivalence holds:

.verb
  (defparm x y)  <-->  (prog1 (defvar x) (set x y))
.brev

The
.code defvar
and
.code defparm
forms return
.metn sym .

.coNP Macros @ defvarl and @ defparml
.synb
.mets (defvarl < sym <> [ value ])
.mets (defparml < sym << value )
.syne
.desc
The
.code defvarl
and
.code defparml
macros behave, respectively, almost exactly like
.code defvar
and
.codn defparm .

The difference is that these operators do not mark
.meta sym
as special.

If a global variable
.meta sym
does not previously exist, then after the evaluation of
either of these forms
.mono
.meti (boundp << sym )
.onom
is true, but
.mono
.meti (special-var-p << sym )
.onom
isn't.

If
.meta sym
had been already introduced as a special variable, it stays that way
after the evaluation of
.code defvarl
or
.codn defparml .

.coNP Operators @ let and @ let*
.synb
.mets (let >> ({ sym | >> ( sym << init-form )}*) << body-form *)
.mets (let* >> ({ sym | >> ( sym << init-form )}*) << body-form *)
.syne
.desc
The
.code let
and
.code let*
operators introduce a new scope with variables and
evaluate forms in that scope. The operator symbol, either
.code let
or
.codn let* ,
is followed by a list which can contain any mixture of
.meta sym
or
.mono
.meti >> ( sym << init-form )
.onom
pairs.
Each
.meta sym
must be a symbol, and specifies the name of variable to be instantiated and
initialized.

The
.mono
.meti >> ( sym << init-form )
.onom
variant specifies that the new variable
.meta sym
receives an initial value from the
evaluation of
.metn init-form .
The plain
.meta sym
variant specifies a variable which is initialized to
.codn nil .
The
.metn init-form -s
are evaluated in order, by both
.code let
and
.codn let* .

The symbols
.code t
and
.code nil
may not be used as variables, and neither
can be keyword symbols: symbols denoted by a leading colon.

The difference between
.code let
and
.code let*
is that in
.codn let* ,
later
.codn init-form -s
are in scope of the variables established by earlier variables in the same
.code let*
construct. In plain
.codn let ,
the
.metn init-form -s
are evaluated in a scope which does not include any of the variables.

When the variables are established, the
.metn body-form -s
are evaluated in order. The value of the last
.meta body-form
becomes the return value of the
.codn let .
If there are no
.metn body-form -s,
then the return value
.code nil
is produced.

The list of variables may be empty.

The list of variables may contain duplicate
.metn sym -s
if the operator is
.codn let* .
In that situation, a given
.meta init-form
has in scope the rightmost duplicate of any given
.meta sym
that has been previously established.
The
.metn body-form -s
have in scope the rightmost duplicate of any
.meta sym
in the construct.
Therefore, the following form calculates the value 3:

.verb
  (let* ((a 1)
         (a (succ a))
         (a (succ a)))
    a)
.brev

Each duplicate is a separately instantiated binding, and may be independently
captured by a lexical closure placed in a subsequent
.codn init-form :

.verb
  (let* ((a 0)
         (f1 (lambda () (inc a)))
         (a 0)
         (f2 (lambda () (inc a))))
    (list [f1] [f1] [f1] [f2] [f2] [f2]))

  --> (1 2 3 1 2 3)
.brev

The preceding example shows that there are two mutable variables named
.code a
in independent scopes, each respectively captured by the separate closures
.code f1
and
.codn f2 .
Three calls to
.code f1
increment the first
.code a
while the second
.code a
retains its initial value.

Under
.codn let ,
the behavior of duplicate variables is unspecified.

Implementation note: the \*(TX compiler diagnoses and rejects duplicate
symbols in
.code let
whereas the interpreter ignores the situation.

When the names of a special variables is specified in
.code let
or
.code let*
remain, a new binding is created for them in the dynamic environment, rather
than the lexical environment.
In
.codn let* ,
later
.metn init-form -s
are evaluated in a dynamic scope in which previous dynamic variables
are established, and later dynamic variables are not yet established.
A special variable may appear multiple times in a
.codn let* ,
just like a lexical variable. Each duplicate occurrence extends the
dynamic environment with a new dynamic binding.
All these dynamic environments are removed when the
.code let
or
.code let*
form terminates. Dynamic environments aren't captured by lexical
closures, but are captured in delimited continuations.

.TP* Examples:
.verb
  (let ((a 1) (b 2)) (list a b)) -> (1 2)
  (let* ((a 1) (b (+ a 1))) (list a b (+ a b))) -> (1 2 3)
  (let ()) -> nil
  (let (:a nil)) -> error, :a and nil can't be used as variables
.brev

.SS* Functions
.coNP Operator @ defun
.synb
.mets (defun < name <> ( param * [: << opt-param *] [. << rest-param ])
.mets \ \  << body-form )
.syne
.desc
The
.code defun
operator introduces a new function in the global function namespace.
The function is similar to a lambda, and has the same parameter syntax
and semantics as the
.code lambda
operator.

Note that the above syntax synopsis describes only the canonical
parameter syntax which remains after parameter list macros are
expanded. See the section Parameter List Macros.

Unlike in
.codn lambda ,
the
.metn body-form -s
of a
.code defun
are surrounded by a block.
The name of this block is the same as the name of the function, making it
possible to terminate the function and return a value using
.mono
.meti (return-from < name << value ).
.onom
For more information, see the definition of the block operator.

A function may call itself by name, allowing for recursion.

The special symbols
.code t
and
.code nil
may not be used as function names. Neither can keyword symbols.

It is possible to define methods as well as macros with
.codn defun ,
as an alternative to the
.code defmeth
and
.code defmacro
forms.

To define a method, the syntax
.mono
.meti (meth < type << name )
.onom
should be used as the argument to the
.meta name
parameter. This gives rise to the syntax
.mono
.meti (defun (meth < type << name ) < args << form *)
.onom
which is equivalent to the
.mono
.meti (defmeth < type < name < args << form *)
.onom
syntax.

Macros can be defined using
.mono
.meti (macro << name )
.onom
as the
.meta name
parameter of
.codn defun .
This way of defining a macro doesn't support destructuring;
it defines the expander as an ordinary function with an ordinary
argument list. To work, the function must accept two arguments:
the entire macro call form that is to be expanded, and the
macro environment. Thus, the macro definition syntax is
.mono
.meti (defun (macro << name ) < form < env << form *)
.onom
which is equivalent to the
.mono
.meti (defmacro < name (:form < form :env << env ) << form *)
.onom
syntax.

.TP* "Dialect Note:"
In ANSI Common Lisp, keywords may be used as function names.
In TXR Lisp, they may not.

.TP* "Dialect Note:"
A function defined by
.code defun
may co-exist with a macro defined by
.codn defmacro .
This is not permitted in ANSI Common Lisp.

.coNP Operator @ lambda
.synb
.mets (lambda <> ( param * [: << opt-param *] [. << rest-param ])
.mets \ \  << body-form )
.mets (lambda < rest-param
.mets \ \  << body-form )
.syne
.desc
The
.code lambda
operator produces a value which is a function.  Like in most other
Lisps, functions are objects in \*(TL.  They can be passed to functions as
arguments, returned from functions, aggregated into lists, stored in variables,
.IR "et cetera" .

Note that the above syntax synopsis describes only the canonical
parameter syntax which remains after parameter list macros are
expanded. See the section Parameter List Macros.

The first argument of
.code lambda
is the list of parameters for the function.   It
may be empty, and it may also be an improper list (dot notation) where the
terminating atom is a symbol other than
.codn nil .
It can also be a single symbol.

The second and subsequent arguments are the forms making up the function body.
The body may be empty.

When a function is called, the parameters are instantiated as variables that
are visible to the body forms. The variables are initialized from the values of
the argument expressions appearing in the function call.

The dotted notation can be used to write a function that accepts
a variable number of arguments. There are two ways write a function that
accepts only a variable argument list and no required arguments:

.mono
.mets (lambda (. << rest-param ) ...)
.mets (lambda < rest-param ...)
.onom

(These notations are syntactically equivalent because the list notation
.code "(. X)"
actually denotes the object
.code X
which isn't wrapped in any list).

The keyword symbol
.code :
(colon) can appear in the parameter list. This is
the symbol in the keyword package whose name is the empty string.  This
symbol is treated specially: it serves as a separator between
required parameters and optional parameters.  Furthermore, the
.code :
symbol has a role to play in function calls: it can be specified as an argument
value to an optional parameter by which the caller indicates that the
optional argument is not being specified. It will be processed exactly
that way.

An optional parameter can also be written in the form
.mono
.meti >> ( name < expr <> [ sym ]).
.onom
In this situation, if the call does not specify a value for the parameter
(or specifies a value as the keyword
.code :
(colon)) then the parameter takes on the
value of the expression
.metn expr .
This expression is only evaluated when its value is required.

If
.meta sym
is specified, then
.meta sym
will be
introduced as an additional binding with a Boolean value which indicates
whether or not the optional parameter had been specified by the caller.

Each
.code expr
that is evaluated is evaluated an environment in which
all of the previous parameters are visible, in addition to the surrounding
environment of the lambda. For instance:

.verb
  (let ((default 0))
    (lambda (str : (end (length str)) (counter default))
      (list str end counter)))
.brev

In this
.codn lambda ,
the initializing expression for the optional parameter
end is
.codn "(length str)" ,
and the
.code str
variable it refers to is the previous
argument. The initializer for the optional variable counter is
the expression default, and it refers to the binding established
by the surrounding let. This reference is captured as part of the
.codn lambda 's
lexical closure.

Keyword symbols, and the symbols
.code t
and
.code nil
may not be used as parameter names.
The behavior is unspecified if the same symbol is specified
more than once anywhere in the parameter list, whether as a parameter name or as
the indicator
.code sym
in an optional parameter or any combination.

Implementation note: the \*(TX compiler diagnoses and rejects duplicate
symbols in
.code lambda
whereas the interpreter ignores the situation.

.TP* Examples:
.IP "Counting function:"
This function, which takes no arguments, captures the
variable
.codn counter .
Whenever this object is called, it increments
.code counter
by
.code 1
and returns the incremented value.

.verb
  (let ((counter 0))
    (lambda () (inc counter)))
.brev

.IP "Function that takes two or more arguments:"
The third and subsequent arguments are aggregated into a list passed as the
single parameter
.codn z :

.verb
  (lambda (x y . z) (list 'my-arguments-are x y z))
.brev

.IP "Variadic function:"

.verb
  (lambda args (list 'my-list-of-arguments args))
.brev

.IP "Optional arguments:"

.verb
  [(lambda (x : y) (list x y)) 1] -> (1 nil)
  [(lambda (x : y) (list x y)) 1 2] -> (1 2)
.brev

.coNP Macros @ flet and @ labels
.synb
.mets (flet >> ({( name < param-list << function-body-form *)}*)
.mets \ \  << body-form *)

.mets (labels >> ({( name < param-list << function-body-form *)}*)
.mets \ \  << body-form *)
.syne
.desc
The
.code flet
and
.code labels
macros bind local, named functions in the lexical scope.

Note that the above syntax synopsis describes only the canonical
parameter syntax which remains after parameter list macros are
expanded. See the section Parameter List Macros.

The difference between
.code flet
and
.code labels
is that a function defined by
.code labels
can see itself, and therefore recurse directly by name. Moreover, if multiple
functions are defined by the same labels construct, they all have each other's
names in scope of their bodies.
By contrast, a
.codn flet -defined
function does not have itself in scope and cannot recurse.
Multiple functions in the same
.code flet
do not have each other's names in their scopes.

More formally, the
.metn function-body-form -s
and
.meta param-list
of the functions defined by
.code labels
are in a scope in which all of the function
names being defined by that same
.code labels
construct are visible.

Under both
.code labels
and
.codn flet ,
the local functions that are defined are
lexically visible to the main
.metn body-form -s.

Note that
.code labels
and
.code flet
are properly scoped with regard to macros.
During macro expansion, function bindings introduced by these
macro operators shadow macros defined by
.code macrolet
and
.codn defmacro .

Furthermore, function bindings introduced by
.code labels
and
.code flet
also shadow symbol macros defined by
.codn symacrolet ,
when those symbol macros occur as arguments of a
.code dwim
form.

See also: the
.code macrolet
operator.

.TP* "Dialect Note:"

The
.code flet
and
.code labels
macros do not establish named blocks around the body forms
of the local functions which they bind. This differs from
ANSI Common Lisp, whose local function have implicit named blocks,
allowing for
.code return-from
to be used.

.TP* Examples:
.verb
  ;; Wastefully slow algorithm for determining evenness.
  ;; Note:
  ;; - mutual recursion between labels-defined functions
  ;; - inner is-even bound by labels shadows the outer
  ;;   one bound by defun so the (is-even n) call goes
  ;;   to the local function.

  (defun is-even (n)
   (labels ((is-even (n)
              (if (zerop n) t (is-odd (- n 1))))
            (is-odd (n)
              (if (zerop n) nil (is-even (- n 1)))))
     (is-even n)))
.brev

.coNP Function @ call
.synb
.mets (call < function << argument *)
.syne
.desc
The
.code call
function invokes
.metn function ,
passing it the given arguments, if any.

.TP* Examples:
Apply arguments
.code "1 2"
to a
.code lambda
which adds them to produce
.codn 3 :

.verb
  (call (lambda (a b) (+ a b)) 1 2)
.brev

Useless use of
.code call
on a named function; equivalent to
.codn "(list 1 2)" :

.verb
  (call (fun list) 1 2)
.brev

.coNP Functions @ apply and @ iapply
.synb
.mets (apply < function <> [ arg * << trailing-args ])
.mets (iapply < function <> [ arg * << trailing-args ])
.syne
.desc
The
.code apply
function invokes
.metn function ,
optionally passing to it an argument
list. The return value of the
.code apply
call is that of
.metn function .

If no arguments are present after
.metn function ,
then
.meta function
is invoked without arguments.

If one argument is present after
.metn function ,
then it is interpreted as
.metn trailing-args .
If this is a sequence (a list, vector or string),
then the elements of the sequence are passed as individual arguments to
.metn function .
If
.meta trailing-args
is not a sequence, then
.meta function
is invoked
with an improper argument list, terminated by the
.meta trailing-args
atom.

If two or more arguments are present after
.metn function ,
then the last of these arguments is interpreted as
.metn trailing-args .
The previous arguments represent leading arguments which are applied to
.metn function ,
prior to the arguments taken from
.metn trailing-args .

Note that if
.meta trailing-args
value is an atom or an improper list, the function is then
invoked with an improper argument list. Only a variadic
function may be invoked with an improper argument lists.
Moreover, all of the function's required and optional
parameters must be satisfied by elements of the
improper list, such that the terminating atom either
matches the
.meta rest-param
directly (see the
.code lambda
operator) or else the
.meta rest-param
receives an improper list terminated by that atom.
To treat the terminating atom of an improper list as an
ordinary element which can satisfy a required or optional
function parameter, the
.code iapply
function may be used, described next.

The
.code iapply
function ("improper apply") is similar to
.codn apply ,
except with regard to the treatment of
.metn trailing-args .
Firstly, under
.codn iapply ,
if
.meta trailing-args
is an atom other than
.code nil
(possibly a sequence, such as a vector or string),
then it is treated as an ordinary argument:
.meta function
is invoked with a proper argument list, whose last element is
.metn trailing-args .
Secondly, if
.meta trailing-args
is a list, but an improper list, then the terminating atom of
.meta trailing-args
becomes an individual argument.
This terminating atom is not split into multiple arguments,
even if it is a sequence.
Thus, in all possible cases,
.code iapply
treats an extra
.cod2 non- nil
atom as an argument, and never calls
.meta function
with an improper argument list.

.TP* Examples:
.verb
  ;; '(1 2 3) becomes arguments to list, thus (list 1 2 3).
  (apply (fun list) '(1 2 3)) -> (1 2 3)

  ;; this effectively invokes (list 1 2 3 4)
  (apply (fun list) 1 2 '(3 4)) -> (1 2 3 4)

  ;; this effectively invokes (list 1 2 . 3)
  (apply (fun list) 1 2 3)) -> (1 2 . 3)

  ;; "abc" is separated into characters
  ;; which become arguments of list
  (apply (fun list) "abc") -> (#\ea #\eb #\ec)
.brev

.TP* "Dialect Note:"
Note that some uses of this function that are necessary in other Lisp dialects
are not necessary in \*(TL. The reason is that in \*(TL, improper list
syntax is accepted as a compound form, and performs application:

.verb
  (foo a b . x)
.brev

Here, the variables
.code a
and
.code b
supply the first two arguments for
.codn foo .
In
the dotted position,
.code x
must evaluate to a list or vector. The list or
vector's elements are pulled out and treated as additional arguments for
.codn foo .
This syntax can only be used if
.code x
is a symbolic form or an atom.  It
cannot be a compound form, because
.code "(foo a b . (x))"
and
.code "(foo a b x)"
are equivalent structures.

.coNP Operator @ fun
.synb
.mets (fun << function-name )
.syne
.desc
The
.code fun
operator retrieves the function object corresponding to a named
function in the current lexical environment.

The
.meta function-name
may be a symbol denoting a named function: a built in
function, or one defined by
.codn defun .

The
.meta function-name
may also take any of the forms specified in the description of the
.code func-get-name
function. If such a
.meta function-name
refers to a function which exists, then the
.code fun
operator yields that function.

Note: the
.code fun
operator does not see macro bindings via their symbolic names
with which they are defined by
.codn defmacro .
However, the name syntax
.mono
.meti (macro << name )
.onom
may be used to refer to macros. This syntax is documented in the
description of
.codn func-get-name .
It is also possible to
retrieve a global macro expander using the function
.codn symbol-macro .

.coNP Operator @ dwim
.synb
.mets (dwim << argument *)
.mets <> '[' argument *']'
.mets (set (dwim < obj-place < index <> [ alt ]) << new-value )
.mets (set >> '[' obj-place < index <> [ alt ]']' << new-value )
.syne
.desc
The
.code dwim
operator's name is an acronym: DWIM may be taken to mean
"Do What I Mean", or alternatively, "Dispatch, in a Way that is
Intelligent and Meaningful".

The notation
.code [...]
is a shorthand which denotes
.codn "(dwim ...)" .

Note that since the
.code [
and
.code ]
are used in this document for indicating optional syntax,
in the above Syntax synopsis the quoted notation
.code '['
and
.code ']'
denotes bracket tokens which literally appear in the syntax.

The
.code dwim
operator takes a variable number of arguments, which are
treated as expressions to be individually macro-expanded
and evaluated, using the same rules.

This means that the first argument isn't a function name, but an ordinary
expression which can simply compute a function object (or, more generally,
a callable object).

Furthermore, for those arguments of
.code dwim
which are symbols (after all macro-expansion is performed), the evaluation
rules are altered. For the purposes of resolving symbols to values, the
function and variable binding namespaces are considered to be merged into a
single space, creating a situation that is similar to a Lisp-1 style
dialect.

This special Lisp-1 evaluation is not recursively applied.  All arguments of
.code dwim
which, after macro expansion, are not symbols are evaluated using the
normal Lisp-2 evaluation rules. Thus, the DWIM operator must be used
in every expression where the Lisp-1 rules for reducing symbols to
values are desired.

If a symbol has bindings both in the variable and function namespace in scope,
and is referenced by a dwim argument, this constitutes a conflict which is
resolved according to two rules.  When nested scopes are concerned, then an
inner binding shadows an outer binding, regardless of their kind.  An inner
variable binding for a symbol shadows an outer or global function binding, and
.IR "vice versa" .

If a symbol is bound to both a function and variable in the global namespace,
then the variable binding is favored.

Macros do not participate in the special scope conflation, with one
exception. What this means is that the space of symbol macros is not folded
together with the space of operator macros. An argument of
.code dwim
that is a symbol might be
symbol macro, variable or function, but it cannot be interpreted as the name of
a operator macro.

The exception is this: from the perspective of a
.code dwim
form, function bindings can shadow symbol macros. If a
function binding is defined in an inner scope relative to a symbol macro for
the same symbol,
using
.code flet
or
.codn labels ,
the function hides the symbol macro. In other words, when
macro expansion processes an argument of a
.code dwim
form, and that argument is a symbol, it is treated specially
in order to provide a consistent name lookup behavior. If the innermost
binding for that symbol is a function binding, it refers to that
function binding, even if a more outer symbol macro binding exists,
and so the symbol is not expanded using the symbol macro.
By contrast, in an ordinary form, a symbolic argument never resolves
to a function binding. The symbol refers to either a symbol macro or a
variable, whichever is nested closer.

If, after macro expansion, the leftmost argument of the
.code dwim
is the name of a special operator or macro, the
.code dwim
form doesn't denote an invocation of that operator or macro.  A
.code dwim
form is an invocation of the
.code dwim
operator, and the leftmost argument of that operator, if it is a symbol, is
treated as a binding to be resolved in the variable or function namespace,
like any other argument.
Thus
.code "[if x y]"
is an invocation of the
.code if
function, not the
.code if
operator.

How many arguments are required by the
.code dwim
operator depends on the type of
object to which the first argument expression evaluates.  The possibilities
are:
.RS
.meIP >> [ function << argument *]
Call the given function object with the given arguments.

.meIP >> [ symbol << argument *]
If the first expression evaluates to a symbol, that symbol
is resolved in the function namespace, and then
the resulting function, if found, is called with the
given arguments.

.meIP >> [ sequence << index ]
Retrieve an element from
.metn sequence ,
at the specified
.metn index ,
which is a nonnegative integer.

This form is also a syntactic place.
If a value is stored to this place, it replaces the
element.

The place may also be deleted, which has the effect of removing the element
from the sequence, shifting the elements at higher indices, if any, down one
element position, and shortening the sequence by one.
If the place is deleted, and if
.meta sequence
is a list, then the
.meta sequence
form itself must be a place.

.meIP >> [ sequence << from-index..to-below-index ]
Retrieve the specified range of elements.
The range of elements is specified in the
.code from
and
.code to
fields of a range object. The
.code ..
(dotdot) syntactic sugar denotes it construction via the
.code rcons
function.  See the section on Range Indexing below.

This form is also a syntactic place.  Storing a value in this place
has the effect of replacing the subsequence with
a new subsequence. Deleting the place has the
effect of removing the specified subsequence
from
.metn sequence .
If
.meta sequence
is a list, then the
.meta sequence
form must itself be a place.
The
.meta new-value
argument in a range assignment can be a string, vector or list,
regardless of whether the target is a string, vector or list.
If the target is a string, the replacement sequence must be
a string, or a list or vector of characters.

.meIP >> [ sequence << index-list ]
Elements specified
by
.metn index-list ,
which may be a list or vector,
are extracted from
.meta sequence
and returned as a sequence
of the same kind as
.metn sequence .

This form is equivalent to
.mono
.meti (select < sequence << where-index )
.onom
except when the target of an assignment operation.

This form is a syntactic place if
.meta sequence
is one. If a sequence is assigned to this place,
then elements of the sequence are distributed to the
specified locations.

The following equivalences hold between index-list-based indexing
and the
.code select
and
.code replace
functions, except that
.code set
always returns the value assigned, whereas
.code replace
returns its first argument:

.verb
  [seq idx-list] <--> (select seq idx-list)

  (set [seq idx-list] new) <--> (replace seq new idx-list)
.brev

Note that unlike the select function, this does not support
.mono
.meti >> [ hash << index-list ]
.onom
because since hash keys may be lists, that syntax is
indistinguishable from a simple hash lookup where
.meta index-list
is the key.

.meIP >> [ hash < key <> [ alt ]]
Retrieve a value from the hash table corresponding to
.metn key ,
or else return
.meta alt
if there is no such entry. The expression
.meta alt
is always evaluated, whether or not its value is used.

.meIP >> [ regex >> [ start <> [ from-end ]] < string ]
Determine whether regular expression
.meta regex
matches
.metn string ,
and in that case return the
(possibly empty) leftmost matching substring.
Otherwise, return
.codn nil .

If
.meta start
is specified, it gives the starting position where
the search begins, and if
.meta from-end
is given, and has a value other than
.codn nil ,
it specifies a search from right to left. These optional
arguments have the same conventions and semantics as
their equivalents in the
.code search-regst
function.

Note that
.meta string
is always required, and is always the rightmost argument.

.meIP >> [ struct << arg *]
The structure instance
.meta struct
is inquired whether it supports a method named by the symbol
.metn lambda .
If so, that method is invoked on the object. The method
receives
.meta struct
followed by the value of every
.metn arg .
If this form is used as a place, then the object must
support a
.code lambda-set
method.
.meIP >> [ carray << index ]
.meIP >> [ carray << from-index..to-below-index ]
Element and range indexing is possible on object of type
.code carray
which manipulate arrays in a foreign ("C language") representation,
and are closely associated with the Foreign Function Interface (FFI).
Just like in the case of sequences, the semantics of referencing
.code carray
objects with the bracket notation is based on the functions
.codn ref ,
.codn refset ,
.code sub
and
.codn replace .
These, in turn, rely on the specialized functions.
.codn carray-ref ,
.codn carray-refset ,
.code carray-sub
and
.codn carray-replace .
.meIP >> [ buf << index ]
Indexing is supported for objects of type
.codn buf .
This provides a way to access and store the individual bytes
of a buffer.
.RE
.PP

.TP* "Range Indexing:"
Vector and list range indexing is based from zero, meaning
that the first element is numbered zero, the second one
and so on.
zero. Negative values are allowed; the value
.code -1
refers to the last element of the vector or
list, and
.code -2
to the second last and so forth. Thus the range
.code "1 .. -2"
means
"everything except for the first element and the last two".

The symbol
.code t
represents the position one past the end of the vector, string or
list, so
.code "0 .. t"
denotes the entire list or vector, and the range
.code "t .. t"
represents the empty range just beyond the last element.
It is possible to assign to
.codn "t .. t" .
For instance:

.verb
  (defvar list '(1 2 3))
  (set [list t .. t] '(4)) ;; list is now (1 2 3 4)
.brev

The value zero has a "floating" behavior when used as the end of a range.
If the start of the range is a negative value, and the end of the
range is zero, the zero is interpreted as being the position past the
end of the sequence, rather than the first element. For instance the range
.code -1..0
means the same thing as
.codn -1..t .
Zero at the start of a range
always means the first element, so that
.code 0..-1
refers to all the elements except for the last one.

.TP* Notes:
The dwim operator allows for a Lisp-1 flavor of programming in \*(TL,
which is principally a Lisp-2 dialect.

A Lisp-1 dialect is one in which an expression like
.code "(a b)"
treats both a and b
as expressions subject to the same evaluation rules\(emat least, when
.code a
isn't an operator or an operator macro. This means that the symbols
.code a
and
.code b
are resolved to values in the same namespace. The form denotes a function call
if the value of variable
.code a
is a function object.  Thus in a Lisp-1, named functions do not exist as
such: they are just variable bindings.  In a Lisp-1, the form
.code "(car 1)"
means that there
is a variable called
.codn car ,
which holds a function, which is retrieved from that
variable and the argument
.code 1
is applied to it. In the expression
.codn "(car car)" ,
both occurrences of
.code car
refer to the variable, and so this form applies the
.code car
function to itself. It is almost certainly meaningless.
In a Lisp-2
.code "(car 1)"
means that there is a function called
.codn car ,
in the function namespace. In the expression
.code "(car car)"
the two occurrences refer to different bindings:
one is a function and the other a variable.
Thus there can exist a variable
.code car
which holds a cons cell object, rather than the
.code car
function, and the form makes sense.

The Lisp-1 approach is useful for functional programming, because it eliminates
cluttering occurrences of the call and fun operators.  For instance:

.verb
  ;; regular notation

  (call foo (fun second) '((1 a) (2 b)))

  ;; [] notation

  [foo second '((1 a) (2 b))]
.brev

Lisp-1 dialects can also provide useful extensions by giving a meaning
to objects other than functions in the first position of a form,
and the
.code dwim/[...]
syntax does exactly this.

\*(TL is a Lisp-2 because Lisp-2 also has advantages. Lisp-2 programs
which use macros naturally achieve hygiene because lexical variables do
not interfere with the function namespace. If a Lisp-2 program has
a local variable called
.codn list ,
this does not interfere with the hidden use of the function
.code list
in a macro expansion in the same block of code. Lisp-1 dialects have to
provide hygienic macro systems to attack this problem. Furthermore, even when
not using macros, Lisp-1 programmers have to avoid using the names of functions
as lexical variable names, if the enclosing code might use them.

The two namespaces of a Lisp-2 also naturally accommodate symbol macros and
operator macros.  Whereas functions and variables can be represented in a
single namespace readily, because functions are data objects, this is not so
with symbol macros and operator macros, the latter of which are distinguished
syntactically by their position in a form. In a Lisp-1 dialect, given
.codn "(foo bar)" ,
either of the two symbols could be a symbol macro, but only
.code foo
can possibly be an operator macro. Yet, having only a single namespace, a
Lisp-1 doesn't permit
.codn "(foo foo)" ,
where
.code foo
is simultaneously a symbol macro and an operator macro, though the situation is
unambiguous by syntax even in Lisp-1.  In other words, Lisp-1 dialects do not
entirely remove the special syntactic recognition given to the leftmost
position of a compound form, yet at the same time they prohibit
the user from taking full advantage of it by providing only one namespace.

\*(TL provides
the "best of both worlds": the DWIM brackets notation provides a model of
Lisp-1 computation that is purer than Lisp-1 dialects (since the leftmost
argument is not given any special syntactic treatment at all)
while the Lisp-2 foundation provides a traditional Lisp environment with its
"natural hygiene".

.coNP Function @ functionp
.synb
.mets (functionp << obj )
.syne
.desc
The
.code functionp
function returns
.code t
if
.meta obj
is a function, otherwise it returns
.codn nil .

.coNP Function @ copy-fun
.synb
.mets (copy-fun << function )
.syne
.desc
The
.code copy-fun
function produces and returns a duplicate of
.metn function ,
which must be a function.

A duplicate of a function is a distinct function object not
.code eq
to the original function, yet which accepts the same arguments
and behaves exactly the same way as the original.

If a function contains no captured environment, then a copy made of that
function by
.code copy-fun
is indistinguishable from the original function in every regard,
except for being a distinct object that compares unequal to the original
under the
.code eq
function.

If a function contains a captured environment, then a copy of that function
made by
.code copy-fun
has its own copy of that environment. If the copied function changes the
values of captured lexical variables, the original function is not affected by
these changes and
.IR "vice versa" .

The entire lexical environment is copied; the copy and original function do not
share any portion of the environment at any level of nesting.

.SS* Sequencing, Selection and Iteration
.coNP Operators/functions @ progn and @ prog1
.synb
.mets (progn << form *)
.mets (prog1 << form *)
.syne
.desc
The
.code progn
operator evaluates each
.meta form
in in left-to-right order, and returns the value
of the last form. The value of the form
.code (progn)
is
.codn nil .

The
.code prog1
operator evaluates each
.meta form
in left-to-right order, and returns the value
of the first form. The value of the form
.code (prog1)
is
.codn nil .

Various other operators such as
.code let
also arrange for the evaluation
of a body of forms, the value of the last of which is returned.
These operators are said to feature an implicit
.codn progn .

These special operators are also functions. The
.code progn
function accepts zero or more arguments. It returns its last argument, or
.code nil
if called with no arguments. The
.code prog1
function likewise accepts zero or more arguments. It returns its first argument, or
.code nil
if called with no arguments.

.TP* "Dialect Notes:"
In ANSI Common Lisp,
.code prog1
requires at least one argument. Neither
.code prog
nor
.code prog1
exist as functions.

.coNP Macro/function @ prog2
.synb
.mets (prog2 << form *)
.syne
.desc
The
.code prog2
evaluates each
.meta form
in left-to-right order. The value is that of the second form, if present,
otherwise it is
.codn nil .

The form
.code "(prog2 1 2 3)"
yields
.codn 2 .
The value of
.code "(prog2 1 2)"
is also
.codn 2 ;
.code "(prog2 1)"
and
.code "(prog2)"
yield
.codn nil .

The
.code prog2
symbol also has a function binding. The
.code prog2
function accepts any number of arguments. If invoked with at least two arguments,
it returns the second one. Otherwise it returns
.codn nil .

.TP* "Dialect Notes:"
In ANSI Common Lisp,
.code prog2
requires at least two arguments.
It does not exist as a function.

.coNP Operator @ cond
.synb
.mets (cond >> {( test << form *)}*)
.syne
.desc
The
.code cond
operator provides a multi-branching conditional evaluation of
forms. Enclosed in the cond form are groups of forms expressed as lists.
Each group must be a list of at least one form.

The forms are processed from left to right as follows: the first form,
.metn test ,
in each group is evaluated. If it evaluates true, then the remaining
forms in that group, if any, are also evaluated. Processing then terminates and
the result of the last form in the group is taken as the result of cond.
If
.meta test
is the only form in the group, then result of
.meta test
is taken
as the result of
.codn cond .

If the first form of a group yields
.codn nil ,
then processing continues with the
next group, if any. If all form groups yield
.codn nil ,
then the cond form yields
.codn nil .
This holds in the case that the syntax is empty:
.code (cond)
yields
.codn nil .

.coNP Macros @, caseq @ caseql and @ casequal
.synb
.mets (caseq < test-form << normal-clause * <> [ else-clause ])
.mets (caseql < test-form << normal-clause * <> [ else-clause ])
.mets (casequal < test-form << normal-clause * <> [ else-clause ])
.syne
.desc
These three macros arrange for the evaluation of
.metn test-form ,
whose value is then compared against the key or keys in each
.meta normal-clause
in turn.
When the value matches a key, then the remaining forms of
.meta normal-clause
are evaluated, and the value of the last form is returned; subsequent
clauses are not evaluated. When the value doesn't match any of the keys
of a
.meta normal-clause
then the next
.meta normal-clause
is tested.
If all these clauses are exhausted, and there is no
.metn else-clause ,
then the value nil is returned. Otherwise, the forms in the
.meta else-clause
are evaluated, and the value of the last one is returned.
If there are no forms, then
.code nil
is returned.

The syntax of a
.meta normal-clause
takes on these two forms:

.mono
.mets >> ( key << form *)
.onom

where
.meta key
may be an atom which denotes a single key, or else a list
of keys.  There is a restriction that the symbol
.code t
may not be used
as
.metn key .
The form
.code (t)
may be used as a key to match that symbol.

The syntax of an
.meta else-clause
is:

.mono
.mets (t << form *)
.onom

which resembles a form that is often used as the final clause
in the
.code cond
syntax.

The three forms of the case construct differ from what type of
test they apply between the value of
.meta test-form
and the keys.
The
.code caseq
macro generates code which uses the
.code eq
function's
equality. The
.code caseql
macro uses
.codn eql ,
and
.code casequal
uses
.codn equal .

.TP* Example
.verb
  (let ((command-symbol (casequal command-string
                          (("q" "quit") 'quit)
                          (("a" "add") 'add)
                          (("d" "del" "delete") 'delete)
                          (t 'unknown))))
    ...)
.brev

.coNP Macros @, caseq* @ caseql* and @ casequal*
.synb
.mets (caseq* < test-form << normal-clause * <> [ else-clause ])
.mets (caseql* < test-form << normal-clause * <> [ else-clause ])
.mets (casequal* < test-form << normal-clause * <> [ else-clause ])
.syne
.desc
The
.codn caseq* ,
.codn caseql* ,
and
.code casequal*
macros are similar to the macros
.codn caseq ,
.codn caseql ,
and
.codn casequal ,
differing from them in only the following regard. The
.metn normal-clause ,
of these macros has the form
.mono
.meti >> ( evaluated-key << form *)
.onom
where
.code evaluated-key
is either an atom, which is evaluated to produce a key, or else
else a compound form, whose elements are evaluated as forms, producing
multiple keys.  This evaluation takes place at macro-expansion time,
in the global environment.

The
.meta else-clause
works the same way under these macros as under
.code caseq
.IR "et al" .

Note that although in a
.metn normal-clause ,
.meta evaluated-key
must not be the atom
.codn t ,
there is no restriction against it being
an atom which evaluates to
.code t.
In this situation, the value
.code t
has no special meaning.

The
.meta evaluated-key
expressions are evaluated in the order in which they appear in
the construct, at the time the
.codn caseq* ,
.code caseql*
or
.code casequal*
macro is expanded.

Note: these macros allow the use of variables and global symbol
macros as case keys.

.TP* Example:

.verb
  (defvarl red 0)
  (defvarl green 1)
  (defvarl blue 2)

  (let ((color blue))
    (caseql* color
      (red "hot")
      ((green blue) "cool")))
  --> "cool"
.brev

.coNP Operator/function @ if
.synb
.mets (if < cond < t-form <> [ e-form ])
.mets '['if < cond < then <> [ else ]']'
.syne
.desc
There exist both an
.code if
operator and an
.code if
function. A list form with the symbol
.code if
in the fist position is interpreted as an invocation of the
.code if
operator.
The function can be accessed using the DWIM bracket notation and in other
ways.

The
.code if
operator provides a simple two-way-selective evaluation control.
The
.meta cond
form is evaluated. If it yields true then
.meta t-form
is evaluated, and that form's return value becomes the return value of the
.codn if .
If
.meta cond
yields false, then
.meta e-form
is evaluated and its return value is taken to be that of
.codn if .
If
.meta e-form
is omitted, then the behavior is as if
.meta e-form
were specified as
.codn nil .

The
.code if
function provides no evaluation control. All of arguments
are evaluated from left to right. If the
.meta cond
argument is true, then it
returns the
.meta then
argument, otherwise it returns the value of the
.meta else
argument if present, otherwise it returns
.codn nil .

.coNP Operator/function @ and
.synb
.mets (and << form *)
.mets '['and << arg *']'
.syne
.desc
There exist both an
.code and
operator and an
.code and
function. A list form with the
symbol
.code and
in the fist position is interpreted as an invocation of the
operator.  The function can be accessed using the DWIM bracket notation and in
other ways.

The
.code and
operator provides three functionalities in one.  It computes the
logical "and" function over several forms.  It controls evaluation (a.k.a.
"short-circuiting").  It also provides an idiom for the convenient substitution
of a value in place of
.code nil
when some other values are all true.

The
.code and
operator evaluates as follows. First, a return value is
established and initialized to the value
.codn t .
The
.metn form -s,
if any, are
evaluated from left to right.  The return value is overwritten with
the result of each form. Evaluation stops when all forms are exhausted,
or when
.code nil
is stored in the return value.
When evaluation stops, the operator yields the return value.

The
.code and
function provides no evaluation control; it receives all of its
arguments fully evaluated. If it is given no arguments, it returns
.codn t .
If it is given one or more arguments, and any of them are
.codn nil ,
it returns
.codn nil .
Otherwise it returns the value of the last argument.

.TP* Examples:
.verb
  (and) -> t
  (and (> 10 5) (stringp "foo")) -> t
  (and 1 2 3) -> 3  ;; shorthand for (if (and 1 2) 3).
.brev

.coNP Operator/function @ or
.synb
.mets (or << form *)
.mets '['or << arg *']'
.syne
.desc
There exist both an
.code or
operator and an
.code or
function. A list form with the
symbol
.code or
in the fist position is interpreted as an invocation of the
operator.  The function can be accessed using the DWIM bracket notation and in
other ways.

The or operator provides three functionalities in one.  It computes the
logical "or" function over several forms.  It controls evaluation (a.k.a.
"short-circuiting").  The behavior of
.code or
also provides an idiom for the selection of the first non-nil value from a
sequence of forms.

The
.code or
operator evaluates as follows.  First, a return value is
established and initialized to the value
.codn nil .
The
.metn form -s,
if any,
are evaluated from left to right. The return value is overwritten
with the result of each
.metn form .
Evaluation stops when all forms are
exhausted, or when a true value is stored into the return value.
When evaluation stops, the operator yields the return value.

The
.code or
function provides no evaluation control; it receives all of its
arguments fully evaluated. If it is given no arguments, it returns
.codn nil .
If all of its arguments are
.codn nil ,
it also returns
.codn nil .
Otherwise, it
returns the value of the first argument which isn't
.codn nil .

.TP* Examples:
.verb
  (or) -> nil
  (or 1 2) -> 1
  (or nil 2) -> 2
  (or (> 10 20) (stringp "foo")) -> t
.brev

.coNP Macros @ when and @ unless
.synb
.mets (when < expression << form *)
.mets (unless < expression << form *)
.syne
.desc
The when macro operator evaluates
.metn expression .
If
.meta expression
yields
true, and there are additional forms, then each
.meta form
is evaluated.
The value of the last form is becomes the result value of the when form.
If there are no forms, then the result is
.codn nil .

The
.code unless
operator is similar to when, except that it reverses the
logic of the test. The forms, if any, are evaluated if, and only if
.meta expression
is false.

.coNP Macros @ while and @ until
.synb
.mets (while < expression << form *)
.mets (until < expression << form *)
.syne
.desc
The
.code while
macro operator provides a looping construct.  It evaluates
.metn expression .
If
.meta expression
yields
.codn nil ,
then the evaluation of the
.code while
form
terminates, producing the value
.codn nil .
Otherwise, if there are additional forms,
then each
.meta form
is evaluated.  Next, evaluation returns to
.metn expression ,
repeating all of the previous steps.

The
.code until
macro operator is similar to while, except that the until form
terminates when
.meta expression
evaluates true, rather than false.

These operators arrange for the evaluation of all their enclosed forms
in an anonymous block. Any of the
.metn form -s,
or
.metn expression ,
may use
the
.code return
operator to terminate the loop, and optionally to specify
a result value for the form.

The only way these forms can yield a value other than
.code nil
is if the
.code return
operator is used to terminate the implicit anonymous block,
and is given an argument, which becomes the result value.

.coNP Macros @ while* and @ until*
.synb
.mets (while* < expression << form *)
.mets (until* < expression << form *)
.syne
.desc
The
.code while*
and
.code until*
macros are similar, respectively, to the macros
.code while
and
.codn until .

They differ in one respect: they begin by evaluating the
.metn form -s
one time unconditionally, without first evaluating
.metn expression .
After this evaluation, the subsequent behavior is
like that of
.code while
or
.codn until .

Another way to regard the behavior is that that these forms execute
one iteration unconditionally, without evaluating the termination test prior to
the first iteration. Yet another view is that these constructs relocate the
test from the "top of the loop" to the "bottom of the loop".

.coNP Macro @ whilet
.synb
.mets (whilet >> ({ sym | >> ( sym << init-form )}+)
.mets \ \  << body-form *)
.syne
.desc
The
.code whilet
macro provides a construct which combines iteration with variable
binding.

The evaluation of the form takes place as follows. First, fresh bindings are
established for
.metn sym -s
as if by the
.code let*
operator.
It is an error for the list of variable bindings to be empty.

After the establishment of the bindings, the the value of the
.meta sym
is tested. If the value is
.codn nil ,
then
.code whilet
terminates. Otherwise,
.metn body-form -s
are evaluated in the scope of the variable bindings, and then
.code whilet
iterates from the beginning, again establishing fresh bindings for the
.metn sym -s,
and testing the value of the last
.metn sym .

All evaluation takes place in an anonymous block, which can be
terminated with the
.code return
operator. Doing so terminates the loop.
If the
.code whilet
loop is thus terminated by an explicit
.codn return ,
a return value can be specified. Under normal termination, the return value is
.codn nil .

In the syntax, a small convenience is permitted. Instead of the last
.mono
.meti >> ( sym << init-form )
.onom
it is permissible for the syntax
.mono
.meti <> ( init-form )
.onom
to appear, the
.meta sym
being omitted. A machine-generated variable is substituted
in place of the missing
.meta sym
and that variable is then initialized from
.meta init-form
and used as the basis of the test.

.TP* Examples:
.verb
  ;; read lines of text from *stdin* and print them,
  ;; until the end-of-stream condition:

  (whilet ((line (get-line)))
    (put-line line))

  ;; read lines of text from *stdin* and print them,
  ;; until the end-of-stream condition occurs or
  ;; a line is identical to the character string "end".

  (whilet ((line (get-line))
           (more (and line (nequal line "end"))))
    (put-line line))
.brev

.coNP Macros @ iflet and @ whenlet
.synb
.mets (iflet >> {({ sym | >> ( sym << init-form )}+) | << atom-form }
.mets \ \  < then-form <> [ else-form ])
.mets (whenlet >> {({ sym | >> ( sym << init-form )}+) | << atom-form }
.mets \ \  << body-form *)
.syne
.desc
The
.code iflet
and
.code whenlet
macros combine the variable binding of
.code let*
with conditional evaluation of
.code if
and
.codn when ,
respectively.

In either construct's syntax, a non-compound form
.meta atom-form
may appear in place of the variable binding list. In this case,
.meta atom-form
is evaluated as a form, and the construct is equivalent to
its respective ordinary
.code if
or
.code when
counterpart.

If the list of variable bindings is empty, it is interpreted as the atom
.code nil
and treated as an
.codn atom-form .

If one or more bindings are specified rather than
.metn atom-form ,
then the evaluation of these forms takes
place as follows. First, fresh bindings are established for
.metn sym -s
as if by the
.code let*
operator.

Then, the last variable's value is tested. If it is not
.code nil
then the test is true, otherwise false.

In the syntax, a small convenience is permitted. Instead of the last
.mono
.meti >> ( sym << init-form )
.onom
it is permissible for the syntax
.mono
.meti <> ( init-form )
.onom
to appear, the
.meta sym
being omitted. A machine-generated variable is substituted
in place of the missing
.meta sym
and that variable is then initialized from
.meta init-form
and used as the basis of the test. This is intended to be useful
in situations in which
.meta then-form
or
.meta else-form
do not require access to the tested value.

In the case of the
.code iflet
operator, if the test is true, the operator evaluates
.meta then-form
and yields its value. Otherwise the test is false, and if the
optional
.meta else-form
is present, that is evaluated instead and its value is returned.
If this form is missing, then
.code nil
is returned.

In the case of the
.code whenlet
operator, if the test is true, then the
.metn body-form -s,
if any, are evaluated. The value of the last one is
returned, otherwise
.code nil
if the forms are missing.
If the test is false, then evaluation of
.metn body-form -s
is skipped, and
.code nil
is returned.

.TP* Examples:
.verb
  ;; dispose of foo-resource if present
  (whenlet ((foo-res (get-foo-resource obj)))
    (foo-shutdown foo-res)
    (set-foo-resource obj nil))

  ;; Contrast with: above, using when and let
  (let ((foo-res (get-foo-resource obj)))
    (when foo-res
      (foo-shutdown foo-res)
      (set-foo-resource obj nil)))

  ;; print frobosity value if it exceeds 150
  (whenlet ((fv (get-frobosity-value))
            (exceeds-p (> fv 150)))
    (format t "frobosity value ~a exceeds 150\en" fv))

  ;; same as above, taking advantage of the
  ;; last variable being optional:
  (whenlet ((fv (get-frobosity-value))
            ((> fv 150)))
    (format t "frobosity value ~a exceeds 150\en" fv))

  ;; yield 4: 3 interpreted as atom-form
  (whenlet 3 4)

  ;; yield 4: nil interpreted as atom-form
  (iflet () 3 4)
.brev

.coNP Macro @ condlet
.synb
.mets (condlet
.mets \ \  ([({ sym | >> ( sym << init-form )}+) | << atom-form ]
.mets \ \ \  << body-form *)*)
.syne
.desc
The
.code condlet
macro generalizes
.codn iflet .

Each argument is a compound consisting of at least one item: a list of
bindings or
.metn atom-form .
This item is followed by zero or more
.metn body-form -s.

If the are are no
.metn body-form -s
then the situation is treated as if there were a single
.meta body-form
specified as
.codn nil .

The arguments of
.code condlet
are considered in sequence, starting with the
leftmost.

If the argument's left item is an
.meta atom-form
then the form is evaluated. If it yields true, then the
.metn body-form -s
next to it are evaluated in order, and the
.code condlet
form terminates, yielding the value obtained from the last
.metn body-form .
If
.meta atom-form
yields false, then the next argument is considered, if there is one.

If the argument's left item is a list of bindings, then it is processed
with exactly the same logic as under the
.code iflet
macro. If the last binding contains a true value, then the
adjoining
.metn body-form -s
are evaluated in a scope in which all of the bindings are visible, and
.code condlet
terminates, yielding the value of the last
.metn body-form .
Otherwise, the next argument of
.code condlet
is considered (processed in a scope in which the bindings produced
by the current item are no longer visible).

If
.code condlet
runs out of arguments, it terminates and returns
.codn nil .

.TP* Example:
.verb
  (let ((l '(1 2 3)))
    (condlet
       ;; first arg
       (((a (first l)   ;; a binding gets 1
         (b (second l)) ;; b binding gets 2
         (g (> a b))))  ;; last variable g is nil
        'foo)           ;; not evaluated
       ;; second arg
       (((b (second l)  ;; b gets 2
         (c (third l))  ;; c gets 3
         (g (> b c))))  ;; last variable g is true
        'bar)))         ;; condlet terminates
   --> bar              ;; result is bar
.brev

.coNP Macro @ ifa
.synb
.mets (ifa < cond < then <> [ else ])
.syne
.desc
The
.code ifa
macro provides a anaphoric conditional operator resembling the
.code if
operator. Around the evaluation of the
.meta then
and
.meta else
forms, the symbol
.code it
is implicitly bound to a subexpression of
.metn cond ,
a subexpression which is thereby identified as the
.IR it-form .
This
.code it
alias provides a convenient reference to that place or value, similar to the
word "it" in the English language, and similar anaphoric pronouns in other
languages.

If
.code it
is bound to a place form, the binding is established
as if using the
.code placelet
operator: the form is evaluated only once, even if the
.code it
alias is used multiple times in the
.meta then
or
.meta else
expressions.  Otherwise, if the form is not a syntactic place
.code it
is bound as an ordinary lexical variable to
the form's value.

An
.I it-candidate
is an an expression viable for having its value or storage location
bound to the
.code it
symbol. An it-candidate is any expression which is not a constant expression
according to the
.code constantp
function, and not a symbol.

The
.code ifa
macro imposes applies several rules to the
.meta cond
expression:
.RS
.IP 1.
The
.meta cond
expression must be either an atom, a function call form,
or a
.code dwim
form.  Otherwise the
.code ifa
expression is ill-formed, and throws an exception at
macro-expansion time. For the purposes of these rules,
a
.code dwim
form is considered as a function call expression, whose first
argument is the second element of the form. That is to say,
.code "[f x]"
which is equivalent to
.code "(dwim f x)"
is treated similarly to
.code "(f x)"
as a one-argument call.

.IP 2.
If the
.meta cond
expression is a function call with two or more arguments,
at most one of them may be an it-candidate.
If two or more arguments are it-candidates, the situation
is ambiguous. The
.code ifa
expression is ill-formed and throws an exception at macro-expansion
time.
.IP 3.
If
.meta cond
is an atom, or a function call expression with no arguments,
then the
.code it
symbol is not bound. Effectively,
.code ifa
macro behaves like the ordinary
.code if
operator.
.IP 4.
If
.meta cond
is a function call or
.code dwim
expression with exactly one argument, then the
.code it
variable is bound to the argument expression, except when
the function being called is
.codn not ,
.codn null ,
or
.codn false .
This binding occurs regardless of whether the expression is
an it-candidate.
.IP 5.
If
.meta cond
is a function call with exactly one argument to the Boolean negation
function which goes by one of the three names
.codn not ,
.codn null ,
or
.codn false ,
then that situation is handled by a rewrite according to the following pattern:

.mono
.mets (ifa (not << expr ) < then << else ) -> (ifa < expr < else << then )
.onom

which applies likewise for
.code null
or
.code false
substituted for
.codn not .
The Boolean inverse function is removed, and the 
.meta then
and
.meta else
expressions are exchanged.
.IP 6.
If
.meta cond
is a function call with two or more arguments, then it is only
well-formed if at most one of those arguments is an it-candidate.
If there is one such argument, then the
.code it
variable is bound to it.
.IP 7.
Otherwise the variable is bound
to the leftmost argument expression, regardless of whether that
argument expression is an it-candidate.
.RE

.IP
In all other regards, the
.code ifa
macro behaves similarly to
.codn if .

The
.meta cond
expression is evaluated, and, if applicable,
the value of, or storage location denoted by the appropriate argument is
captured and bound to the variable
.code it
whose scope extends over the
.meta then
form, as well as over
.metn else ,
if present.

If
.meta cond
yields a true value, then
.meta then
is evaluated and the resulting value is returned, otherwise
.meta else
is evaluated if present and its value is returned.
A missing
.meta else
is treated as if it were the
.code nil
form.

.TP* Examples:
.verb
  (ifa t 1 0)  ->  1

  ;; Rule 6: it binds to (* x x), which is
  ;; the only it-candidate.
  (let ((x 6) (y 49))
    (ifa (> y (* x x)) ;; it binds to (* x x)
      (list it)))
  -> (36)

  ;; Rule 4: it binds to argument of evenp,
  ;; even though 4 isn't an it-candidate.
  (ifa (evenp 4)
    (list it))
  -> (4)

  ;; Rule 5:
  (ifa (not (oddp 4))
    (list it))
  -> (4)

  ;; Rule 7: no candidates: choose leftmost
  (let ((x 6) (y 49))
    (ifa (< 1 x y)
      (list it)))
  -> (1)

  -> (4)
  ;; Violation of Rule 1:
  ;; while is not a function
  (ifa (while t (print 42))
    (list it))
  --> exception!

  ;; Violation of Rule 2:
  (let ((x 6) (y 49))
    (ifa (> (* y y y) (* x x)))
      (list it))
  --> exception!
.brev

.coNP Macro @ conda
.synb
.mets (conda >> {( test << form *)}*)
.syne
.desc
The
.code conda
operator provides a multi-branching conditional evaluation of
forms, similarly to the
.code cond
operator. Enclosed in the cond form are groups of forms expressed as lists.
Each group must be a list of at least one form.

The
.code conda
operator is anaphoric: it expands into a nested structure of zero or more
.code ifa
invocations, according to these patterns:

.verb
  (conda) -> nil
  (conda (x y ...) ...) -> (ifa x (progn y ...) (conda ...))
.brev

Thus,
.code conda
inherits all the restrictions on the
.meta test
expressions from
.codn ifa ,
as well as the anaphoric
.code it
variable feature.

.coNP Macro @ whena
.synb
.mets (whena < test << form *)
.syne
.desc
The
.code whena
macro is similar to the
.code when
macro, except that it is anaphoric in exactly the same manner as the
.code ifa
macro. It may be understood as conforming to the following equivalence:

.verb
  (whena x f0 f2 ...)  <-->  (if x (progn f0 f2 ...))
.brev

.coNP Macro @ dotimes
.synb
.mets (dotimes >> ( var < count-form <> [ result-form ])
.mets \ \  << body-form *)
.syne
.desc
The
.code dotimes
macro implements a simple counting loop.
.meta var
is established as a variable, and initialized to zero.
.meta count-form
is evaluated one time to produce a limiting value, which should be a number.
Then, if the value of
.meta var
is less than the limiting value, the
.metn body-form -s
are evaluated,
.meta var
is incremented by one, and the process repeats with a new comparison
of
.meta var
against the limiting value possibly leading to another evaluation of
the forms.

If
.meta var
is found to equal or exceed the limiting value, then the loop terminates.

When the loop terminates, its return value is
.code nil
unless a
.meta result-form
is present, in which case the value of that form specifies the return value.

.metn body-form -s
as well as
.meta result-form
are evaluated in the scope in which the binding of
.meta var
is visible.

.coNP Operators @, each @, each* @, collect-each @, collect-each* @ append-each and @ append-each*
.synb
.mets (each >> ({( sym << init-form )}*) << body-form *)
.mets (each* >> ({( sym << init-form )}*) << body-form *)
.mets (collect-each >> ({( sym << init-form )}*) << body-form *)
.mets (collect-each* >> ({( sym << init-form )}*) << body-form *)
.mets (append-each >> ({( sym << init-form )}*) << body-form *)
.mets (append-each* >> ({( sym << init-form )}*) << body-form *)
.syne
.desc
These operators establish a loop for iterating over the elements of one or more
sequences. Each
.meta init-form
must evaluate to an iterable object that is suitable as an argument for the
.code iter-begin
function.
The sequences are then iterated in
parallel over repeated evaluations of the
.metn body-form -s,
with each
.meta sym
variable being assigned to successive elements of its sequence. The shortest
list determines the number of iterations, so if any of the
.metn init-form -s
evaluate to
an empty sequence, the body is not executed.

If the list of
.mono
.meti >> ( sym << init-form )
.onom
pairs itself is empty, then an infinite loop is specified.

The body forms are enclosed in an anonymous block, allowing the
.code return
operator to terminate the loop prematurely and optionally specify
the return value.

The
.code collect-each
and
.code collect-each*
variants are like
.code each
and
.codn each* ,
except that for each iteration, the resulting value of the body is collected
into a list. When the iteration terminates, the return value of the
.code collect-each
or
.code collect-each*
operator is this collection.

The
.code append-each
and
.code append-each*
variants are like
.code each
and
.codn each* ,
except that for each iteration other than the last, the resulting value of the
body must be a list. The last iteration may produce either an atom or a list.
The objects produced by the iterations are combined together as if they
were arguments to the append function, and the resulting value is the
value of the
.code append-each
or
.code append-each*
operator.

The alternate forms denoted by the adorned symbols
.codn each* ,
.code collect-each*
and
.codn append-each* ,
differ from
.codn each ,
.code collect-each
and
.code append-each
in the following way. The plain forms evaluate the
.metn init-form -s
in an environment in which none of the
.code sym
variables are yet visible. By contrast, the alternate
forms evaluate each
.meta init-form
in an environment in which bindings for the
previous
.meta sym
variables are visible.  In this phase of evaluation,
.meta sym
variables are list-valued: one by one they are each bound to the list object
emanating from their corresponding
.metn init-form .
Just before the first loop
iteration, however, the
.meta sym
variables are assigned the first item from each
of their lists.

.TP* Note:
The semantics of
.code collect-each
may be understood in terms of an equivalence to a code pattern involving
.codn mapcar :

.mono
  (collect-each ((x xinit)        (mapcar (lambda (x y)
                 (y yinit))  <-->           body)
    body)                                 xinit yinit)
.onom

The
.code collect-each*
variant may be understood in terms of the following equivalence involving
.code let*
for sequential binding and
.codn mapcar :

.mono
  (collect-each* ((x xinit)        (let* ((x xinit)
                  (y yinit))  <-->        (y yinit))
    body)                            (mapcar (lambda (x y)
                                                body)
                                             x y))
.onom

However, note that the
.code let*
as well as each invocation of the
.code lambda
binds fresh instances of the variables, whereas these operators are permitted
to bind a single instance of the variables, which are first initialized with
the initializing expressions, and then re-used as iteration variables which are
stepped by assignment.

The other operators may be understood likewise, with the substitution
of the
.code mapdo
function in the case of
.code each
and
.code each*
and of the
.code mappend
function in the case of
.code append-each
and
.codn append-each* .

.TP* Example:
.mono
 ;; print numbers from 1 to 10 and whether they are even or odd
 (each* ((n 1..11) ;; n is just a range object in this scope
         (even (collect-each ((m n)) (evenp m))))
   ;; n is an integer in this scope
   (format t "~s is ~s\en" n (if even "even" "odd")))
.onom
.TP* Output:
.mono
 1 is "odd"
 2 is "even"
 3 is "odd"
 4 is "even"
 5 is "odd"
 6 is "even"
 7 is "odd"
 8 is "even"
 9 is "odd"
 10 is "even"
.onom

.coNP Operators @ for and @ for*
.synb
.mets ({for | for*} >> ({ sym | >> ( sym << init-form )}*)
.mets \ \ \ \ \ \ \ \ \ \ \ \ \  >> ([ test-form << result-form *])
.mets \ \ \ \ \ \ \ \ \ \ \ \ \  <> ( inc-form *)
.mets \ \  << body-form *)
.syne
.desc
The
.code for
and
.code for*
operators combine variable binding with loop iteration.
The first argument is a list of variables with optional initializers,
exactly the same as in the
.code let
and
.code let*
operators. Furthermore, the
difference between
.code for
and
.code for*
is like that between
.code let
and
.code let*
with regard to this list of variables.

The
.code for
and
.code for*
operators execute these steps:
.RS
.IP 1.
Establish an anonymous block over the entire form, allowing
the
.code return
operator to be used to terminate the loop.
.IP 2.
Establish bindings for the specified variables similarly to
.code let
and
.codn let* .
The variable bindings are visible over the
.metn test-form ,
each
.metn result-form ,
each
.meta inc-form
and each
.metn body-form .
.IP 3.
Evaluate
.metn test-form .
If
.meta test-form
yields
.codn nil ,
then the loop terminates.  Each
.meta result-form
is evaluated, and the value of the last of these
forms is is the result value of the loop.
If there are no
.metn result-form -s
then the result value is
.codn nil .
If the
.meta test-form
is omitted, then the test
is taken to be true, and the loop does not terminate.
.IP 4.
Otherwise, if
.meta test-form
yields true, then each
.meta body-form
is evaluated in turn. Then, each
.code inc-form
is evaluated in turn and processing resumes at step 2.
.RE

.IP
Furthermore, the
.code for
and
.code for*
operators establish an anonymous block,
allowing the
.code return
operator to be used to terminate at any point.

.coNP Macros @ doloop and @ doloop*
.synb
.mets ({doloop | doloop*}
.mets \ \  ({ sym | >> ( sym >> [ init-form <> [ step-form ])}*)
.mets \ \  >> ([ test-form << result-form *])
.mets \ \  << tagbody-form *)
.syne
.desc
The
.code doloop
and
.code doloop*
macros provide an iteration construct inspired by the ANSI Common Lisp
.code do
and
.code do*
macros.

Each
.meta sym
element in the form must be a symbol suitable for use as a variable name.

The
.metn tagbody-form -s
are placed into an implicit
.codn tagbody ,
meaning that a
.meta tagbody-form
which is an integer, character or symbol is interpreted
as a
.code tagbody
label which may be the target of a control transfer via the
.code go
macro.

The
.code doloop
macro binds each
.meta sym
to the value produced by evaluating the adjacent
.metn init-form .
Then, in the environment in which these variables now exist,
.meta test-form
is evaluated. If that form yields
.codn nil ,
then the loop terminates. The
.metn result-form -s
are evaluated, and the value of the last one is returned.

If
.metn result-form -s
are absent, then
.code nil
is returned.

If
.meta test-form
is also absent, then the loop terminates and returns
.codn nil .

If
.meta test-form
produces a true value, then
.metn result-form -s
are not evaluated. Instead, the implicit
.code tagbody
comprised of the
.metn tagbody-form -s
is evaluated.
If that evaluation terminates normally, the loop variables are
then updated by assigning to each
.meta sym
the value of
.metn step-form .

The following defaulting behaviors apply in regard to the variable
syntax. For each
.meta sym
which has an associated
.meta init-form
but no
.metn step-form ,
the
.meta init-form
is duplicated and taken as the
.metn step-form .
Thus a variable specification like
.code "(x y)"
is equivalent to
.codn "(x y y)" .
If both forms are omitted, then the
.meta init-form
is taken to be
.codn nil ,
and the
.meta step-form
is taken to be
.metn sym .
This means that the variable form
.code "(x)"
is equivalent to
.code "(x nil x)"
which has the effect that
.code x
retains its current value when the next loop iteration begins.
Lastly, the
.meta sym
variant is equivalent to
.mono
.meti <> ( sym )
.onom
so that
.code x
is also equivalent to
.codn "(x nil x)" .

The differences between
.code doloop
and
.code doloop*
are:
.code doloop
binds the variables in parallel, similarly to
.codn let ,
whereas
.code doloop*
binds sequentially, like
.codn let* ;
moreover,
.code doloop
performs the
.meta step-form
assignments in parallel as if using a single
.mono
.meti (pset < sym0 < step-form-0 < sym1 < step-form-1 ...)
.onom
form, whereas
.code doloop*
performs the assignment sequentially as if using
.code set
rather than
.codn pset .

The
.code doloop
and
.code doloop*
macros establish an anonymous
.codn block ,
allowing early return from the loop, with a value, via the
.code return
operator.

.TP* "Dialect Note:"
These macros are substantially different from the ANSI Common Lisp
.code do
and
.code do*
macros. Firstly, the termination logic is inverted; effectively they
implement "while" loops, whereas their ANSI CL counterparts implement
"until" loops. Secondly, in the ANSI CL macros, the defaulting of
the missing
.meta step-form
is different. Variables with no
.meta step-form
are not updated. In particular, this means that the form
.code "(x y)"
is not equivalent to
.codn "(x y y)" ;
the ANSI CL macros do not feature the automatic replication of
.meta init-form
into the
.meta step-form
position.

.coNP Macros @, each-prod @ collect-each-prod and @ append-each-prod
.synb
.mets (each-prod >> ({( sym << init-form )}*) << body-form *)
.mets (collect-each-prod >> ({( sym << init-form )}*) << body-form *)
.mets (append-each-prod >> ({( sym << init-form )}*) << body-form *)
.syne
.desc
The macros
.codn each-prod ,
.code collect-each-prod
and
.code append-each-prod
have a similar syntax to
.codn each ,
.code collect-each
and
.codn collect-each-prod .
However, instead of iterating over sequences in parallel, they iterate over
the Cartesian product of the elements from the sequences.
The difference between
.code collect-each
and
.code collect-each-prod
is analogous to that between the functions
.code mapcar
and
.codn maprod .

These macros can be understood as providing syntactic sugar according to the
pattern established by the following equivalences:

.mono
  (each-prod               (mapdo (lambda (x y)
    ((x xinit)                      body)
     (y yinit))       <-->        xinit
    body)                         yinit)

  (collect-each-prod       (maprod (lambda (x y)
    ((x xinit)                       body)
     (y yinit))       <-->         xinit
    body)                          yinit)

  (append-each-prod        (maprend (lambda (x y)
    ((x xinit)                        body)
     (y yinit))       <-->          xinit
    body)                           yinit)
.onom

However, note that each invocation of the
.code lambda
binds fresh instances of the variables, whereas these operators are
permitted to bind a single instance of the variables, which are then stepped by
assignment.

.TP* Example:

.mono
  (collect-each-prod ((a '(a b c))
                      (n #(1 2)))
    (cons a n))

 --> ((a . 1) (a . 2) (b . 1) (b . 2) (c . 1) (c . 2))
.onom

.coNP Macros @, each-prod* @ collect-each-prod* and @ append-each-prod*
.synb
.mets (each-prod* >> ({( sym << init-form )}*) << body-form *)
.mets (collect-each-prod* >> ({( sym << init-form )}*) << body-form *)
.mets (append-each-prod* >> ({( sym << init-form )}*) << body-form *)
.syne
.desc
The macros
.codn each-prod* ,
.code collect-each-prod*
and
.code append-each-prod*
are variants of
.codn each-prod* ,
.code collect-each-prod*
and
.code append-each-prod*
with sequential binding.

These macros can be understood as providing syntactic sugar according to the
pattern established by the following equivalences:

.mono
  (each-prod*              (let* ((x xinit)
    ((x xinit)                    (y yinit))
     (y yinit))       <-->   (mapdo (lambda (x y) body)
    body)                           x y)

  (collect-each-prod*      (let* ((x xinit)
    ((x xinit)                    (y yinit))
     (y yinit))       <-->   (maprod (lambda (x y) body)
    body)                            x y)

  (append-each-prod*       (let* ((x xinit)
    ((x xinit)                    (y yinit))
     (y yinit))       <-->   (maprend (lambda (x y) body)
    body)                             x y)
.onom

However, note that the
.code let*
as well as each invocation of the
.code lambda
binds fresh instances of the variables, whereas these operators are permitted
to bind a single instance of the variables, which are first initialized with
the initializing expressions, and then re-used as iteration variables which are
stepped by assignment.

.TP* Example:

.mono
  (collect-each-prod* ((a "abc")
                       (b (upcase-str a)))
    `@a@b`)

  --> ("aA" "aB" "aC" "bA" "bB" "bC" "cA" "cB" "cC")
.onom

.coNP Operators @ block and @ block*
.synb
.mets (block < name << body-form *)
.mets (block* < name-form << body-form *)
.syne
.desc
The
.code block
operator introduces a named block around the execution of
some forms. The
.meta name
argument must be a symbol. Since a block name is not
a variable binding, keyword symbols are permitted, and so are the symbols
.code t
and
.codn nil .
A block named by the symbol nil is slightly special: it is
understood to be an anonymous block.

The
.code block*
operator differs from
.code block
in that it evaluates
.metn name-form ,
which is expected to produce a symbol. The resulting symbol
is used for the name of the block.

A named or anonymous block establishes an exit point for the
.code return-from
or
.code return
operator, respectively. These operators can be invoked within a block
to cause its immediate termination with a specified return value.

A block also establishes a prompt for a
.IR "delimited continuation" .
Anywhere in a block, a continuation can be captured using the
.code sys:capture-cont
function. Delimited continuations are described in the section
Delimited Continuations. A delimited continuation allows an apparently
abandoned block to be restarted at the capture point, with the
entire call chain and dynamic environment between the prompt and the capture
point intact.

Blocks in \*(TL have dynamic scope. This means that the following
situation is allowed:

.verb
  (defun func () (return-from foo 42))
  (block foo (func))
.brev

The function can return from the
.code foo
block even though the
.code foo
block
does not lexically surround
.codn foo .

It is because blocks are dynamic that the
.code block*
variant exists; for lexically scoped blocks, it would make little
sense to have support a dynamically computed name.

Thus blocks in \*(TL provide dynamic non-local returns, as well
as returns out of lexical nesting.

It is permitted for blocks to be aggressively
.codn progn -converted
by compilation.  This means that a
.code block
form which meets certain criteria is converted to a
.code progn
form which surrounds the
.metn body-form -s
and thus no longer establishes an exit point.

A
.code block
form will be spared from
.codn progn -conversion
by the compiler if it meets the following rules.
.RS
.IP 1
Any
.meta body-form
references the block's
.meta name
in a
.codn return ,
.codn return-from ,
.code sys:abscond-from
or
.code sys:capture-cont
expression.
.IP 2
The form contains at least one direct call to a function
not in the standard \*(TL library.
.IP 3
The form contains at least one direct call to the functions
.codn sys:capture-cont ,
.codn return* ,
.codn sys:abscond* ,
.codn match-fun ,
.codn eval ,
.codn load ,
.codn compile ,
.code compile-file
or
.codn compile-toplevel .
.IP 4
The form references any of the functions in rules 2 and 3
as a function binding via the
.code dwim
operator (or the DWIM brackets notation) or via the
.code fun
operator.
.IP 5
The form is a
.code block*
form; these are spared from the optimization.
.RE
.IP

Removal of blocks under the above rules means that some use of blocks which
works in interpreted code will not work in compiled programs. Programs which
adhere to the rules are not affected by such a difference.

Additionally, the compiler may
.codn progn -convert
blocks in contravention of the above rules, but only if doing so makes no
difference to visible program behavior.

.TP* Examples:
.verb
  (defun helper ()
    (return-from top 42))

  ;; defun implicitly defines a block named top
  (defun top ()
    (helper) ;; function returns 42
    (prinl 'notreached)) ;; never printed

  (defun top2 ()
    (let ((h (fun helper)))
      (block top (call h))   ;; may progn-convert
      (block top (call 'helper)) ;; may progn-convert
      (block top (helper)))) ;; not removed
.brev
In the above examples, the block containing
.code "(call h)"
may be converted to
.code progn
because it doesn't express a
.B direct
call to the
.code helper
function. The block which calls
.code helper
using
.code "(call 'helper)"
is also not considered to be making a direct call.

.TP* "Dialect Note:"
In Common Lisp, blocks are lexical. A separate mechanism consisting of
catch and throw operators performs non-local transfer based on symbols.
The \*(TL example:

.verb
  (defun func () (return-from foo 42))
  (block foo (func))
.brev

is not allowed in Common Lisp, but can be transliterated to:

.verb
  (defun func () (throw 'foo 42))
  (catch 'foo (func))
.brev

Note that foo is quoted in CL. This underscores the dynamic nature of
the construct.
.code throw
itself is a function and not an operator. Also note that the CL
example, in turn, is even more closely transcribed back into
\*(TL simply by replacing its
.code throw
and
.code catch
with
.code return*
and
.codn block* :

.verb
  (defun func () (return* 'foo 42))
  (block* 'foo (func))
.brev

Common Lisp blocks also do not support delimited continuations.

.coNP Operators @ return and @ return-from
.synb
.mets (return <> [ value ])
.mets (return-from < name <> [ value ])
.syne
.desc
The
.code return
operator must be dynamically enclosed within an anonymous
block (a block named by the symbol
.codn nil ).
It immediately terminates the
evaluation of the innermost anonymous block which encloses it, causing
it to return the specified value. If the value is omitted, the anonymous
block returns
.codn nil .

The
.code return-from
operator must be dynamically enclosed within a named block
whose name matches the
.meta name
argument. It immediately terminates the
evaluation of the innermost such block, causing it to return the specified
value. If the value is omitted, that block returns
.codn nil .

.TP* Example:
.verb
    (block foo
      (let ((a "abc\en")
            (b "def\en"))
        (pprint a *stdout*)
        (return-from foo 42)
        (pprint b *stdout*)))
.brev

Here, the output produced is
.strn "abc" .
The value of
.code b
is not printed
because.
.code return-from
terminates block
.codn foo ,
and so the second pprint form is not evaluated.

.coNP Function @ return*
.synb
.mets (return* < name <> [ value ])
.syne
.desc
The
.code return*
function is similar to the the
.code return-from
operator, except that
.code name
is an ordinary function parameter, and so when
.code return*
is used, an argument expression must be specified which evaluates
to a symbol. Thus
.code return*
allows the target block of a return to be dynamically computed.

The following equivalence holds between the operator and function:

.verb
  (return-from a b)  <-->  (return* 'a b)
.brev

Expressions used as
.meta name
arguments to
.code return*
which do not simply quote a symbol have no equivalent in
.codn return-from .

.coNP Macros @ tagbody and @ go
.synb
.mets (tagbody >> { form | << label }*)
.mets (go << label )
.syne
.desc
The
.code tagbody
macro provides a form of the "go to" control construct. The arguments of a
.code tagbody
form are a mixture of zero or more forms and
.IR "go labels" .
The latter consist of those arguments which are symbols, integers or
characters.  Labels are not considered by
.code tagbody
and
.code go
to be forms, and are not subject to macro expansion or evaluation.

The
.code go
macro is available inside
.codn tagbody .
It is erroneous for a
.code go
form to occur outside of a
.codn tagbody .
This situation is diagnosed by global macro called
.codn go ,
which unconditionally throws an error.

In the absence of invocations of
.code go
or other control transfers, the
.code tagbody
macro evaluates each
.meta form
in left to right order. The go labels are ignored.
After the last
.meta form
is evaluated, the
.code tagbody
form terminates, and yields
.codn nil .

Any
.meta form
itself, or else any of its sub-forms, may be the form
.mono
.meti (go << label )
.onom
where
.meta label
matches one of the go labels of a surrounding
.codn tagbody .
When this
.code go
form is evaluated, then the evaluation of
.meta form
is immediately abandoned, and control transfers to the specified
label. The forms are then evaluated in left-to-right order starting
with the form immediately after that label. If the label is not
followed by any forms, then the
.code tagbody
terminates. If
.meta label
doesn't match to any label in any surrounding
.codn tagbody ,
the
.code go
form is erroneous.

The abandonment of a
.meta form
by invocation of
.code go
is a dynamic transfer. All necessary unwinding inside
.meta form
takes place.

The go labels are lexically scoped, but dynamically bound. Their scope
being lexical means that the labels are not visible to forms which are not
enclosed within the
.codn tagbody ,
even if their evaluation is invoked from that
.codn tagbody .
The dynamic binding means that the labels of a
.code tagbody
form are established when it begins evaluating, and removed when
that form terminates. Once a label is removed, it is not available
to be the target of a
.code go
control transfer, even if that
.code go
form has the label in its lexical scope. Such an attempted transfer
is erroneous.

It is permitted for
.code tagbody
forms to nest arbitrarily. The labels of an inner
.code tagbody
are not visible to an outer
.codn tagbody .
However, the reverse is true: a
.code go
form in an inner
.code tagbody
may branch to a label in an outer
.codn tagbody ,
in which case the entire inner
.code tagbody
terminates.

In cases where the same objects are used as labels
by an inner and outer
.codn tagbody ,
the inner labels shadow the outer labels.

There is no restriction on what kinds of symbols may be labels.
Symbols in the
.code keyword
package as well as the symbols
.code t
and
.code nil
are valid
.code tagbody
labels.

.TP* "Dialect Note:"

ANSI Common Lisp
.code tagbody
supports only symbols and integers as labels (which are called "go tags");
characters are not supported.

.TP* Examples:
.verb
  ;; print the numbers 1 to 10
  (let ((i 0))
    (tagbody
      (go skip) ;; forward goto skips 0
     again
      (prinl i)
     skip
      (when (<= (inc i) 10)
        (go again))))

  ;; Example of erroneous usage: by the time func is invoked
  ;; by (call func) the tagbody has already terminated. The
  ;; lambda body can still "see" the label, but it doesn't
  ;; have a binding.
  (let (func)
    (tagbody
      (set func (lambda () (go label)))
      (go out)
     label
      (prinl 'never-reached)
      out)
    (call func))

  ;; Example of unwinding when the unwind-protect
  ;; form is abandoned by (go out). Output is:
  ;;   reached
  ;;   cleanup
  ;;   out
  (tagbody
     (unwind-protect
       (progn
         (prinl 'reached)
         (go out)
         (prinl 'notreached))
       (prinl 'cleanup))
   out
     (prinl 'out))
.brev

.coNP Macros @ prog and @ prog*
.synb
.mets (prog >> ({ sym | >> ( sym << init-form )}*)
.mets \ \  >> { body-form | << label }*)
.mets (prog* >> ({ sym | >> ( sym << init-form )}*)
.mets \ \  >> { body-form | << label }*)
.syne
.desc
The
.code prog
and
.code progn*
macros combine the features of
.code let
and
.codn let* ,
respectively,
anonymous block and
.codn tagbody .

The
.code prog
macro treats the
.meta sym
and
.code init-form
expressions similarly to
.codn let ,
establishing variable bindings in parallel.
The
.code prog*
macro treats these expressions in a similar way to
.codn let* .

The forms enclosed are treated like the argument forms of the
.code tagbody
macro: labels are permitted, along with use of
.codn go .

Finally, an anonymous block is established around all of the enclosed
forms (both the
.metn init-form -s
and
.metn body-forms -s)
allowing the use of
.code return
to terminate evaluation with a value.

The
.code prog
macro may be understood according to the following equivalence:

.verb
   (prog vars forms ...)  <-->  (block nil
                                  (let vars
                                    (tagbody forms ...)))
.brev

Likewise, the
.code prog*
macro follows an analogous equivalence, with
.code let
replaced by
.codn let* .

.SS* Evaluation

.coNP Function @ eval
.synb
.mets (eval < form <> [ env ])
.syne
.desc
The
.code eval
function treats the
.meta form
object as a Lisp expression, which is expanded and
evaluated. The side effects implied by the form are performed, and the value
which it produces is returned. The optional
.meta env
object specifies an environment for
resolving the function and variable references encountered in the expression.
If this argument is omitted
.code nil
then evaluation takes place in the global environment.

The
.meta form
is not expanded all at once. Rather, it is treated by the following algorithm:
.RS
.IP 1
First, if
.meta form
is a macro, it is macro-expanded as if by an application of the function
.codn macroexpand .
.IP 2
If the resulting expanded form is a
.codn progn ,
.codn compile-only ,
or
.code eval-only
form, then
.code eval
iterates over that form's argument expressions, passing each expression to a
recursive call to
.code eval
using the same
.metn env .
.IP 3
Otherwise, if the expanded form isn't one of the above three kinds of
expressions, it is subject to a full expansion and evaluation.
.RE
.IP
This algorithm allows a sequence of top-level forms to be combined into a
single top-level form, even when the expansion of forms occurring later in the
sequence depends on the evaluation effects of forms earlier in the sequence.

For instance, a form like
.code "(progn (defmacro foo ()) (foo))"
may be processed with
.codn eval ,
because the above algorithm ensures that the
.code "(defmacro foo ())"
expression is fully evaluated first, thereby providing the
macro definition required by
.codn "(foo)" .

This expansion and evaluation order is important because the semantics of
.code eval
forms the reference model for how the
.code load
function processes top-level forms.

See also: the
.code make-env
function.

.coNP Function @ constantp
.synb
.mets (constantp < form <> [ env ])
.syne
.desc
The
.code constantp
function determines whether
.meta form
is a constant form, with respect to environment
.metn env .

If
.meta env
is absent, the global environment is used.
The
.meta env
argument is used for macro-expanding
.metn form .

Currently,
.code constantp
returns true for any form which, after macro-expansion, is any of
the following: a compound form with the symbol
.code quote
in its first position; a non-symbolic atom; or one of the symbols
which evaluate to themselves and cannot be bound as variables.
These symbols are the keyword symbols, and the symbols
.code t
and
.codn nil .

In the future,
.code constantp
will be able to recognize more constant forms, such as calls to certain
functions whose arguments are constant forms.

.coNP Function @ make-env
.synb
.mets (make-env >> [ var-bindings >> [ fun-bindings <> [ next-env ]]])
.syne
.desc
The
.code make-env
function creates an environment object suitable as the
.code env
parameter.

The
.meta var-bindings
and
.meta fun-bindings
parameters, if specified,
should be association lists, mapping symbols to objects.  The objects in
.meta fun-bindings
should be functions, or objects callable as functions.

The
.meta next-env
argument, if specified, should be an environment.

Note: bindings can also be added to an environment using the
.code env-vbind
and
.code env-fbind
functions.

.coNP Functions @ env-vbind and @ env-fbind
.synb
.mets (env-vbind < env < symbol << value )
.mets (env-fbind < env < symbol << value )
.syne
.desc
These functions bind a symbol to a value in either the function or variable
space of environment
.codn env .

Values established in the function space should be functions or objects that
can be used as functions such as lists, strings, arrays or hashes.

If
.meta symbol
already exists in the environment, in the given space, then its
value is updated with
.codn value .

If
.meta env
is specified as
.codn nil ,
then the binding takes place in the global environment.

.coNP Functions @, env-vbindings @ env-fbindings and @ env-next
.synb
.mets (env-vbindings << env )
.mets (env-fbindings << env )
.mets (env-next << env )
.syne
.desc
These function retrieve the components of
.metn env ,
which must be an environment. The
.code env-vbindings
function retrieves the the association list representing variable
bindings. Similarly, the
.code env-fbindings
retrieves the association list of function bindings.
The
.code env-next
function retrieves the next environment, if
.meta env
has one, otherwise
.codn nil .

If
.code e
is an environment constructed by the expression
.codn "(make-env v f n)" ,
then
.code "(env-vbindings e)"
retrieves
.codn v ,
.code "(env-fbindings e)"
retrieves
.code f
and
.code "(env-next e)"
returns
.codn n .

.SS* Global Environment
.coNP Accessors @, symbol-function @ symbol-macro and @ symbol-value
.synb
.mets (symbol-function >> { symbol | < method-name | << lambda-expr })
.mets (symbol-macro << symbol )
.mets (symbol-value << symbol )
.mets (set (symbol-function >> { symbol | << method-name }) << new-value )
.mets (set (symbol-macro << symbol ) << new-value )
.mets (set (symbol-value << symbol ) << new-value )
.syne
.desc
If given a
.meta symbol
argument, the
.code symbol-function
function retrieves the value of the global function binding of the
given
.meta symbol
if it has one: that is, the function object bound to the
.metn symbol .
If
.meta symbol
has no global function binding, then
.code nil
is returned.

The
.code symbol-function
function supports method names of the form
.mono
.meti (meth < struct << slot )
.onom
where
.meta struct
names a struct type, and
.meta slot
is either a static slot or one of the keyword symbols
.code :init
or
.code :postinit
which refer to special functions associated with a structure type.
Names in this format are returned by the
.meta func-get-name
function.  The
.code symbol-function
function also supports names of the form
.mono
.meti (macro << name )
.onom
which denote macros. Thus,
.code symbol-function
provides unified access to functions, methods and macros.

If a
.code lambda
expression is passed to
.codn symbol-function ,
then the expression is macro-expanded and if that is successful, the function
implied by that expression is returned.
It is unspecified whether this function is interpreted or compiled.

The
.code symbol-macro
function retrieves the value of the global macro binding of
.meta symbol
if it has one.

Note: the name of this function has nothing to do with symbol macros;
it is named for consistency with
.code symbol-function
and
.codn symbol-value ,
referring to the "macro-expander binding of the symbol cell".

The value of a macro binding is a function object.
Intrinsic macros are C functions in the \*(TX kernel, which receive
the entire macro call form and macro environment, performing their
own destructuring. Currently, macros written in \*(TL are represented
as curried C functions which carry the following list object in their
environment cell:

.mono
.mets (#<environment object> < macro-parameter-list << body-form *)
.onom

Local macros created by
.code macrolet
have
.code nil
in place of the environment object.

This representation is likely to change or expand to include other
forms in future \*(TX versions.

The
.code symbol-value
function retrieves the value stored in the dynamic binding of
.meta symbol
that is apparent in the current context. If the variable has no dynamic
binding, then
.code symbol-value
retrieves its value in the global environment.
If
.meta symbol
has no variable binding, but is defined as a global symbol macro,
then the value of that symbol macro binding is retrieved.
The value of a symbol macro binding is simply the replacement form.

Rather than throwing an exception, each of these functions returns
.code nil
if the argument symbol doesn't have the binding in the respective
namespace or namespaces which that function searches.

A
.codn symbol-function ,
.codn symbol-macro ,
or
.code symbol-value
form denotes a place, if
.meta symbol
has a binding of the respective kind.  This place may be assigned to or
deleted. Assignment to the place causes the denoted binding to have a new
value. Deleting a place with the
.code del
macro removes the binding,
and returns the previous contents of that binding. A binding
denoted by a
.code symbol-function
form is removed using
.codn fmakunbound ,
one denoted by by
.code symbol-macro
is removed using
.code mmakunbound
and a binding denoted by
.code symbol-value
is removed using
.codn makunbound .

Deleting a method via
.code symbol-function
is not possible; an attempt to do so has no effect.

Storing a value, using any one of these three accessors, to a nonexistent
variable, function or macro binding, is not erroneous. It has has the effect of
creating that binding.

Using
.code symbol-function
accessor to assign to a lambda expression is erroneous.

Deleting a binding, using any of these three accessors, when the binding does not
exist, also isn't erroneous. There is no effect and the
.code del
operator yields
.code nil
as the prior value, consistent with the behavior when accessors are used to
retrieve a nonexistent value.

.TP* "Dialect note:"

In ANSI Common Lisp, the
.code symbol-function
function retrieves a function, macro or special operator binding
of a symbol.
These are all in one space and may not co-exist. In \*(TL, it
retrieves a symbol's function binding only. Common Lisp has an accessor
named
.code macro-function
similar to
.codn symbol-macro .

.coNP Functions @, boundp @ fboundp and @ mboundp
.synb
.mets (boundp << symbol )
.mets (fboundp >> { symbol | < method-name | << lambda-expr })
.mets (mboundp << symbol )
.syne
.desc
.code boundp
returns
.code t
if the
.meta symbol
is bound as a variable or symbol macro in the global
environment, otherwise
.codn nil .

.code fboundp
returns
.code t
if the
.meta symbol
has a function binding in the global
environment, the method specified by
.meta method-name
exists, or a lambda expression argument is given.
Otherwise it returns nil
.codn nil .

.code mboundp
returns
.code t
if the symbol has an operator macro binding in the global environment,
otherwise
.codn nil .

.TP* "Dialect Notes:"

The
.code boundp
function in ANSI Common Lisp doesn't report that
global symbol macros have a binding. They are not considered
bindings. In \*(TL, they are considered bindings.

The ANSI Common Lisp
.code fboundp
yields true if its argument has a function, macro or operator
binding. The behavior of the Common Lisp expression
.code "(fboundp x)"
in Common Lisp can be obtained in \*(TL using the

.verb
  (or (fboundp x) (mboundp x) (special-operator-p x))
.brev

expression.

The
.code mboundp
function doesn't exist in ANSI Common Lisp.

.coNP Function @ makunbound
.synb
.mets (makunbound << symbol )
.syne
.desc
The function
.code makunbound
the binding of
.meta symbol
from either the dynamic environment or the global symbol
macro environment. After the call to
.codn makunbound ,
.meta symbol
appears to be unbound.

If the
.code makunbound
call takes place in a scope in which there exists a dynamic rebinding of
.metn symbol ,
the information for restoring the previous binding is not
affected by
.codn makunbound .
When that scope terminates, the previous binding will be restored.

If the
.code makunbound
call takes place in a scope in which the dynamic binding for
.code symbol
is the global binding, then the global binding is removed.
When the global binding is removed, then
if
.meta symbol
was previously marked as special (for instance
by
.codn defvar )
this marking is removed.

Otherwise if
.meta symbol
has a global symbol macro binding, that binding is removed.

If
.meta symbol
has no apparent dynamic binding, and no global symbol macro binding,
.code makunbound
does nothing.

In all cases,
.code makunbound
returns
.metn symbol .

.TP* "Dialect Note:"

The behavior of
.code makunbound
differs from its counterpart in ANSI Common Lisp.

The
.code makunbound
function in Common Lisp only removes a value from a dynamic variable. The
dynamic variable does not cease to exist, it only ceases to have a value
(because a binding is a value). In \*(TL, the variable ceases to exist. The
binding of a variable isn't its value, it is the variable itself: the
association between a name and an abstract storage location, in some
environment.  If the binding is undone, the variable disappears.

The
.code makunbound
function in Common Lisp does not remove global symbol macros,
which are not considered to be bindings in the variable namespace.
That is to say, the Common Lisp
.code boundp
does not report true for symbol macros.

The Common Lisp
.code makunbound
also doesn't remove the special attribute from a symbol. If a variable
is introduced with
.code defvar
and then removed with
.codn makunbound ,
the symbol continues to exhibit dynamic binding rather than lexical
in subsequent scopes. In \*(TL, if a global binding is removed, so
is the special attribute.

.coNP Functions @ fmakunbound and @ mmakunbound
.synb
.mets (fmakunbound << symbol )
.mets (mmakunbound << symbol )
.syne
.desc
The function
.code fmakunbound
removes any binding for
.meta symbol
from the function namespace of the global environment. If
.meta symbol
has no such binding, it does nothing.
In either case, it returns
.metn symbol .

The function
.code mmakunbound
removes any binding for
.meta symbol
from the operator macro namespace of the global environment.  If
.meta symbol
has no such binding, it does nothing.
In either case, it returns
.metn symbol .

.TP* "Dialect Note:"

The behavior of
.code fmakunbound
differs from its counterpart in ANSI Common Lisp. The
.code fmakunbound
function in Common Lisp removes a function or macro binding, which
do not coexist.

The
.code mmakunbound
function doesn't exist in Common Lisp.

.coNP Function @ func-get-form
.synb
.mets (func-get-form << func )
.syne
.desc
The
.code func-get-form
function retrieves a source code form of
.metn func ,
which must be an interpreted function. The source code form has the syntax
.mono
.meti >> ( name < arglist << body-form *) .
.onom

.coNP Function @ func-get-name
.synb
.mets (func-get-name < func <> [ env ])
.syne
.desc
The
.code func-get-name
tries to resolve the function object
.meta func
to a name. If that is not possible, it returns
.codn nil .

The resolution is performed by an exhaustive search through
up to three spaces.

If an environment is specified by
.metn env ,
then this is searched first. If a binding is found in that
environment which resolves to the function, then the search
terminates and the binding's symbol is returned as the
function's name.

If the search through environment
.meta env
fails, or if that argument is not specified, then the
global environment is searched for a function binding
which resolves to
.metn func .
If such a binding is found, then the search terminates,
and the binding's symbol is returned. If two or more
symbols in the global environment resolve to the function,
it is not specified which one is returned.

If the global function environment search fails,
then the function is considered as a possible macro.
The global macro environment is searched for a macro
binding whose expander function is
.metn func ,
similarly to the way the function environment was
searched. If a binding is found, then the syntax
.mono
.meti (macro << name )
.onom
is returned, where
.meta name
is the name of the global macro binding that was found
which resolves to
.metn func .
If two or more global macro bindings share
.metn func ,
it is not specified which of those bindings provides
.metn name .

If the global macro search fails, then
.meta func
is considered as a possible method.
The static slot space of all struct types is searched for
a slot which contains
.metn func .
If such a slot is found, then the method name is returned,
consisting of the syntax
.mono
.meti (meth < type << name )
.onom
where
.meta type
is a symbol denoting the struct type and
.meta name
is the static slot of the struct type which holds
.metn func .

A check is also performed whether
.meta func
might be equal to one of the two special functions of
a structure type: its
.meta initfun
or
.metn postinitfun ,
in which case it is returned as either the
.mono
.meti (meth < type :init)
.onom
or the
.mono
.meti (meth < type :postinit)
.onom
syntax.

If
.meta func
is an interpreted function not found under any name,
then a lambda expression denoting that function
is returned in the syntax
.mono
.meti (lambda < args << form *)
.onom

If
.meta func
cannot be identified as a function, then
.code nil
is returned.

.coNP Function @ func-get-env
.synb
.mets (func-get-env << func )
.syne
.desc
The
.code func-get-env
function retrieves the environment object associated with
function
.metn func .
The environment object holds the captured bindings of a
lexical closure.

.coNP Functions @ fun-fixparam-count and @ fun-optparam-count
.synb
.mets (fun-fixparam-count << func )
.mets (fun-optparam-count << func )
.syne
.desc
The
.code fun-fixparam-count
reports
.metn func 's
number of fixed parameters. The fixed parameters consist of the required
parameters and the optional parameters.  Variadic functions have a parameter
which captures the remaining arguments which are in excess of the fixed
parameters. That parameter is not considered a fixed parameter and therefore
doesn't contribute to this count.

The
.code fun-optparam-count
reports
.metn func 's
number of optional parameters.

The
.meta func
argument must be a function.

Note: if a function isn't variadic (see the
.meta fun-variadic
function) then the value reported by
.code fun-fixparam-count
represents the maximum number of arguments which can be passed to the function.
The minimum number of required arguments can be calculated for any function by
subtracting the value from
.code fun-optparam-count
from the value from
.codn fun-fixparam-count .

.coNP Function @ fun-variadic
.synb
.mets (fun-variadic << func )
.syne
.desc
The
.code fun-variadic
function returns
.code t
if
.meta func
is a variadic function, otherwise
.codn nil .

The
.meta func
argument must be a function.

.coNP Function @ interp-fun-p
.synb
.mets (interp-fun-p << obj )
.syne
.desc
The
.code interp-fun-p
function returns
.code t
if
.meta obj
is an interpreted function, otherwise it returns
.codn nil .

.coNP Function @ vm-fun-p
.synb
.mets (vm-fun-p << obj )
.syne
.desc
The
.code vm-fun-p
function returns
.code t
if
.meta obj
a function compiled for the virtual machine: a function representation produced
by means of the functions
.codn compile-file ,
.code compile-toplevel
or
.codn compile .
If
.meta obj
is of any other type, the function returns
.codn nil .

.coNP Function @ special-var-p
.synb
.mets (special-var-p << obj )
.syne
.desc
The
.code special-var-p
function returns
.code t
if
.meta obj
is a symbol marked for special variable binding, otherwise it returns
.codn nil .
Symbols are marked special by
.code defvar
and
.codn defparm .

.coNP Function @ special-operator-p
.synb
.mets (special-operator-p << obj )
.syne
.desc
The
.code special-operator-p
function returns
.code t
if
.meta obj
is a symbol which names a special operator, otherwise it returns
.codn nil .

.SS* Object Type

In \*(TL, objects obey the following type hierarchy. In this type hierarchy,
the internal nodes denote abstract types: no object is an instance of
an abstract type. Nodes in square brackets indicate an internal structure
in the type graph, invisible to programs, and angle
brackets indicate a plurality of types which are not listed by name:

.verb
  t ----+--- [cobj types] ---+--- hash
        |                    |
        |                    +--- hash-iter
        |                    |
        |                    +--- stream
        |                    |
        |                    +--- random-state
        |                    |
        |                    +--- regex
        |                    |
        |                    +--- buf
        |                    |
        |                    +--- tree
        |                    |
        |                    +--- tree-iter
        |                    |
        |                    +--- cptr
        |                    |
        |                    +--- dir
        |                    |
        |                    +--- struct-type
        |                    |
        |                    +--- <all structures>
        |                    |
        |                    +--- ... others
        |
        |
        +--- sequence ---+--- string ---+--- str
        |                |              |
        |                |              +--- lstr
        |                |              |
        |                |              +--- lit
        |                |
        |                +--- list ---+--- null
        |                |            |
        |                |            +--- cons
        |                |            |
        |                |            +--- lcons
        |                |
        |                +--- vec
        |                |
        |                +--- <structures with car or length methods>
        |
        +--- number ---+--- float
        |              |
        |              +--- integer ---+--- fixnum
        |                              |
        |                              +--- bignum
        |
        +--- sym
        |
        +--- env
        |
        +--- range
        |
        +--- tnode
        |
        +--- pkg
        |
        +--- fun
.brev

In addition to the above hierarchy, the following relationships also exist:

.verb
  t ---+--- atom --- <any type other than cons> --- nil
       |
       +--- cons ---+--- lcons --- nil
                    |
                    +--- nil

  sym --- null

  struct ---- <all structures>
.brev

That is to say, the types are exhaustively partitioned into atoms and conses;
an object is either a
.code cons
or else it isn't, in which case it is the abstract
type
.codn atom .

The
.code cons
type is odd in that it is both an abstract type,
serving as a supertype for the type
.code lcons
and it is also a concrete type in that regular conses are of
this type.

The type
.code nil
is an abstract type which is empty. That is to say, no object is of
type
.codn nil .
This type is considered the abstract subtype of every other type,
including itself.

The type
.code nil
is not to be confused with the type
.code null
which is the type of the
.code nil
symbol.

Because the type of
.code nil
is the type
.code null
and
.code nil
is also a symbol, the
.code null
type is a subtype of
.codn sym .

Lastly, the symbol
.code struct
serves as the supertype of all structures.

.coNP Function @ typeof
.synb
.mets (typeof << value )
.syne
.desc
The
.code typeof
function returns a symbol representing the type of
.metn value .

The core types are identified by the following symbols:

.coIP cons
Cons cell.

.coIP str
String.

.coIP lit
Literal string embedded in the \*(TX executable image.

.coIP chr
Character.

.coIP fixnum
Fixnum integer: an integer that fits into the value word, not having to
be heap-allocated.

.coIP bignum
A bignum integer: arbitrary precision integer that is heap-allocated.

.coIP float
Floating-point number.

.coIP sym
Symbol.

.coIP pkg
Symbol package.

.coIP fun
Function.

.coIP vec
Vector.

.coIP lcons
Lazy cons.

.coIP range
Range object.

.coIP lstr
Lazy string.

.coIP env
Function/variable binding environment.

.coIP hash
Hash table.

.coIP stream
I/O stream of any kind.

.coIP regex
Regular expression object.

.coIP struct-type
A structure type: the type of any one of the values which represents
a structure type.

.coIP tnode
Binary search tree node.

.coIP tree
Binary search tree.

.coIP args
Function argument list represented as an object.
.PP

There are more kinds of objects, such as user-defined structures.

.coNP Function @ subtypep
.synb
.mets (subtypep < left-type-symbol << right-type-symbol )
.syne
.desc
The
.code subtypep
function tests whether
.meta left-type-symbol
and
.meta right-type-symbol
name a pair of types, such that the left type is a subtype of the right
type.

If either argument doesn't name a type, the behavior is
unspecified.

Each type is a subtype of itself. Most other type relationships can be inferred
from the type hierarchy diagrams given in the introduction to this section.

In addition, there are inheritance relationships among structures. If
.meta left-type-symbol
and
.meta right-type-symbol
both name structure types, then
.code subtypep
yields true if the types are the same struct type, or if the right
type is a direct or indirect supertype of the left.

The type symbol
.code struct
is a supertype of all structure types.

.coNP Function @ typep
.synb
.mets (typep < object << type-symbol )
.syne
.desc
The
.code typep
function tests whether the type of
.meta object
is a subtype of the type named by
.metn type-symbol .

The following equivalence holds:

.verb
  (typep a b) --> (subtypep (typeof a) b)
.brev

.coNP Macro @ typecase
.synb
.mets (typecase < test-form >> {( type-sym << clause-form *)}*)
.syne
.desc
The
.code typecase
macro evaluates
.meta test-form
and then successively tests its type against each clause.

Each clause consists of a type symbol
.meta type-sym
and zero or more
.metn clause-form -s.

The first clause whose
.meta type-sym
is a supertype of the type of
.metn test-form 's
value is considered to be the matching clause.
That clause's
.metn clause-form -s
are evaluated, and the value of the last form is returned.

If there is no matching clause, or there are no clauses present,
or the matching clause has no
.metn clause-form -s,
then
.code nil
is returned.

Note: since
.code t
is the supertype of every type, a clause whose
.meta type-sym
is the symbol
.code t
always matches.  If such a clause is placed as the last clause of a
.codn typecase ,
it provides a fallback case, whose forms are evaluated if none of the
previous clauses match.

.SS* Object Equivalence

.coNP Functions @, identity @ identity and @ use
.synb
.mets (identity << value )
.mets (identity* << value *)
.mets (use << value )
.syne
.desc
The
.code identity
function returns its argument.

If the
.code identity*
function is given at least one argument, then it returns its
leftmost argument, otherwise it returns nil.

The
.code use
function is a synonym of
.codn identity .

.TP* Notes:
The
.code identity
function is useful as a functional argument, when a transformation
function is required, but no transformation is actually desired.
In this role, the
.code use
synonym leads to readable code. For instance:
.verb
  ;; construct a function which returns its integer argument
  ;; if it is odd, otherwise it returns its successor.
  ;; "If it's odd, use it, otherwise take its successor".

  [iff oddp use succ]

  ;; Applications of the function:

  [[iff oddp use succ] 3] -> 3  ;; use applied to 3

  [[iff oddp use succ] 2] -> 3  ;; succ applied to 2
.brev

.coNP Functions @, null @ not and @ false
.synb
.mets (null << value )
.mets (not << value )
.mets (false << value )
.syne
.desc
The
.codn null ,
.code not
and
.code false
functions are synonyms.  They tests whether
.meta value
is
the object
.codn nil .
They return
.code t
if this is the case,
.code nil
otherwise.

.TP* Examples:
.verb
  (null '()) -> t
  (null nil) -> t
  (null ()) -> t
  (false t) -> nil

  (if (null x) (format t "x is nil!"))

  (let ((list '(b c d)))
    (if (not (memq 'a list))
      (format t "list ~s does not contain the symbol a\en")))
.brev

.coNP Functions @ true and @ have
.synb
.mets (true << value )
.mets (have << value )
.syne
.desc
The
.code true
function is the complement of the
.codn null ,
.code not
and
.code false
functions. The
.code have
function is a synonym for
.codn true .

It return
.code t
if the
.meta value
is any object other than
.codn nil .
If
.meta value
is
.codn nil ,
it returns
.codn nil .

Note: programs should avoid explicitly testing values with true.
For instance
.code "(if x ...)"
should be favored over
.codn "(if (true x) ...)" .
However, the latter is useful with the
.code ifa
macro because
.mono
.meti (ifa (true << expr ) ...)
.onom
binds the
.code it
variable to the value of
.metn expr ,
no matter what kind of form
.meta expr
is, which is not true in the
.mono
.meti (ifa < expr ...)
.onom
form.

.TP* Example:
.verb
   ;; Compute indices where the list '(1 nil 2 nil 3)
   ;; has true values:
   [where '(1 nil 2 nil 3) true] -> (1 3)
.brev

.coNP Functions @, eq @ eql and @ equal
.synb
.mets (eq < left-obj << right-obj )
.mets (eql < left-obj << right-obj )
.mets (equal < left-obj << right-obj )
.syne
.desc
The principal equality test functions
.codn eq ,
.code eql
and
.code equal
test whether two objects are equivalent, using different criteria. They return
.code t
if the objects are equivalent, and
.code nil
otherwise.

The
.code eq
function uses the strictest equivalence test, called implementation
equality.  The eq function returns
.code t
if, and only if,
.meta left-obj
and
.meta right-obj
are actually the same object. The
.code eq
test is is implemented
by comparing the raw bit pattern of the value, whether or not it is
an immediate value or a pointer to a heaped object.
Two character values are
.code eq
if they are the same character, and two fixnum integers
are
.code eq
if they have the same value.  All other object representations are actually
pointers, and are
.code eq
if, and only, if they point to the same object in memory.
So, for instance, two bignum integers might not be
.code eq
even if they have the same numeric
value, two lists might not be
.code eq
even if all their corresponding elements are
.code eq
and two strings might not be eq even if they hold identical text.

The
.code eql
function is slightly less strict than
.codn eq .
The difference between
.code eql
and
.code eq
is that if
.meta left-obj
and
.meta right-obj
are numbers which are of the same kind and have the same numeric value,
.code eql
returns
.metn t ,
even if they are different objects.
Note that an integers and a floating-point number are not
.code eql
even if one has a value which converts to the other: thus,
.code "(eql 0.0 0)"
yields
.codn nil ;
a comparison expression which finds these numbers equal is
.codn "(= 0.0 0)" .
The
.code eql
function also specially treats range objects. Two distinct range objects are
.code eql
if their corresponding
.meta from
and
.meta to
fields are
.codn eql .
For all other object types,
.code eql
behaves like
.codn eq .

The
.code equal
function is less strict still than
.codn eql .
In general, it recurses into some kinds of aggregate objects to perform a
structural equivalence check.  For struct types, it also supports customization
via equality substitution.  See the Equality Substitution section under
Structures.

Firstly, if
.meta left-obj
and
.meta right-obj
are
.code eql
then they are also
.codn equal ,
though the converse isn't necessarily the case.

If two objects are both cons cells, then they are equal if their
.code car
fields are
.code equal
and their
.code cdr
fields are
.codn equal .

If two objects are vectors, they are
.code equal
if they have the same length, and
their corresponding elements are
.codn equal .

If two objects are strings, they are equal if they are textually identical.

If two objects are functions, they are
.code equal
if they have
.code equal
environments,
and if they have
the same code.  Two compiled functions are considered to have
the same code if and only if they are pointers to the same function.
Two interpreted functions are considered to have the same
code if their list
structure is
.codn equal .

Two hashes are
.code equal
if they use the same equality (both are
.codn :equal-based ,
or both are
.code :eql-based
or else both are
.codn :eq-based ),
if their associated user data elements are equal (see the function
.codn hash-userdata ),
if their sets of keys are identical, and if the data items associated with
corresponding keys from each respective hash are
.code equal
objects.

Two ranges are
.code equal
if their corresponding
.meta to
and
.meta from
fields are equal.

For some aggregate objects, there is no special semantics.  Two arguments
which are symbols, packages, or streams are
.code equal
if and only if they are the same object.

Certain object types have a custom
.code equal
function.

.coNP Functions @, neq @ neql and @ nequal
.synb
.mets (neq < left-obj << right-obj )
.mets (neql < left-obj << right-obj )
.mets (nequal < left-obj << right-obj )
.syne
.desc
The functions
.codn neq ,
.code neql
and
.code nequal
are logically negated counterparts of, respectively,
.codn eq ,
.code eql
and
.codn equal .

If
.code eq
returns
.code t
for a given pair of arguments
.meta left-obj
and
.metn right-obj ,
then
.code neq
returns
.codn nil .
.IR "Vice versa" ,
if
.code eq
returns
.codn nil ,
.code neq
returns
.codn t .

The same relationship exits between
.code eql
and
.codn neql ,
and between
.code equal
and
.codn nequal .

.coNP Functions @, meq @ meql and @ mequal
.synb
.mets (meq < left-obj << right-obj *)
.mets (meql < left-obj << right-obj *)
.mets (mequal < left-obj << right-obj *)
.syne
.desc
The functions
.codn meq ,
.code meql
and
.code mequal
("member equal" or "multi-equal")
provide a particular kind of a generalization of the binary
equality functions
.codn eq ,
.code eql
and
.code equal
to multiple arguments.

The
.meta left-obj
value is compared to each
.meta right-obj
value using the corresponding binary equality function.
If a match occurs, then
.code t
is returned, otherwise
.codn nil .

The traversal of the
.meta right-obj
argument values proceeds from left to right, and stops
when a match is found.

.coNP Function @ less
.synb
.mets (less < left-obj << right-obj )
.mets (less < obj << obj *)
.syne
.desc
The
.code less
function, when called with two arguments, determines whether
.meta left-obj
compares less than
.meta right-obj
in a generic way which handles arguments of various types.

The argument syntax of
.code less
is generalized. It can accept one argument, in which case it unconditionally
returns
.code t
regardless of that argument's value. If more than two arguments are
given, then
.code less
generalizes in a way which can be described by the following equivalence
pattern, with the understanding that each argument expression
is evaluated exactly once:

.verb
  (less a b c) <--> (and (less a b) (less b c))
  (less a b c d) <--> (and (less a b) (less b c) (less c d))
.brev

The
.code less
function is used as the default for the
.meta lessfun
argument of the functions
.code sort
and
.codn merge ,
as well as the
.meta testfun
argument of the
.code pos-min
and
.codn find-min .

The
.code less
function is capable of comparing numbers, characters, symbols, strings,
as well as lists and vectors of these. It can also compare buffers.

If both arguments are the same object so that
.mono
.meti (eq < left-obj << right-obj )
.onom
holds true, then the function returns
.code nil
regardless of the type of
.metn left-obj ,
even if the function doesn't handle comparing different instances
of that type. In other words, no object is less than itself, no matter
what it is.

The
.code less
function pairs with the
.code equal
function. If values
.code a
and
.code b
are objects which are of suitable types to the
.code less
function, then exactly one of the following three expressions must be true:
.codn "(equal a b)" ,
.code "(less a b)"
or
.codn "(less b a)" .

The
.code less
relation is: antisymmetric, such that if
.code "(less a b)"
is true, then
then
.code "(less b a)"
is false; irreflexive, such that
.code "(less a a)"
is false; and transitive, such that
.code "(less a b)"
and
.code "(less b c)"
imply
.codn "(less a c)" .

The following are detailed criteria that
.code less
applies to arguments of different types and combinations thereof.

If both arguments are numbers or characters, they are compared as if using the
.code <
function.

If both arguments are strings, they are compared as if using the
.code string-lt
function.

If both arguments are symbols, the following rules apply.
If the symbols have names which are different, then the result is
that of their names being compared by the
.code string-lt
function. If
.code less
is passed symbols which have the same name, and neither of these
symbols has a home package, then the raw bit patterns of their
values are compared as integers: effectively, the object with the
lower machine address is considered lesser than the other.
If only one of the two same-named symbols has no home package, then if
that symbol is the left argument,
.code less
returns
.codn t ,
otherwise
.codn nil .
If both same-named symbols have home packages, then the result of
.code less
is that of
.code string-lt
applied to the names of their respective packages. Thus
.code a:foo
is less than
.codn z:foo .

If both arguments are conses, then they are compared as follows:
.RS
.IP 1.
The
.code less
function is recursively applied to the
.code car
fields of both arguments. If it yields true, then
.meta left-obj
is deemed to be less than
.metn right-obj .
.IP 2.
Otherwise, if the
.code car
fields are unequal under
the
.code equal
function,
.code less
returns
.codn nil .
.IP 3.
If the
.code car
fields are
.code equal
then
.code less
is recursively applied to the
.code cdr
fields of the arguments, and the result of that comparison is returned.
.RE

.IP
This logic performs a lexicographic comparison on ordinary lists such
that for instance
.code "(1 1)"
is less than
.code "(1 1 1)"
but not less than
.code "(1 0)"
or
.codn (1) .

Note that the empty
.code nil
list nil compared to a cons is handled by type-based precedence, described
below.

Two vectors are compared by
.code less
lexicographically, similarly
to strings. Corresponding elements, starting with element 0, of the
vectors are compared until an index position is found where corresponding
elements of the two vectors are not
.metn equal .
If this differing position is beyond the end of one of the two vectors,
then the shorter vector is considered to be lesser. Otherwise, the result
of
.code less
is the outcome of comparing those differing elements themselves
with
.codn less .

Two buffers are also compared by
.code less
lexicographically, as if they were vectors of integer byte values.

Two ranges are compared by
.code less
using lexicographic logic similar to conses and vectors.
The
.code from
fields of the ranges are first compared. If they are not
.codn equal ,
equal then
.code less
is applied to those fields and the result is returned.
If the
.code from
fields are
.codn equal ,
then
.code less
is applied to the
.code to
fields and that result is returned.

If the two arguments are of the above types, but of different types from
each other, then
.code less
resolves the situation based on the following precedence: numbers and
characters are less than ranges, which are less than strings, which are less
than symbols, which are less than conses, which are less than vectors,
which are less than buffers.

Note that since
.code nil
is a symbol, it is ranked lower than a cons. This interpretation ensures
correct behavior when
.code nil
is regarded as an empty list, since the empty list is lexicographically prior to
a nonempty list.

If either argument is a structure for which the
.code equal
method is defined, the method is invoked on that argument, and the
value returned is used in place of that argument for performing
the comparison.  Structures with no
.code equal
method cannot participate in a comparison, resulting in an error.
See the Equality Substitution section under Structures.

Finally, if either of the arguments has a type other than the above
types, the situation is an error.

.coNP Function @ greater
.synb
.mets (greater < left-obj << right-obj )
.mets (greater < obj << obj *)
.syne
.desc
The
.code greater
function is equivalent to
.code less
with the arguments reversed. That is to say, the following
equivalences hold:

.verb
  (greater a <--> (less a) <--> t
  (greater a b) <--> (less b a)
  (greater a b c ...) <--> (less ... c b a)
.brev

The
.code greater
function is used as the default for the
.meta testfun
argument of the
.code pos-max
and
.code find-max
functions.

.coNP Functions @ lequal and @ gequal
.synb
.mets (lequal < obj << obj *)
.mets (gequal < obj << obj *)
.syne
.desc
The functions
.code lequal
and
.code gequal
are similar to
.code less
and
.code greater
respectively, but differ in the following respect:
when called with two arguments which compare true under the
.code equal
function, the
.code lequal
and
.code gequal
functions return
.codn t .

When called with only one argument, both functions return
.code t
and both functions generalize to three or more arguments
in the same way as do
.code less
and
.codn greater .

.coNP Function @ copy
.synb
.mets (copy << object )
.syne
.desc
The
.code copy
function duplicates objects of various supported types: sequences, hashes,
structures and random states.  If
.meta object
is
.codn nil ,
it
returns
.codn nil .
Otherwise,
.code copy
is equivalent to invoking a more specific copying function according to
the type of the argument, as follows:
.RS
.coIP cons
.meti (copy-list << object )
.coIP str
.meti (copy-str << object )
.coIP vec
.meti (copy-vec << object )
.coIP hash
.meti (copy-hash << object )
.IP "struct type"
.meti (copy-struct << object )
.coIP fun
.meti (copy-fun << object )
.coIP buf
.meti (copy-buf << object )
.coIP carray
.meti (copy-carray << object )
.coIP random-state
.meti (make-random-state << object )
.coIP tnode
.meti (copy-tnode << object )
.coIP tree
.meti (copy-search-tree << object )
.RE

.IP
For all other types of
.metn object ,
the invocation is erroneous.

Except in the case when
.meta sequence
is
.codn nil ,
.code copy
returns a value that
is distinct from (not
.code eq
to)
.metn sequence .
This is different from
the behavior of
.mono
.meti >> [ sequence 0..t]
.onom
or
.mono
.meti (sub < sequence 0 t)
.onom
which recognize
that they need not make a copy of
.metn sequence ,
and just return it.

Note however, that the elements of the returned sequence may be
eq to elements of the original sequence. In other words, copy is
a deeper copy than just duplicating the
.code sequence
value itself,
but it is not a deep copy.

.SS* List Manipulation
.coNP Function @ cons
.synb
.mets (cons < car-value << cdr-value )
.syne
.desc
The
.code cons
function allocates, initializes and returns a single cons cell.
A cons cell has two fields called
.code car
and
.codn cdr ,
which are accessed by
functions of the same name, or by the functions
.code first
and
.codn rest ,
which are synonyms for these.

Lists are made up of conses. A (proper) list is either the symbol
.code nil
denoting an empty list, or a cons cell which holds the first item of
the list in its
.codn car ,
and the list of the remaining items in
.codn cdr .
The expression
.code "(cons 1 nil)"
allocates and returns a single cons cell which denotes the one-element
list
.codn (1) .
The
.code cdr
is
.codn nil ,
so there are no additional items.

A cons cell whose
.code cdr
is an atom other than
.code nil
is printed with the dotted
pair notation. For example the cell produced by
.code "(cons 1 2)"
is denoted
.codn "(1 . 2)" .
The notation
.code "(1 . nil)"
is perfectly valid as input, but the cell which it denotes
will print back as
.codn (1) .
The notations are equivalent.

The dotted pair notation can be used regardless of what type
of object is the cons cell's
.codn cdr .
so that for instance
.code "(a . (b c))"
denotes the cons cell whose
.code car
is the symbol a
.code a
and whose
.code cdr
is the list
.codn "(b c)" .
This is exactly the same thing as
.codn "(a b c)" .
In other words
.code "(a b ... l m . (n o ... w . (x y z)))"
is exactly the same as
.codn "(a b ... l m n o ... w x y z)" .

Every list, and more generally cons cell tree structure, can be written
in a "fully dotted" notation, such that there are as many dots as there
are cells. For instance the cons structure of the nested list
.code "(1 (2) (3 4 (5)))"
can be made more explicit using
.codn "(1 . ((2 . nil) . ((3 . (4 . ((5 . nil) . nil))) . nil))))" .
The structure contains eight conses, and so there are eight dots
in the fully dotted notation.

The number of conses in a linear list like
.code "(1 2 3)"
is simply the number of items, so that list in particular is
made of three conses. Additional nestings require additional conses,
so for instance
.code "(1 2 (3))"
requires four conses. A visual way to count the conses from the printed
representation is to count the atoms, then add the count of open parentheses,
and finally subtract one.

A list terminated by an atom other than
.code nil
is called an improper
list, and the dot notation is extended to cover improper lists.
For instance
.code "(1 2 . 3)"
is an improper list of two elements,
terminated by
.codn 3 ,
and can be constructed using
.codn "(cons 1 (cons 2 3))" .
The fully dotted notation for this list is
.codn "(1 . (2 . 3))" .

.coNP Function @ atom
.synb
.mets (atom << value )
.syne
.desc
The
.code atom
function tests whether
.meta value
is an atom. It returns
.code t
if this is the
case,
.code nil
otherwise.  All values which are not cons cells are atoms.

.code "(atom x)"
is equivalent to
.codn "(not (consp x))" .

.TP* Examples:
.verb
  (atom 3) -> t
  (atom (cons 1 2)) -> nil
  (atom "abc") -> t
  (atom '(3)) -> nil
.brev

.coNP Function @ consp
.synb
.mets (consp << value )
.syne
.desc
The
.code consp
function tests whether
.meta value
is a cons.  It returns
.code t
if this is the
case,
.code nil
otherwise.

.code "(consp x)"
is equivalent to
.codn "(not (atom x))" .

Non-empty lists test positive under
.code consp
because a list is represented as a reference to the first cons in a chain of
one or more conses.

Note that a lazy cons is a cons and satisfies the
.code consp
test.  See the function
.code make-lazy-cons
and the macro
.codn lcons .

.TP* Examples:
.verb
  (consp 3) -> nil
  (consp (cons 1 2)) -> t
  (consp "abc") -> nil
  (consp '(3)) -> t
.brev

.coNP Accessors @ car and @ first
.synb
.mets (car << object )
.mets (first << object )
.mets (set (car << object ) << new-value )
.mets (set (first << object ) << new-value )
.syne
.desc
The functions
.code car
and
.code first
are synonyms.

If
.meta object
is a cons cell, these functions retrieve the
.code car
field of that cons cell.
.code "(car (cons 1 2))"
yields
.codn 1 .

For programming convenience,
.meta object
may be of several other kinds in addition to conses.

.code "(car nil)"
is allowed, and returns
.codn nil .

.meta object
may also be a vector or a string. If it is an empty vector or
string, then
.code nil
is returned. Otherwise the first character of the string or
first element of the vector is returned.

.meta object
may be a structure. The
.code car
operation is possible if the object has a
.code car
method. If so,
.code car
invokes that method and returns whatever the method returns.
If the structure has no
.code car
method, but has a
.code lambda
method, then the
.code car
function calls that method with one argument, that being
the integer zero. Whatever the method returns,
.code car
returns. If neither method is defined, an error
exception is thrown.

A
.code car
form denotes a valid place whenever
.meta object
is a valid argument for the
.code rplaca
function. Modifying the place denoted by the form is equivalent to invoking
.code rplaca
with
.meta object
as the left argument, and the replacement value as the right
argument. It takes place in the manner given under the description
.code rplaca
function, and obeys the same restrictions.

A
.code car
form supports deletion. The following equivalence
then applies:

.verb
  (del (car place)) <--> (pop place)
.brev

This implies that deletion requires the argument of the
.code car
form to be a place, rather than the whole form itself.
In this situation, the argument place may have a value
which is
.codn nil ,
because
.code pop
is defined on an empty list.

The abstract concept behind deleting a
.code car
is that physically deleting this field from a cons,
thereby breaking it in half, would result in just the
.code cdr
remaining. Though fragmenting a cons in this manner is impossible,
deletion simulates it by replacing the place which previously held the
cons, with that cons'
.code cdr
field. This semantics happens to coincide with deleting the first element
of a list by a
.code pop
operation.

.coNP Accessors @ cdr and @ rest
.synb
.mets (cdr << object )
.mets (rest << object )
.mets (set (cdr << object ) << new-value )
.mets (set (rest << object ) << new-value )
.syne
.desc
The functions
.code cdr
and
.code rest
are synonyms.

If
.meta object
is a cons cell, these functions retrieve the
.code cdr
field of that cons cell.
.code "(cdr (cons 1 2))"
yields
.codn 2 .

For programming convenience,
.meta object
may be of several other kinds in addition to conses.

.code "(cdr nil)"
is allowed, and returns
.codn nil .

.meta object
may also be a vector or a string. If it is a non-empty string or vector
containing at least two items, then the remaining part of the object is
returned, with the first element removed. For example
.mono
(cdr "abc")
.onom
yields
.strn "bc" .
If
.meta object
is is a one-element vector or string, or an empty vector or string,
then
.code nil
is returned. Thus
.mono
(cdr "a")
.onom
and
.mono
(cdr "")
.onom
both result in
.codn nil .

If
.meta object
is a structure, then
.code cdr
requires it to support either the
.code cdr
method or the
.code lambda
method. If both are present,
.code cdr
is used. When the
.code cdr
function uses the
.code cdr
method, it invokes it with no arguments.
Whatever value the method returns becomes the
return value of
.codn cdr .
When
.code cdr
invokes a structure's
.code lambda
method, it passes as the argument the range object
.codn "#R(1 t)" .
Whatever the
.code lambda
method returns becomes the return value of
.codn cdr .

The invocation syntax of a
.code cdr
or
.code rest
form is a syntactic place.
The place is semantically correct if
.meta object
is a valid argument for the
.code rplacd
function. Modifying the place denoted by the form is equivalent to invoking
.code rplacd
with
.meta object
as the left argument, and the replacement value as the right
argument. It takes place in the manner given under the description
.code rplacd
function, and obeys the same restrictions.

A
.code cdr
place supports deletion, according to the following near equivalence:

.verb
  (del (cdr place)) <--> (prog1 (cdr place)
                                (set place (car place)))
.brev

The
.code place
expression is evaluated only once.

Note that this is symmetric with the delete semantics of
.code car
in that the cons stored in
.code place
goes away, as does the
.code cdr
field, leaving just the
.codn car ,
which takes the place of the original cons.

.TP*
Example:

Walk every element of the list
.code "(1 2 3)"
using a
.code for
loop:

.verb
    (for ((i '(1 2 3))) (i) ((set i (cdr i)))
      (print (car i) *stdout*)
      (print #\enewline *stdout*))
.brev

The variable
.code i
marches over the cons cells which make up the "backbone"
of the list. The elements are retrieved using the
.code car
function.
Advancing to the next cell is achieved using
.codn "(cdr i)" .
If
.code i
is the
last cell in a (proper) list,
.code "(cdr i)"
yields
.code nil
and so
.code i
becomes
.codn nil ,
the loop guard expression
.code i
fails and the loop terminates.

.coNP Functions @ rplaca and @ rplacd
.synb
.mets (rplaca < object << new-car-value )
.mets (rplacd < object << new-cdr-value )
.syne
.desc
If
.code object
is a cons cell or lazy cons cell, then
.code rplaca
and
.code rplacd
functions assign new values into the
.code car
and
.code cdr
fields of the
.metn object .
In addition, these functions are meaningful for other kinds of objects also.

Note that, except for the difference in return value,
.code "(rplaca x y)"
is the same as the more generic
.codn "(set (car x) y)" ,
and likewise
.code "(rplacd x y)"
can be written as
.codn "(set (cdr x) y)" .

The
.code rplaca
and
.code rplacd
functions return
.metn cons .
Note: \*(TX versions 89 and earlier, these functions returned the new value.
The behavior was undocumented.

The
.meta cons
argument does not have to be a cons cell. Both functions support meaningful
semantics for vectors and strings.  If
.meta cons
is a string, it must be modifiable.

The
.code rplaca
function replaces the first element of a vector or first character
of a string. The vector or string must be at least one element long.

The
.code rplacd
function replaces the suffix of a vector or string after the first element
with a new suffix. The
.meta new-cdr-value
must be a sequence, and if the suffix of a string is being replaced,
it must be a sequence of characters. The suffix here refers to the portion of
the vector or string after the first element.

It is permissible to use
.code rplacd
on an empty string or vector. In this case,
.meta new-cdr-value
specifies the contents of the entire string or vector, as if the operation
were done on a non-empty vector or string, followed by the deletion of the
first element.

The
.meta object
argument may be a structure. In the case of
.codn rplaca ,
the structure must have a defined
.code rplaca
method or else, failing that, a
.code lambda-set
method. The first of these methods which is available, in the given order, is
used to perform the operation.  Whatever the respective method returns,
If the
.code lambda-set
method is used, it is called with two arguments (in addition to
.codn object ):
the integer zero, and
.metn new-car-value .

In the case of
.codn rplacd ,
the structure must have a defined
.code rplacd
method or else, failing that, a
.code lambda-set
method. The first of these methods which is available, in the given order, is
used to perform the operation.  Whatever the respective method returns,
If the
.code lambda-set
method is used, it is called with two arguments (in addition to
.codn object ):
the range value
.code "#R(1 t)"
and
.metn new-car-value .

.coNP Accessors @, second @, third @, fourth @, fifth @, sixth @, seventh @, eighth @ ninth and @ tenth
.synb
.mets (first << object )
.mets (second << object )
.mets (third << object )
.mets (fourth << object )
.mets (fifth << object )
.mets (sixth << object )
.mets (seventh << object )
.mets (eighth << object )
.mets (ninth << object )
.mets (tenth << object )
.mets (set (first << object ) << new-value )
.mets (set (second << object ) << new-value )
.mets ...
.mets (set (tenth << object ) << new-value )
.syne
.desc
Used as functions, these accessors retrieve the elements of a sequence by
position.  If the sequence is shorter than implied by the position, these
functions return
.codn nil .

When used as syntactic places, these accessors denote the storage locations
by position. The location must exist, otherwise an error exception results.
The places support deletion.


.TP* Examples:
.verb
  (third '(1 2)) -> nil
  (second "ab") -> #\eb
  (third '(1 2 . 3)) -> **error, improper list*

  (let ((x (copy "abcd")))
    (inc (third x))
    x) -> "abce"
.brev

.coNP Functions @ append and @ nconc
.synb
.mets (append <> [ sequence *])
.mets (nconc <> [ sequence *])
.syne
.desc
The
.code append
function creates a new object which is a catenation of the
.meta list
arguments. All arguments are optional;
.code (append)
produces the empty list, and if
a single argument is specified, that argument
is returned.

If two or more arguments are present, then the situation
is identified as one or more
.meta sequence
arguments followed by
.metn last-arg .
The
.meta sequence
arguments must be sequences;
.meta last-arg
may be a sequence or atom.

The
.code append
operation over three or more arguments is left-associative, such that
.code "(append x y z)"
is equivalent to both
.code "(append (append x y) z)"
and
.codn "(append x (append z y))" .

This allows the catenation of an arbitrary number of arguments
to be understood in terms of a repeated application of the two-argument
case, whose semantics is given by these rules:
.RS
.IP 1.
.code nil
catenates with
.code nil
to produce
.codn nil :
.verb
  (append nil nil) -> nil
.brev
.IP 2.
.code nil
catenates with a proper or improper list, producing that list itself:
.verb
  (append nil '(1 2)) -> (1 2)
  (append nil '(1 2 . 3)) -> (1 2 . 3)
.brev
.IP 3.
A proper list catenates with
.codn nil ,
producing that list itself:
.verb
  (append '(1 2) nil) -> (1 2)
.brev
.IP 4.
A proper list catenates with an atom,
producing an improper list terminated by that atom,
whether or not that atom is a sequence:
.verb
  (append '(1 2) #(3)) -> (1 2 . #(3))
  (append '(1 2) 3) -> (1 2 . 3)
.brev
.IP 5.
A non-list sequence catenates with another sequence into a sequence,
producing a sequence which contains the elements of both,
of the same kind as the left sequence. The elements must be
compatible; a string can only catenate with a sequence of characters.
.verb
  (append #(1 2) #(3 4)) -> #(1 2 3 4)
  (append "ab" "cd") -> "abcd"
  (append "ab" #(#\ec #\ed)) -> "abcd"
  (append "ab" #(3 4)) -> ;; error
.brev
.IP 6.
A non-list sequence catenates with an atom if it is a suitable element
type for that kind of sequence. The resulting sequence is of the same
kind, and includes that atom:
.verb
  (append #(1 2) 3) -> #(1 2 3)
  (append "ab" #\c) -> "abc"
  (append "ab" 3) -> ;; error
.brev
.IP 7.
If an improper list is catenated with any object, the catenation
takes place between the terminating atom of that list and that object. This
requires the terminating atom to be a sequence.  If the catenation is possible,
then the result is a new improper list which is a copy of the original, but
with the terminating atom replaced by a catenation of that atom and the object:
.verb
  (append '(1 2 . "ab") "c") -> (1 2 . "abc")
  (append '(1 2 . "ab") '(2 3)) -> ;; error
.brev
.IP 8.
A non-sequence atom doesn't catenate; the situation is erroneous:
.verb
  (append 1 2) -> ;; error
  (append '(1 . 2) 3) -> ;; error
.brev
.RE

.IP
If N arguments are specified, where N > 1, then the first N-1 arguments must be
proper lists. Copies of these lists are catenated together. The last argument
N, shown in the above syntax as
.metn last-arg ,
may be any kind of object. It is
installed into the
.code cdr
field of the last cons cell of the resulting list.
Thus, if argument N is also a list, it is catenated onto the resulting list,
but without being copied. Argument N may be an atom other than
.codn nil ;
in that case
.code append
produces an improper list.

The
.code nconc
function works like
.codn append ,
but may destructively manipulate any of the input objects.

.TP* Examples:
.verb
  ;; An atom is returned.
  (append 3) -> 3

  ;; A list is also just returned: no copying takes place.
  ;; The eq function can verify that the same object emerges
  ;; from append that went in.
  (let ((list '(1 2 3)))
    (eq (append list) list)) -> t

  (append '(1 2 3) '(4 5 6) 7) -> '(1 2 3 4 5 6 . 7))

  ;; the (4 5 6) tail of the resulting list is the original
  ;; (4 5 6) object, shared with that list.

  (append '(1 2 3) '(4 5 6)) -> '(1 2 3 4 5 6)

  (append nil) -> nil

  ;; (1 2 3) is copied: it is not the last argument
  (append '(1 2 3) nil) -> (1 2 3)

  ;; empty lists disappear
  (append nil '(1 2 3) nil '(4 5 6)) -> (1 2 3 4 5 6)
  (append nil nil nil) -> nil

  ;; atoms and improper lists other than in the last position
  ;; are erroneous
  (append '(a . b) 3 '(1 2 3)) -> **error**

  ;; sequences other than lists can be catenated.
  (append "abc" "def" "g" #\eh) -> "abcdefgh"

  ;; lists followed by non-list sequences end with non-list
  ;; sequences catenated in the terminating atom:
  (append '(1 2) '(3 4) "abc" "def") -> (1 2 3 4 . "abcdef")
.brev

.coNP Function @ append*
.synb
.mets (append* <> [ list *])
.syne
.desc
The
.code append*
function lazily catenates lists.

If invoked with no arguments, it returns
.codn nil .
If invoked with a single argument, it returns that argument.

Otherwise, it returns a lazy list consisting of the elements of every
.meta list
argument from left to right.

Arguments other than the last are treated as lists, and traversed using
.code car
and
.code cdr
functions to visit their elements.

The last argument isn't traversed: rather, that object itself becomes the
.code cdr
field of the last cons cell of the lazy list constructed from the
previous arguments.

.coNP Functions @ revappend and @ nreconc
.synb
.mets (revappend < list1 << list2 )
.mets (nreconc < list1 << list2 )
.syne
.desc
The
.code revappend
function returns a list consisting of
.code list2
appended to a reversed copy of
.metn list1 .
The returned object shares structure
with
.metn list2 ,
which is unmodified.

The
.code nreconc
function behaves similarly, except
that the the returned object may share
structure with not only
.meta list2
but also
.metn list1 ,
which is modified.

.coNP Function @ list
.synb
.mets (list << value *)
.syne
.desc
The
.code list
function creates a new list, whose elements are the
argument values.

.TP* Examples:
.verb
  (list) -> nil
  (list 1) -> (1)
  (list 'a 'b) -> (a b)
.brev

.coNP Function @ list*
.synb
.mets (list* << value *)
.syne
.desc
The
.code list*
function is a generalization of cons. If called with exactly
two arguments, it behaves exactly like cons:
.code "(list* x y)"
is identical to
.codn "(cons x y)" .
If three or more arguments are specified,
the leading arguments specify additional atoms to be consed to the
front of the list. So for instance
.code "(list* 1 2 3)"
is the same as
.code "(cons 1 (cons 2 3))"
and produces the improper list
.codn "(1 2 . 3)" .
Generalizing in the other direction,
.code list*
can be called with just
one argument, in which case it returns that argument, and
can also be called with no arguments in which case it returns
.codn nil .

.TP* Examples:
.verb
  (list*) -> nil
  (list* 1) -> 1
  (list* 'a 'b) -> (a . b)
  (list* 'a 'b 'c) -> (a b . c)
.brev

.TP* "Dialect Note:"
Note that unlike in some other Lisp dialects, the effect
of
.code "(list* 1 2 x)"
can also be obtained using
.codn "(list 1 2 . x)" .
However,
.code "(list* 1 2 (func 3))"
cannot be rewritten as
.code "(list 1 2 . (func 3))"
because the latter is equivalent to
.codn "(list 1 2 func 3)" .

.coNP Accessor @ sub-list
.synb
.mets (sub-list < list >> [ from <> [ to ]])
.mets (set (sub-list < list >> [ from <> [ to ]]) << new-value )
.syne
.desc
The
.code sub-list
function has the same parameters and semantics as the
.code sub
function, except that it operates on its
.meta list
argument using list operations, and assumes that
.meta list
it is terminated by
.codn nil .

If a
.code sub-list
form is used as a place, then the
.meta list
argument form must also be a place.

The
.code sub-list
place denotes a subrange of
.meta list
as if it were a storage location. The previous value of this location,
if needed, is fetched by a call to
.codn sub-list .
Storing
.meta new-value
to the place is performed by a call to
.codn replace-list .
The return value of
.meta replace-list
is stored into
.metn list .
In an update operation which accesses the prior value and stores a new value,
the arguments
.metn list ,
.metn from ,
.meta to
and
.meta new-value
are evaluated once.

.coNP Function @ replace-list
.synb
.mets (replace-list < list < item-sequence >> [ from <> [ to ]])
.syne
.desc
The
.code replace-list
function is like the
.code replace
function, except that it operates on its
.meta list
argument using list operations. It assumes that
.meta list
it is terminated by
.codn nil ,
and that it is made of cells which can be mutated using
.codn rplaca .

.coNP Functions @ listp and @ proper-list-p
.synb
.mets (listp << value )
.mets (proper-list-p << value )
.syne
.desc
The
.code listp
and
.code proper-list-p
functions test, respectively, whether
.meta value
is a list, or a proper list, and return
.code t
or
.code nil
accordingly.

The
.code listp
test is weaker, and executes without having to traverse
the object.
The value produced by the expression
.code "(listp x)"
is the same as that of
.codn "(or (null x) (consp x))" ,
except that
.code x
is evaluated only once.
The empty list
.code nil
is a list, and a cons cell is a list.

The
.code proper-list-p
function returns
.code t
only for proper lists.  A proper list is
either
.codn nil ,
or a cons whose
.code cdr
is a proper list.
.code proper-list-p
traverses the
list, and its execution will not terminate if the list is circular.

These functions return
.code nil
for list-like sequences that are not made of actual
.code cons
cells.

Dialect Note: in \*(TX 137 and older,
.code proper-list-p
is called
.codn proper-listp .
The name was changed for adherence to conventions and compatibility with other
Lisp dialects, like Common Lisp. However, the function continues to be
available under the old name. Code that must run on \*(TX 137 and older
installations should use
.codn proper-listp ,
but its use going forward is deprecated.

.coNP Function @ endp
.synb
.mets (endp << object )
.syne
.desc
The
.code endp
function returns
.code t
if
.meta object
is the object
.codn nil .

If
.meta object
is a cons cell, then
.code endp
returns
.codn t .

Otherwise,
.code endp
function throws an exception.

.coNP Function @ length-list
.synb
.mets (length-list << list )
.syne
.desc
The
.code length-list
function returns the length of
.metn list ,
which may be
a proper or improper list. The length of a list is the number of conses in that
list.

.coNP Function @ copy-list
.synb
.mets (copy-list << list )
.syne
.desc
The
.code copy-list
function which returns a list similar to
.metn list ,
but with
a newly allocated cons cell structure.

If
.meta list
is an atom, it is simply returned.

Otherwise,
.meta list
is a cons cell, and
.code copy-list
returns the same object as the expression
.mono
.meti (cons (car << list ) (copy-list (cdr << list ))).
.onom

Note that the object
.mono
.meti (car << list )
.onom
is not deeply copied, but only
propagated by reference into the new list.
.code copy-list
produces
a new list structure out of the same items that are in
.metn list .

.TP* "Dialect Note:"
Common Lisp does not allow the argument to be an atom, except
for the empty list
.codn nil .

.coNP Function @ copy-cons
.synb
.mets (copy-cons << cons )
.syne
.desc
The
.code copy-cons
function creates and returns a new object that is a replica of
.metn cons .

The
.meta cons
argument must be either a
.code cons
cell, or else a lazy cons: an object of type
.codn lcons .

A new cell of the same type as
.meta cons
is created, and all of its fields are initialized by
copying the corresponding fields from
.metn cons .

If
.meta cons
is lazy, the newly created object is in the same
state as the original. If the original has not yet been updated
and thus has an update function, the copy also has not yet been
updated and has the same update function.

.coNP Function @ copy-tree
.synb
.mets (copy-tree << obj )
.syne
.desc
The
.code copy-tree
function returns a copy of
.meta obj
which represents an arbitrary
.codn cons -cell-based
structure.

The cell structure of
.meta obj
is traversed and a similar structure is constructed, but without regard for
substructure sharing or circularity.

More precisely, if
.meta obj
is an atom, then it is returned.
If it is an ordinary
.code cons
cell, then
.code copy-tree
is recursively applied to the
.code car
and
.code cdr
fields to produce their individual replicas. A new
.code cons
cell is then produced from the replicated
.code car
and
.codn cdr .
If
.meta obj
is a lazy
.codn cons ,
then just like in the ordinary
.code cons
case, the
.code car
and
.code cdr
fields are duplicated with a recursive call to
.codn copy-tree .
Then, a lazy
.code cons
is created from these replicated fields. If
.meta cell
has an update function, then the newly created lazy
.code cons
has the same update function; the function isn't copied.

Like
.codn copy-cons ,
the
.code copy-tree
function doesn't trigger the update of lazy conses.
The copies of lazy conses which have not been updated
are also conses which have not been updated.

.coNP Functions @ reverse and @ nreverse
.synb
.mets (reverse << list )
.mets (nreverse << list )
.syne
.desc
Description:

The functions
.code reverse
and
.code nreverse
produce an object which contains
the same items as proper list
.metn list ,
but in reverse order.
If
.meta list
is
.codn nil ,
then both functions return
.codn nil .

The
.code reverse
function is non-destructive: it creates a new list.

The
.code nreverse
function creates the structure of the reversed list out of the
cons cells of the input list, thereby destructively altering it (if it contains
more than one element). How
.code nreverse
uses the material from the original list
is unspecified. It may rearrange the cons cells into a reverse order, or it may
keep the structure intact, but transfer the
.code car
values among cons cells into
reverse order.  Other approaches are possible.

.coNP Accessor @ nthlast
.synb
.mets (nthlast < index << list )
.mets (set (nthlast < index << list ) << new-value )
.syne
.desc
The
.code nthlast
function retrieves the n-th last cons cell of a list,
indexed from one.
The
.meta index
parameter must be a an integer. If
.meta index
is positive and so large that it specifies a nonexistent cons beyond the
beginning of the list,
.code nthlast
returns
.metn list .
Effectively, values of
.meta index
larger than the length of the list are clamped to the length.
If
.meta index
is negative, then
.code nthlast
yields nil. An
.meta index
value of zero retrieves the terminating atom of
.meta list
or else the value
.meta list
itself, if
.meta list
is an atom.

The following equivalences hold:

.verb
  (nthlast 1 list) <--> (last list)
.brev

An
.code nthlast
place designates the storage location which holds the n-th cell,
as indicated by the value of
.metn index .

A negative
.meta index
doesn't denote a place.

A positive
.meta index
greater than the length of the list is treated as if it were
equal to the length of the list.

If
.meta list
is itself a syntactic place, then the
.meta index
value
.I n
is permitted for a list of length
.IR n .
This index value denotes the
.meta list
place itself.  Storing to this value overwrites
.metn list .
If
.meta list
isn't a syntactic place, then storing to position
.I n
isn't permitted.

If
.meta list
is is of length zero, or an atom (in which case its
length is considered to be zero) then the above
remarks about position
.I n
apply to an
.meta index
value of zero: if
.meta list
is a syntactic place, then the position denotes
.meta list
itself, otherwise the position doesn't exist as a place.

If
.meta list
contains one or more elements, then
.meta index
value of zero denotes the
.code cdr
field of its last cons cell. Storing a value to this
place overwrites the terminating atom.

.coNP Accessor @ butlastn
.synb
.mets (butlastn < num << list )
.mets (set (butlastn < num << list ) new-value )
.syne
.desc
The
.code butlastn
function calculates that initial portion of
.meta list
which excludes the last
.meta num
elements.

Note: the
.code butlastn
function doesn't support non-list sequences as sequences;
it treats them as the terminating atom of a zero-length improper list.
The
.code butlast
sequence function supports non-list sequences. If
.code x
is a list, then the following equivalence holds:

.verb
  (butlastn n x)  <-->  (butlast x n)
.brev

If
.meta num
is zero, or negative, then
.code butlastn
returns
.metn list .

If
.meta num
is positive, and meets or exceeds the length of
.metn list ,
then
.code butlastn
returns
.codn nil .

If a
.code butlastn
form is used as a syntactic place, then
.meta list
must be a place. Assigning to the form causes
.meta list
to be replaced with a new list which is a catenation
of the new value and the last
.meta num
elements of the original list, according to the following equivalence:

.verb
  (set (butlastn n x) v)

  <-->

  (progn (set x (append v (nthlast n x))) v)
.brev

except that
.codn n ,
.code x
and
.code v
are evaluated only once, in left-to-right order.

.coNP Accessor @ nth
.synb
.mets (nth < index << object )
.mets (set (nth < index << object ) << new-value )
.syne
.desc
The
.code nth
function performs random access on a list, retrieving the n-th
element indicated by the zero-based index value given by
.metn index .
The
.meta index
argument must be a non-negative integer.

If
.meta index
indicates an element beyond the end of the list, then
the function returns
.codn nil .

The following equivalences hold:

.verb
  (nth 0 list) <--> (car 0) <--> (first list)
  (nth 1 list) <--> (cadr list) <--> (second list)
  (nth 2 list) <--> (caddr list) <--> (third list)

  (nth x y) <--> (car (nthcdr x y))
.brev

.coNP Accessor @ nthcdr
.synb
.mets (nthcdr < index << list )
.mets (set (nthcdr < index << list ) << new-value )
.syne
.desc
The
.code nthcdr
function retrieves the n-th cons cell of a list, indexed from zero.
The
.meta index
parameter must be a non-negative integer. If
.meta index
specifies a nonexistent cons beyond the end of the list,
then
.code nthcdr
yields nil.

The following equivalences hold:

.verb
  (nthcdr 0 list) <--> list
  (nthcdr 1 list) <--> (cdr list)
  (nthcdr 2 list) <--> (cddr list)

  (car (nthcdr x y)) <--> (nth x y)
.brev

An
.code nthcdr
place designates the storage location which holds the n-th cell,
as indicated by the value of
.metn index .
Indices beyond the last cell of
.meta list
do not designate a valid place.
If
.meta list
is itself a place, then the zeroth index is permitted and the
resulting place denotes
.metn list .
Storing a value to
.mono
.meti (nthcdr < 0 << list)
.onom
overwrites
.metn list .
Otherwise if
.meta list
isn't a syntactic place, then the zeroth index does not designate a valid
place;
.meta index
must have a positive value. A
.code nthcdr
place does not support deletion.

.TP* "Dialect Note:"
In Common Lisp,
.code nthcdr
is only a function, not an accessor;
.code nthcdr
forms do not denote places.

.coNP Function @ tailp
.synb
.mets (tailp < object << list)
.syne
.desc
The
.code tailp
function tests whether
.meta object
is a tail of
.metn list .
This means that
.meta object
is either
.meta list
itself, or else one of the
.code cons
cells of
.meta list
or else the terminating atom of
.metn list .

More formally, a recursive definition follows.
If
.meta object
and
.meta list
are the same object (thus equal under the
.code eq
function) then
.code tailp
returns
.codn t .
If
.meta list
is an atom, and is not
.metn object ,
then the function returns
.codn nil .
Otherwise,
.meta list
is a
.code cons
that is not
.meta object
and
.code tailp
yields the same value as the
.mono
.meti "(tailp < object (cdr << list ))"
.onom
expression.

.coNP Accessors @, caar @, cadr @, cdar @, cddr @ ... and @ cdddddr
.synb
.mets (caar << object )
.mets (cadr << object )
.mets (cdar << object )
.mets (cddr << object )
.mets ...
.mets (cdddr << object )
.mets (set (caar << object ) << new-value )
.mets (set (cadr << object ) << new-value )
.mets ...
.syne
.desc
The
.I a-d accessors
provide a shorthand notation for accessing two to five
levels deep into a cons-cell-based tree structure. For instance, the
the equivalent of the nested function call expression
.mono
.meti (car (car (cdr << object )))
.onom
can be achieved using the single function call
.mono
.meti (caadr << object ).
.onom
The symbol names of the a-d accessors are a generalization of the words
"car" and "cdr". They encode the pattern of
.code car
and
.code cdr
traversal of the structure using a sequence of the the letters
.code a
and
.code d
placed between
.code c
and
.codn r .
The traversal is encoded in right-to-left order, so that
.code cadr
indicates a traversal of the
.code cdr
link, followed by the
.codn car .
This order corresponds to the nested function call notation, which also
encodes the traversal right-to-left. The following diagram illustrates
the straightforward relationship:
.verb
  (cdr (car (cdr x)))
    ^    ^    ^
    |   /     |
    |  /     /
    | / ____/
    || /
  (cdadr x)
.brev

\*(TL provides all possible a-d accessors up to five levels deep, from
.code caar
all the way through
.codn cdddddr .

Expressions involving a-d accessors are places. For example,
.code "(caddr x)"
denotes the same place as
.codn "(car (cddr x))" ,
and
.code "(cdadr x)"
denotes the same place as
.codn "(cdr (cadr x))" .

The a-d accessor places support deletion, with semantics derived from
the deletion semantics of the
.code car
and
.code cdr
places. For example,
.code "(del (caddr x))"
means the same as
.codn "(del (car (cddr x)))" .

.coNP Functions @ flatten and @ flatten*
.synb
.mets (flatten << list )
.mets (flatten* << list )
.syne
.desc
The
.code flatten
function produces a list whose elements are all of the
.cod2 non- nil
atoms contained in the structure of
.metn list .

The
.code flatten*
function
works like
.code flatten
except that it produces a lazy list. It can be used to lazily flatten an
infinite lazy structure.

.TP* Examples:
.verb
  (flatten '(1 2 () (3 4))) -> (1 2 3 4)

  ;; equivalent to previous, since
  ;; nil is the same thing as ()
  (flatten '(1 2 nil (3 4))) -> (1 2 3 4)

  (flatten nil) -> nil

  (flatten '(((()) ()))) -> nil
.brev

.coNP Functions @ flatcar and @ flatcar*
.synb
.mets (flatcar << tree )
.mets (flatcar* << tree )
.syne
.desc
The
.code flatcar
function produces a list of all the atoms contained in the
tree structure
.metn tree ,
in the order in which they appear, when the structure is traversed
left to right.

This list includes those
.code nil
atoms which appear in
.code car
fields.

The list excludes
.code nil
atoms which appear in
.code cdr
fields.

The
.code flatcar*
function
works like
.code flatcar
except that it produces a lazy list. It can be used to lazily flatten an
infinite lazy structure.

.TP* Examples:
.verb
  (flatcar '(1 2 () (3 4))) -> (1 2 nil 3 4)

  (flatcar '(a (b . c) d (e) (((f)) . g) (nil . z) nil . h))

  --> (a b c d e f g nil z nil h)
.brev

.coNP Function @ tree-find
.synb
.mets (tree-find < obj < tree << test-function )
.syne
.desc
The
.code tree-find
function searches
.meta tree
for an occurrence of
.metn obj .
Tree can be
any atom, or a cons. If
.meta tree
it is a cons, it is understood to be a proper
list whose elements are also trees.

The equivalence test is performed by
.meta test-function
which must take two
arguments, and has conventions similar to
.codn eq ,
.code eql
or
.codn equal .

.code tree-find
works as follows.  If
.meta tree
is equivalent to
.meta obj
under
.metn test-function ,
then
.code t
is returned to announce a successful finding.
If this test fails, and
.meta tree
is an atom,
.code nil
is returned immediately to
indicate that the find failed.  Otherwise,
.meta tree
is taken to be a proper list,
and tree-find is recursively applied to each element of the list in turn, using
the same
.meta obj
and
.meta test-function
arguments, stopping at the first element
which returns a
.cod2 non- nil
value.

.coNP Functions @, memq @ memql and @ memqual
.synb
.mets (memq < object << list )
.mets (memql < object << list )
.mets (memqual < object << list )
.syne
.desc
The
.codn memq ,
.code memql
and
.code memqual
functions search
.meta list
for a member
which is, respectively,
.codn eq ,
.code eql
or
.code equal
to
.metn object .
(See the
.codn eq ,
.code eql
and
.code equal
functions above.)

If no such element found,
.code nil
is returned.

Otherwise, that suffix of
.meta list
is returned whose first element
is the matching object.

.coNP Functions @ member and @ member-if
.synb
.mets (member < key < sequence >> [ testfun <> [ keyfun ]])
.mets (member-if < predfun < sequence <> [ keyfun ])
.syne
.desc
The
.code member
and
.code member-if
functions search through
.meta sequence
for an item which
matches a key, or satisfies a predicate function, respectively.

The
.meta keyfun
argument specifies a function which is applied to the elements
of the sequence to produce the comparison key. If this argument is omitted,
then the untransformed elements of the sequence themselves are examined.

The
.code member
function's
.meta testfun
argument specifies the test function which is
used to compare the comparison keys taken from the sequence to the search key.
If this argument is omitted, then the
.code equal
function is used.
If
.code member
does not find a matching element, it returns
.codn nil .
Otherwise it
returns the suffix of
.meta sequence
which begins with the matching element.

The
.code member-if
function's
.meta predfun
argument specifies a predicate function
which is applied to the successive comparison keys pulled from the sequence
by applying the key function to successive elements.  If no match is found,
then
.code nil
is returned, otherwise what is returned is the suffix of
.meta sequence
which begins with the matching element.

.coNP Functions @, rmemq @, rmemql @, rmemqual @ rmember and @ rmember-if
.synb
.mets (rmemq < object << list )
.mets (rmemql < object << list )
.mets (rmemqual < object << list )
.mets (rmember < key < sequence >> [ testfun <> [ keyfun ]])
.mets (rmember-if < predfun < sequence <> [ keyfun ])
.syne
.desc
These functions are counterparts to
.codn memq ,
.codn memql ,
.codn memqual ,
.code member
and
.code member-if
which look for the right-most
element which matches
.metn object ,
rather than for the left-most element.

.coNP Functions @ conses and @ conses*
.synb
.mets (conses << list )
.mets (conses* << list )
.syne
.desc
These functions return a list whose elements are the conses which make
up
.metn list .
The
.code conses*
function does this in a lazy way, avoiding the
computation of the entire list: it returns a lazy list of the conses of
.metn list .
The
.code conses
function computes the entire list before returning.

The input
.meta list
may be proper or improper.

The first cons of
.meta list
is that
.meta list
itself. The second cons is the rest
of the list, or
.mono
.meti (cdr << list ).
.onom
The third cons is
.mono
.meti (cdr (cdr << list ))
.onom
and so on.

.TP* Example:
.verb
  (conses '(1 2 3)) -> ((1 2 3) (2 3) (3))
.brev

.TP* "Dialect Note:"

These functions are useful for simulating the
.code maplist
function found in other dialects like Common Lisp.

\*(TL's
.code "(conses x)"
can be expressed in Common Lisp as
.codn "(maplist #'identity x)" .

Conversely, the Common Lisp operation
.code "(maplist function list)"
can be computed in \*(TL as
.codn "(mapcar function (conses list))" .

More generally, the Common Lisp operation

.verb
  (maplist function list0 list1 ... listn)
.brev

can be expressed as:

.verb
  (mapcar function (conses list0)
                   (conses list1) ... (conses listn))
.brev

.SS* Association Lists

Association lists are ordinary lists formed according to a special convention.
Firstly, any empty list is a valid association list. A non-empty association
list contains only cons cells as the key elements. These cons cells are
understood to represent key/value associations, hence the name "association
list".

.coNP Function @ assoc
.synb
.mets (assoc < key << alist )
.syne
.desc
The
.code assoc
function searches an association list
.meta alist
for a cons cell whose
.code car
field is equivalent to
.meta key
under the
.code equal
function.
The first such cons is returned. If no such cons is found,
.code nil
is returned.

.coNP Functions @ assq and @ assql
.synb
.mets (assq < key << alist )
.mets (assql < key << alist )
.syne
.desc
The
.code assq
and
.code assql
functions are very similar to
.codn assoc ,
with the only difference being that they determine equality using,
respectively, the
.code eq
and
.code eql
functions rather than
.codn equal .

.coNP Functions @, rassq @ rassql and @ rassoc
.synb
.mets (rassq < value << alist )
.mets (rassql < value << alist )
.mets (rassoc < value << alist )
.syne
.desc
The
.codn rassq ,
.code rassql
and
.code rassoc
functions are reverse lookup counterparts to
.code assql
and
.codn assoc .
When searching, they examine the
.code cdr
field of the pairs of
.meta alist
rather than the
.code car
field.

The
.code rassoc
function searches association list
.meta alist
for a cons whose
.code cdr
field equivalent to
.meta value
according to the
.code equal
function. If such a cons is found, it is returned.
Otherwise
.code nil
is returned.

The
.code rassq
and
.code rassql
functions search in the same way as
.code rassoc
but compares values using, respectively,
.code eq
and
.codn eql .

.coNP Function @ acons
.synb
.mets (acons < car < cdr << alist )
.syne
.desc
The
.code acons
function constructs a new alist by consing a new cons to the
front of
.metn alist .
The following equivalence holds:

.verb
  (acons car cdr alist) <--> (cons (cons car cdr) alist)
.brev

.coNP Function @ acons-new
.synb
.mets (acons-new < car < cdr << alist )
.syne
.desc
The
.code acons-new
function searches
.metn alist ,
as if using the assoc function,
for an existing cell which matches the key provided by the car argument.
If such a cell exists, then its cdr field is overwritten with the
.meta cdr
argument, and then the
.meta alist
is returned. If no such cell exists, then
a new list is returned by adding a new cell to the input list consisting
of the
.meta car
and
.meta cdr
values, as if by the
.code acons
function.

.coNP Function @ aconsql-new
.synb
.mets (aconsql-new < car < cdr << alist )
.syne
.desc
The
.code aconsql-new
function has similar same parameters and semantics as
.codn acons-new ,
except that the
.code eql
function is used
for equality testing. Thus, the list is searched for an existing cell
as if using the
.code assql
function rather than
.codn assoc .

.coNP Function @ alist-remove
.synb
.mets (alist-remove < alist << keys )
.syne
.desc
The
.code alist-remove
function takes association list
.meta alist
and produces a
duplicate from which cells matching the specified keys have been removed. The
.meta keys
argument is a list of the keys not to appear in the output list.

.coNP Function @ alist-nremove
.synb
.mets (alist-nremove < alist << keys )
.syne
.desc
The
.code alist-nremove
function is like
.codn alist-remove ,
but potentially destructive.
The input list
.meta alist
may be destroyed and its structural material re-used to
form the output list. The application should not retain references to the input
list.

.coNP Function @ copy-alist
.synb
.mets (copy-alist << alist )
.syne
.desc
The
.code copy-alist
function duplicates
.codn alist .
Unlike
.codn copy-list ,
which only duplicates list structure,
.code copy-alist
also duplicates each cons
cell of the input alist. That is to say, each element of the output list
is produced as if by the
.code copy-cons
function applied to the corresponding
element of the input list.

.SS* Property Lists
A
.IR "property list",
also referred to as a
.IR plist ,
is a flat list of even length consisting of interleaved
pairs of property names (usually symbols) and their values (arbitrary
objects). An example property list is (:a 1 :b "two") which contains
two properties, :a having value 1, and :b having value "two".

An
.I "improper plist"
represents Boolean properties in a condensed way, as property
indicators which are not followed by a value. Such properties
only indicate their presence or absence, which is useful for
encoding a Boolean value. If it is absent, then the property
is false. Correctly using an improper plist requires that the
exact set of Boolean keys is established by convention.

In this document, the unqualified terms
.I "property list"
and
.I "plist"
refer strictly to an ordinary plist, not to an improper plist.

.TP* "Dialect Note:"

Unlike in some other Lisp dialects, including ANSI Common Lisp,
symbols do not have property lists in \*(TL. Improper plists
aren't a concept in ANSI CL.

.coNP Function @ prop
.synb
.mets (prop < plist << key )
.syne
.desc
The
.code prop
function searches property list
.meta plist
for key
.metn key .
If the key is found, then the value next to it is returned. Otherwise
.code nil
is returned.

It is ambiguous whether
.code nil
is returned due to the property not being
found, or due to the property being present with a
.code nil
value.

The indicators in
.meta plist
are compared with
.meta key
using
.code eq
equality, allowing them to be symbols, characters or
.code fixnum
integers.

.coNP Function @ memp
.synb
.mets (memp < key << plist )
.syne
.desc
The
.code memp
function searches property list
.meta plist
for key
.metn key ,
using
.code eq
equality.

If the key is found, then the entire suffix of
.meta plist
beginning with the indicator is returned, such that the first
element of the returned list is
.meta key
and the second element is the property value.

Note the reversed argument convention relative to the
.code prop
function, harmonizing with functions in the
.code member
family.

.coNP Functions @ plist-to-alist and @ improper-plist-to-alist
.synb
.mets (plist-to-alist << plist )
.mets (improper-plist-to-alist < imp-plist << bool-keys )
.syne
.desc
The functions
.code plist-to-alist
and
.code improper-plist-to-alist
convert, respectively, a property list and improper property
list to an association list.

The
.code plist-to-alist
function scans
.meta plist
and returns the indicator-property pairs as a list of cons
cells, such that each
.code car
is the indicator, and each
.code cdr
is the value.

The
.code improper-plist-to-alist
is similar, except that it handles the Boolean properties
which, by convention, aren't followed by a value. The list of
all such indicators is specified by the
.code bool-keys
argument.

.TP* "Examples:"
.verb
  (plist-to-alist '(a 1 b 2))  -->  ((a . 1) (b . 2))

  (improper-plist-to-alist '(:x 1 :blue :y 2) '(:blue))
  -->  ((:x . 1) (:blue) (:y . 2))
.brev


.SS* List Sorting

Note: these functions operate on lists. The principal sorting function
in \*(TL is
.codn sort ,
described under Sequence Manipulation.

The
.code merge
function described here provides access to an elementary step
of the algorithm used internally by
.code sort
when operating on lists.

The
.code multi-sort
operation sorts multiple lists in parallel. It is implemented using
.codn sort .

.coNP Function @ merge
.synb
.mets (merge < seq1 < seq2 >> [ lessfun <> [ keyfun ]])
.syne
.desc
The
.code merge
function merges two sorted sequences
.meta seq1
and
.meta seq2
into a single
sorted sequence. The semantics and defaulting behavior of the
.meta lessfun
and
.meta keyfun
arguments are the same as those of the sort function.

The sequence which is returned is of the same kind as
.metn seq1 .

This function is destructive of any inputs that are lists. If the output
is a list, it is formed out of the structure of the input lists.

.coNP Function @ multi-sort
.synb
.mets (multi-sort < columns < less-funcs <> [ key-funcs ])
.syne
.desc
The
.code multi-sort
function regards a list of lists to be the columns of a
database. The corresponding elements from each list constitute a record.
These records are to be sorted, producing a new list of lists.

The
.meta columns
argument supplies the list of lists which comprise the columns of
the database. The lists should ideally be of the same length. If the lists are
of different lengths, then the shortest list is taken to be the length of the
database. Excess elements in the longer lists are ignored, and do not appear in
the sorted output.

The
.meta less-funcs
argument supplies a list of comparison functions which are
applied to the columns. Successive functions correspond to successive
columns. If
.meta less-funcs
is an empty list, then the sorted database will
emerge in the original order. If
.meta less-funcs
contains exactly one function,
then the rows of the database is sorted according to the first column. The
remaining columns simply follow their row. If
.meta less-funcs
contains more than
one function, then additional columns are taken into consideration if the items
in the previous columns compare
.codn equal .
For instance if two elements from column
one compare
.codn equal ,
then the corresponding second column elements are compared
using the second column comparison function.

The optional
.meta key-funcs
argument supplies transformation functions through
which column entries are converted to comparison keys, similarly to the single
key function used in the sort function and others.  If there are more key
functions than less functions, the excess key functions are ignored.

.SS* Lazy Lists and Lazy Evaluation
.coNP Function @ make-lazy-cons
.synb
.mets (make-lazy-cons < function >> [ car <> [ cdr ]])
.syne
.desc
The function
.code make-lazy-cons
makes a special kind of cons cell called a lazy
cons, whose type is
.codn lcons .
Lazy conses are useful for implementing lazy lists.

Lazy lists are lists which are not allocated all at once. Rather,
the elements of its structure materialize just before they are accessed.

A lazy cons has
.code car
and
.code cdr
fields like a regular cons, and those
fields are initialized to the values of the
.meta car
and
.meta cdr
arguments of
.code make-lazy-cons
when the lazy cons is created. These arguments default to
.meta nil
if omitted.  A lazy cons also
has an update function, which is specified by the
.meta function
argument to
.codn make-lazy-cons .

The
.meta function
argument must be a function that may be called with exactly one
parameter.

When either the
.code car
and
.code cdr
fields of a cons are accessed for the first time to retrieve their value,
.meta function
is automatically invoked first, and is given the lazy cons
as a parameter. That function has the opportunity
to store new values into the
.code car
and
.code cdr
fields. Once the function is called, it is removed
from the lazy cons: the lazy cons no longer has an update function.
If the update function itself attempts to retrieve the value of the
lazy cons cell's
.code car
or
.code cdr
field, it will be recursively invoked.

The functions
.code lcons-car
and
.code lcons-cdr
may be used to access the fields of a lazy cons without
triggering the update function.

Storing a value into either the
.code car
or
.code cdr
field does not have the effect of invoking the update function.

If the function terminates by returning normally, the access to the value of
the field then proceeds in the ordinary manner, retrieving whatever value has
most recently been stored.

The return value of the function is ignored.

To perpetuate the growth of a lazy list, the function can make another call to
.code make-lazy-cons
and install the resulting cons as the
.code cdr
of the lazy cons.

.TP* Example:

.verb
  ;;; lazy list of integers between min and max
  (defun integer-range (min max)
    (let ((counter min))
      ;; min is greater than max; just return empty list,
      ;; otherwise return a lazy list
      (if (> min max)
        nil
        (make-lazy-cons
          (lambda (lcons)
            ;; install next number into car
            (rplaca lcons counter)
            ;; now deal wit cdr field
            (cond
              ;; max reached, terminate list with nil!
              ((eql counter max)
               (rplacd lcons nil))
              ;; max not reached: increment counter
              ;; and extend with another lazy cons
              (t
                (inc counter)
                (rplacd lcons
                        (make-lazy-cons
                          (lcons-fun lcons))))))))))
.brev

.coNP Function @ lconsp
.synb
.mets (lconsp << value )
.syne
.desc
The
.code lconsp
function returns
.code t
if
.meta value
is a lazy cons cell. Otherwise
it returns
.codn nil ,
even if
.meta value
is an ordinary cons cell.

.coNP Function @ lcons-fun
.synb
.mets (lcons-fun << lazy-cons )
.syne
.desc
The
.code lcons-fun
function retrieves the update function of a lazy cons.
Once a lazy cons has been accessed, it no longer has an update function
and
.code lcons-fun
returns
.codn nil .
While the update function of a lazy cons is
executing, it is still accessible. This allows the update function
to retrieve a reference to itself and propagate itself into
another lazy cons (as in the example under
.codn make-lazy-cons ).

.coNP Functions @ lcons-car and @ lcons-cdr
.synb
.mets (lcons-car << lazy-cons )
.mets (lcons-cdr << lazy-cons )
.syne
.desc
The functions
.code lcons-car
and
.code lcons-cdr
retrieve the
.code car
and
.code cdr
fields of
.metn lazy-cons ,
without triggering the invocation of its associated update function.

The
.meta lazy-cons
argument must be an object of type
.codn lcons .
Unlike the functions
.code car
and
.codn cdr ,
These functions cannot be applied to any other type of object.

Note: these functions may be used by the update function to retrieve
the values which were stored into
.meta lazy-cons
by the
.code make-lazy-cons
constructor, without triggering recursion. The function may then
overwrite either or both of these values.  This allows the fields of the lazy
cons to store state information necessary for the propagation of a lazy list.
If that state information consists of no more than two values, then
no additional context object need be allocated.

.coNP Macro @ lcons
.synb
.mets (lcons < car-expression << cdr-expression )
.syne
.desc
The
.code lcons
macro simplifies the construction of structures based on lazy conses.
Syntactically, it resembles the
.code cons
function. However, the arguments are expressions rather than values.
The macro generates code which, when evaluated, immediately produces
a lazy cons. The expressions
.meta car-expression
and
.meta cdr-expression
are not immediately evaluated. Rather, when either the
.code car
or
.code cdr
field of the lazy cons cell is accessed, these expressions are both
evaluated at that time, in the order that they appear in the
.code lcons
expression, and in the original lexical scope in which that
expression was evaluated. The return values of these expressions
are used, respectively, to initialize the corresponding fields
of the lazy cons.

Note: the
.code lcons
macro may be understood in terms of the following reference
implementation, as a syntactic sugar combining the
.code make-lazy-cons
constructor with a lexical closure provided by a
.code lambda
function:

.verb
  (defmacro lcons (car-form cdr-form)
    (let ((lc (gensym)))
       ^(make-lazy-cons (lambda (,lc)
                          (rplaca ,lc ,car-form)
                          (rplacd ,lc ,cdr-form)))))
.brev

.TP* Example:

.verb
  ;; Given the following function ...

  (defun fib-generator (a b)
    (lcons a (fib-generator b (+ a b))))

  ;; ... the following function call generates the Fibonacci
  ;; sequence as an infinite lazy list.

  (fib-generator 1 1) -> (1 1 2 3 5 8 13 ...)
.brev

.coNP Functions @ lazy-stream-cons and @ get-lines
.synb
.mets (lazy-stream-cons << stream )
.mets (get-lines <> [ stream ])
.syne
.desc
The
.code lazy-stream-cons
and
.code get-lines
functions are synonyms, except that the
.meta stream
argument is optional in
.code get-lines
and defaults to
.codn *stdin* .
Thus, the following
description of
.code lazy-stream-cons
also applies to
.codn get-lines .

The
.code lazy-stream-cons
returns a lazy cons which generates a lazy list based on
reading lines of text from input stream
.metn stream ,
which form the elements of
the list. The
.code get-line
function is called on demand to add elements to the
list.

The
.code lazy-stream-cons
function itself makes the first call to
.code get-line
on the stream. If this returns
.codn nil ,
then the stream is closed and
.code nil
is
returned. Otherwise, a lazy cons is returned whose update function will install
that line into the
.code car
field of the lazy cons, and continue the lazy list
by making another call to
.codn lazy-stream-cons ,
installing the result into the
.code cdr
field.

.code lazy-stream-cons
inspects the real-time property of a stream
as if by the
.code real-time-stream-p
function. This determines which of two
styles of lazy list are returned. For an ordinary (non-real-time) stream,
the lazy list treats the end-of-file condition accurately: an empty
file turns into the empty list
.codn nil ,
a one line file into a one-element
list which contains that line and so on. This accuracy requires one
line of lookahead which is not acceptable in real-time streams, and
so a different type of lazy list is used, which generates an extra
.code nil
item after the last line. Under this type of lazy list, an empty input stream
translates to the list
.codn (nil) ;
a one-line stream translates to
.mono
("line" nil)
.onom
and so forth.

.coNP Macro @ delay
.synb
.mets (delay << expression )
.syne
.desc
The delay operator arranges for the delayed (or "lazy") evaluation of
.metn expression .
This means that the expression is not evaluated immediately.
Rather, the delay expression produces a promise object.

The promise object can later be passed to the
.code force
function (described
later in this document). The force function will trigger the evaluation
of the expression and retrieve the value.

The expression is evaluated in the original scope, no matter where
the
.code force
takes place.

The expression is evaluated at most once, by the first call to
.codn force .
Additional calls to
.code force
only retrieve a cached value.

.TP* Example:

.verb
  ;; list is popped only once: the value is computed
  ;; just once when force is called on a given promise
  ;; for the first time.

  (defun get-it (promise)
    (format t "*list* is ~s\en" *list*)
    (format t "item is ~s\en" (force promise))
    (format t "item is ~s\en" (force promise))
    (format t "*list* is ~s\en" *list*))

  (defvar *list* '(1 2 3))

  (get-it (delay (pop *list*)))

  Output:

  *list* is (1 2 3)
  item is 1
  item is 1
  *list* is (2 3)
.brev

.coNP Accessor @ force
.synb
.mets (force << promise )
.mets (set (force << promise ) << new-value )
.syne
.desc
The
.code force
function accepts a promise object produced by the
.code delay
macro.
The first time
.code force
is invoked, the
.meta expression
which was wrapped inside
.meta promise
by the
.code delay
macro is evaluated (in its original lexical environment, regardless of where in
the program the
.code force
call takes place). The value of
.meta expression
is
cached inside
.meta promise
and returned, becoming the return value of the
.code force
function call.  If the
.code force
function is invoked additional times on
the same promise, the cached value is retrieved.

A
.code force
form is a syntactic place, denoting the value cache location within
.metn promise .

Storing a value in a
.code force
place causes future accesses to the
.meta promise
to return that value.

If the promise had not yet been forced, then
storing a value into it prevents that from ever happening. The
delayed
.meta expression
will never be evaluated.

If, while a promise is being forced, the evaluation of
.meta expression
itself causes an assignment to the promise, it is not specified whether
the promise will take on the value of
.meta expression
or the assigned value.

.coNP Function @ promisep
.synb
.mets (promisep << object )
.syne
.desc
The
.code promisep
function returns
.code t
if
.meta object
is a promise object: an object created by the
.code delay
macro.  Otherwise it returns
.codn nil .

Note: promise objects are conses. The
.code typeof
function applied to a promise returns
.codn cons .

.coNP Macro @ mlet
.synb
.mets (mlet >> ({ sym | >> ( sym << init-form )}*) << body-form *)
.syne
.desc
The
.code mlet
macro ("magic let" or "mutual let") implements a variable binding construct
similar to
.code let
and
.codn let* .

Under
.codn mlet ,
the scope of the bindings of the
.meta sym
variables extends over the
.metn init-form -s,
as well as the
.metn body-form -s.

Unlike the
.code let*
construct, each
.meta init-form
has each
.meta sym
in scope. That is to say, an
.meta init-form
can refer not only to previous variables, but also to later variables
as well as to its own variable.

The variables are not initialized until their values are accessed for
the first time. Any
.meta sym
whose value is not accessed is not initialized.

Furthermore, the evaluation of each
.meta init-form
does not take place until the time when its value is needed
to initialize the associated
.metn sym .
This evaluation takes place once. If a given
.meta sym
is not accessed during the evaluation of the
.code mlet
construct, then its
.meta init-form
is never evaluated.

The bound variables may be assigned. If, before initialization, a variable is
updated in such a way that its prior value is not needed, it is unspecified
whether initialization takes place, and thus whether its
.meta init-form
is evaluated.

Direct circular references are erroneous and are diagnosed. This takes
place when the macro-expanded form is evaluated, not during the
expansion of
.codn mlet .

.TP* Examples:

.verb
  ;; Dependent calculations in arbitrary order
  (mlet ((x (+ y 3))
         (z (+ x 1))
         (y 4))
    (+ z 4))  -->  12

  ;; Error: circular reference:
  ;; x depends on y, y on z, but z on x again.
  (mlet ((x (+ y 1))
         (y (+ z 1))
         (z (+ x 1)))
    z)

  ;; Okay: lazy circular reference because lcons is used
  (mlet ((list (lcons 1 list)))
    list)  -->  (1 1 1 1 1 ...) ;; circular list
.brev

In the last example, the
.code list
variable is accessed for the first time in the body of the 
.code mlet
form. This causes the evaluation of the
.code lcons
form. This form evaluates its arguments lazily, which means that it
is not a problem that
.code list
is not yet initialized. The form produces a lazy cons, which is then used
to initialize
.code list.
When the
.code car
or
.code cdr
fields of the lazy cons are accessed, the
.code list
expression in the
.code lcons
argument is accessed. By that time, the variable is initialized
and holds the lazy cons itself, which creates the circular reference,
and a circular list.

.coNP Functions @, generate @ giterate and @ ginterate
.synb
.mets (generate < while-fun << gen-fun )
.mets (giterate < while-fun < gen-fun <> [ value ])
.mets (ginterate < while-fun < gen-fun <> [ value ])
.syne
.desc
The
.code generate
function produces a lazy list which dynamically produces items
according to the following logic.

The arguments to
.code generate
are functions which do not take any arguments.  The
return value of generate is a lazy list.

When the lazy list is accessed, for instance with the functions car and cdr, it
produces items on demand. Prior to producing each item,
.meta while-fun
is
called. If it returns a true Boolean value (any value other than
.codn nil ),
then
the
.meta gen-fun
function is called, and its return value is incorporated as
the next item of the lazy list. But if
.meta while-fun
yields
.codn nil ,
then the lazy list immediately terminates.

Prior to returning the lazy list, generate invokes the
.meta while-fun
one time.
If
.code while-fun
yields
.codn nil ,
then
.code generate
returns the empty list
.code nil
instead of a lazy list. Otherwise, it instantiates a lazy list, and invokes the
.code gen-fun
to populate it with the first item.

The
.code giterate
function is similar to
.codn generate ,
except that
.meta while-fun
and
.meta gen-fun
are functions of one argument rather than functions of
no arguments. The optional
.meta value
argument defaults to
.code nil
and is threaded through the function calls. That is to say, the lazy
list returned is
.mono
.meti >> ( value >> [ gen-fun << value ] >> [ gen-fun >> [ gen-fun << value ]] ...).
.onom

The lazy list terminates when a value fails to satisfy
.metn while-fun .
That is to say, prior to generating each value, the lazy list tests
the value using
.metn while-fun .
If that function returns
.codn nil ,
then the item is not added, and the sequence terminates.

Note:
.code giterate
could be written in terms of
.code generate
like this:

.verb
  (defun giterate (w g v)
     (generate (lambda () [w v])
               (lambda () (prog1 v (set v [g v])))))
.brev

The
.code ginterate
function is a variant of
.code giterate
which includes the test-failing item in the generated sequence.
That is to say
.code ginterate
generates the next value and adds it to the lazy list.
The value is then tested using
.metn while-fun .
If that function returns
.codn nil ,
then the list is terminated, and no more items are produced.

.TP* Example:

.verb
  (giterate (op > 5) (op + 1) 0) -> (0 1 2 3 4)
  (ginterate (op > 5) (op + 1) 0) -> (0 1 2 3 4 5)
.brev

.coNP Function @ expand-right
.synb
.mets (expand-right < gen-fun << value )
.syne
.desc
The
.code expand-right
function is a complement to
.codn reduce-right ,
with lazy semantics.

The
.meta gen-fun
parameter is a function, which must accept a single argument,
and return either a cons pair
or
.codn nil .

The
.meta value
parameter is any value.

The first call to
.meta gen-fun
receives
.metn value .

The return value is interpreted as follows. If
.meta gen-fun
returns a cons cell pair
.mono
.meti >> ( elem . << next )
.onom
then
.meta elem
specifies the element to be added to the lazy list,
and
.meta next
specifies the value to be passed to the next call
to
.metn gen-fun .
If
.meta gen-fun
returns
.code nil
then the lazy list ends.

.TP* Examples:

.verb
  ;; Count down from 5 to 1 using explicit lambda
  ;; for gen-fun:

  (expand-right
    (lambda (item)
      (if (zerop item) nil
        (cons item (pred item))))
    5)
  --> (5 4 3 2 1)

  ;; Using functional combinators:
  [expand-right [iff zerop nilf [callf cons identity pred]] 5]
  --> (5 4 3 2 1)

  ;; Include zero:
  [expand-right
    [iff null
       nilf
       [callf cons identity [iff zerop nilf pred]]] 5]
  --> (5 4 3 2 1 0)
.brev

.coNP Functions @ expand-left and @ nexpand-left
.synb
.mets (expand-left < gen-fun << value )
.mets (nexpand-left < gen-fun << value )
.syne
.desc
The
.code expand-left
function is a companion to
.codn expand-right .

Unlike
.codn expand-right ,
it has eager semantics: it calls
.code gen-fun
repeatedly and accumulates an output list, not returning
until
.code gen-fun
returns
.codn nil .

The semantics is as follows.
.code expand-left
initializes an empty accumulation list. Then
.meta gen-fun
is called, with
.meta value
as its argument.

If
.meta gen-fun
it returns a cons cell, then the
.code car
of that cons cell is pushed onto the accumulation list,
and the procedure is repeated:
.meta gen-fun
is called again, with
.code cdr
taking the place of
.metn value .

If
.meta gen-fun
returns
.codn nil ,
then the accumulation list is returned.

If the expression
.code "(expand-right f v)"
produces a terminating list, then the following equivalence holds:

.verb
  (expand-left f v) <--> (reverse (expand-right f v))
.brev

The equivalence cannot hold for arguments to
.code expand-left
which produce an infinite list.

The
.code nexpand-left
function is a destructive version of
.codn expand-left .

The list returned by
.code nexpand-left
is composed of the cons cells returned by
.code gen-fun
whereas the list returned by
.code expand-left
is composed of freshly allocated cons cells.

.coNP Function @ repeat
.synb
.mets (repeat < list <> [ count ])
.syne
.desc
If
.meta list
is empty, then repeat returns an empty list.

If
.meta count
is omitted, the
.code repeat
function produces an infinite lazy list
formed by catenating together copies of
.metn list .

If
.meta count
is specified and is zero or negative, then an empty list is
returned.

Otherwise a list is returned consisting of
.meta count
repetitions of
.meta list
catenated together.

.coNP Function @ pad
.synb
.mets (pad < sequence < object <> [ count ])
.syne
.desc
The
.code pad
function produces a lazy list which consists of all of the
elements of
.meta sequence
followed by repetitions of
.metn object .

If
.meta count
is omitted, then the repetition of
.meta object
is infinite. Otherwise the specified number of repetitions
occur.

Note that
.meta sequence
may be a lazy list which is infinite. In that case, the repetitions
of
.meta object
will never occur.

.coNP Function @ weave
.synb
.mets (weave <> { sequence }*)
.syne
.desc
The
.code weave
function interleaves elements from the sequences given as arguments.

If called with no arguments, it returns the empty list.

If called with a single sequence, it returns the elements of that sequence
as a new lazy list.

When called with two or more sequences,
.code weave
returns a lazy list which draws elements from the sequences in a round-robin
fashion, repeatedly scanning the sequences from left to right, and
taking an item from each one, removing it from the sequence.
Whenever a sequence runs out of items, it is deleted; the weaving then
continues with the remaining sequences. The weaved sequence terminates
when all sequences are eliminated. (If at least one of the sequences
is an infinite lazy list, then the weaved sequence is infinite.)

.TP* Examples:

.verb
  ;; Weave negative integers with positive ones:
  (weave (range 1) (range -1 : -1)) -> (1 -1 2 -2 3 -3 ...)

  (weave "abcd" (range 1 3) '(x x x x x x x))
  --> (#\ea 1 x #\eb 2 x #\ec 3 x #\ed x x x x)
.brev

.coNP Macros @ gen and @ gun
.synb
.mets (gen < while-expression << produce-item-expression )
.mets (gun << produce-item-expression )
.syne
.desc
The
.code gen
macro operator produces a lazy list, in a manner similar to the
.code generate
function. Whereas the
.code generate
function takes functional arguments,
the
.code gen
operator takes two expressions, which is often more convenient.

The return value of
.code gen
is a lazy list. When the lazy list is accessed, for
instance with the functions
.code car
and
.codn cdr ,
it produces items on demand. Prior to
producing each item, the
.meta while-expression
is evaluated, in its original
lexical scope.  If the expression yields a
.cod2 non- nil
value, then
.meta produce-item-expression
is evaluated, and its return value is incorporated as
the next item of the lazy list. If the expression yields
.codn nil ,
then the lazy list immediately terminates.

The
.code gen
operator itself immediately evaluates
.meta while-expression
before
producing the lazy list. If the expression yields
.codn nil ,
then the operator
returns the empty list
.codn nil .
Otherwise, it instantiates the lazy list and
invokes the
.meta produce-item-expression
to force the first item.

The
.code gun
macro similarly creates a lazy list according to the following
rules. Each successive item of the lazy list is obtained as a result of
evaluating
.metn produce-item-expression .
However, when
.meta produce-item-expression
yields
.codn nil ,
then the list terminates (without adding that
.code nil
as an item).

Note 1: the form
.code gun
can be implemented as a macro-expanding to
an instance of the
.code gen
operator, like this:

.verb
  (defmacro gun (expr)
    (let ((var (gensym)))
      ^(let (,var)
         (gen (set ,var ,expr)
              ,var))))
.brev

This exploits the fact that the
.code set
operator returns the value that is
assigned, so the set expression is tested as a condition by
.codn gen ,
while having the side effect of storing the next item temporarily
in a hidden variable.

In turn,
.code gen
can be implemented as a macro expanding to some
.code lambda
functions which are passed to the
.code generate
function:

.verb
  (defmacro gen (while-expr produce-expr)
    ^(generate (lambda () ,while-expr)
               (lambda () ,produce-expr)))
.brev

Note 2:
.code gen
can be considered as an acronym for Generate, testing Expression
before Next item, whereas
.code gun
stands for Generate Until Null.

.TP* Example:

.verb
  ;; Make a lazy list of integers up to 1000
  ;; access and print the first three.
  (let* ((counter 0)
         (list (gen (< counter 1000) (inc counter))))
    (format t "~s ~s ~s\en" (pop list) (pop list) (pop list)))

  Output:
  1 2 3
.brev

.coNP Functions @ range and @ range*
.synb
.mets (range >> [ from >> [ to <> [ step ]]])
.mets (range* >> [ from >> [ to <> [ step ]]])
.syne
.desc
The
.code range
and
.code range*
functions generate a lazy sequence of integers, with a
fixed step between successive values.

The difference between
.code range
and
.code range*
is that
.code range*
excludes the endpoint.
For instance
.code "(range 0 3)"
generates the list
.codn "(0 1 2 3)" ,
whereas
.code "(range* 0 3)"
generates
.codn "(0 1 2)" .

All arguments are optional. If the
.meta step
argument is omitted, then it defaults
to
.codn 1 :
each value in the sequence is greater than the previous one by
.codn 1 .
Positive or negative step sizes are allowed. There is no check for a step size
of zero, or for a step direction which cannot meet the endpoint.

The
.meta to
argument specifies the endpoint value, which, if it occurs in the
sequence, is excluded from it by the
.code range*
function, but included by the range
function. If
.meta to
is missing, or specified as
.codn nil ,
then there is no endpoint,
and the sequence which is generated is infinite, regardless of
.metn step .

If
.meta from
is omitted, then the sequence begins at zero, otherwise
.meta from
must be an integer which specifies the initial value.

The sequence stops if it reaches the endpoint value (which is included in the
case of
.codn range ,
and excluded in the case of
.codn range *).
However, a sequence with a stepsize greater than
.code 1
or less than
.code -1
might step over the endpoint value, and
therefore never attain it. In this situation, the sequence also stops, and the
excess value which surpasses the endpoint is excluded from the sequence.

.coNP Functions @ rlist and @ rlist*
.synb
.mets (rlist << item *)
.mets (rlist* << item *)
.syne
.desc
The
.code rlist
("range list") function is useful for producing a list consisting of a mixture
of discontinuous numeric or character ranges and individual items.

The function returns a lazy list of elements. The items are produced
by converting the function's successive
.meta item
arguments into lists, which are lazily catenated together to form the
output list.

Each
.meta item
is transformed into a list as follows. Any item which is
.B not
a range object is trivially turned into a one-element list as if by the
.mono
.meti (list << item *)
.onom
expression.

Any item which is a range object, whose
.code to
field
.B isn't
a range is turned into a lazy list as if by evaluating the
.mono
.meti (range (from << item) (to << item))
.onom
expression. Thus for instance the argument
.code 1..10
turns into the (lazy) list
.codn "(1 2 3 4 5 6 7 8 9 10)" .

Any item which is a range object such that its
.code to
field is also a range is turned into a lazy  list as if by evaluating the
.mono
.meti (range (from << item) (from (to << item)) (to (to << item)))
.onom
expression. Thus for instance the argument expression
.code 1..10..2
produces an
.meta item
which
.code rlist
turns into the lazy list
.code "(1 3 5 7 9)"
as if by the call
.codn "(range 1 10 2)" .
Note that the expression
.code 1..10..2
stands for the expression
.code "(rcons 1 (rcons 10 2))"
which evaluates to
.codn "#R(1 #R(10 2))" .

The
.code "#R(1 #R(10 2))"
range literal syntax can be passed as an argument to
.code rlist
with the same result as
.codn 1..10..2 .

The
.code rlist*
function differs from
.code rlist
in one regard: under
.codn rlist* ,
the ranges denoted by the range notation exclude the endpoint. That is,
the ranges are generated as if by the
.code range*
function rather than
.codn range .

Note: it is permissible for
.meta item
objects to specify infinite ranges.
It is also permissible to apply an infinite argument list to
.codn rlist .

.TP* Examples:
.verb
  (rlist 1 "two" :three)  ->  (1 "two" :three)
  (rlist 10 15..16 #\ea..#\ed 2) -> (10 15 16 #\ea #\eb #\ec #\ed 2)
  (take 7 (rlist 1 2 5..:)) -> (1 2 5 6 7 8 9)
.brev

.SS* Ranges
Ranges are objects that aggregate two values, not unlike
.code cons
cells. However, they are atoms, and are primarily intended to hold numeric or
character values in their two fields. These fields are called
.code from
and
.code to
which are the names of the functions which access them. These fields
are not mutable; a new value cannot be stored into either field of
a range.

The printed notation for a range object consists of the prefix
.code #R
(hash R) followed by the two values expressed as a two-element
list.  Ranges can be constructed using the
.code rcons
function. The notation
.code x..y
corresponds to
.codn "(rcons x y)" .

Ranges behave as a numeric type and support a subset of the numeric
operations. Two ranges can be added or subtracted, which obeys
these equivalences:

.verb
  (+ a..b c..d)  <-->  (+ a c)..(+ b d)
  (- a..b c..d)  <-->  (- a c)..(- b d)
.brev

A range
.code a..b
can be combined with a character or number
.code n
using addition or subtractions, which obeys these equivalences:

.verb
  (+ a..b n)  <-->  (+ n a..b)  <-->  (+ a n)..(+ b n)
  (- a..b n)  <-->  (- a n)..(- b n)
  (- n a..b)  <-->  (- n a)..(- n b)
.brev

A range can be multiplied by a number:

.verb
  (* a..b n)  <-->  (* n a..b)  <-->  (* a n)..(* b n)
.brev

A range can be divided by a number using the
.code /
or
.code trunc
functions, but a number cannot be divided by a range:

.verb
  (trunc a..b n)  <-->  (trunc a n)..(trunc b n)
  (/ a..b n)      <-->  (/ a n)..(/ b n)
.brev

Ranges can be compared using the equality and inequality functions
.codn = ,
.codn < ,
.codn > ,
.code <=
and
.codn >= .
Equality obeys this equivalence:

.verb
  (= a..b c..d)  <-->  (and (= a c) (= b d))
.brev

Inequality comparisons treat the
.code from
component with precedence over
.code to
such that only if the
.code from
components of the two ranges are not equal under the
.code =
function, then the inequality is based solely on them.
If they are equal, then the inequality is based on the
.code to
components. This gives rise to the following equivalences:

.verb
  (< a..b c..d)   <-->  (if (= a c) (< b d) (< a c))
  (> a..b c..d)   <-->  (if (= a c) (> b d) (> a c))
  (>= a..b c..d)  <-->  (if (= a c) (>= b d) (> a c))
  (<= a..b c..d)  <-->  (if (= a c) (<= b d) (< a c))
.brev

Ranges can be negated with the one-argument form of the
.code -
function, which is equivalent to subtraction from zero:
the negation distributes over the two range components.

The
.code abs
function also applies to ranges and distributes into
their components.

The
.code succ
and
.code pred
family of functions also operate on ranges.

The length of a range may be obtained with the
.code length
function;

The length of the range
.code a..b
is defined as
.codn "(- b a)" ,
and may be obtained using the
.code length
function. The
.code empty
function accepts ranges and tests them for zero length.

.coNP Function @ rcons
.synb
.mets (rcons < from << to )
.syne
.desc
The
.code rcons
function constructs a range object which holds the values
.meta from
and
.metn to .

Though range objects are effectively binary cells like conses, they are atoms.
They also aren't considered sequences, nor are they structures.

Range objects are used for indicating numeric ranges, such as substrings of
lists, arrays and strings. The dotdot notation serves as a syntactic sugar for
.codn rcons .
The syntax
.code a..b
denotes the expression
.codn "(rcons a b)" .

Note that ranges are immutable, meaning that it is not possible to
replace the values in a range.

.coNP Function @ rangep
.synb
.mets (rangep << value )
.syne
.desc
The
.code rangep
function returns
.code t
if
.meta value
is a range. Otherwise it returns
.codn nil .

.coNP Functions @ from and @ to
.synb
.mets (from << range )
.mets (to << range )
.syne
.desc
The
.code from
and
.code to
functions retrieve, respectively, the from and to fields
of a range.

Note that these functions are not accessors, which is because
ranges are immutable.

.coNP Functions @ in-range and @ in-range*
.synb
.mets (in-range < range << value )
.mets (in-range* < range << value )
.syne
.desc
The
.code in-range
and
.code in-range*
functions test whether the
.meta value
argument lies in the range represented by the
.meta range
argument, indicating the Boolean result using one of the values
.code t
or
.codn nil .

The
.meta range
argument must be a range object.

It is expected that the range object's
.code from
value does not exceed the
.code to
value; a reversed range is considered empty.

The
.code in-range*
function differs from
.code in-range
in that it excludes the
upper endpoint.

The implicit comparison against the range endpoints is performed
using the
.code less
and
.code lequal
functions, as appropriate.

The following equivalences hold:

.verb
  (in-range r x)  <-->  (and (lequal (from r) x)
                             (lequal x (to r)))

  (in-range* r x)  <-->  (and (lequal (from r) x)
                              (less x (to r)))
.brev
.SS* Characters and Strings
.coNP Function @ mkstring
.synb
.mets (mkstring < length <> [ char ])
.syne
.desc
The
.code mkstring
function constructs a string object of a length specified
by the
.meta length
parameter.  Every position in the string is initialized
with
.metn char ,
which must be a character value.

If the optional argument
.meta char
is not specified, it defaults to the space character.

.coNP Function @ copy-str
.synb
.mets (copy-str << string )
.syne
.desc
The
.code copy-str
function constructs a new string whose contents are identical
to
.metn string .

If
.meta string
is a lazy string, then a lazy string is constructed with the
same attributes as
.metn string .
The new lazy string has its own copy of the prefix portion of
.meta string
which has been forced so far. The unforced list and separator
string are shared between
.meta string
and the newly constructed lazy string.

.coNP Function @ upcase-str
.synb
.mets (upcase-str << string )
.syne
.desc
The
.code upcase-str
function produces a copy of
.meta string
such that all lower-case
characters of the English alphabet are mapped to their upper case counterparts.

.coNP Function @ downcase-str
.synb
.mets (downcase-str << string )
.syne
.desc
The
.code downcase-str
function produces a copy of
.meta string
such that
all upper case characters of the English alphabet are mapped to their
lower case counterparts.

.coNP Function @ string-extend
.synb
.mets (string-extend < string << tail )
.syne
.desc
The
.code string-extend
function destructively increases the length of
.metn string ,
which must be an ordinary dynamic string.  It is an error to invoke this
function on a literal string or a lazy string.

The
.meta tail
argument can be a character, string or integer. If it is a string or
character, it specifies material which is to be added to the end of the string:
either a single character or a sequence of characters. If it is an integer, it
specifies the number of characters to be added to the string.

If
.meta tail
is an integer, the newly added characters have indeterminate contents.
The string appears to be the original one because of an internal terminating
null character remains in place, but the characters beyond the terminating zero
are indeterminate.

.coNP Function @ stringp
.synb
.mets (stringp << obj )
.syne
.desc
The
.code stringp
function returns t if
.meta obj
is one of the several
kinds of strings. Otherwise it returns
.codn nil .

.coNP Function @ length-str
.synb
.mets (length-str << string )
.syne
.desc
The
.code length-str
function returns the length
.meta string
in characters.  The argument must be a string.

.coNP Function @ coded-length
.synb
.mets (coded-length << string )
.syne
.desc
The
.code coded-length
function returns the number of bytes required to encode
.meta string
in UTF-8.

The argument must be a character string.

If the string contains only characters in the ASCII range U+0001 to U+007F
range, then the value returned shall be the same as that returned by the
.code length-str
function.

.coNP Function @ search-str
.synb
.mets (search-str < haystack < needle >> [ start <> [ from-end ]])
.syne
.desc
The
.code search-str
function finds an occurrence of the string
.meta needle
inside
the
.meta haystack
string and returns its position. If no such occurrence exists,
it returns
.codn nil .

If a
.meta start
argument is not specified, it defaults to zero. If it is
a non-negative integer, it specifies the starting character position for
the search.  Negative values of
.meta start
indicate positions from the end of the
string, such that
.code -1
is the last character of the string.

If the
.meta from-end
argument is specified and is not
.codn nil ,
it means
that the search is conducted right-to-left. If multiple matches are possible,
it will find the rightmost one rather than the leftmost one.

.coNP Function @ search-str-tree
.synb
.mets (search-str-tree < haystack < tree >> [ start <> [ from-end ]])
.syne
.desc
The
.code search-str-tree
function is similar to
.codn search-str ,
except that instead of
searching
.meta haystack
for the occurrence of a single needle string, it searches
for the occurrence of numerous strings at the same time.  These search strings
are specified, via the
.meta tree
argument, as an arbitrarily structured tree whose
leaves are strings.

The function finds the earliest possible match, in the given search direction,
from among all of the needle strings.

If
.meta tree
is a single string, the semantics is equivalent to
.codn search-str .

.coNP Function @ match-str
.synb
.mets (match-str < bigstring < littlestring <> [ start ])
.syne
.desc
Without the
.meta start
argument, the
.code match-str
function determines whether
.meta littlestring
is a prefix of
.metn bigstring ,
returning a
.code t
or
.code nil
indication.

If the
.meta start
argument is specified, and is a non-negative integer, then the
function tests whether
.meta littlestring
matches a prefix of that portion of
.meta bigstring
which starts at the given position.

If the
.meta start
argument is a negative integer, then
.code match-str
determines
whether
.meta littlestring
is a suffix of
.metn bigstring ,
ending on that position
of bigstring, where
.code -1
denotes the last character of
.metn bigstring ,
.code -2
the second last one and so on.

If
.meta start
is
.codn -1 ,
then this corresponds to testing whether
.meta littlestring
is a suffix of
.metn bigstring .

.coNP Function @ match-str-tree
.synb
.mets (match-str-tree < bigstring < tree <> [ start ])
.syne
.desc
The
.code match-str-tree
function is a generalization of match-str which matches
multiple test strings against
.meta bigstring
at the same time. The value
reported is the longest match from among any of the strings.

The strings are specified as an arbitrarily shaped tree structure which has
strings at the leaves.

If
.meta tree
is a single string atom, then the function behaves
exactly like match-str.

.coNP Accessor @ sub-str
.synb
.mets (sub-str < str >> [ from <> [ to ]])
.mets (set (sub-str < str >> [ from <> [ to ]]) << new-value )
.syne
.desc
The
.code sub-str
function has the same parameters and semantics as the
.code sub
function,
function, except that the first argument is operated upon
using string operations.

If a
.code sub-str
form is used as a place, it denotes a subrange of
.meta list
as if it were a storage location. The previous value of this location,
if needed, is fetched by a call to
.codn sub-str .
Storing
.meta new-value
to the place is performed by a call to
.codn replace-str .
In an update operation which accesses the prior value and stores a new value,
the arguments
.metn str ,
.metn from ,
.meta to
and
.meta new-value
are evaluated once.

The
.meta str
argument is not itself required to be a place; it is not updated
when a value is written to the
.code sub-str
storage location.

.coNP Function @ replace-str
.synb
.mets (replace-str < string < item-sequence >> [ from <> [ to ]])
.syne
.desc
The
.code replace-str
function has the same parameters and semantics as the
.code replace
function, except that the first argument is operated upon
using string operations.

.coNP Function @ cat-str
.synb
.mets (cat-str < string-list <> [ sep ])
.syne
.desc
The
.code cat-str
function catenates a list of strings given by
.meta string-list
into a
single string.  The optional
.meta sep
argument specifies a separator
which is interposed between the catenated strings.
It must be either a character or a string.

.coNP Function @ split-str
.synb
.mets (split-str < string < sep <> [ keep-between ])
.syne
.desc
The
.code split-str
function breaks the
.meta string
into pieces, returning a list
thereof. The
.meta sep
argument must be one of three types: a string, a character
or a regular expression. It determines the separator character
sequences within
.metn string .

All non-overlapping matches for
.meta sep
within
.meta string
are identified in left
to right order, and are removed from
.metn string .
The string is broken into pieces
according to the gaps left behind by the removed separators, and a list
of the remaining pieces is returned.

If
.meta sep
is the empty string, then the separator pieces removed from the
string are considered to be the empty strings between its
characters. In this case, if
.meta string
is of length one or zero, then it is considered to have no such pieces, and a
list of one element is returned containing the original string.
These remarks also apply to the situation when
.meta sep
is a regular expression which matches only an empty
substring of
.metn string .

If a match for
.meta sep
is not found in the string at all (not even an empty match), then the string is
not split at all: a list of one element is returned containing the original
string.

If
.meta sep
matches the entire string, then a list of two empty strings is
returned, except in the case that the original string is empty, in which case a
list of one element is returned, containing the empty string.

Whenever two adjacent matches for
.meta sep
occur, they are considered separate
cuts with an empty piece between them.

This operation is nondestructive:
.meta string
is not modified in any way.

If the optional
.meta keep-between
argument is specified and is not
.codn nil ,
If an argument is given and is true, then
.meta split-str
incorporates the matching separating pieces of
.meta string
into the resulting list, such that if the resulting
list is catenated, a string equivalent to the original
string will be produced.

Note: to split a string into pieces of length one such that an empty string
produces
.code nil
rather than
.codn ("") ,
use the
.mono
.meti (tok-str < string #/./)
.onom
pattern.

Note: the function call
.code "(split-str s r t)"
produces a resulting list identical to
.codn "(tok-str s r t)" ,
for all values of
.code r
and
.codn s ,
provided that
.code r
does not match empty strings. If
.code r
matches empty strings, then the
.code tok-str
call returns extra elements compared to
.codn split-str ,
because
.code tok-str
allows empty matches to take place and extract empty tokens
before the first character of the string, and after the
last character, whereas
.code split-str
does not recognize empty separators at these outer limits
of the string.

.coNP Function @ spl
.synb
.mets (spl < sep <> [ keep-between ] << string )
.syne
.desc
The
.code spl
function performs the same computation as
.codn split-str .
The same-named parameters of
.code spl
and
.code split-str
have the same semantics. The difference is the argument order.
The
.code spl
function takes the
.meta sep
argument first.
The last argument is always
.meta string
whether or not there are two arguments or three. If there are
three arguments, then
.meta keep-between
is the middle one.

Note: the argument conventions of
.code spl
facilitate less verbose partial application, such as with macros in the
.code op
family, in the common situation when
.meta string
is the unbound argument.

.coNP Functions @ split-str-set and @ sspl
.synb
.mets (split-str-set < string << set )
.mets (sspl < set << string )
.syne
.desc
The
.code split-str-set
function breaks the
.meta string
into pieces, returning a list
thereof. The
.meta set
argument must be a string. It specifies a set of
characters.  All occurrences of any of these characters within
.meta string
are
identified, and are removed from
.metn string .
The string is broken into pieces
according to the gaps left behind by the removed separators.

Adjacent occurrences of characters from
.meta set
within
.meta string
are considered to
be separate gaps which come between empty strings.

This operation is nondestructive:
.meta string
is not modified in any way.

The
.code sspl
function performs the same operation; the only difference between
.code sspl
and
.code split-str-set
is argument order.

.coNP Functions @ tok-str and @ tok-where
.synb
.mets (tok-str < string < regex <> [ keep-between ])
.mets (tok-where < string << regex )
.syne
.desc
The
.code tok-str
function searches
.meta string
for tokens, which are defined as
substrings of
.meta string
which match the regular expression
.meta regex
in the
longest possible way, and do not overlap. These tokens are extracted from the
string and returned as a list.

Whenever
.meta regex
matches an empty string, then an empty token is returned, and
the search for another token within
.meta string
resumes after advancing by one
character position. However, if an empty match occurs immediately
after a non-empty token, that empty match is not turned into
a token.

So for instance,
.mono
(tok-str "abc" #/a?/)
.onom
returns
.mono
("a" "" "").
.onom
After the token
.str "a"
is extracted from a non-empty match
for the regex, an empty match for the regex occurs just
before the character
.codn b .
This match is discarded because it is an empty match which
immediately follows the non-empty match. The character
.code b
is skipped. The next match is an empty match between the
.code b
and
.code c
characters. This match causes an empty token to be
extracted. The character
.code c
is skipped, and one more empty match occurs after that
character and is extracted.

If the
.meta keep-between
argument is specified, and is not
.codn nil ,
then the behavior
of
.code tok-str
changes in the following way. The pieces of
.meta string
which are
skipped by the search for tokens are included in the output. If no token is
found in
.metn string ,
then a list of one element is returned, containing
.metn string .
Generally, if N tokens are found, then the returned list consists of 2N + 1
elements. The first element of the list is the (possibly empty) substring which
had to be skipped to find the first token. Then the token follows. The next
element is the next skipped substring and so on. The last element is the
substring of
.meta string
between the last token and the end.

The
.code tok-where
function works similarly to
.codn tok-str ,
but instead of returning
the extracted tokens themselves, it returns a list of the character position
ranges within
.meta string
where matches for
.meta regex
occur. The ranges
are pairs of numbers, represented as cons cells, where the first number
of the pair gives the starting character position, and the second number
is one position past the end of the match.  If a match is empty, then the
two numbers are equal.

The tok-where function does not support the
.meta keep-between
parameter.

.coNP Function @ tok
.synb
.mets (tok < regex <> [ keep-between ] << string )
.syne
.desc
The
.code tok
function performs the same computation as
.codn tok-str .
The same-named parameters of
.code tok
and
.code tok-str
have the same semantics. The difference is the argument order.
The
.code tok
function takes the
.meta regex
argument first.
The last argument is always
.meta string
whether or not there are two arguments or three. If there are
three arguments, then
.meta keep-between
is the middle one.

Note: the argument conventions of
.code tok
facilitate less verbose partial application, such as  with macros in the
.code op
family, in the common situation when
.meta string
is the unbound argument.

.coNP Function @ list-str
.synb
.mets (list-str << string )
.syne
.desc
The
.code list-str
function converts a string into a list of characters.

.coNP Function @ trim-str
.synb
.mets (trim-str << string )
.syne
.desc
The
.code trim-str
function produces a copy of
.meta string
from which leading and
trailing tabs, spaces and newlines are removed.

.coNP Function @ chrp
.synb
.mets (chrp << obj )
.syne
.desc
Returns
.code t
if
.meta obj
is a character, otherwise nil.

.coNP Function @ chr-isalnum
.synb
.mets (chr-isalnum << char )
.syne
.desc
Returns
.code t
if
.meta char
is an alphanumeric character, otherwise nil. Alphanumeric
means one of the upper or lower case letters of the English alphabet found in
ASCII, or an ASCII digit. This function is not affected by locale.

.coNP Function @ chr-isalpha
.synb
.mets (chr-isalpha << char )
.syne
.desc
Returns
.code t
if
.meta char
is an alphabetic character, otherwise
.codn nil .
Alphabetic
means one of the upper or lower case letters of the English alphabet found in
ASCII. This function is not affected by locale.

.coNP Function @ chr-isascii
.synb
.mets (chr-isascii << char )
.syne
.desc
The
.code chr-isascii
function returns
.code t
if the code of character
.meta char
is in the range 0 to 127 inclusive. For characters outside of this range, it
returns
.codn nil .

.coNP Function @ chr-iscntrl
.synb
.mets (chr-iscntrl << char )
.syne
.desc
The
.code chr-iscntrl
function returns
.code t
if the character
.meta char
is a character whose code
ranges from 0 to 31, or is 127. In other words, any non-printable ASCII
character. For other characters, it returns
.codn nil .

.coNP Functions @ chr-isdigit and @ chr-digit
.synb
.mets (chr-isdigit << char )
.mets (chr-digit << char )
.syne
.desc
If
.meta char
is is an ASCII decimal digit character,
.code chr-isdigit
returns the value
.code t
and
.code chr-digit
returns the integer value corresponding to that digit character,
a value in the range 0 to 9.  Otherwise, both functions return
.codn nil .

.coNP Function @ chr-isgraph
.synb
.mets (chr-isgraph << char )
.syne
.desc
The
.code chr-isgraph
function returns
.code t
if
.meta char
is a non-space printable ASCII character.
It returns nil if it is a space or control character.

It also returns nil for non-ASCII characters: Unicode characters with a code
above 127.

.coNP Function @ chr-islower
.synb
.mets (chr-islower << char )
.syne
.desc
The
.code chr-islower
function returns
.code t
if
.meta char
is an ASCII lower case letter. Otherwise it returns
.codn nil .

.coNP Function @ chr-isprint
.synb
.mets (chr-isprint << char )
.syne
.desc
The
.code chr-isprint
function returns
.code t
if
.meta char
is an ASCII character which is not a
control character.  It also returns
.code nil
for all non-ASCII characters: Unicode
characters with a code above 127.

.coNP Function @ chr-ispunct
.synb
.mets (chr-ispunct << char )
.syne
.desc
The
.code chr-ispunct
function returns
.code t
if
.meta char
is an ASCII character which is not a
control character.  It also returns nil for all non-ASCII characters: Unicode
characters with a code above 127.

.coNP Function @ chr-isspace
.synb
.mets (chr-isspace << char )
.syne
.desc
The
.code chr-isspace
function returns
.code t
if
.meta char
is an ASCII whitespace character: any of the
characters in the set
.codn #\espace ,
.codn #\etab ,
.codn #\elinefeed ,
.codn #\enewline ,
.codn #\ereturn ,
.code #\evtab
and
.codn #\epage .
For all other characters, it returns
.codn nil .

.coNP Function @ chr-isblank
.synb
.mets (chr-isblank << char )
.syne
.desc
The
.code chr-isblank
function returns
.code t
if
.meta char
is a space or tab: the character
.code #\espace
or
.codn #\etab .
For all other characters, it returns
.codn nil .

.coNP Function @ chr-isunisp
.synb
.mets (chr-isunisp << char )
.syne
.desc
The
.code chr-isunisp
function returns
.code t
if
.meta char
is a Unicode whitespace character. This the case for
all the characters for which
.code chr-isspace
returns
.codn t .
It also returns
.code t
for these additional characters:
.codn #\exa0 ,
.codn #\ex1680 ,
.codn #\ex180e ,
.codn #\ex2000 ,
.codn #\ex2001 ,
.codn #\ex2002 ,
.codn #\ex2003 ,
.codn #\ex2004 ,
.codn #\ex2005 ,
.codn #\ex2006 ,
.codn #\ex2007 ,
.codn #\ex2008 ,
.codn #\ex2009 ,
.codn #\ex200a ,
.codn #\ex2028 ,
.codn #\ex2029 ,
.codn #\ex205f ,
and
.codn #\ex3000 .
For all other characters, it returns
.codn nil .

.coNP Function @ chr-isupper
.synb
.mets (chr-isupper < char )
.syne
.desc
The
.code chr-isupper
function returns
.code t
if
.meta char
is an ASCII upper case letter. Otherwise it returns
.codn nil .

.coNP Functions @ chr-isxdigit and @ chr-xdigit
.synb
.mets (chr-isxdigit << char )
.mets (chr-xdigit << char )
.syne
.desc
If
.meta char
is a hexadecimal digit character,
.code chr-isxdigit
returns the value
.code t
and
.code chr-xdigit
returns the integer value corresponding to that digit character,
a value in the range 0 to 15.  Otherwise, both functions returns
.codn nil .

A hexadecimal digit is one of the ASCII
digit characters
.code 0
through
.codn 9 ,
or else one of the letters
.code A
through
.code F
or their lower-case equivalents
.code a
through
.code f
denoting the values 10 to 15.

.coNP Function @ chr-toupper
.synb
.mets (chr-toupper << char )
.syne
.desc
If character
.meta char
is a lower case ASCII letter character, this function
returns the upper case equivalent character. If it is some other
character, then it just returns
.metn char .

.coNP Function @ chr-tolower
.synb
.mets (chr-tolower << char )
.syne
.desc
If character
.meta char
is an upper case ASCII letter character, this function
returns the lower case equivalent character. If it is some other
character, then it just returns
.metn char .

.coNP Functions @ int-chr and @ chr-int
.synb
.mets (int-chr << char )
.mets (chr-int << num )
.syne
.desc
The argument
.meta char
must be a character. The
.code num-chr
function returns that
character's Unicode code point value as an integer.

The argument
.meta num
must be a fixnum integer in the range
.code 0
to
.codn #\ex10FFFF .
The argument is taken to be a Unicode code point value and the
corresponding character object is returned.

Note: these functions are also known by the obsolescent names
.code num-chr
and
.codn chr-num .

.coNP Accessor @ chr-str
.synb
.mets (chr-str < str << idx )
.mets (set (chr-str < str << idx ) << new-value )
.syne
.desc
The
.code chr-str
function performs random access on string
.meta str
to retrieve
the character whose position is given by integer
.metn idx ,
which must
be within range of the string.

The index value 0 corresponds to the first (leftmost) character of the string
and so non-negative values up to one less than the length are possible.

Negative index values are also allowed, such that -1 corresponds to the
last (rightmost) character of the string, and so negative values down to
the additive inverse of the string length are possible.

An empty string cannot be indexed. A string of length one supports index 0 and
index -1. A string of length two is indexed left to right by the values 0 and
1, and from right to left by -1 and -2.

If the element
.meta idx
of string
.meta str
exists, and the string is modifiable, then the
.code chr-str
form denotes a place.

A
.code chr-str
place
supports deletion. When a deletion takes place,
then the character at
.meta idx
is removed from the string. Any characters
after that position move by one position
to close the gap, and the length of the string
decreases by one.

.TP* Notes:

Direct use of
.code chr-str
is equivalent to the DWIM bracket notation except
that
.code str
must be a string. The following relation holds:

.verb
  (chr-str s i) --> [s i]
.brev

since
.codn "[s i] <--> (ref s i)" ,
this also holds:

.verb
  (chr-str s i) --> (ref s i)
.brev

However, note the following difference. When the expression
.code "[s i]"
is used as a place, then the subexpression
.code s
must be a place. When
.code "(chr-str s i)"
is used as a place,
.code s
need not be a place.

.coNP Function @ chr-str-set
.synb
.mets (chr-str-set < str < idx << char )
.syne
.desc
The
.code chr-str
function performs random access on string
.meta str
to overwrite
the character whose position is given by integer
.metn idx ,
which must
be within range of the string. The character at
.meta idx
is overwritten
with character
.metn char .

The
.meta idx
argument works exactly as in
.codn chr-str .

The
.meta str
argument must be a modifiable string.

.TP* Notes:

Direct use of
.code chr-str
is equivalent to the DWIM bracket notation provided that
.meta str
is a string and
.meta idx
an integer. The following relation holds:

.verb
  (chr-str-set s i c) --> (set [s i] c)
.brev

Since
.code "(set [s i] c) <--> (refset s i c)"
for an integer index
.codn i ,
this also holds:

.verb
  (chr-str s i) --> (refset s i c)
.brev

.coNP Function @ span-str
.synb
.mets (span-str < str << set )
.syne
.desc
The
.code span-str
function determines the longest prefix of string
.meta str
which
consists only of the characters in string
.metn set ,
in any combination.

.coNP Function @ compl-span-str
.synb
.mets (compl-span-str < str << set )
.syne
.desc
The
.code compl-span-str
function determines the longest prefix of string
.meta str
which
consists only of the characters which do not appear in
.metn set ,
in any combination.

.coNP Function @ break-str
.synb
.mets (break-str < str << set )
.syne
.desc
The
.code break-str
function returns an integer which represents the position of the
first character in string
.meta str
which appears in string
.metn set .

If there is no such character, then
.code nil
is returned.

.SS* Lazy Strings
Lazy strings are objects that were developed for the \*(TX pattern matching
language, and are exposed via \*(TL. Lazy strings behave much like strings,
and can be substituted for strings. However, unlike regular strings, which
exist in their entirety, first to last character, from the moment they are
created, lazy strings do not exist all at once, but are created on demand.  If
character at index N of a lazy string is accessed, then characters 0 through N
of that string are forced into existence. However, characters at indices
beyond N need not necessarily exist.

A lazy string dynamically grows by acquiring new text from a list of strings
which is attached to that lazy string object.  When the lazy string is accessed
beyond the end of its hitherto materialized prefix, it takes enough strings
from the list in order to materialize the index. If the list doesn't have
enough material, then the access fails, just like an access beyond the end of a
regular string.  A lazy string always takes whole strings from the attached
list.

Lazy string growth is achieved via the
.code lazy-str-force-upto
function which
forces a string to exist up to a given character position. This function is
used internally to handle various situations.

The
.code lazy-str-force
function forces the entire string to materialize.  If the
string is connected to an infinite lazy list, this will exhaust all memory.

Lazy strings are specially recognized in many of the regular string functions,
which do the right thing with lazy strings. For instance when
.code sub-str
is invoked on a lazy string, a special version of the
.code sub-str
logic is
used which handles various lazy string cases, and can potentially return
another lazy string. Taking a
.code sub-str
of a lazy string from a given character position
to the end does not force the entire lazy string to exist,
and in fact the operation will work on a lazy string that is infinite.

Furthermore, special lazy string functions are provided which allow programs to
be written carefully to take better advantage of lazy strings. What carefully
means is code that avoids unnecessarily forcing the lazy string.  For instance,
in many situations it is necessary to obtain the length of a string, only to
test it for equality or inequality with some number. But it is not necessary to
compute the length of a string in order to know that it is greater than some
value.

.coNP Function @ lazy-str
.synb
.mets (lazy-str < string-list >> [ terminator <> [ limit-count ]])
.syne
.desc
The
.code lazy-str
function constructs a lazy string which draws material from
.meta string-list
which is a list of strings.

If the optional
.meta terminator
argument is given, then it specifies a string
which is appended to every string from
.metn string-list ,
before that string is
incorporated into the lazy string. If
.meta terminator
is not given,
then it defaults to the string
.strn "\en" ,
and so the strings from
.meta string-list
are effectively treated as lines which get terminated by newlines
as they accumulate into the growing prefix of the lazy string.
To avoid the use of a terminator string, a null string
.meta terminator
argument
must be explicitly passed. In that case, the lazy string grows simply
by catenating elements from
.metn string-list .

If the
.meta limit-count
argument is specified, it must be a positive integer.  It
expresses a maximum limit on how many elements will be consumed from
.meta string-list
in order to feed the lazy string. Once that many elements are
drawn, the string ends, even if the list has not been exhausted.

.coNP Function @ lazy-stringp
.synb
.mets (lazy-stringp << obj )
.syne
.desc
The
.code lazy-stringp
function returns
.code t
if
.meta obj
is a lazy
string. Otherwise it returns
.codn nil .

.coNP Function @ lazy-str-force-upto
.synb
.mets (lazy-str-force-upto < lazy-str << index )
.syne
.desc
The
.code lazy-str-force-upto
function tries to instantiate the lazy string such that
the position given by
.meta index
materializes. The
.meta index
is a character
position, exactly as used in the
.code chr-str
function.

Some positions beyond
.meta index
may also materialize, as a side effect.

If the string is already materialized through to at least
.metn index ,
or if it is
possible to materialize the string that far, then the value
.code t
is returned to indicate success.

If there is insufficient material to force the lazy string through to the
.meta index
position, then nil is returned.

It is an error if the
.meta lazy-str
argument isn't a lazy string.

.coNP Function @ lazy-str-force
.synb
.mets (lazy-str-force << lazy-str )
.syne
.desc
The
.meta lazy-str
argument must be a lazy string. The lazy string is forced
to fully materialize.

The return value is an ordinary, non-lazy string equivalent to the fully
materialized lazy string.

.coNP Function @ lazy-str-get-trailing-list
.synb
.mets (lazy-str-get-trailing-list < string << index )
.syne
.desc
The
.code lazy-str-get-trailing-list
function can be considered, in some way, an inverse operation to
the production of the lazy string from its associated list.

First,
.meta string
is forced up through the position
.metn index .
That is the only extent to which
.meta string
is modified by this function.

Next, the suffix of the materialized part of the lazy string starting at
position
.metn index ,
is split into pieces on occurrences of the
terminator character (which had been given as the
.meta terminator
argument in the
.code lazy-str
constructor, and defaults to newline).   If the
.meta index
position is beyond the part of the string which can be materialized
(in adherence with the lazy string's
.meta limit-count
constructor parameter), then the list of pieces is considered
to be empty.

Finally, a list is returned consisting of the pieces produced by the split,
to which is appended the remaining list of the string which has not yet been
forced to materialize.

.coNP Functions @, length-str-> @, length-str->= @ length-str-< and @ length-str-<=
.synb
.mets (length-str-> < string << len )
.mets (length-str->= < string << len )
.mets (length-str-< < string << len )
.mets (length-str-<= < string << len )
.syne
.desc
These functions compare the lengths of two strings. The following
equivalences hold, as far as the resulting value is concerned:

.verb
  (length-str-> s l) <--> (> (length-str s) l)
  (length-str->= s l) <--> (>= (length-str s) l)
  (length-str-< s l) <--> (< (length-str s) l)
  (length-str-<= s l) <--> (<= (length-str s) l)
.brev

The difference between the functions and the equivalent forms is that if the
string is lazy, the
.code length-str
function will fully force it in order to
calculate and return its length.

These functions only force a string up to position
.metn len ,
so they are not
only more efficient, but on infinitely long lazy strings they are usable.

.code length-str
cannot compute the length of a lazy string with an unbounded
length; it will exhaust all memory trying to force the string.

These functions can be used to test such as string whether it is longer
or shorter than a given length, without forcing the string beyond
that length.

.coNP Function @ cmp-str
.synb
.mets (cmp-str < left-string << right-string )
.syne
.desc
The
.code cmp-str
function returns -1 if
.meta left-string
is lexicographically prior to
.metn right-string .
If the reverse relationship holds, it returns 1.
Otherwise the strings are equal
and zero is returned.

If either or both of the strings are lazy, then they are only forced to the
minimum extent necessary for the function to reach a conclusion and return the
appropriate value, since there is no need to look beyond the first character
position in which they differ.

The lexicographic ordering is naive, based on the character code point
values in Unicode taken as integers, without regard for locale-specific
collation orders.

Note: in \*(TX 232 and earlier versions,
.code cmp-str
conforms to a weaker requirements: any negative integer value
may be returned rather than -1, and any positive integer value
can be returned instead of 1.

.coNP Functions @, str= @, str< @, str> @ str>= and @ str<=
.synb
.mets (str= < left-string << right-string )
.mets (str< < left-string << right-string )
.mets (str> < left-string << right-string )
.mets (str<= < left-string << right-string )
.mets (str>= < left-string << right-string )
.syne
.desc
These functions compare
.meta left-string
and
.meta right-string
lexicographically,
as if by the
.code cmp-str
function.

The
.code str=
function returns
.code t
if the two strings are exactly the same, character
for character, otherwise it returns
.codn nil .

The
.code str<
function returns
.code t
if
.meta left-string
is lexicographically before
.metn right-string ,
otherwise nil.

The
.code str>
function returns
.code t
if
.meta left-string
is lexicographically after
.metn right-string ,
otherwise
.codn nil .

The
.code str<
function returns
.code t
if
.meta left-string
is lexicographically before
.metn right-string ,
or if they are exactly the same, otherwise
.codn nil .

The
.code str<
function returns
.code t
if
.meta left-string
is lexicographically after
.metn right-string ,
or if they are exactly the same, otherwise
.codn nil .

.coNP Function @ string-lt
.synb
.mets (string-lt < left-str << right-str )
.syne
.desc
The
.code string-lt
is a deprecated alias for
.codn str< .

.SS* Vectors
.coNP Function @ vector
.synb
.mets (vector < length <> [ initval ])
.syne
.desc
The
.code vector
function creates and returns a vector object of the specified
length.  The elements of the vector are initialized to
.metn initval ,
or to nil if
.meta initval
is omitted.

.coNP Function @ vec
.synb
.mets (vec << arg *)
.syne
.desc
The
.code vec
function creates a vector out of its arguments.

.coNP Function @ vectorp
.synb
.mets (vectorp << obj )
.syne
.desc
The
.code vectorp
function returns t if
.meta obj
is a vector, otherwise it returns
.codn nil .

.coNP Function @ vec-set-length
.synb
.mets (vec-set-length < vec << len )
.syne
.desc
The
.code vec-set-length
modifies the length of
.metn vec ,
making it longer or
shorter. If the vector is made longer, then the newly added elements
are initialized to nil. The
.meta len
argument must be nonnegative.

The return value is
.metn vec .

.coNP Accessor @ vecref
.synb
.mets (vecref < vec << idx )
.mets (set (vecref < vec << idx ) << new-value )
.syne
.desc
The
.code vecref
function performs indexing into a vector. It retrieves
an element of
.meta vec
at position
.metn idx ,
counted from zero.
The
.meta idx
value must range from 0 to one less than the
length of the vector. The specified element is returned.

If the element
.meta idx
of vector
.meta vec
exists, then the
.code vecref
form denotes a place.

A
.code vecref
place
supports deletion. When a deletion takes place,
then if
.meta idx
denotes the last element in the vector, the
vector's length is decreased by one, so that
the vector no longer has that element.
Otherwise, if
.meta idx
isn't the last element, then each elements
values at a higher index than
.meta idx
shifts by one one element position to the
adjacent lower index. Then, the length of the
vector is decreased by one, so that the last
element position disappears.

.coNP Function @ vec-push
.synb
.mets (vec-push < vec << elem )
.syne
.desc
The
.code vec-push
function extends the length of a vector
.meta vec
by one element, and
sets the new element to the value
.metn elem .

The previous length of the vector (which is also the position of
.metn elem )
is returned.

.coNP Function @ length-vec
.synb
.mets (length-vec << vec )
.syne
.desc
The
.code length-vec
function returns the length of vector
.metn vec .
It performs
similarly to the generic
.code length
function, except that the argument must
be a vector.

.coNP Function @ size-vec
.synb
.mets (size-vec << vec )
.syne
.desc
The
.code size-vec
function returns the number of elements for which storage
is reserved in the vector
.metn vec .

.TP* Notes:

The
.code length
of the vector can be extended up to this size without any memory
allocation operations having to be performed.

.coNP Function @ vec-list
.synb
.mets (vec-list << list )
.syne
.desc
The
.code vec-list
function returns a vector which contains all of the same elements
and in the same order as list
.metn list .

Note: this function is also known by the obsolescent name
.codn vector-list .

.coNP Function @ list-vec
.synb
.mets (list-vec << vec )
.syne
.desc
The
.code list-vec
function returns a list of the elements of vector
.metn vec .

Note: this function is also known by the obsolescent name
.codn list-vector .

.coNP Function @ copy-vec
.synb
.mets (copy-vec << vec )
.syne
.desc
The
.code copy-vec
function returns a new vector object of the same length
as
.meta vec
and containing the same elements in the same order.

.coNP Accessor @ sub-vec
.synb
.mets (sub-vec < vec >> [ from <> [ to ]])
.mets (set (sub-vec < vec >> [ from <> [ to ]]) << new-value )
.syne
.desc
The
.code sub-vec
function has the same parameters and semantics as the
function
.codn sub ,
except that the
.meta vec
argument must be a vector.

If a
.code sub-vec
form is used as a place, it denotes a subrange of
.meta list
as if it were a storage location. The previous value of this location,
if needed, is fetched by a call to
.codn sub-vec .
Storing
.meta new-value
to the place is performed by a call to
.codn replace-vec .
In an update operation which accesses the prior value and stores a new value,
the arguments
.metn vec ,
.metn from ,
.meta to
and
.meta new-value
are evaluated once.

The
.meta vec
argument is not itself required to be a place; it is not updated
when a value is written to the
.code sub-vec
storage location.

.coNP Function @ replace-vec
.synb
.mets (replace-vec < vec < item-sequence >> [ from <> [ to ]])
.syne
.desc
The
.code replace-vec
is like the
.code replace
function except that the
.meta vec
argument must be a vector.

.coNP Function @ cat-vec
.synb
.mets (cat-vec << vec-list )
.syne
.desc
The
.meta vec-list
argument is a list of vectors. The
.code cat-vec
function
produces a catenation of the vectors listed in
.metn vec-list .
It returns
a single large vector formed by catenating those vectors together in
order.

.SS* Buffers

.coNP The @ buf type

Object of the type
.code buf
are
.IR buffers :
vector-like objects specialized for holding binary data represented as
a sequence of 8 bit bytes.  Buffers support operations specialized toward the
encoding of Lisp values into machine-oriented data types, and decoding such
data types into Lisp values.

Buffers are particularly useful in conjunction with the Foreign Function
Interface (FFI), since they can be used to prepare arbitrary data which
can be passed into and out of a function by pointer. They are also useful for
binary I/O.

.coNP Conventions Used by the @ buf-put- Functions

Buffers support a number of similar functions for converting Lisp numeric
values into common data types, which are placed into the buffer. These
functions are named starting with the
.code buf-put-
prefix, followed by an abbreviated type name.

Each of these functions takes three arguments:
.meta buf
specifies the buffer,
.meta pos
specifies the byte offset position into the buffer which receives
the low-order byte of the data transfer, and
.meta val
indicates the value.

If
.meta pos
has a value such that any portion of the data transfer would
like outside of the buffer, the buffer is automatically extended
in length to contain the data transfer. If this extension causes
any padding bytes to appear between the previous length of the
buffer and
.metn pos ,
those bytes are initialized to zero.

The argument
.meta val
giving the value to be stored must be an integer or character,
except in the case of the types
.meta float
and
.metn double (the
functions
.code buf-put-float
and
.codn buf-put-double )
for which it is required to be of type
.codn float ,
and in case of the function
.code buf-put-cptr
which expects the
.meta val
argument to be a
.code cptr
object.

The
.meta val
argument must be in range for the data type, or an exception
results.

Unless otherwise indicated, the stored datum is in the local format
used by the machine with regard to byte order and other representational
details.

.coNP Conventions Used by the @ buf-get- Functions

Buffers support a number of similar functions for extracting
common data types, and converting them into Lisp values.
These functions are named starting with the
.code buf-get-
prefix, followed by an abbreviated type name.

Each of these functions takes two arguments:
.meta buf
specifies the buffer and
.meta pos
specifies the byte offset position into the buffer which holds
the low-order byte of the datum to be extracted.

If any portion of requested datum lies outside of the boundaries
of the buffer, an error exception is thrown.

The extracted value is converted to a Lisp datum. For the
majority of these functions, the returned value is of type
integer. The
.code buf-get-float
and
.code buf-get-double
return a floating-point value.
The
.code buf-get-cptr
function returns a value of type
.codn cptr .

.coNP Function @ make-buf
.synb
.mets (make-buf < len >> [ init-val <> [ alloc-size ]])
.syne
.desc
The
.code make-buf
function creates a new buffer object which holds
.meta len
bytes. This argument may be zero.

If
.meta init-val
is present, it specifies the value with which the first
.meta len
byte of the buffer are initialized. If omitted, it
defaults to zero.
bytes. The value of
.meta init-val
must lie in the range 0 to 255.

The
.meta alloc-size
parameter indicates how much memory to actually allocate for
the buffer.
If an argument is not given, the parameter takes on
the same value as
.metn len .
If an argument is given, its value must not be less than
.metn len .

.coNP Function @ bufp
.synb
.mets (bufp << object )
.syne
.desc
The
.code bufp
function returns
.code t
if
.meta object
is a
.codn buf ,
otherwise it returns
.codn nil .

.coNP Function @ length-buf
.synb
.mets (length-buf << buf )
.syne
.desc
The
.code length-buf
function retrieves the buffer length: how many bytes are stored
in the buffer.

Note: the generic
.code length
function is also applicable to buffers.

.coNP Function @ buf-alloc-size
.synb
.mets (buf-alloc-size << buf )
.syne
.desc
The
.code buf-alloc-size
function retrieves the allocation size of the buffer.

.coNP Function @ buf-trim
.synb
.mets (buf-trim << buf )
.syne
.desc
The
.code buf-trim
function reduces the amount of memory allocated to the buffer
to the minimum required to hold it contents, effectively
setting the allocation size to the current length.

The previous allocation size is returned.

.coNP Function @ buf-set-length
.synb
.mets (buf-set-length < buf < len <> [ init-val ])
.syne
.desc
The
.code buf-set-length
function changes the length of the buffer. If the buffer
is made longer, the newly added bytes appear at the end,
and are initialized to the value given by
.metn init-val .
If
.meta init-val
is specified, its value must be in the range 0 to 255.
It defaults to zero.

.coNP Function @ copy-buf
.synb
.mets (copy-buf << buf )
.syne
.desc
The
.code copy-buf
function returns a duplicate of
.metn buf :
an object distinct from
.meta buf
which has the same length and contents, and compares
.code equal
to
.metn buf .

.coNP Accessor @ sub-buf
.synb
.mets (sub-buf < buf >> [ from <> [ to ]])
.mets (set (sub-buf < buf >> [ from <> [ to ]]) << new-val )
.syne
.desc
The
.code sub-buf
function has the same semantics as the
.code sub
function, except that the first argument must be a buffer.

The extracted sub-range of a buffer is itself a buffer object.

If
.code sub-buf
is used as a syntactic place, the argument expressions
.metn buf ,
.metn from ,
.meta to
and
.meta new-val
are evaluated just once. The prior value, if required, is accessed by calling
.code buf-sub
and
.meta new-val
is then stored via
.codn replace-buf .

.coNP Function @ replace-buf
.synb
.mets (replace-buf < buf < item-sequence >> [ from <> [ to ]])
.syne
.desc
The
.code replace-buf
function has the same semantics as the
.code replace
function, except that the first argument must be a buffer.

The elements of
.code item-sequence
are stored into
.meta buf
as if using the
.code buf-put-u8
function and therefore must be suitable
.meta val
arguments for that function.

The of the arguments, semantics and return value given for
.code replace
apply to
.codn replace-buf .

.coNP Function @ buf-list
.synb
.mets (buf-list << list )
.syne
.desc
The
.code buf-list
function creates and returns a new buffer, whose contents are derived from the
elements of
.metn list ,
which may be any kind of sequence.

The elements of
.meta list
must be integers whose values lie in the range 0 to 255, or else
characters whose code point values lie in that range.
These values are placed into the newly created buffer, which
therefore has the same length as
.metn list .

.coNP Function @ buf-put-buf
.synb
.mets (buf-put-buf < dst-buf < pos << src-buf )
.syne
.desc
The
.code buf-put-buf
function stores a copy of buffer
.meta src-buf
into
.meta dst-buf
at the offset indicated by
.metn pos .

The source and destination memory regions may overlap.

The return value is
.metn src-buf .

Note: the effect of a
.code buf-put-buf
operation may also be performed by a suitable call to
.codn replace-buf ;
however,
.code buf-put-buf
is less general: it doesn't insert or delete by replacing
destination ranges with data of differing length,
and requires a source operand of buffer type.

.coNP Function @ buf-put-i8
.synb
.mets (buf-put-i8 < buf < pos << val )
.syne
.desc
The
.code buf-put-i8
converts
.meta val
into an eight bit signed integer, and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

.coNP Function @ buf-put-u8
.synb
.mets (buf-put-u8 < buf < pos << val )
.syne
.desc
The
.code buf-put-u8
converts
.meta val
into an eight bit unsigned integer, and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

.coNP Function @ buf-put-i16
.synb
.mets (buf-put-i16 < buf < pos << val )
.syne
.desc
The
.code buf-put-i16
converts
.meta val
into a sixteen bit signed integer, and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

.coNP Function @ buf-put-u16
.synb
.mets (buf-put-u16 < buf < pos << val )
.syne
.desc
The
.code buf-put-u16
converts
.meta val
into a sixteen bit unsigned integer, and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

.coNP Function @ buf-put-i32
.synb
.mets (buf-put-i32 < buf < pos << val )
.syne
.desc
The
.code buf-put-i32
converts
.meta val
into a 32 bit signed integer, and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

.coNP Function @ buf-put-u32
.synb
.mets (buf-put-u32 < buf < pos << val )
.syne
.desc
The
.code buf-put-u32
converts
.meta val
into a 32 bit unsigned integer, and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

.coNP Function @ buf-put-i64
.synb
.mets (buf-put-i64 < buf < pos << val )
.syne
.desc
The
.code buf-put-i64
converts
.meta val
into a 64 bit signed integer, and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

.coNP Function @ buf-put-u64
.synb
.mets (buf-put-u64 < buf < pos << val )
.syne
.desc
The
.code buf-put-u64
converts the value
.meta val
into a 64 bit unsigned integer, and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

.coNP Function @ buf-put-char
.synb
.mets (buf-put-char < buf < pos << val )
.syne
.desc
The
.code buf-put-char
converts
.meta val
into a value of the C type
.code char
and stores it into the buffer at
the offset indicated by
.metn pos .

The return value is
.metn val .

Note that the
.code char
type may be signed or unsigned.

.coNP Function @ buf-put-uchar
.synb
.mets (buf-put-uchar < buf < pos << val )
.syne
.desc
The
.code buf-put-uchar
converts
.meta val
into a value of the C type
.code "unsigned char"
and stores it into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-put-short
.synb
.mets (buf-put-short < buf < pos << val )
.syne
.desc
The
.code buf-put-short
converts
.meta val
into a value of the C type
.code short
and stores it into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-put-ushort
.synb
.mets (buf-put-ushort < buf < pos << val )
.syne
.desc
The
.code buf-put-ushort
converts
.meta val
into a value of the C type
.code "unsigned short"
and stores it into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-put-int
.synb
.mets (buf-put-int < buf < pos << val )
.syne
.desc
The
.code buf-put-int
converts
.meta val
into a value of the C type
.code int
and stores it into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-put-uint
.synb
.mets (buf-put-uint < buf < pos << val )
.syne
.desc
The
.code buf-put-uint
converts
.meta val
into a value of the C type
.code "unsigned int"
and stores it into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-put-long
.synb
.mets (buf-put-long < buf < pos << val )
.syne
.desc
The
.code buf-put-long
converts
.meta val
into a value of the C type
.code long
and stores it into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-put-ulong
.synb
.mets (buf-put-ulong < buf < pos << val )
.syne
.desc
The
.code buf-put-ulong
converts
.meta val
into a value of the C type
.code "unsigned long"
and stores it into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-put-float
.synb
.mets (buf-put-float < buf < pos << val )
.syne
.desc
The
.code buf-put-float
converts
.meta val
into a value of the C type
.code float
and stores it into the buffer at
the offset indicated by
.metn pos .

Note: the conversion of a \*(TL floating-point value
to the C type float may be inexact, reducing the
numeric precision.

.coNP Function @ buf-put-double
.synb
.mets (buf-put-double < buf < pos << val )
.syne
.desc
The
.code buf-put-double
converts
.meta val
into a value of the C type
.code double
and stores it into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-put-cptr
.synb
.mets (buf-put-cptr < buf < pos << val )
.syne
.desc
The
.code buf-put-cptr
expects
.meta val
to be of type
.codn cptr .
It stores the object's pointer value into the buffer at
the offset indicated by
.metn pos .

.coNP Function @ buf-get-i8
.synb
.mets (buf-get-i8 < buf << pos )
.syne
.desc
The
.code buf-get-i8
function extracts and returns signed eight bit integer from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-u8
.synb
.mets (buf-get-u8 < buf << pos )
.syne
.desc
The
.code buf-get-u8
function extracts and returns an unsigned eight bit integer from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-i16
.synb
.mets (buf-get-i16 < buf << pos )
.syne
.desc
The
.code buf-get-i16
function extracts and returns a signed 16 bit integer  from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-u16
.synb
.mets (buf-get-u16 < buf << pos )
.syne
.desc
The
.code buf-get-u16
function extracts and returns an unsigned 16 bit integer  from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-i32
.synb
.mets (buf-get-i32 < buf << pos )
.syne
.desc
The
.code buf-get-i32
function extracts and returns a signed 32 bit integer  from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-u32
.synb
.mets (buf-get-u32 < buf << pos )
.syne
.desc
The
.code buf-get-u32
function extracts and returns an unsigned 32 bit integer  from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-i64
.synb
.mets (buf-get-i64 < buf << pos )
.syne
.desc
The
.code buf-get-i64
function extracts and returns a signed 64 bit integer  from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-u64
.synb
.mets (buf-get-u64 < buf << pos )
.syne
.desc
The
.code buf-get-u64
function extracts and returns an unsigned 64 bit integer  from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-char
.synb
.mets (buf-get-char < buf << pos )
.syne
.desc
The
.code buf-get-char
function extracts and returns a value of the C type
.code char
from
.meta buf
at the offset given by
.metn pos .
Note that
.code char
may be signed or unsigned.

.coNP Function @ buf-get-uchar
.synb
.mets (buf-get-uchar < buf << pos )
.syne
.desc
The
.code buf-get-uchar
function extracts and returns a value of the C type
.code "unsigned char"
from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-short
.synb
.mets (buf-get-short < buf << pos )
.syne
.desc
The
.code buf-get-short
function extracts and returns a value of the C type
.code short
from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-ushort
.synb
.mets (buf-get-ushort < buf << pos )
.syne
.desc
The
.code buf-get-ushort
function extracts and returns a value of the C type
.code "unsigned short"
from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-int
.synb
.mets (buf-get-int < buf << pos )
.syne
.desc
The
.code buf-get-int
function extracts and returns a value of the C type
.code int
from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-uint
.synb
.mets (buf-get-uint < buf << pos )
.syne
.desc
The
.code buf-get-uint
function extracts and returns a value of the C type
.code "unsigned int"
from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-long
.synb
.mets (buf-get-long < buf << pos )
.syne
.desc
The
.code buf-get-long
function extracts and returns a value of the C type
.code long
from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-ulong
.synb
.mets (buf-get-ulong < buf << pos )
.syne
.desc
The
.code buf-get-ulong
function extracts and returns a value of the C type
.code "unsigned long"
from
.meta buf
at the offset given by
.metn pos .

.coNP Function @ buf-get-float
.synb
.mets (buf-get-float < buf << pos )
.syne
.desc
The
.code buf-get-float
function extracts and returns a value of the C type
.code float
from
.meta buf
at the offset given by
.metn pos ,
returning that value as a Lisp floating-point number.

.coNP Function @ buf-get-double
.synb
.mets (buf-get-double < buf << pos )
.syne
.desc
The
.code buf-get-double
function extracts and returns a value of the C type
.code double
from
.meta buf
at the offset given by
.metn pos ,
returning that value as a Lisp floating-point number.

.coNP Function @ buf-get-cptr
.synb
.mets (buf-get-cptr < buf << pos )
.syne
.desc
The
.code buf-get-cptr
function extracts a C pointer from
.meta buf
at the offset given by
.metn pos ,
returning that value as a Lisp object of type
.codn cnum .

.coNP Function @ put-buf
.synb
.mets (put-buf < buf >> [ pos <> [ stream ]])
.syne
.desc
The
.code put-buf
function writes the contents of buffer
.metn buf ,
starting at position
.meta pos
to a stream, through to the last byte, if possible.
Successive bytes from the buffer are written to the stream as if by a
.code put-byte
operation.

If
.meta stream
is omitted, it defaults to
.codn *stdout* .

If
.meta pos
is omitted, it defaults to zero.
It indicates the starting position within the buffer.

The stream must support the
.code put-byte
operation. Streams which support
.code put-byte
can be expected to support
.code put-buf
and, conversely, streams which do not support
.code put-byte
do not support
.codn put-buf .

The
.code put-buf
function returns the position of the last byte that was successfully written.
If the buffer was written through to the end, then this value corresponds to
the length of the buffer.

If an error occurs before any bytes are written, the function
throws an error.

.coNP Functions @ fill-buf and @ fill-buf-adjust
.synb
.mets (fill-buf < buf >> [ pos <> [ stream ]])
.mets (fill-buf-adjust < buf >> [ pos <> [ stream ]])
.syne
.desc
The
.code fill-buf
reads bytes from
.meta stream
and writes them into consecutive locations in buffer
.meta buf
starting at position
.metn pos .
The bytes are read as if using the
.code get-byte
function.

If the
.meta stream
argument is omitted, it defaults to
.codn *stdin* .

If
.meta pos
is omitted, it defaults to zero.
It indicates the starting position within the buffer.

The stream must support the
.code get-byte
operation. Buffers which support
.code get-byte
can be expected to support
.code fill-buf
and, conversely, streams which do not support
.code get-byte
do not support
.codn fill-buf .

The
.code fill-buf
function returns the position that is one byte past the last byte that
was successfully read.
If an end-of-file or other error condition occurs before the buffer is filled
through to the end, then the value returned is smaller than the buffer length.
In this case, the area of the buffer beyond the read size retains its previous
content.

If an error situation occurs other than a premature end-of-file before
any bytes are read, then an exception is thrown.

If an end-of-file condition occurs before any bytes are read, then zero
is returned.

The
.code fill-buf-adjust
differs usefully from
.code fill-buf
as follows. Whereas
.code fill-buf
doesn't manipulate the length of the buffer at any stage of the operation, the
.code fill-buf-adjust
begins by adjusting the length of the buffer to the underlying allocated size.
Then it performs the fill operation in
exactly the same manner as
.codn fill-buf .
Finally, if the operation succeeds, then
.code fill-buf-adjust
adjusts the length of the buffer to match the position that is returned.

.coNP Function @ get-line-as-buf
.synb
.mets (get-line-as-buf <> [ stream ])
.syne
.desc
The
.code get-line-as-buf
reads bytes from
.meta stream
as if using the
.code get-byte
function, until either a the newline character is encountered, or else the end
of input is encountered. The bytes which are read, exclusive of the newline
character, are returned in a new buffer object.  The newline character, if it
occurs, is consumed.

If
.meta stream
is omitted, it defaults to
.codn *stdin* .

The stream is required to support byte input.

.coNP Functions @ file-get-buf and @ command-get-buf
.synb
.mets (file-get-buf < name >> [ max-bytes <> [ skip-bytes ]])
.mets (command-get-buf < cmd >> [ max-bytes <> [ skip-bytes ]])
.syne
.desc
The
.code file-get-buf
function opens a binary stream over the file indicated by the string argument
.meta name
for reading. By default, the entire file is read and its contents are returned as a
buffer object. The buffer's length corresponds to the number of bytes
read from the file.

The
.code command-get
function opens a binary stream over an input command pipe created for
the command string
.metn cmd ,
as if by the
.code open-command
function.  It read bytes from the pipe until the indication that no more
input is available. The bytes are returned aggregated into a buffer object.

If the
.meta max-bytes
parameter is given an argument, it must be a non-negative integer.
That value specifies a limit on the number of bytes to read. A buffer
no longer than
.meta max-bytes
shall be returned.

If the
.meta skip-bytes
parameter is given an argument, it must be a non-negative integer.
That value specifies how many initial bytes of the input should be
discarded before accumulation of the buffer begins.
If possible, the semantics of this parameter is achieved by performing a
.code seek-stream
operation, falling back on reading and discarding bytes if the
stream doesn't support seeking.

.coNP Functions @, file-put-buf @ file-append-buf and @ command-put-buf
.synb
.mets (file-put-buf < name < buf << skip-bytes )
.mets (file-place-buf < name < buf << skip-bytes )
.mets (file-append-buf < name << buf )
.mets (command-put-buf < cmd << buf )
.syne
.desc
The
.code file-put-buf
function opens a text stream over the file indicated by the string argument
.metn name ,
writes the contents of the buffer object
.meta buf
into the file, and then closes the file.  If the file doesn't exist, it is
created.  If it exists, it is truncated to zero length and overwritten.
The default value of the optional
.meta skip-bytes
parameter is zero. If an argument is given, it must be a non-negative integer.
If it is nonzero, then after opening the file, before writing the buffer,
the function will seek to an offset of that many bytes from the start of the
file. The contents of
.meta buf
will be written at that offset.

The
.code file-place-buf
function does not truncate an existing file to zero length.
In all other regards, it is equivalent to
.codn file-put-buf .

The
.code file-append-buf
function is similar to
.code file-put-buf
except that if the file exists, it isn't overwritten. Rather, the buffer
is appended to the file.

The
.code command-put-buf
function opens an output text stream over an output command pipe created
for the command specified in the string argument
.metn cmd ,
as if by the
.code open-command
function.
It then writes the contents of buffer
.meta buf
into the stream and closes the stream.

The return value of all three functions is that of the
.code put-buf
operation which is implicitly performed.

.coNP Functions @ buf-str and @ str-buf
.synb
.mets (buf-str < buf <> [ null-term-p ])
.mets (str-buf < str <> [ null-term-p ])
.syne
.desc
The
.code buf-str
and
.code str-buf
functions perform UTF-8 conversion between the buffer and character string
data types.

The
.code buf-str
function takes the contents of buffer
.meta buf
to be UTF-8 data, which is converted to a character string and returned.
Null bytes in the buffer are mapped to the pseudo-null character
.codn #\exDC00 .
If a true argument is given to the
.meta null-term-p
parameter, then if the contents of
.meta buf
end in a null byte, that byte is not included in the conversion.

The
.code str-buf
function UTF-8-encodes
.meta str
and returns a buffer containing the converted representation.
If a true argument is given to the
.meta null-term-p
parameter, then a null terminating byte is added to the buffer.
This byte is added even if the previous byte is already a null byte
from the conversion of a pseudo-null character occurring in
.metn str .

.coNP Functions @ buf-int and @ buf-uint
.synb
.mets (buf-int < integer )
.mets (buf-uint < integer )
.syne
.desc
The
.code buf-int
and
.code buf-uint
functions convert a signed and unsigned integer, respectively, or else a
character, into a binary representation, which is returned as a buffer object.

Under both functions, the representation uses big endian byte order: most
significant byte first.

The
.code buf-uint
function requires a non-negative
.meta integer
argument, which may be a character. The representation stored in the
buffer is a pure binary representation of the value using the smallest
number of bytes required for the given
.meta integer
value.

The
.code buf-int
function requires an integer or character argument. The representation
stored in the buffer is a two's complement representation of
.meta integer
using the smallest number of bytes which can represent that value.
If
.meta integer
is non-negative, then the first byte of the buffer lies in the range
0 to 127.
If
.meta integer
is negative, then the first byte of the buffer lies in the range 128 to 255.
The integer 255 therefore doesn't convert to the buffer
.code #b'ff'
but rather
.codn #b'00ff' .
The buffer
.code #b'ff'
represents -1.

If the
.meta integer
argument is a character object, it is taken to be its Unicode code
point value, as returned by the
.code int-chr
function.

.coNP Functions @ int-buf and @ uint-buf
.synb
.mets (int-buf < buf )
.mets (uint-buf < buf )
.syne
.desc
The
.code int-buf
and
.code uint-buf
functions recover an integer value from its binary form which appears
inside
.metn buf ,
which must be a buffer object. These functions expect
.meta buf
to contain the representation produced by, respectively, the functions
.code buf-int
and
.codn buf-uint .

If
.meta buf
holds the representation of an integer value
.metn n ,
as produced by
.mono
.meti (buf-int << n )
.onom
then
.mono
.meti (int-buf << buf )
.onom
returns
.metn n .

The same relationship holds between
.code buf-uint
and
.codn uint-buf .

Thus, these equalities hold:

.verb
.mets (= (int-buf (buf-int << n )) << n )
.mets (= (uint-buf (buf-uint << n )) << n )
.brev

provided that
.meta n
is of integer type and, in the case of
.codn buf-uint ,
nonnegative.

.SS* Structures

\*(TX supports application-defined types in the form of structures. Structures
are objects which hold multiple storage locations called slots, which are named
by symbols.  Structures can be related to each other by inheritance. Multiple
inheritance is permitted.

The type of a structure is itself an object, of type
.codn struct-type .

When the program defines a new structure type, it does so by creating a new
.code struct-type
instance, with properties which describe the new structure type: its
name, its list of slots, its initialization and "boa constructor" functions,
and the structures type it inherits from (the
.IR supertypes ).

The
.code struct-type
object is then used to generate instances.

Structures instances are not only containers which hold named slots, but they
also indicate their struct type. Two structures which have the same number of
slots having the same names are not necessarily of the same type.

Structure types and structures may be created and manipulated using
a programming interface based on functions.

For more convenient and clutter-free expression of structure-based
program code, macros are also provided.

Furthermore, concise and expressive slot access syntax is provided courtesy of
the referencing dot and unbound referencing dot syntax, a syntactic sugar
for the
.code qref
and
.code uref
macros.

Structure types have a name, which is a symbol. The
.code typeof
function, when applied to any struct type, returns the symbol
.codn struct-type .
When
.code typeof
is applied to a struct instance, it returns the name of
the struct type. Effectively, struct names are types.

The consequences are unspecified if an existing struct name is re-used for a
different struct type, or an existing type name is used for a struct type.

.NP* Static Slots

Structure slots can be of two kinds: they can be the ordinary instance slots or
they can be static slots.  The instances of a given structure type have their
own instance of a given instance slot. However, they all share a single
instance of a static slot.

Static slots are allocated in a global area associated with a structure type
and are initialized when the structure type is created. They are useful for
efficiently representing properties which have the same value for all instances
of a struct. These properties don't have to occupy space in each instance, and
time doesn't have to be wasted initializing them each time a new instance is
created.  Static slots are also useful for struct-specific global variables.
Lastly, static slots are also useful for holding methods and functions.
Although structures can have methods and functions in their instances, usually,
all structures of the same type share the same functions. The
.code defstruct
macro supports a special syntax for defining methods and struct-specific
functions at the same time when a new structure type is defined.
The
.code defmeth
macro can be used for adding new methods and functions to an existing
structure and its descendants.

Static slots may be assigned just like instance slots. Changing a static
slot changes that slot in every structure of the same type.

Static slots are not listed in the
.code #S(...)
notation when a structure is printed. When the structure notation is
read from a stream, if static slots are present, they will be processed
and their values stored in the static locations they represent, thus
changing their values for all instances.

Static slots are inherited just like instance slots. The following
simplified discussion is restricted to single inheritance. A detailed
description of multiple inheritance is given in the Multiple Inheritance
section below.  If a given structure
.meta B
has some static slot
.metn s ,
and a new structure
.meta D
is derived from
.metn B ,
using
.codn defstruct ,
and does not define a slot
.metn s ,
then
.meta D
inherits
.metn s .
This means that
.meta D
shares the static slot with
.metn B :
both types share a single instance of that slot.

On the other hand if
.code D
defines a static slot
.meta s
then that slot will have its own instance in the
.meta D
structure type;
.meta D
will not inherit the
.meta B
instance of slot
.metn s .
Moreover, if the the definition of
.code D
omits the
.meta init-form
for slot
.metn s ,
then that slot will be initialized with a copy of the current value of slot
.meta s
of the
.meta B
base type, which allows derived types to obtain the value of base type's
static slot, yet have that in their own instance.

The slot type can be overridden. A structure type deriving from another
type can introduce slots which have the same names as the supertype,
but are of a different kind: an instance slot in the supertype
can be replaced by a static slot in the derived type or
.IR "vice versa" .

Note that, in light of the above type overriding possibility, the static slot
value propagation happens only from the immediate supertype.
If
.code D
is is derived from
.code G
which has a static slot
.codn s ,
whereas
.code D
specifies
.code s
as an instance slot, but then
.code B
again specifies a static slot
.codn s ,
then
.codn B 's
slot
.code s
will not inherit the value from
.codn G 's
.code s
slot.
Simply,
.codn B 's
supertype is
.code D
and that supertype is not considered to have a static slot
.codn s .

A structure type is associated with a static initialization function
which may be used to store initial values into static slots. This function
is invoked once in a type's life time, when the type is created.
The function is also inherited by derived struct types and invoked when
they are created.

.NP* Multiple Inheritance
When a structure type is defined, two or more supertypes may be specified.  The
new structure type then potentially inherits instance and static slots from all
of the specified supertypes, and is considered to be a subtype of all of them.
This situation with two or more supertypes is called
.IR "multiple inheritance" .
The contrasting term is
.IR "single inheritance" ,
denoting the situation when a structure has exactly one supertype.
\*(TL's struct types initially permitted only single inheritance.
Multiple inheritance support was introduced in version 229, as a
straightforward extension of single inheritance semantics.

In the
.code make-struct-type
function and
.code defstruct
macro, a list of supertypes can be given instead of just one.
The type then inherits slots from all of the specified types.
If any conflicts arise among the supertypes due to slots having the same name,
the leftmost supertype dominates: that type's slot will be inherited.
If the leftmost slot is static, then that static slot will be inherited.
Otherwise, the instance slot will be inherited.

Of course, any slot which is specified in the newly defined type itself
dominates over any same-named slots among the supertypes.

The new structure type inherits all of the slot initializing expressions, as
well as
.code :init
and
.code :postinit
methods of all of its supertypes.

Each time the structure is instantiated, the
.code :init
initializing expressions inherited from the supertypes, together with the slot
initializing expressions, are all evaluated, in right-to-left order:
the initializations contributed by each supertype are performed before
considering the next supertype to the left.
The
.code :postinit
methods are similarly invoked in right-to-left order, before the
.code :postinit
methods of the new type itself.
Thus the order is: supertype inits, own inits, supertype post-inits,
own post-inits.

.NP* Duplicate Supertypes
Multiple inheritance makes it possible for a type to inherit the
same supertype more than once, either directly (by naming it more than
once as a direct supertype) or indirectly (by inheriting two or
more different types, which have a common ancestor).
The latter situation is sometimes referred to as the
.IR "diamond problem" .

Until \*(TX 242, the situation of duplicate supertypes was
ignored for the purposes of object initialization. It was documented that if a
supertype is referenced by inheritance, directly or indirectly, two or more
times, then its initializing expressions are evaluated that many times.

Starting in \*(TX 243, duplicate supertypes no longer give rise to duplicate
initialization. When an object is instantiated, only one initialization of a
duplicated supertype occurs. The subsequent initializations that would take
place in the absence of duplicate detection are suppressed.

Note also that the
.code :fini
mechanism is tied to initialization. Initialization of an object
registers the finalizers, and so in \*(TX 242,
.code :fini
finalizers are also executed multiple times, if
.code :init
initializers are.

.TP* Examples:

Consider following program:

.verb
  (defstruct base ()
    (:init (me) (put-line "base init"))
    (:fini (me) (put-line "base fini")))

  (defstruct d1 (base)
    (:init (me) (put-line "d1 init"))
    (:fini (me) (put-line "d1 fini")))

  (defstruct d2 (base)
    (:init (me) (put-line "d2 init"))
    (:fini (me) (put-line "d2 fini")))

  (defstruct s (d1 d2))

  (call-finalizers (new s))
.brev

Under \*(TX 242, and earlier versions that support multiple inheritance, it
produces the output:

.verb
  base init
  d2 init
  base init
  d1 init
  d1 fini
  base fini
  d2 fini
  base fini
.brev

The supertypes are initialized in a right-to-left traversal of the
type lattice, without regard for
.code base
being duplicated.

Starting with \*(TX 243, the output is:

.verb
  base init
  d2 init
  d1 init
  d1 fini
  d2 fini
  base fini
.brev

The rightmost duplicate of the base is initialized, so that the initialization
is complete prior to the initializations of any dependent types.
Likewise, the same rightmost duplicate of the base is finalized, so that
finalization takes place after that of any dependent struct types.

Note, however, that the
.code derived
function function mechanism is not required to detect duplicated direct
supertypes.
If a supertype implements the
.code derived
function to detect situations when it is the target of inheritance,
and some subtype inherits that type more than once, that function
may be called more than once. The behavior is unspecified.

.NP* Dirty Flags
All structure instances contain a Boolean flag called the
.IR "dirty flag" .
This flag is not a slot, but rather a meta-data property that is exposed
to program access. When the flag is set, an object is said to be dirty;
otherwise it is clean.

Newly constructed objects come into existence dirty. The dirty flag
state can be tested with the function
.codn test-dirty .
An object can be marked as clean by clearing its dirty flag with
.codn clear-dirty .
A combined operation
.code test-clear-dirty
is provided which clears the dirty flag, and
returns its previous value.

The dirty flag is set whenever a new value is stored into the instance
slot of an object.

Note: the dirty flag can be used to support support the caching of values
derived from an object's slots. The derived values don't have to be
re-computed while an object remains clean.

.NP* Equality Substitution

In object-based or object-oriented programming, sometimes it is necessary for a
new data type to provide its own notion of equality: its own requirements for
when two distinct instances of the type are considered equal. Furthermore,
types sometimes have to implement their own notion, also, of inequality: the
requirements for the manner in which one instance is considered lesser or
greater than another.

\*(TL structures implement a concept called
.IR "equality substitution"
which provides a simple, unified way for the implementor of an object to
encode the requirements for both equality and inequality.
Equality substitution allows for objects to be used as keys in a hash
table according to the custom equality, without the programmer being
burdened with the responsibility of developing a custom hashing function.

An object participates in equality substitution by implementing the
.code equal
method. The
.code equal
method takes no arguments other than the object itself. It returns
a representative value which is used in place of that object
for the purposes of
.code equal
comparison.

Whenever an object which supports equality substitution is used as an argument
of any of the functions
.codn equal ,
.codn nequal ,
.codn greater ,
.codn less ,
.codn gequal ,
.code lequal
or
.codn hash-equal ,
the
.code equal
method of that object is invoked, and the return value of that method
is taken in place of that object.

The same is true if an object which supports equality substitution is used as a
key in an
.code :equal-based
hash table.

The substitution is applied repeatedly: if the return value of the object's
.code equal
method is an object which itself supports equality substitution,
than that returned object's method is invoked on that object
to fetch its equality substitute. This repeats as many times as necessary
until an object is determined which isn't a structure that supports
equality substitution.

Once the equality substitute is determined, then the given function proceeds
with the replacement object. Thus for example
.code equal
compares the replacement object in place of the original, and an
.code :equal-based
hash table uses the replacement object as the key for the purposes of
hashing and comparison.

.coNP Macro @ defstruct
.synb
.mets (defstruct >> { name | >> ( name << arg *)} < super
.mets \ \  << slot-specifier *)
.syne
.desc
The
.code defstruct
macro defines a new structure type and registers it under
.metn name ,
which must be a bindable symbol, according to the
.code bindable
function. Likewise, the name of every
.meta slot
must also be a bindable symbol.

The
.meta super
argument must either be
.codn nil ,
or a symbol which names an existing struct type,
or else a list of such symbols.
The newly defined struct type will inherit all slots,
as well as initialization behaviors from the specified
struct types.

The
.code defstruct
macro is implemented using the
.code make-struct-type
function, which is more general. The macro analyzes the
.code defstruct
argument syntax, and synthesizes arguments which are then
used to call the function. Some remarks in the description of
.code defstruct
only apply to structure types defined using that macro.

Slots are specified using zero or more
.IR "slot specifiers" .
Slot specifiers come in the following variety:
.RS
.meIP < name
The simplest slot specifier is just a name, which must be a bindable
symbol, as defined by the
.code bindable
function. This form is a short form for the
.mono
.meti (:instance << name )
.onom
syntax.
.meIP >> ( name << init-form )
This syntax is a short form for the
.mono
.meti (:instance < name << init-form )
.onom
syntax.
.meIP (:instance < name <> [ init-form ])
This syntax specifies an instance slot called
.meta name
whose initial value is obtained by evaluating
.meta init-form
whenever a new instance of the structure is created.
This evaluation takes place in the original lexical environment in which the
.code defstruct
form occurs. If
.meta init-form
is omitted, the slot is initialized to
.codn nil .
.meIP (:static < name <> [ init-form ])
This syntax specifies a static slot called
.meta name
whose initial value is obtained by evaluating
.meta init-form
once, during the evaluation of the
.code defstruct
form in which it occurs, if the
.meta init-form
is present. If
.meta init-form
is absent, and a static slot with the same name
exists in the
.meta super
base type, then this slot is initialized
with the value of that slot.
Otherwise it is initialized to
.codn nil .

The definition of a static slot in a
.code defstruct
causes the new type to have its own instance
that slot, even if a same-named static
slot occurs in the
.meta super
base type, or its bases.
.meIP (:method < name <> ( param +) << body-form *)
This syntax creates a static slot called
.meta name
which is initialized with an anonymous function.
The anonymous function is created during the
evaluation of the
.code defstruct
form. The function takes the arguments specified
by the
.meta param
symbols, and its body consists of the
.metn body-form -s.
There must be at least one
.metn param .
When the function is invoked as a method, as intended,
the leftmost
.meta param
receives the structure instance.
The
.metn body-form -s
are evaluated in a context in which a block named
.meta name
is visible. Consequently,
.code return-from
may be used to terminate the execution of a method
and return a value.
Methods are invoked
using the
.code "instance.(name arg ...)"
syntax, which implicitly inserts the instance into the argument list.

Due to the semantics of static slots, methods are naturally
inherited from a base structure to a derived one,
and defining a method in a derived class which also exists
in a base class performs OOP-style overriding.
.meIP (:function < name <> ( param *) << body-form *)
This syntax creates a static slot called
.meta name
which is initialized with an anonymous function.
The anonymous function is created during the
evaluation of the
.code defstruct
form. The function takes the arguments specified
by the
.meta param
symbols, and its body consists of the
.metn body-form -s.
This specifier differs from
.code :method
only in one respect: there may be zero
parameters. A structure function defined this way is
intended to be used as a utility function which doesn't
receive the structure instance as an argument.
The
.metn body-form -s
are evaluated in a context in which a block named
.meta name
is visible. Consequently,
.code return-from
may be used to terminate the execution of the function
and return a value.
Such functions are called using the
.code "instance.[name arg ...]"
syntax which doesn't insert the instance into
the argument list.

The remarks about inheritance and overriding
in the description of
.code :method
also apply to
.codn :function .
.meIP (:init <> ( param ) << body-form *)
The
.code :init
specifier doesn't describe a slot. Rather, it specifies code
which is executed when a structure is instantiated, before
the slot initializations specific to the structure type
are performed. The code consists of
.metn body-form -s
which are evaluated in order in a lexical scope in
which the variable
.meta param
is bound to the structure object.

The
.code :init
specifier may not appear more than once in a given
.code defstruct
form.

When an object with one or more levels of inheritance
is instantiated, the
.code :init
code of a base structure type, if any, is executed
before any initializations specific to a derived
structure type. Under multiple inheritance, the
.code :init
code of the rightmost base type is executed first,
then that of the remaining bases in right-to-left
order.

The
.code :init
initializations are executed before any other
slot initializations. The argument values passed to the
.code new
or
.code lnew
operator or the
.code make-struct
function are not yet stored in the object's slots,
and are not accessible. Initialization code which needs
these values to be stable can be defined with
.codn :postinit .

Initializers in base structures must be careful about assumptions about slot
kinds, because derived structures can alter static slots to instance slots or
.IR "vice versa" .
To avoid an unwanted initialization being applied to the
wrong kind of slot, initialization code can be made conditional on the
outcome of
.code static-slot-p
applied to the slot.
(Code generated by
.code defstruct
for initializing instance slots performs this kind of check).

The
.metn body-form -s
of an
.code :init
specifier are not surrounded by an implicit
.codn block .
.meIP (:postinit <> ( param ) << body-form *)
The
.code :postinit
specifier is similar to
.codn :init .
Both specify forms which are evaluated during object instantiation.
The difference is that the
.codn body-form -s
of a
.code :postinit
are evaluated after other initializations have taken
place, including the
.code :init
initializations, as a second pass. By the time
.code :postinit
initialization runs, the argument material from the
.codn make-struct ,
.code new
or
.code lnew
invocation has already been processed and stored
into slots.
Like
.code :init
actions,
.code :postinit
actions registered at different levels of the type's
inheritance hierarchy are invoked in the base-to-derived
order, and in right-to-left order among multiple bases
at the same level.
.meIP (:fini <> ( param ) << body-form *)
The
.code :fini
specifier doesn't describe a slot. Rather, it specifies
a finalization function which is associated with the
structure instance, as if by use of the
.code finalize
function. This finalization registration takes place
as the first step when an instance of the structure
is created, before the slots are initialized and
the
.code :init
code, if any, has been executed. The registration
takes place as if by the evaluation of the form
.mono
.meti (finalize < obj (lambda <> ( param ) << body-form ...) t)
.onom
where
.meta obj
denotes the structure instance. Note the
.code t
argument which requests reverse order of registration, ensuring that if an
object has multiple finalizers registered at different levels of inheritance
hierarchy, the finalizers specified for a derived structure type are called
before inherited finalizers.

The
.metn body-form -s
of a
.code :fini
specifier are not surrounded by an implicit
.codn block .

Note that an object's finalizers can be called explicitly with
.codn call-finalizers .
.RE
.IP
The
.code with-objects
macro arranges for finalizers to be called on objects when the execution
of a scope terminates by any means.

The slot names given in a
.code defstruct
must all be unique among themselves, but they
may match the names of existing slots in the
.meta super
base type.

A given structure type can have only one slot under a given
symbolic name.  If a newly specified  slot matches the name of an existing slot
in the
.meta super
type or that type's chain of ancestors, it is called a
.IR "repeated slot" .

The kind of the repeated slot (static or instance) is not inherited; it
is established by the
.code defstruct
and may be different from the type of the same-named slot in the
supertype or its ancestors.

If a repeated slot is introduced as a static slot, and
has no
.meta init-form
then it receives the current of the a static of the same name from
the nearest supertype which has such a slot.

If a repeated slot is an instance slot, no such inheritance of value
takes place; only the local
.meta init-form
applies to it; if it is absent, the slot it initialized to
.code nil
in each newly created instance of the new type.

However,
.code :init
and
.code :postinit
initializations are inherited from a base type and they apply to
the repeated slots, regardless of their kind.  These initializations
take place on the instantiated object, and the slot references
resolve accordingly.

The initialization for slots which are specified using the
.code :method
or
.code :function
specifiers is re-ordered with regard to
.code :static
slots. Regardless of their placement in the
.code defstruct
form,
.code :method
and
.code :function
slots are initialized before
.code :static
slots. This ordering is useful, because it means that when the initialization
expression for a given static slot constructs an instance of the struct type,
any instance initialization code executing for that instance can use
all functions and methods of the struct type.
However, note the static slots which follow that slot in the
.code defstruct
syntax are not yet initialized. If it is necessary for a structure's
initialization code to have access to all static slots, even when the
structure is instantiated during the initialization of a static slot,
a possible solution may be to use lazy instantiation using the
.code lnew
operator, rather than ordinary eager instantiation via
.codn new .
It is also necessary to ensure that that the instance isn't accessed until all
static initializations are complete, since access to the instance slots of a
lazily instantiated structure triggers its initialization.

The structure name is specified using two forms, plain
.meta name
or the syntax
.mono
.meti >> ( name << arg *)
.onom
If the second form is used, then the structure type will support
"boa construction", where "boa" stands for "by order of arguments".
The
.metn arg -s
specify the list of slot names which are to be initialized in the
by-order-of-arguments style. For instance, if three slot names
are given, then those slots can be optionally initialized by giving three
arguments in the
.code new
macro or the
.code make-struct
function.

Slots are first initialized according to their
.metn init-form -s,
regardless of whether they are involved in boa construction

A slot initialized in this style still has a
.meta init-form
which is processed independently of the existence of, and prior to,
boa construction.

The boa constructor syntax can specify optional parameters, delimited
by a colon, similarly to the
.code lambda
syntax. However, the optional parameters may not be arbitrary symbols;
they must be symbols which name
slots. Moreover, the
.mono
.meti >> ( name < init-form <> [ present-p ])
.onom
optional parameter syntax isn't supported.

When boa construction is invoked with optional arguments missing,
the default values for those arguments come from the
.metn init-form -s
in the remaining
.code defstruct
syntax.

.TP* Examples:
.verb
  (defvar *counter* 0)

  ;; New struct type foo with no super type:
  ;; Slots a and b initialize to nil.
  ;; Slot c is initialized by value of (inc *counter*).
  (defstruct foo nil (a b (c (inc *counter*))))

  (new foo) -> #S(foo a nil b nil c 1)
  (new foo) -> #S(foo a nil b nil c 2)

  ;; New struct bar inheriting from foo.
  (defstruct bar foo (c 0) (d 100))

  (new bar) -> #S(bar a nil b nil c 0 d 100)
  (new bar) -> #S(bar a nil b nil c 0 d 100)

  ;; counter was still incremented during
  ;; construction of d:
  *counter* -> 4

  ;; override slots with new arguments
  (new foo a "str" c 17) -> #S(foo a "str" b nil c 17)

  *counter* -> 5

  ;; boa initialization
  (defstruct (point x : y) nil (x 0) (y 0))

  (new point) -> #S(point x 0 y 0)
  (new (point 1 1)) -> #S(point x 1 y 1)

  ;; property list style initialization
  ;; can always be used:
  (new point x 4 y 5) -> #S(point x 4 y 5)

  ;; boa applies last:
  (new (point 1 1) x 4 y 5) -> #S(point x 1 y 1)

  ;; boa with optional argument omitted:
  (new (point 1)) -> #S(point x 1 y 0)

  ;; boa with optional argument omitted and
  ;; with property list style initialization:
  (new (point 1) x 5 y 5) -> #S(point x 1 y 5)
.brev

.coNP Macro @ defmeth
.synb
.mets (defmeth < type-name < name < param-list << body-form *)
.syne
.desc
Unless
.meta name
is one of the two symbols
.code :init
or
.codn :postinit ,
the
.code defmeth
macro installs a function into the static slot named by the symbol
.meta name
in the struct type indicated by
.metn type-name .

If the structure type doesn't already have such a static slot, it is
first added, as if by the
.code static-slot-ensure
function, subject to the same checks.

If the function has at least one argument, it can be used as a method. In that
situation, the leftmost argument passes the structure instance on which the
method is being invoked.

The function takes the arguments specified
by the
.meta param-list
symbols, and its body consists of the
.metn body-form -s.

The
.metn body-form -s
are placed into a
.code block
named
.codn name .

A method named
.code lambda
allows a structure to be used as if it were a function. When arguments
are applied to the structure as if it were a function, the
.code lambda
method is invoked with those arguments, with the object itself inserted
into the leftmost argument position.

If
.code defmeth
is used to redefine an existing method, the semantics can be inferred
from that of
.codn static-slot-ensure .
In particular, the method will be imposed into all subtypes which inherit
(do not override) the method.

If
.meta name
is the keyword symbol
.codn :init ,
then instead of operating on a static slot, the macro redefines the
.meta initfun
of the given structure type, as if by a call to the function
.codn struct-set-initfun .

Similarly, if
.meta name
is the keyword symbol
.codn :postinit ,
then the macro redefines the
.meta postinitfun
of the given structure type, as if by a call to the function
.codn struct-set-postinitfun .

When redefining
.code :initfun
the admonishments given in the description of
.code struct-set-initfun
apply: if the type has an
.meta initfun
generated by the
.code defstruct
macro, then that
.meta initfun
is what implements all of the slot initializations given in the
slot specifier syntax. These initializations are lost if the
.meta initfun
is overwritten.

The
.code defmeth
macro returns a method name: a unit of syntax of the form
.mono
.meti (meth < type-name << name)
.onom
which can be used as an argument to the accessor
.code symbol-function
and other situations.

.coNP Macros @ new and @ lnew
.synb
.mets (new >> { name | >> ( name << arg *)} >> { slot << init-form }*)
.mets (lnew >> { name | >> ( name << arg *)} >> { slot << init-form }*)
.syne
.desc
The
.code new
macro creates a new instance of the structure type named by
.metn name .

If the structure supports "boa construction", then, optionally, the
arguments may be given using the syntax
.mono
.meti >> ( name << arg *)
.onom
instead of
.metn name .

Slot values may also be specified by the
.meta slot
and
.meta init-form
arguments.

Note: the evaluation order in
.code new
is surprising: namely,
.metn init-form -s
are evaluated before
.metn arg -s
if both are present.

When the object is constructed, all default initializations take place
first. If the object's structure type has a supertype, then the supertype
initializations take place. Then the type's initializations take
place, followed by the
.meta slot
.meta init-form
overrides from the
.code new
macro, and lastly the "boa constructor" overrides.

If any of the initializations abandon the evaluation of
.code new
by a non-local exit such as an exception throw, the object's
finalizers, if any, are invoked.

The macro
.code lnew
differs from new in that it specifies the construction of a
lazy struct, as if by the
.code make-lazy-struct
function.
When
.code lnew
is used to construct an instance, a lazy struct is returned
immediately, without evaluating any of the the
.meta arg
and
.meta init-form
expressions.
The expressions are evaluated when any of the object's
instance slots is accessed for the first time. At that time,
these expressions are evaluated (in the same order as under
.codn new )
and initialization proceeds in the same way.

If any of the initializations abandon the delayed initializations steps
arranged by
.code lnew
by a non-local exit such as an exception throw, the object's
finalizers, if any, are invoked.

Lazy initialization does not detect cycles. Immediately prior to the lazy
initialization of a struct, the struct is marked as no longer requiring
initialization. Thus, during initialization, its instance slots may be
freely accessed. Slots not yet initialized evaluate as
.codn nil .

.coNP Macros @ new* and @ lnew*
.synb
.mets (new* >> { expr | >> ( expr << arg *)} >> { slot << init-form }*)
.mets (lnew* >> { expr | >> ( expr << arg *)} >> { slot << init-form }*)
.syne
.desc
The
.code new*
and
.code lnew*
macros are variants, respectively, of
.code new
and
.codn lnew .

The only difference in behavior in these macros relative to
.code new
and
.code lnew
is that the
.meta name
argument is replaced with an expression
.meta expr
which is evaluated. The value of
.meta expr
must be a struct type, or a symbol which is the name of a struct type.

.coNP Macro @ with-slots
.synb
.mets (with-slots >> ({ slot | >> ( sym << slot )}*) < struct-expr
.mets \ \  << body-form *)
.syne
.desc
The
.code with-slots
binds lexical macros to serve as aliases for the slots of a structure.

The
.meta struct-expr
argument is expected to be an expression which evaluates to a struct
object. It is evaluated once, and its value is retained. The aliases are then
established to the slots of the resulting struct value.

The aliases are specified as zero or more expressions which consist of either
a single symbol
.meta slot
or a
.mono
.meti >> ( sym << slot )
.onom
pair. The simple form binds a macro named
.meta slot
to a slot also named
.metn slot .
The pair form binds a macro named
.meta sym
to a slot named
.metn slot .

The lexical aliases are syntactic places: assigning to an alias causes
the value to be stored into the slot which it denotes.

After evaluating
.meta struct-expr
the
.code with-slots
macro arranges for the evaluation of
.metn body-form -s
in the lexical scope in which the aliases are visible.

.TP* "Dialect Notes:"

The intent of the
.code with-slots
macro is to help reduce the verbosity of code which makes multiple
references to the same slot. Use of
.code with-slots
is less necessary in \*(TL than other Lisp dialects
thanks to the dot operator for accessing struct slots.

Lexical aliases to struct places can also be
arranged with considerable convenience using the
.code placelet
operator. However,
.code placelet
will not bind multiple aliases to multiple slots of the same object
such that the expression which produces the object is evaluated only
once.

.TP* Example:
.verb
  (defstruct point nil x y)

  ;; Here, with-slots introduces verbosity because
  ;; each slot is accessed only once. The function
  ;; is equivalent to:
  ;;
  ;; (defun point-delta (p0 p1)
  ;;   (new point x (- p1.x p0.x) y (- p1.y p0.y)))
  ;;
  ;; Also contrast with the use of placelet:
  ;;
  ;; (defun point-delta (p0 p1)
  ;;   (placelet ((x0 p0.x) (y0 p0.y)
  ;;              (x1 p1.x) (y1 p1.y))
  ;;     (new point x (- x1 x0) y (- y1 y0)))))

  (defun point-delta (p0 p1)
    (with-slots ((x0 x) (y0 y)) p0
      (with-slots ((x1 x) (y1 y)) p1
        (new point x (- x1 x0) y (- y1 y0)))))


.brev

.coNP Macro @ qref
.synb
.mets (qref < object-form
.mets \ \  >> { slot | >> ( slot << arg *) | >> [ slot << arg *]}+)
.syne
.desc
The
.code qref
macro ("quoted reference") performs structure slot access.  Structure slot
access is more conveniently expressed using the referencing dot notation, which
works by translating to qref
.code qref
syntax, according to the following equivalence:

.verb
  a.b.c.d <--> (qref a b c d)  ;; a b c d must not be numbers
.brev

(See the Referencing Dot section under Additional Syntax.)

The leftmost argument of
.code qref
is an expression which is evaluated. This argument is followed by one or more
reference designators.
If there are two or more designators, the following equivalence applies:

.verb
  (qref obj d1 d2 ...)  <---> (qref (qref obj d1) d2 ...)
.brev

That is to say,
.code qref
is applied to the object and a single designator. This must yield
an object, which to which the next designator is applied as if by
another
.code qref
operation, and so forth.

If the null-safe syntax
.code "(t ...)"
is present, the equivalence becomes more complicated:

.verb
  (qref (t obj) d1 d2 ...)  <---> (qref (qref (t obj) d1) d2 ...)

  (qref obj (t d1) d2 ...)  <---> (qref (t (qref obj d1)) d2 ...)
.brev

Thus,
.code qref
can be understood in terms of the semantics of the
binary form
.mono
.meti (qref < object-form << designator )
.onom

Designators come in three basic forms: a lone symbol, an ordinary compound expression
consisting of a symbol followed by arguments, or a DWIM expression
consisting of a symbol followed by arguments.

A lone symbol designator indicates the slot of that name. That is to say, the
following equivalence applies:

.verb
  (qref o n)  <-->  (slot o 'n)
.brev

where
.code slot
is the structure slot accessor function. Because
.code slot
is an accessor, this form denotes the slot as a syntactic place;
slots can be modified via assignment to the
.code qref
form and the referencing dot syntax.

The slot name being implicitly quoted is the basis of the term
"quoted reference", giving rise to the
.code qref
name.

A compound designator indicates that the named slot is a function,
and arguments are to be applied to it. The following equivalence applies
in this case, except that
.code o
is evaluated only once:

.verb
  (qref o (n arg ...)) <--> (call (slot o 'n) o arg ...)
.brev

A DWIM designator indicates that the named slot is a function or an
indexable or callable object. The following equivalence applies:

.verb
  (qref obj [name arg ...])  <-->  [(slot obj 'name) arg ...]
.brev

If the
.meta object-form
has the syntax
.mono
.meti (t << expression )
.onom
this indicates null-safe access: if
.meta expression
evaluates to
.code nil
then the entire expression
.mono
.meti (qref (t << expression ) << designator )
.onom
form yields
.codn nil .
This syntax is produced by the
.code .?
notation.

The null-safe access notation prevents not only slot access, but also
method or function calls on
.codn nil .
When a method or function call is suppressed due to the object being
.codn nil ,
no aspect of the method or function call is evaluated; not only
is the slot not accessed, but the argument expressions are not evaluated.

.TP* Example:

.verb
  (defstruct foo nil
    (array (vec 1 2 3))
    (increment (lambda (self index delta)
                 (inc [self.array index] delta))))

  (defvarl s (new foo))

  ;; access third element of s.array:
  s.[array 2]  -->  3

  ;; increment first element of array by 42
  s.(increment 0 42)  -->  43

  ;; access array member
  s.array  -->  #(43 2 3)
.brev

Note how
.code increment
behaves much like a single-argument-dispatch object-oriented method.
Firstly, the syntax
.mono
s.(increment 0 42)
.onom
effectively selects the
.code increment
function which is particular to the
.code s
object.  Secondly, the object is passed to the selected function as the
leftmost argument, so that the function has access to the object.

.coNP Macro @ uref
.synb
.mets (uref >> { slot | >> ( slot << arg *) | >> [ slot << arg *]}+)
.syne
.desc
The
.code uref
macro ("unbound reference") expands to an expression which evaluates to a
function.  The function takes exactly one argument: an object.
When the function is invoked on an object, it references slots
or methods relative to that object.

Note: the
.code uref
syntax may be used directly, but it is also produced by the unbound referencing
dot syntactic sugar:

.verb
  .a          -->  (uref a)
  .?a         -->  (uref t a)
  .(f x)      -->  (uref (f x))
  .(f x).b    -->  (uref (f x) b)
  .a.(f x).b  -->  (uref a (f x) b)
.brev

The macro may be understood in terms of the following translation
scheme:

.verb
  (uref a b ...)    -->  (lambda (o) (qref o a b ...))
  (uref t a b ...)  -->  (lambda (o) (if o (qref o a b ...)))
.brev

where
.code o
is understood to be a unique symbol (for instance, as produced by the
.code gensym
function).

When only one
.code uref
argument is present, these equivalences also hold:

.verb
  (uref (f a b c ...))  <-->  (umeth f a b c ...)
  (uref s)  <-->  (usl s)
.brev

The terminology "unbound reference" refers to the property that
.code uref
expressions produce a function which isn't bound to a structure
object.  The function binds a slot or method; the call to that function then
binds an object to that function, as an argument.

.TP* Examples:

Suppose that the objects in
.code list
have slots
.code a
and
.codn b .
Then, a list of the
.code a
slot values may be obtained using:

.verb
  (mapcar .a list)
.brev

because this is equivalent to

.verb
  (mapcar (lambda (o) o.a) list)
.brev

Because
.code uref
produces a function, its result can be operated upon by
functional combinators. For instance, we can use the
.code juxt
combinator to produce a list of two-element lists,
which hold the
.code a
and
.code b
slots from each object in
.codn list :

.verb
  (mapcar (juxt .a .b) list)
.brev

.coNP Macro @ meth
.synb
.mets (meth < struct < slot << curried-expr *)
.syne
.desc
The
.code meth
macro allows indirection upon a method-like function stored
in a function slot.

The
.code meth
macro binds
.meta struct
as the leftmost argument of the function stored in
.metn slot ,
returning a function which takes the remaining arguments.
That is to say, it returns a function
.meta f
such that
.mono
.meti >> [ f < arg ... ]
.onom
calls
.mono
.meti >> [ struct.slot < struct < arg ... ]
.onom
except that
.meta struct
is evaluated only once.

If one or more
.meta curried-expr
expressions are present, their values are bound inside
.meta f
also, and when
.meta f
is invoked, these are passed to the function stored in the slot.
Thus if
.meta f
is produced by
.code "(meth struct slot c1 c2 c3 ...)"
then
.mono
.meti >> [ f < arg ... ]
.onom
calls
.mono
.meti >> [ struct.slot < struct < c1v < c2v < c3v ... arg ... ]
.onom
except that
.meta struct
is evaluated only once, and
.metn c1v ,
.meta c2v
and
.meta c3v
are the values of expressions
.codn c1 ,
.code c2
and
.codn c3 .

The argument
.meta struct
must be an expression which evaluates to a struct.
The
.meta slot
argument is not evaluated, and must be a symbol denoting a slot.
The syntax can be understood as a translation to a call of the
.code method
function:

.verb
  (meth a b)  <-->  (method a 'b)
.brev

If
.meta curried-arg
expressions are present, the translation may be be understood
as:

.verb
  (meth a b c1 c2 ...)  <-->  [(fun method) a 'b c1 c2 ...]
.brev

In other words the
.meta curried-arg
expressions are evaluated under the
.code dwim
operator evaluation rules.

.TP* Example:

.verb
  ;; struct for counting atoms eq to key
  (defstruct (counter key) nil
    key
    (count 0)
    (:method increment (self key)
      (if (eq self.key key)
        (inc self.count))))

  ;; pass all atoms in tree to func
  (defun map-tree (tree func)
    (if (atom tree)
      [func tree]
      (progn (map-tree (car tree) func)
             (map-tree (cdr tree) func))))

  ;; count occurrences of symbol a
  ;; using increment method of counter,
  ;; passed as func argument to map-tree.
  (let ((c (new (counter 'a)))
        (tr '(a (b (a a)) c a d)))
    (map-tree tr (meth c increment))
    c)
  --> #S(counter key a count 4
                 increment #<function: type 0>)
.brev

.coNP Macro @ umeth
.synb
.mets (umeth < slot << curried-expr *)
.syne
.desc
The
.code umeth
macro binds the symbol
.meta slot
to a function and returns that function.

The
.meta curried-expr
arguments, if present, are evaluated as if they were
arguments to the
.code dwim
operator.

When that function is called, it expects at least one argument.
The leftmost argument must be an object of struct type.

The slot named
.meta slot
is retrieved from that object, and is expected to be a function.
That function is called with the object, followed by the values
of the
.metn curried-expr -s,
if any, followed by that function's arguments.

The syntax can be understood as a translation to a call of the
.code umethod
function:

.verb
  (umeth s ...)  <-->  [umethod 's ...]
.brev

The macro merely provides the syntactic sugar of not having to quote the
symbol, and automatically treating the curried argument expressions
using Lisp-1 semantics of the
.code dwim
operator.

.TP* Example:

.verb
   ;; seal and dog are variables which hold structures of
   ;; different types. Both have a method called bark.

   (let ((bark-fun (umeth bark)))
     [bark-fun dog]     ;; same effect as dog.(bark)
     [bark-fun seal])   ;; same effect as seal.(bark)
.brev

The
.code u
in
.code umeth
stands for "unbound". The function produced by
.code umeth
is not bound to any specific object; it binds to an object whenever it is
invoked by retrieving the actual method from the object's slot at call time.

.coNP Macro @ usl
.synb
.mets (usl << slot )
.syne
.desc
The
.code usl
macro binds the symbol
.meta slot
to a function and returns that function.

When that function is called, it expects exactly one argument.
That argument must be an object of struct type.
The slot named
.meta slot
is retrieved from that object and returned.

The name
.code usl
stands for "unbound slot". The term "unbound" refers to the returned
function not being bound to a particular object. The binding of the
slot to an object takes place whenever the function is called.

.coNP Function @ make-struct-type
.synb
.mets (make-struct-type < name < super < static-slots < slots
.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \  < static-initfun < initfun << boactor
.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \  < boactor << postinitfun )
.syne
.desc
The
.code make-struct-type
function creates a new struct type.

The
.meta name
argument must be a bindable symbol, according to the
.code bindable
function. It specifies the name property of the struct
type as well as the name under which the struct type
is globally registered.

The
.meta super
argument indicates the supertype for the struct type.
It must be either a value of type
.codn struct-type ,
a symbol which names a struct type, or else
.codn nil ,
indicating that the newly created struct type has no supertype.

The
.meta static-slots
argument is a list of symbol which specify static slots.
The symbols must be bindable and the list must not contain duplicates.

The
.meta slots
argument is a list of symbols which specifies the instance slots.
The symbols must be bindable and there must not be any duplicates
within the list, or against entries in the
.meta static-slots
list.

The new struct type's effective list of slots is formed by appending
together
.meta static-slots
and
.metn slots ,
and then appending that to the list of the supertype's slots, and
de-duplicating the resulting list as if by the
.code uniq
function. Thus, any slots which are already present in the supertype are
removed. If the structure has no supertype, then the list of supertype
slots is taken to be empty. When a structure is instantiated, it shall have all
the slots specified in the effective list of slots. Each instance slot
shall be initialized to the value
.codn nil ,
prior to the invocation of
.meta initfun
and
.metn boactor .

The
.meta static-initfun
argument either specifies an initialization function, or is
.codn nil ,
which is equivalent to specifying a function which does nothing.

Prior to the invocation of
.metn static-initfun ,
each new static slot shall be initialized the value
.codn nil .
Inherited static slots retain their values from the supertype.

If specified,
.meta static-initfun
function must
accept one argument. When the structure type is created (before
the
.code make-struct-type
function returns) the
.meta static-initfun
function is invoked, passed the newly created
structure type as its argument.

The
.meta initfun
argument either specifies an initialization function, or is
.codn nil ,
which is equivalent to specifying a function which does nothing.
If specified, this function must
accept one argument. When a structure is instantiated, every
.meta initfun
in its chain of supertype ancestry is invoked, in order of inheritance,
so that the root supertype's
.meta initfun
is called first and the structure's own specific
.meta initfun
is called last. These calls occur before the slots are initialized
from the
.meta arg
arguments
or the
.meta slot-init-plist
of
.codn make-struct .
Each function is passed the newly created structure
object, and may alter its slots.
If multiple inheritance occurs, the
.meta initfun
functions of multiple supertypes are called in right-to-left order.

The
.meta boactor
argument either specifies a by-order-of-arguments initialization
function ("boa constructor") or is
.codn nil ,
which is equivalent to specifying a constructor which does nothing.
If specified, it must be a function which takes at least one argument.
When a structure is instantiated, and boa arguments are given, the
.meta boactor
is invoked, with the structure as the leftmost argument, and
the boa arguments as additional arguments. This takes place
after the processing of
.meta initfun
functions, and after the processing of the
.meta slot-init-plist
specified in the
.code make-struct
call.  Note that the
.meta boactor
functions of the supertypes are not called, only the
.meta boactor
specific to the type being constructed.

The
.meta postinitfun
argument either specifies an initialization function, or is
.codn nil ,
which is equivalent to specifying a function which does nothing.
If specified, this function must accept one argument.
The
.meta postinitfun
function is similar to
.metn initfun .
The difference is that
.meta postinitfun
functions are called after all other initialization processing,
rather than before. They are are also called in order of
inheritance: the
.meta postinitfun
of a structure's supertype is called before its own,
and in right-to-left order among multiple supertypes
under multiple inheritance.

.coNP Function @ find-struct-type
.synb
.mets (find-struct-type << name )
.syne
.desc
The
.code find-struct-type
returns a
.code struct-type
object corresponding to the symbol
.metn name .

If no struct type is registered under
.metn name ,
then it returns
.codn nil .

A
.code struct-type
object exists for each structure type and holds information about it.
These objects are not themselves structures and are all of the
same type,
.codn struct-type .

.coNP Function @ struct-type-p
.synb
.mets (struct-type-p << obj )
.syne
.desc
The
.code struct-type-p
function returns t if
.meta obj
is a structure type, otherwise it returns
.codn nil .

A structure type is an object of type
.codn struct-type ,
returned by
.codn find-struct-type .

.coNP Function @ struct-type-name
.synb
.mets (struct-type-name << type )
.syne
.desc
The
.code struct-type-name
function returns the symbol which serves as the name of
.metn type ,
which must be either a struct type object (such as the return value of
a successful lookup via
.codn find-struct-type ),
or else a struct type name.

.coNP Function @ super
.synb
.mets (super << type )
.syne
.desc
The
.code super
function returns the struct type object which is the
supertype of
.metn type ,
or returns
.code nil
if
.meta type
has no supertype.

The
.meta type
argument must be either a struct type object, a
a symbol which names a struct type (which is resolved to that type),
or else a structure instance (which is resolved to its structure type).

.coNP Function @ make-struct
.synb
.mets (make-struct < type < slot-init-plist << arg *)
.syne
.desc
The
.code make-struct
function returns a new object which is an instance of the
structure type
.metn type .

The
.meta type
argument must either be a
.code struct-type
object, or else a symbol which is the name of a structure.

The
.meta slot-init-plist
argument gives a list of slot initializations in the
style of a property list, as defined by the
.code prop
function. It may be empty, in which case
it has no effect. Otherwise, it specifies slot names
and their values. Each slot name which is given must
be a slot of the structure type. The corresponding value
will be stored into the slot of the newly created object. If a slot is
repeated, it is unspecified which value takes effect.

The optional
.metn arg -s
specify arguments to the structure type's boa constructor.
If the arguments are omitted, the boa constructor is not invoked.
Otherwise the boa constructor is invoked on the structure object
and those arguments.  The argument list must match the trailing parameters of
the boa constructor (the remaining parameters which follow the leftmost
argument which passes the structure to the boa constructor).

When a new structure is instantiated by
.codn make-struct ,
its slot values are first initialized by the structure type's registered
functions as described under
.codn make-struct-type .
Then, the
.meta slot-init-plist
is processed, if not empty, and finally, the
.metn arg -s
are processed, if present, and passed to the boa constructor.

If any of the initializations abandon the evaluation of
.code make-struct
by a non-local exit such as an exception throw, the object's
finalizers, if any, are invoked.

.coNP Function @ make-lazy-struct
.synb
.mets (make-lazy-struct < type << argfun )
.syne
.desc
The
.code make-lazy-struct
function returns a new object which is an instance of the
structure type
.metn type .

The
.meta type
argument must either be a
.code struct-type
object, or else a symbol which is the name of a structure.

The
.meta argfun
argument should be a function which can be called with no parameters
and returns a cons cell. More requirements are specified below.

The object returned by
.code make-lazy-struct
is a lazily-initialized struct instance, or
.IR "lazy struct" .

A lazy struct remains uninitialized until just before the first access
to any of its instance slots. Just before an instance slot is
accessed, initialization
takes place as follows. The
.meta argfun
function is invoked with no arguments. Its return value must be a cons
cell. The
.code car
of the cons cell is taken to be a property list, as defined by the
.code prop
function.  The
.code cdr
field is taken to be a list of arguments. These values are treated
as if they were, respectively, the
.meta slot-init-plist
and the boa constructor arguments given in a
.code make-struct
invocation. Initialization of the structure proceeds as described
in the description of
.codn make-struct .

.coNP Functions @ struct-from-plist and @ struct-from-args
.synb
.mets (struct-from-plist < type >> { slot << value }*)
.mets (struct-from-arg < type << arg *)
.syne
.desc
The
.code struct-from-plist
and
.code struct-from-arg
are interfaces to the
.code make-struct
function.

The
.code struct-from-plist
function passes its
.meta slot
and
.meta value
arguments as the
.meta slot-init-plist
argument of
.codn make-struct .
It passes no boa constructor arguments.

The
.code struct-from-plist
function calls
.meta make-struct
with an empty
.metn slot-init-plist ,
passing down the list of
.metn arg -s.

The following equivalences hold:

.verb
  (struct-from-plist a s0 v0 s1 v1 ...)
  <-->  (make-struct a (list s0 v0 s1 v1 ...))

  (struct-from-args a v0 v1 v2 ...)
  <-->  (make-struct a nil v0 v1 v2 ...)
.brev

.coNP Function @ allocate-struct
.synb
.mets (allocate-struct << type )
.syne
.desc
The
.code allocate-struct
provides a low-level allocator for structure objects.

The
.meta type
argument must either be a
.code struct-type
object, or else a symbol which is the name of a structure.

The
.code allocate-struct
creates and returns a new instance of
.meta type
all of whose instance slots take on the value
.codn nil .
No initializations are performed. The struct type's
registered initialization functions are not invoked.

.coNP Function @ copy-struct
.synb
.mets (copy-struct << struct-obj )
.syne
.desc
The
.code copy-struct
function creates and returns a new object which is a duplicate of
.metn struct-obj ,
which must be a structure.

The duplicate object is a structure of the same type as
.meta struct-obj
and has the same slot values.

The creation of a duplicate does not involve calling any of the
struct type's initialization functions.

Only instance slots participate in the duplication. Since
the original structure and copy are of the same structure type,
they already share static slots.

This is a low-level, "shallow" copying mechanism. If an object design
calls for a higher level cloning mechanism with deep copying or other
additional semantics, one can be built on top of
.codn copy-struct .
For instance, a structure can have a
.code copy
method similar to the following:

.verb
  (:method copy (me)
    (let ((my-copy (copy-struct me)))
      ;; inform the copy that it has been created
      ;; by invoking its copied method.
      my-copy.(copied)
      my-copy))
.brev

since this logic is generic, it can be placed in a base
method. The
.code copied
method which it calls is the means by which the new object is notified that it
is a copy. This method takes on whatever special responsibilities are required
when a copy is produced, such as registering the object in various necessary
associations, or performing a deeper copy of some of the objects held
in the slots.

The
.code copied
handler can be implemented at multiple levels of an inheritance hierarchy. The
initial call to
.code copied
from
.code copy
will call the most derived override of that method.

To call the corresponding method in the base class, a given derived method
can use the
.code call-super-fun
function, or else the
.code "(meth ...)"
syntax in the first position of a compound form, in place of a function name.
Examples of both are given in the documentation for
.codn call-super-fun .

Thus derived structs can inherit the copy handling logic from base structs, and
extend it with their own.

.coNP Accessor @ slot
.synb
.mets (slot < struct-obj << slot-name )
.mets (set (slot < struct-obj << slot-name ) << new-value )
.syne
.desc
The
.code slot
function retrieves a structure's slot. The
.meta struct-obj
argument must be a structure, and
.meta slot-name
must be a symbol which names a slot in that structure.

Because
.code slot
is an accessor, a
.code slot
form is a syntactic place which denotes the
slot's storage location.

A syntactic place expressed by
.code slot
does not support deletion.

.coNP Function @ slotset
.synb
.mets (slotset < struct-obj < slot-name << new-value )
.syne
.desc
The
.code slotset
function stores a value in a structure's slot.
 The
.meta struct-obj
argument must be a structure, and
.meta slot-name
must be a symbol which names a slot in that structure.

The
.meta new-value
argument specifies the value to be stored in the slot.

If a successful store takes place to an instance slot of
.metn struct-obj ,
then the dirty flag of that object is set, causing the
.code test-dirty
function to report true for that object.

The
.code slotset
function returns
.metn new-value .

.coNP Functions @, test-dirty @ clear-dirty and @ test-clear-dirty
.synb
.mets (test-dirty << struct-obj )
.mets (clear-dirty << struct-obj )
.mets (test-clear-dirty << struct-obj )
.syne
.desc
The
.codn test-dirty ,
.code clear-dirty
and
.code test-clear-dirty
functions comprise the interface for interacting with structure
dirty flags.

Each structure instance has a dirty flag. When this flag is set, the
structure instance is said to be dirty, otherwise it is said to be clean. A
newly created structure is dirty.  A structure remains dirty until its dirty
flag is explicitly reset.  If a structure is clean, and one of its instance
slots is overwritten with a new value, it becomes dirty.

The
.code test-dirty
function returns the dirty flag of
.metn struct-obj :
.code t
if
.meta struct-obj
is dirty, otherwise
.codn nil .

The
.code clear-dirty
function clears the dirty flag of
.meta struct-obj
and returns
.meta struct-obj
itself.

The
.code test-clear-dirty
flag combines these operations: it makes a note of the dirty flag of
.meta struct-obj
and clears it. Then it returns the noted value,
.code t
or
.codn nil .

.coNP Function @ structp
.synb
.mets (structp << obj )
.syne
.desc
The
.code structp
function returns t if
.meta obj
is a structure, otherwise it returns
.codn nil .

.coNP Function @ struct-type
.synb
.mets (struct-type << struct-obj )
.syne
.desc
The
.code struct-type
function returns the structure type object which
represents the type of the structure object instance
.metn struct-obj .

.coNP Function @ clear-struct
.synb
.mets (clear-struct < struct-obj <> [ value ])
.syne
.desc
The
.code clear-struct
replaces all instance slots of
.meta struct-obj
with
.metn value ,
which defaults to
.code nil
if omitted.

Note that finalizers are not executed prior to replacing
the slot values.

.coNP Function @ reset-struct
.synb
.mets (reset-struct << struct-obj )
.syne
.desc
The
.code reset-struct
function reinitializes the structure object
.meta struct-obj
as if it were being newly created.
First, all the slots are set to
.code nil
as if by the
.code clear-struct
function. Then the slots are initialized by invoking the
initialization functions, in order of the supertype ancestry, just as would be
done for a new structure object created by
.code make-struct
with an empty
.meta slot-init-plist
and no boa arguments.

Note that finalizers registered against
.meta struct-obj
are not invoked prior to the reset operation, and remain registered.

If the structure has state which is cleaned up by
finalizers, it is advisable to invoke them using
.code call-finalizers
prior to using
.codn reset-struct ,
or to take other measures to deal with the
situation.

If the structure specifies
.code :fini
handlers, then the reinitialization will cause
these to registered, just like when a new object
it constructed. Thus if
.code call-finalizers
is not used prior to
.codn reset-struct ,
this will result in the existence of duplicate registrations of the
finalization functions.

Finalizers registered against
.meta struct-obj
.B are
invoked if an exception is thrown
during the reinitialization, just like when a new
structure is being constructed.

.coNP Function @ replace-struct
.synb
.mets (replace-struct < target-obj << source-obj )
.syne
.desc
The
.code replace-struct
function causes
.meta target-obj
to take on the attributes of
.meta source-obj
without changing its identity.

The type of
.code target-obj
is changed to that of
.codn source-obj .

All instance slots of
.code target-obj
are discarded, and it is given new slots,
which are copies of the instance slots of
.codn source-obj .

Because of the type change,
.code target-obj
implicitly loses all of its original static slots,
and acquires those of
.codn "source obj" .

Note that finalizers registered against
.meta target-obj
are not invoked, and remain registered.
If
.meta target-obj
has state which is cleaned up by
finalizers, it is advisable to invoke them using
.code call-finalizers
prior to using
.codn replace-struct ,
or to take other measures to handle the situation.

If the
.meta target-obj
and
.meta source-obj
arguments are the same object,
.code replace-struct
has no effect.

The return value is
.metn target-obj .

.coNP Function @ method
.synb
.mets (method < struct-obj < slot-name << curried-arg *)
.syne
.desc
The
.code method
function retrieves a function
.meta m
from a structure's slot
and returns a new function which binds that function's
left argument. If
.meta curried-arg
arguments are present, then they are also stored in
the returned function. These are the
.IR "curried arguments" .

The
.meta struct-obj
argument must be a structure, and
.meta slot-name
must be a symbol denoting a slot in that structure.
The slot must hold a function of at least one
argument.

The function
.meta f
which
.code method
function returns, when invoked,
calls the function
.meta m
previously retrieved from the object's
slot, passing to that function
.meta struct-obj
as the leftmost argument, followed by the curried
arguments, followed by all of
.metn f 's
own arguments.

Note: the
.code meth
macro is an alternative interface which is suitable if
the slot name isn't a computed value.

.coNP Function @ super-method
.synb
.mets (super-method < struct-obj << slot-name )
.syne
.desc
The
.code super-method
function retrieves a function from a static
slot belonging to one of the direct supertypes of the structure type of
.metn struct-obj .

It then returns a function which binds
that function's left argument to the structure.

The
.meta struct-obj
argument must be a structure which has at least one supertype, and
.meta slot-name
must be a symbol denoting a static slot in one of those supertypes.
The slot must hold a function of at least one
argument. The supertypes are searched from left to right for a static
slot named
.metn slot-name ;
when the first such slot is found, its value is used.

The
.code super-method
function returns a function which, when invoked,
calls the function previously retrieved from
the supertype's static slot, passing to that function
.meta struct-obj
as the leftmost argument, followed by the function's
own arguments.

.coNP Function @ umethod
.synb
.mets (umethod < slot-name << curried-arg *)
.syne
.desc
The
.code umethod
returns a function which represents the set of all methods named by
the slot
.meta slot-name
in all structure types, including ones not yet defined.
The
.meta slot-name
argument must be a symbol.

If one or more
.meta curried-arg
argument are present, these values represent the
.I "curried arguments"
which are stored in the function object which is returned.

This returned function must be called with at least one argument. Its leftmost
argument must be an object of structure type, which has a slot named
.metn slot-name .
The function will retrieve the value of the slot from that object,
expecting it to be a function, and calls it, passing to it the following
arguments: the object itself; all of the curried arguments, if any; and
all of its remaining arguments.

Note: the
.code umethod
name stands for "unbound method". Unlike the
.code method
function,
.code umethod
doesn't return a method whose leftmost argument is already bound to
an object; the binding occurs at call time.

.coNP Function @ uslot
.synb
.mets (uslot << slot-name )
.syne
.desc
The
.code uslot
returns a function which represents all slots named
.meta slot-name
in all structure types, including ones not yet defined.
The
.meta slot-name
argument must be a symbol.

The returned function must be called with exactly one argument.
The argument must be a structure which has a slot named
.metn slot-name .
The function will retrieve the value of the slot from that object
and return it.

Note: the
.code uslot
name stands for "unbound slot". The returned function
isn't bound to a particular object. The binding of
.code slot-name
to a slot in the structure object occurs when the function is called.

.coNP Function @ slots
.synb
.mets (slots << type )
.syne
.desc
The
.code slots
function returns a list of all of the slots of struct type
.metn type .

The
.meta type
argument must be a structure type, or else a symbol
which names a structure type.
.coNP Function @ slotp
.synb
.mets (slotp < type << name )
.syne
.desc
The
.code slotp
function returns
.code t
if name
.meta name
is a symbol which names a slot in the structure type
.metn type .
Otherwise it returns
.codn nil .

The
.meta type
argument must be a structure type, or else a symbol
which names a structure type.

.coNP Function @ static-slot-p
.synb
.mets (static-slot-p < type << name )
.syne
.desc
The
.code static-slot-p
function returns
.code t
if name
.meta name
is a symbol which names a slot in the structure type
.metn type ,
and if that slot is a static slot.
Otherwise it returns
.codn nil .

The
.meta type
argument must be a structure type, or else a symbol
which names a structure type.

.coNP Function @ static-slot
.synb
.mets (static-slot < type << name )
.syne
.desc
The
.code static-slot
function retrieves the value of the static slot
named by symbol
.meta name
of the structure type
.metn type .

The
.meta type
argument must be a structure type or a symbol which names a
structure type, and
.meta name
must be a static slot of this type.

.coNP Function @ static-slot-set
.synb
.mets (static-slot-set < type < name << new-value )
.syne
.desc
The
.code static-slot-set
function stores
.meta new-value
into the static slot named by symbol
.meta name
of the structure type
.metn type .

It returns
.metn new-value .

The
.meta type
argument must be a structure type or the name of a structure type, and
.meta name
must be a static slot of this type.

.coNP Function @ static-slot-ensure
.synb
.mets (static-slot-ensure < type < name < new-value <> [ no-error-p ])
.syne
.desc
The
.code static-slot-ensure
ensures, if possible, that the struct type
.metn type ,
as well as possibly one or more struct types derived from it,
have a static slot called
.metn name ,
that this slot is not shared with a supertype,
and that the value stored in it is
.metn new-value .

Note: this function supports the redefinition of methods,
as the implementation underlying the
.code defmeth
macro; its semantics is designed to harmonize with expected
behaviors in that usage.

The function operates as follows.

If
.meta type
itself already has an instance slot called
.meta name
then an error is thrown, and the function has no effect, unless a
true argument is specified for the
.meta no-error-p
Boolean parameter. In that case, in the same situation, the function
has no effect and simply returns
.metn new-value .

If
.meta type
already has a non-inherited static slot called
.meta name
then this slot is overwritten with
.meta new-value
and the function returns
.metn new-value .
Types derived from
.meta type
may also have this slot, via inheritance; consequently, its value
changes in those types also.

If
.meta type
already has an inherited static slot called
.meta name
then its inheritance is severed; the slot is converted
to a non-inherited static slot of
.meta type
and initialized with
.metn new-value .
Then all struct types derived from
.meta type
are scanned. In each such type, if the original inherited
static slot is found, it is replaced with the same
newly converted static slot that was just introduced into
.metn type ,
so that all these types now inherit this new slot from
.meta type
rather than the original slot from some supertype of
.metn type .
These types all share a single instance of the slot with
.metn type ,
but not with supertypes of
.metn type .

In the remaining case,
.meta type
has no slot called
.metn name .
The slot is added as a static slot to
.metn type .
Then it is added to every struct type derived from
.meta type
which does not already have a slot by that name, as if
by inheritance.  That is to say, types to which this slot is introduced share a
single instance of that slot.  The value of the new slot is
.metn new-value ,
which is also returned from the function.  Any subtypes of
.meta type
which already have a slot called
.meta name
are ignored, as are their subtypes.

.coNP Function @ static-slot-home
.synb
.mets (static-slot-home < type << name )
.syne
.desc
The
.code static-slot-home
method determines which structure type actually defines the
static slot
.meta name
present in struct type
.metn type .

If
.meta type
isn't a struct type, or the name of a struct type,
the function throws an error. Likewise, if
.meta name
isn't a static slot of
.metn type .

If
.meta name
is a static slot of
.meta type
then the function returns a struct type name symbol which is either
then name of
.meta type
itself, if the slot is defined specifically for
.meta type
or else the most distant ancestor of
.meta type
from which the slot is inherited.

.coNP Function @ call-super-method
.synb
.mets (call-super-method < struct-obj < name << argument *)
.syne
.desc
The
.code call-super-method
function is deprecated. Solutions involving
.code call-super-method
should be reworked in terms of
.codn call-super-fun .

The
.code call-super-method
retrieves the function stored in the static slot
.meta name
of one of the direct supertypes of
.meta struct-obj
and invokes it, passing to that function
.meta struct-obj
as the leftmost argument, followed by the given
.metn argument -s,
if any.

The
.meta struct-obj
argument must be of structure type. Moreover,
that structure type must be derived from one or more supertypes,
and
.meta name
must name a static slot available from at least one of those supertypes.
The supertypes are searched left to right in search of this slot.

The object retrieved from that static slot must be
callable as a function, and accept the arguments.

Note that it is not correct for a method that is defined
against a particular type to use
.code call-super-method
to call the same method (or any other method) in the supertype
of that particular type. This is because
.code call-super-method
refers to the type of the object instance
.metn struct-obj ,
not to the type against which the calling method is defined.

.coNP Function @ call-super-fun
.synb
.mets (call-super-fun < type < name << argument *)
.syne
.desc
The
.code call-super-fun
retrieves the function stored in the slot
.meta name
of one of the supertypes of
.meta type
and invokes it, passing to that function the given
.metn argument -s,
if any.

The
.meta type
argument must be a structure type. Moreover,
that structure type must be derived from one or more supertypes,
and
.meta name
must name a static slot available from at least one of those supertypes.
The supertypes are searched left to right in search of this slot.

The object retrieved from that static slot must be
callable as a function, and accept the arguments.

.TP* Example:

Print a message and call supertype method:

.verb
  (defstruct base nil)

  (defstruct derived base)

  (defmeth base fun (obj arg)
    (format t "base fun method called with arg ~s\en" arg))

  (defmeth derived fun (obj arg)
    (format t "derived fun method called with arg ~s\en" arg)
    (call-super-fun 'derived 'fun obj arg))

  ;; Interactive Listener:
  1> (new derived).(fun 42)
  derived fun method called with arg 42
  base fun method called with arg 42
.brev

Note that a static method or function in any structure type
can be invoked by using the
.code "(meth ...)"
name syntax in the first position of a compound form, as
a function name. Thus, the above
.code "derived fun"
can also be written:

.verb
  (defmeth derived fun (obj arg)
    (format t "derived fun method called with arg ~s\en" arg)
    ((meth base fun) obj arg))
.brev

.coNP Functions @ struct-get-initfun and @ struct-get-postinitfun
.synb
.mets (struct-get-initfun << type )
.mets (struct-get-postinitfun << type )
.syne
.desc
The
.code struct-get-initfun
and
.code struct-get-postinitfun
functions retrieve, respectively, a structure type's
.meta initfun
and
.meta postinitfun
functions. These are the functions which are initially configured in the call to
.code make-struct-type
via the
.meta initfun
and
.meta postinitfun
arguments.

Either one may be
.codn nil ,
indicating that the type has no
.meta initfun
or
.metn postinitfun .

.coNP Functions @ struct-set-initfun and @ struct-set-postinitfun
.synb
.mets (struct-set-initfun < type << function )
.mets (struct-set-postinitfun < type << function )
.syne
.desc
The
.code struct-set-initfun
and
.code struct-set-postinitfun
functions overwrite, respectively, a structure type's
.meta initfun
and
.meta postinitfun
functions. These are the functions which are initially configured in the call to
.code make-struct-type
via the
.meta initfun
and
.meta postinitfun
arguments.

The
.meta function
argument must either be
.code nil
or else a function which accepts one argument.

Note that
.meta initfun
has the responsibility for all instance slot initializations. The
.code defstruct
syntax compiles the initializing expressions in the slot specifier syntax
into statements which are placed into a function, which becomes the
.meta initfun
of the struct type.

.coNP Macro @ with-objects
.synb
.mets (with-objects >> ({( sym << init-form )}*) << body-form *)
.syne
.desc
The
.code with-objects
macro provides a binding construct similar to
.codn let* .

Each
.meta sym
must be a symbol suitable for use as a variable name.

Each
.meta init-form
is evaluated in sequence, and a binding is established for its
corresponding
.meta sym
which is initialized with the value of that form. The binding
is visible to subsequent
.metn init-form -s.

Additionally, the values of the
.metn init-form -s
are noted as they are produced.  When the
.code with-objects
form terminates, by any means, the
.code call-finalizers
function is invoked on each value which was returned by an
.meta init-form
and had been noted. These calls are performed in the
reverse order relative to the original evaluation of the forms.

After the variables are established and initialized, the
.metn body-form -s
are evaluated in the scope of the variables. The value of the
last form is returned, or else
.code nil
if there are no forms. The invocations of
.code call-finalizers
take place just before the value of the last form is returned.

.SS* Special Structure Functions

Special structure functions are user-defined methods or structure functions
which are specially recognized by certain functions in \*(TL. They endow
structure objects with the ability to participate in certain usage scenarios,
or to participate in a customized way.

Special functions are required to bound to static slots, which is the
case if the
.code defmeth
macro is used, or when methods or functions are defined using syntax
inside a
.code defstruct
form. If a special function or method is defined as an instance slot,
then the behavior of library functions which depend on this method is
unspecified.

Special functions introduced below by the word "Method" receive an object
instance as an argument. Their syntax is indicated using the same notation
which may be used to invoke them, such as:

.verb
.mets << object .(function-name < arg << ... )
.brev

However, those introduced as "Function" do not operate on an instance. For
brevity, their syntax is nevertheless exemplified as

.verb
.mets << object .'['function-name < arg << ... ']'
.brev

If such a invocation is actually used, the
.meta object
instance only serves for identifying the struct type whose static slot
.code function-name
provides the function;
.meta object
doesn't participate in the call. An object is not required since
the function can be called using

.verb
.mets [(static-slot < type 'function-name) < arg << ... ]
.brev

which looks up the function in the struct
.meta type
directly.

.coNP Method @ equal
.synb
.mets << object .(equal)
.syne
.desc
Normally, two struct values are not considered the same under the
.code equal
function unless they are the same object.

However, if the
.code equal
method is defined for a structure type, then instances of
that structure type support
.IR "equality substitution" .

The
.code equal
method must not require any arguments other than
.metn object .
Moreover, the method must never return
.codn nil .

When a struct which supports equality substitution is compared using
.codn equal ,
.code less
or
.codn greater ,
its
.code equal
method is invoked, and the return value is used in place of that
structure for the purposes of the comparison.

The same applies when an struct is hashed using the
.code hash-equal
function, or implicitly by an
.code :equal-hash
hash table.

Note: if an
.code equal
method is defined or redefined with different semantics for a struct
type whose instances have already been inserted as keys in an
.code :equal-based
hash table, the behavior of subsequent insertion and lookup operations
on that hash table becomes unspecified.

.coNP Method @ print
.synb
.mets << object .(print < stream << pretty-p )
.syne
.desc
If a method named by the symbol
.code print
is defined for a structure type, then it is used for printing instances
of that type.

The
.meta stream
argument specifies the output stream to which the printed representation
is to be written.

The
.meta pretty-p
argument is a Boolean flag indicating whether pretty-printing
is requested. Its value may simply be passed to recursive calls to
.codn print ,
or used to select between
.code ~s
or
.code ~a
formatting if
.code format
is used.

The value returned by the
.code print
method is significant. If the special keyword symbol
.code :
(colon) is returned, then the system will print the object
in the default way, as if no
.code print
method existed: it is understood that the method declined
the responsibility for printing the object.

If any other value is returned, then it is understood
that the method
.code print
method accepted the responsibility for printing the object,
and the system consequently will generate into
.meta stream
any output output pertaining to
.metn object 's
representation.

.coNP Method @ lambda
.synb
.mets << object .(lambda << arg *)
.syne
.desc
If a structure type provides a method called
.code lambda
then it can be used as a function.

This method can be called by name, using the syntax given
in the above syntactic description.

However, the intended use is that it allows the structure instance itself to be
used as a function.  When arguments are applied to a structure object as if it
were a function, this is erroneous, unless that object has a
.code lambda
method. In that case, the arguments are passed to the lambda method.
The leftmost argument of the method is the structure instance
itself.

That is to say, the following equivalences apply, except that
.code s
is evaluated only once:

.verb
  (call s args ...)  <-->  s.(lambda args ...)

  [s args ...]  <-->  [s.lambda s args ...]

  (mapcar s list)  <-->  (mapcar (meth s lambda) list)
.brev

Note: a form such as
.code "[s args ...]"
where
.code s
is a structure can be treated as a place if the method
.code lambda-set
is also implemented.

.coNP Method @ lambda-set
.synb
.mets << object .(lambda-set << arg * << new-value )
.syne
.desc
The
.code lambda-set
method, in conjunction with a
.code lambda
method, allows structures to be used as place accessors. If
structure
.code s
supports a
.meta lambda-set
with four arguments, then the following use of the
.code dwim
operator is possible:

.verb
  (set [s a b c d] v)
  (set (dwim s a b c d) v) ;; precisely equivalently
.brev

This has an effect which can be described by the following code:

.verb
  (progn
    s s.(lambda-set a b c d v)
    v)
.brev

except that
.code s
and
.code v
are evaluated only once, and
.code a
through
.code d
are evaluated using the Lisp-1 semantics due the
.code dwim
operator.

If a place-mutating operator is used on this form which requires the prior
value, such as the
.code inc
macro, then the structure must support the
.code lambda
function also.

If
.code lambda
takes
.I n
arguments, then
.code lambda-set
should take
.I n+1
arguments. The first
.I n
arguments of these two methods are congruent; the extra rightmost argument
of
.code lambda-set
is the new value to be stored into the place denoted by the prior
arguments.

The return value of
.code lambda-set
is ignored.

Note: the
.code lambda-set
method is also used by the
.code rplaca
function, if no
.code rplaca
method exists.

.TP* Example

The following defines a structure with a single instance
slot
.code hash
which holds a hash table, as well as
.code lambda
and
.code lambda-set
methods:

.verb
  (defstruct hash-wrapper nil
    (hash (hash))

    (:method lambda (self key)
      [self.hash key])

    (:method lambda-set (self key new-val)
      (set [self.hash key] new-val) self))
.brev

An instance of this structure can now be used as follows:

.verb
   (let ((s (new hash-wrapper)))
     (set [s "apple"] 3
          [s "orange] 4)
     [s "apple"]) -> 3
.brev

.coNP Method @ length
.synb
.mets << object .(length)
.syne
.desc
If a structure has
.code length
method, then it can be used as an argument to the
.code length
function.

Structures which implement the methods
.codn lambda ,
.code lambda-set
and
.code length
can be treated as abstract vector-like sequences, because such
structures support the
.codn ref ,
.code refset
and
.code length
functions.

For instance, the
.code nreverse
function will operate on such objects.

Note: a structure which supports the
.code car
method also supports the
.code length
function, in a different way. Such a structure is treated by
.code length
as a list-like sequence, and its length is measured by walking the
sequence with
.code cdr
operations. If a structure supports both
.code length
and
.codn car ,
preference is given to
.codn length ,
which is likely to be much more efficient.

.coNP Methods @, car @ cdr and @ nullify
.synb
.mets << object .(car)
.mets << object .(cdr)
.mets << object .(nullify)
.syne
.desc
Structures may be treated as sequences if they define methods named
by the symbols
.codn car ,
.codn cdr ,
and
.codn nullify .

If a structure supports these methods, then these methods are used
by the functions
.codn car ,
.codn cdr ,
.codn nullify ,
.code empty
and various other sequence manipulating functions derived from them, when those
functions are applied to that object.

An object which implements these three methods can be considered to represent a
.I list-like
abstract sequence.

The object's
.code car
method should return the first value in that abstract sequence, or else
.code nil
if that sequence is empty.

The object's
.code cdr
method should return an object denoting the remainder of the sequence,
or else
.code nil
if the sequence is empty or contains only one value.  This returned object can
be of any type: it may be of the same structure type as that object, a
different structure type, a list, or whatever else.  If a non-sequence object
is returned.

The
.code nullify
method should return
.code nil
if the object is considered to denote an empty sequence. Otherwise it
should either return that object itself, or else return the sequence which
that object represents.

.coNP Methods @ rplaca and @ rplacd
.synb
.mets << object .(rplaca << new-car-value )
.mets << object .(rplacd << new-cdr-value )
.syne
.desc
If a structure type defines the methods
.code rplaca
and
.code rplacd
then, respectively, the
.code rplaca
and
.code rplacd
functions will use these methods if they are applied to instances of that type.

That is to say, when the function call
.mono
.meti (rplaca < o << v )
.onom
is evaluated, and
.meta o
is a structure type, the function inquires whether
.meta o
supports a
.code rplaca
method. If so, then, effectively,
.mono
.meti << o . (rplaca << v)
.onom
is invoked. The return value of this method call is ignored;
.code rplaca
returns
.metn o .
The analogous requirements apply to
.code rplacd
in relation to the
.code rplacd
method.

Note: if the
.code rplaca
method doesn't exist, the
.code rplaca
function falls back on trying to store
.meta new-car-value
by means of the structure type's
.code lambda-set
method, using an index of zero. That is to say, if the type has no
.code rplaca
method, but does have a
.code lambda-set
method, then
.mono
.meti << o . (lambda-set 0 << v)
.onom
is invoked.

.coNP Function @ from-list
.synb
.mets << object .'['from-list << list ']'
.syne
.desc
If a
.code from-list
structure function is defined for a structure type, it is called in certain
situations with an argument which is a list object. The function's purpose
is to construct a new instance of the structure type, derived from that
list.

The purpose of this function is to allow sequence processing operations
such as
.code mapcar
and
.code remove
to operate on a structure object as if it were a sequence, and return a
transformed sequence of the same type.  This is analogous to the way such
functions can operate on a vector or string, and return a vector or string.

If a structure object behaves as a sequence thanks to providing
.codn car ,
.code cdr
and
.code nullify
methods, but does not have a
.code from-list
function, then those sequence-processing operations which return a sequence
will always return a plain list of items.

.coNP Function @ derived
.synb
.mets << object .'['derived < supertype << subtype ']'
.syne
.desc
If a structure type supports a function called
.metn derived ,
this function is called whenever a new type is defined which names
that type as its supertype.

The function is called with two arguments which are both struct types.
The
.meta supertype
argument gives the type that is being inherited from.
The
.meta subtype
gives the new type that is inheriting from
.metn supertype .

When a new structure type is defined, its list of immediate
supertypes is considered. For each of those supertypes which defines the
.code derived
function, the function is invoked.

The function is not retroactively invoked. If it is defined for
a structure type from which subtypes have already been derived,
it is not invoked for those existing subtypes.

If
.meta derived
directly inherits
.meta supertype
more than once, it is not specified whether this function is called
once, or multiple times.

Note: the
.meta supertype
parameter exists because the
.code derived
function is itself inherited. If the same version of this function is shared by
multiple structure types due to inheritance, this argument informs the function
which of those types it is being invoked for.

.coNP Methods @ iter-begin and @ iter-reset
.synb
.mets << object .(iter-begin)
.mets << object .(iter-reset << iter )
.syne
.desc
If an object supports the
.code iter-begin
method, it is considered iterable; the
.code iterable
function will return
.code t
if invoked on this object.

The responsibility of the
.code iter-begin
method is to return an iterator object: an object which supports
certain special methods related to iteration, according to one of two
protocols, described below.

The
.code iter-reset
method is optional. It is similar to
.code iter-begin
but takes an additional
.meta iter
argument, an iterator object that was previously returned by the
.code iter-begin
method of the same
.metn object .

If
.code iter-reset
determines that
.meta iter
can be re-used for a new iteration, then it can suitably mutate the
state of
.meta iter
and return it.  Otherwise, it behaves like
.code iter-begin
and returns a new iterator.

There are two protocols for iteration: the fast protocol, and the canonical
protocol.
Both protocols require the iterator object returned by the
.code iter-begin
method to provide the methods
.code iter-item
and
.codn iter-step .
If the iterator also provides the
.code iter-more
method, then the protocol which applies is the canonical protocol. If
that method is absent, then the fast protocol is followed.

Under the fast protocol, the
.code iter-more
method does not exist and is not involved. The iterable object's
.code iter-begin
method must return
.code nil
if the abstract sequence is empty. If an iterator is returned, it is assumed
that an object can be retrieved from the iterator by invoking its
.code iter-item
method. The iterator's
.code iter-next
method should return
.code nil
if there are no more objects in the abstract sequence, or else it should
return an iterator that obeys the fast protocol (possibly itself).

Under the canonical protocol, the iterator implements the
.code iter-more
function. The iterable object's
.code iter-begin
always returns an iterator object. The iterator object's
.code iter-more
method is always invoked to determine whether another item is available
from the sequence. The iterator object's
.code iter-step
method is expected to return an iterator object which conforms to the
canonical protocol.

.coNP Method @ iter-item
.synb
.mets << object .(iter-item)
.syne
.desc
The
.code iter-item
method is invoked on an iterator
.meta object
to retrieve the next item in the sequence.

Under the fast protocol, it
is assumed that if
.meta object
was returned by an iterable object's
.code iter-begin
method, or by an iterator's
.code iter-step
method, that an item is available. This method will be unconditionally invoked.

Under the canonical protocol for iteration, the
.code iter-more
method will be invoked on
.meta object
first. If that method yields true, then
.code iter-item
is expected to yield the next available item in the sequence.

Note: calls to the
.code iter-item
function, with
.meta object
as its argument, invoke the
.code iter-item
method. It is possible for an application to call
.code iter-item
through this function or directly as a method call
without first calling
.codn iter-more .
No iteration mechanism in the \*(TL standard library behaves this way.
If the iterator
.meta object
has no more items available and
.code iter-more
is invoked anyway, no requirements apply to its behavior or return value.

.coNP Method @ iter-step
.synb
.mets << object .(iter-step)
.syne
.desc
The
.code iter-step
method is invoked on an iterator object to produce an iterator object for the
remainder of the sequence, excluding the current item.

Under the fast iteration protocol, this method returns
.code nil
if there are no more items in the sequence.

Under the canonical iteration protocol, this method always returns
an iterator object. If no items remain in the sequence, then that
iterator object's
.code iter-more
method returns
.codn nil .
Furthermore, under this protocol,
.code iter-step
is not called if
.code iter-more
returns
.codn nil .

Note: calls to the
.code iter-step
function, with
.meta object
as its argument, invoke the
.code iter-step
method. It is possible for an application to call
.code iter-step
through this function or directly as a method call
without first calling
.codn iter-more .
No iteration mechanism in the \*(TL standard library behaves this way.
If the iterator
.meta object
has no more items available and
.code iter-step
is invoked anyway, no requirements apply to its behavior or return value.

.coNP Method @ iter-more
.synb
.mets << object .(iter-more)
.syne
.desc
If an iterator
.meta object
returned by
.code iter-begin
supports the
.code iter-more
method, then the canonical iteration protocol applies to that iteration
session. All subsequent iterators that are involved in the iteration
are assumed to conform to the protocol and should implement the
.code iter-more
method also. The behavior is unspecified otherwise.

The
.code iter-more
method is used to interrogate an iterator whether more unvisited items
remain in the sequence. This method does not advance the iteration,
and does not change the state of the iterator. It is idempotent: if it is
called multiple times without any intervening call to any other method,
it yields the same value.

If an iterator does not implement the
.code iter-more
method, then if the
.code iter-more
function is applied to that iterator, it unconditionally returns
.codn t .

.SS* Sequence Manipulation

Functions in this category uniformly manipulate abstract sequences. Lists,
strings and vectors are sequences.

Structure objects can behave
like sequences, either list-like or vector-like sequences, if they have
certain methods: see the previous section Special Structure Functions.

Moreover, hash tables behave like sequences of key-value entries represented by
.code cons
pairs. Not all sequence-processing functions accept hash table sequences.

Additionally, some sequence-processing functions work not only with sequences
but with all iterable objects: objects that can be used as arguments to the
.code iter-begin
function. Such arguments are called
.meta iterable
rather than
.metn sequence ,
possibly abbreviated to
.meta iter
with or without a numeric suffix.
Hash tables are always supported if they appear as
.meta iterable
arguments.

.coNP Function @ seqp
.synb
.mets (seqp << object )
.syne
.desc
The function
.code seqp
returns
.code t
if
.meta object
is a sequence, otherwise
.codn nil .

Lists, vectors and strings are sequences. The object
.code nil
denotes
the empty list and so is a sequence.

Objects of type
.code buf
and
.code carray
are sequences, as are hash tables.

Structures which implement the
.code length
or
.code car
methods are considered sequences.

No other objects are sequences. However, future revisions of
the language may specify additional objects that are sequences.

.coNP Function @ iterable
.synb
.mets (iterable << object )
.syne
.desc
The
.code iterable
function returns
.code t
if
.meta object
is iterable, otherwise
.codn nil .

If
.meta object
is a sequence according to the
.code seqp
function, then it is iterable.

If
.meta object
is a structure which supports the
.code iter-begin
method, then it is iterable.

Additional objects that are not sequences are also iterable:
numeric or character ranges, and numbers. Future revisions
of the language may specify additional iterable objects.

.coNP Function @ make-like
.synb
.mets (make-like < list << object )
.syne
.desc
The
.meta list
argument must be a list.  If
.meta object
is a sequence type,
then
.meta list
is converted to the same type of sequence and returned.
Otherwise the original
.meta list
is returned.

Conversion is supported to string and vector type.

Conversion to a structure type is possible for structures. If
.meta object
is an object of a structure type which has a static function
.codn from-list ,
then
.code make-like
calls that function, passing to it, and the resulting value is returned.
.meta list
and returns whatever value that function returns.

If
.meta object
is a
.codn carray ,
then
.meta list
is passed to the
.code carray-list
function, and the resulting value is returned. The second argument in the
.code carray-list
call is the element type taken from
.metn object .
The third argument is
.codn nil ,
indicating that the resulting
.code carray
is not to be null terminated.

Note: the
.code make-like
function is a helper which supports the development of
unoptimized versions of a generic function that accepts any type of
sequence as input, and produces a sequence of the same type as output.
The implementation of such a function can internally accumulate a list, and
then convert the resulting list to the same type as an input value
by using
.codn make-like .

.coNP Functions @, list-seq @ vec-seq and @ str-seq
.synb
.mets (list-seq << iterable )
.mets (vec-seq << iterable )
.mets (str-seq << iterable )
.syne
.desc
The
.codn list-seq ,
.code vec-seq
and
.code str-seq
functions convert an iterable object of any type into a list, vector
or string, respectively.

The list returned by
.code list-seq
is lazy.

The
.code list-seq
and
.code vec-seq
iterate the items of
.meta iterable
and accumulate these items into a new list or vector.

The
.code str-seq
similarly iterates the items of
.metn iterable ,
requiring them to be a mixture of characters and strings.

.coNP Functions @ length and @ len
.synb
.mets (length << iterable )
.mets (len << iterable )
.syne
.desc
The
.code length
function returns the number of items contained in
.metn iterable .

The
.code len
function is a synonym of
.codn length .

An attempt to calculate the length of infinite lazy lists will not terminate.
Iterable objects representing infinite ranges, such as integers and characters
are invalid arguments.

.coNP Function @ empty
.synb
.mets (empty << iterable )
.syne
.desc
If
.meta iterable
is a suitable argument for the
.code length
function, then the
.code empty
Returns
.code t
if
.mono
.meti (length << iterable )
.onom
is zero, otherwise
.codn nil .

The
.code empty
function also supports certain objects not suitable as arguments for
.codn length .

An infinite lazy list is not empty, and so
.code empty
returns
.code nil
for such an object.

The function also returns
.code nil
for iterable objects representing non-empty spaces, even if
those spaces are infinite. For instance
.code "(empty 0)"
yields
.code nil
because the set of integers beginning with 0 isn't empty.

.coNP Function @ nullify
.synb
.mets (nullify << iterable )
.syne
.desc
The
.code nullify
function returns
.code nil
if
.meta iterable
denotes an empty sequence.
Otherwise, if
.meta iterable
is not an empty sequence, or isn't a sequence, then
.meta iterable
itself is returned.

If
.meta iterable
is a structure object which supports the
.code nullify
method, then that method is called. If it returns
.code nil
then
.code nil
is returned. If the
.code nullify
method returns a substitute object other than the
.meta iterable
object itself, then
.code nullify
is invoked on that returned substitute object.

Note: the
.code nullify
function is a helper to support unoptimized generic
traversal of sequences.  Thanks to the generalized behavior of
.codn cdr ,
non-list sequences can be traversed using
.codn cdr ,
similarly to proper lists, by checking for
.code cdr
returning the terminating value
.codn nil .
However, empty non-list sequences are handled incorrectly because
since they are not the
.code nil
object, they look non-empty under this paradigm of traversal.
The
.code nullify
function provides a correction: if the input sequence is filtered
through
.code nullify
then the subsequent list-like iteration works correctly.

Examples:

.verb
  ;; Incorrect for empty strings:

  (defun print-chars (string)
    (while string
      (prinl (pop string))))

  ;; Corrected with nullify:

  (defun print-chars (string)
    (let ((s (nullify string)))
      (while s
        (prinl (pop s)))))
.brev

Note: optimized generic iteration is available in the form of iteration
based on
.code iter-begin
rather than
.cod3 car / cdr
and
.codn nullify .

Examples:

.verb
  ;; Efficient with iterators,
  ;; at the cost of verbosity:

  (defun print-chars (string)
    (let ((i (iter-begin string)))
      (while (iter-more i)
        (prinl (iter-item s))
        (set s (iter-step s)))))

  ;; Using mapping function built on iterators:

  (defun print-chars (string)
    [mapdo prinl string])
.brev

.coNP Accessor @ sub
.synb
.mets (sub < sequence >> [ from <> [ to ]])
.mets (set (sub < sequence >> [ from <> [ to ]]) << new-val )
.syne
.desc
The
.code sub
function extracts a slice from input sequence
.metn sequence .
The slice is
a sequence of the same type as
.metn sequence .

If the
.meta from
argument is omitted, it defaults to
.codn 0 .
If the
.meta to
parameter is
omitted, it defaults to
.codn t .
Thus
.code "(sub a)"
means
.codn "(sub a 0 t)" .

The following semantic equivalence exists between a call to the
.code sub
function and
the DWIM-bracket syntax, except that
.code sub
is an ordinary function call form, which doesn't apply the
Lisp-1 evaluation semantics to its arguments:

.verb
  ;; from is not a list
  (sub seq from to) <--> [seq from..to]
.brev

The description of the
.code dwim
operator\(emin particular, the section
on Range Indexing\(emexplains the semantics of the range specification.

The output sequence may share structure with the input sequence.

If
.meta sequence
is a
.code carray
object, then the function behaves like
.codn carray-sub .

If
.meta sequence
is a
.code buf
object, then the function behaves like
.codn buf-sub .

If
.meta sequence
is a structure, it must support the
.code lambda
method. The
.code sub
operation is transformed into a call to the
.code lambda
method according to the following equivalence:

.verb
  (sub o from to) <--> o.(lambda (rcons from to))
  (sub o : to)    <--> o.(lambda (rcons : to))
  (sub o from)    <--> o.(lambda (rcons from :))
  (sub o)         <--> o.(lambda (rcons : :))
.brev

That is to say, the
.meta from
and
.code to
arguments are converted to range object. If either argument
is missing, the symbol
.code :
is used for the corresponding element of the range.

When a
.code sub
form is used as a syntactic place, that place denotes a slice of
.metn seq .
The
.meta seq
argument must be itself be syntactic place, because
receives a new value, which may be different from its original value in
cases when
.meta seq
is a list.

Overwriting that slice is equivalent to using the
.code replace
function. The following equivalences give the semantics, except that
.codn x ,
.codn a ,
.code b
and
.code v
are evaluated only once, in left-to-right order:

.verb
  (set (sub x a b) v)  <-->  (progn (set x (replace x v a b))
                                    v)

  (del (sub x a b))    <-->  (prog1 (sub x a b)
                                    (set x (replace x nil a b)))
.brev

Note that the value of
.code x
is overwritten with the value returned by
.codn replace .
If
.code x
is a vector or string, then the return value of
.code replace
is just
.codn x :
the identity of the object doesn't change under mutation.
However, if
.code x
is a list, its identity changes when items are added to or removed from
the front of the list, and in those cases
.code replace
will return a value different from its first argument.
Similarly, if
.code x
is an object with a
.code lambda-set
method, that method's return value becomes the return value of
.code replace
and must be taken into account.

.coNP Function @ replace
.synb
.mets (replace < sequence < replacement-sequence >> [ from <> [ to ]])
.mets (replace < sequence < replacement-sequence << index-list )
.syne
.desc
The
.meta replace
function modifies
.meta sequence
in the ways described below.

The operation is destructive: it may work "in place" by modifying
the original sequence. The caller should retain the return value
and stop relying on the original input sequence.

The return value of
.code replace
is the modified
version of
.metn sequence .
This may be the same object as
.meta sequence
or it may be a newly allocated object.

Note that the form:

.verb
  (set seq (replace seq new fr to))
.brev

has the same effect on the variable
.code seq
as the form:

.verb
  (set [seq fr..to] new)
.brev

except that the former
.code set
form returns the entire modified sequence, whereas the latter
returns the value of the
.code new
argument.

The
.code replace
function has two invocation styles, distinguished by the
type of the third argument. If the third argument is a sequence, then it
is deemed to be the
.meta index-list
parameter of the second form.
Otherwise, if the third argument is missing, or is not a list, then
it is deemed to be the
.meta from
argument of the first form.

The first form of the replace function replaces a contiguous subsequence of the
.meta sequence
with
.metn replacement-sequence .
The replaced subsequence may be empty,
in which case an insertion is performed. If
.meta replacement-sequence
is empty
(for example, the empty list
.codn nil ),
then a deletion is performed.

If the
.meta from
and
.meta to
arguments are omitted, their values default
to
.code 0
and
.code t
respectively.

The description of the dwim operator\(emin particular, the section
on Range Indexing\(emexplains the semantics of the range specification.

The second form of the replace function replaces a subsequence of
elements from
.meta sequence
given by
.metn index-list ,
with their counterparts
from
.metn replacement-sequence .
This form of the replace function does not insert
or delete; it simply overwrites elements. If
.meta replacement-sequence
and
.meta index-list
are of different lengths, then the shorter of the two determines
the maximum number of elements which are overwritten.
Whenever a negative value occurs in
.meta index-list
the length of
.meta sequence
is added to that value.
Furthermore, similar restrictions apply on
.meta index-list
as under the
select function. Namely, the replacement stops when an index value
in
.meta index-list
is encountered which is out of range for
.metn sequence .
furthermore, if
.meta sequence
is a list, then
.meta index-list
must
be monotonically increasing, after consideration of the
displacement of negative values.

If
.meta replacement-sequence
shares storage with the target range of
.metn sequence ,
or, in the case when that range is resized by the
.code replace
operation, shares storage with any portion of
.meta sequence
above that range, then the effect of
.code replace
on either object is unspecified.

If
.meta sequence
is a
.code carray
object, then
.code replace
behaves like
.codn carray-replace .

If
.meta sequence
is a
.code buf
object, then
.code replace
behaves like
.codn buf-replace .

If
.meta sequence
is a structure, then the structure must support the
.code lambda-set
method. The
.code replace
operation is translated into a call of the
.code lambda-set
method according to the following equivalences:

.verb
  (replace o items from to)
  <--> o.(lambda-set (rcons from to) items)

  (replace o items index-list)
  <--> o.(lambda-set index-list items)
.brev

Thus, the
.meta from
and
.meta to
arguments are converted to single range object,
whereas an
.meta index-list
is passed as-is.
It is an error if the
.code from
argument is a sequence, indicating an
.metn index-list ,
and a
.code to
argument is also given; the situation is diagnosed. If either
.code from
or
.code to
are omitted, the range object contains the
.code :
symbol in the corresponding place:

.verb
  (replace o items from)
  <--> o.(lambda-set (rcons from :) items)

  (replace o items : to)
  <--> o.(lambda-set (rcons : to) items)

  (replace o items)
  <--> o.(lambda-set (rcons : :) items)
.brev

It is the responsibility of the object's
.code lambda-set
method to implement semantics consistent with the
description of
.codn replace .

.coNP Function @ take
.synb
.mets (take < count << sequence )
.syne
.desc
The
.code take
function returns
.meta sequence
with all except the first
.meta count
items removed.

If
.meta sequence
is a list, then
.code take
returns a lazy list which produces the first
.meta count
items of sequence.

For other kinds of sequences, including lazy strings,
.code take
works eagerly.

If
.meta count
exceeds the length of
.meta sequence
then a sequence is returned which has all the items.
This object may be
.meta sequence
itself, or a copy.

If
.meta count
is negative, it is treated as zero.

.coNP Functions @ take-while and @ take-until
.synb
.mets (take-while < predfun < sequence <> [ keyfun ])
.mets (take-until < predfun < sequence <> [ keyfun ])
.syne
.desc
The
.code take-while
and
.code take-until
functions return a prefix of
.meta sequence
whose items satisfy certain conditions.

The
.code take-while
function returns the longest prefix of
.meta sequence
whose elements, accessed through
.meta keyfun
satisfy the function
.metn predfun .

The
.meta keyfun
argument defaults to the identity function: the elements
of
.meta sequence
are examined themselves.

The
.code take-until
function returns the longest prefix of
.meta sequence
which consists of elements, accessed through
.metn keyfun ,
that do
.B not
satisfy
.meta predfun
followed by an element which does satisfy
.metn predfun .
If
.meta sequence
has no such prefix, then an empty sequence
is returned of the same kind as
.metn sequence .

If
.meta sequence
is a list, then these functions return a lazy list.

.coNP Function @ drop
.synb
.mets (drop < count << sequence )
.syne
.desc
The
.code drop
function returns
.meta sequence
with the first
.meta count
items removed.

If
.meta count
is negative, it is treated as zero.

If
.meta count
is zero, then
.meta sequence
is returned.

If
.meta count
exceeds the length of
.meta sequence
then an empty sequence is returned
of the same kind as
.metn sequence .

.coNP Functions @ drop-while and @ drop-until
.synb
.mets (drop-while < predfun < sequence <> [ keyfun ])
.mets (drop-until < predfun < sequence <> [ keyfun ])
.syne
.desc
The
.code drop-while
and
.code drop-until
functions return
.meta sequence
with a prefix of that sequence removed,
according to conditions involving
.meta predfun
and
.metn keyfun .


The
.code drop-while
function removes the longest prefix of
.meta sequence
whose elements, accessed through
.meta keyfun
satisfy the function
.metn predfun ,
and returns the remaining sequence.

The
.meta keyfun
argument defaults to the identity function: the elements
of
.meta sequence
are examined themselves.

The
.code drop-until
function removes the longest prefix of
.meta sequence
which consists of elements, accessed through
.metn keyfun ,
that do
.B not
satisfy
.meta predfun
followed by an element which does satisfy
.metn predfun .
A sequence of the remaining elements is
returned.

If
.meta sequence
has no such prefix, then a sequence
same as
.meta sequence
is returned, which may be
.meta sequence
itself or a copy.

.coNP Accessor @ last
.synb
.mets (last < sequence <> [ num ])
.mets (set (last < sequence <> [ num ]) << new-value)
.syne
.desc
The
.meta last
function returns a subsequence of
.meta sequence
consisting of the last
.meta num
of its elements, where
.meta num
defaults to 1.

If
.meta num
is zero or negative, then an empty sequence is returned.
If
.meta num
is positive, and greater than or equal to the length of sequence,
then sequence
.meta sequence
is returned.

If a
.code last
form is used as a place, then
.code sequence
must be a place. The following equivalence gives the semantics
of assignment to a
.codn last :

.verb
  (set (last x n) v)   <-->  (set (sub x (- (max n 0)) t) v)
.brev

A
.code last
place is deletable. The semantics of deletion may be understood
in terms of the following equivalence:

.verb
  (del (last x n))   <-->  (del (sub x (- (max n 0)) t))
.brev

.coNP Accessor @ butlast
.synb
.mets (butlast < sequence <> [ num ])
.mets (set (butlast < sequence <> [ num ]) << new-value )
.syne
.desc
The
.code butlast
function returns the prefix of
.meta sequence
consisting of a copy of it, with the last
.meta num
items removed.

The parameter
.meta num
defaults to 1
if an argument is omitted.

If
.meta sequence
is empty, an empty sequence is returned.

If
.meta num
is zero or negative, then
.meta sequence
is returned.

If
.meta num
is positive, and meets or exceeds the length of
.metn sequence ,
then an empty sequence is returned.

If a
.code butlast
form is used as a place, then
.meta sequence
must itself be a place. The following equivalence gives the semantics
of assignment to a
.codn last :

.verb
  (set (butlast x n) v)   <-->  (set (sub x 0 (- (max n 0))) v)
.brev

A
.code butlast
place is deletable. The semantics of deletion may be understood
in terms of the following equivalence:

.verb
  (del (last x n))   <-->  (del (sub x 0 (- (max n 0))))
.brev

Note: the \*(TL
.code take
function also computes the prefix of a list; however, it counts items
from the beginning, and provides lazy semantics which allow it
to work with infinite lists.

See also: the
.code butlastn
accessor, which operates on lists. That function has useful semantics for
improper lists and treats an atom as the terminator of a zero-length improper
list.

Dialect note: a destructive function similar to Common Lisp's
.code nbutlast
isn't provided. Assignment to a
.code butlast
form is destructive; Common Lisp doesn't support
.code butlast
as a place.

.coNP Function @ ldiff
.synb
.mets (ldiff < sequence << tail-sequence )
.syne
.desc
The
.code ldiff
function is a somewhat generalized version of the same-named classic Lisp
function found in traditional Lisp dialects.

The
.code ldiff
function supports the original
.code ldiff
semantics when both inputs are lists. It determines whether the
.meta tail-sequence
list is a structural suffix of
.metn sequence ;
which is to say: is
.meta tail-sequence
one of the
.code cons
cells which comprise
.metn sequence ?
If so, then a list is returned consisting of all the items of
.meta sequence
before
.metn tail-sequence :
a copy of
.meta sequence
with the
.meta tail-sequence
part removed, and replaced by the
.code nil
terminator. If
.meta tail-sequence
is
.code nil
or the lists are unrelated, then
.meta sequence
is returned.

The \*(TL
.code ldiff
function supports the following additional semantics.

.RS
.IP 1.
The basic description of
.code ldiff
is extended to work with list-like sequences, not
merely lists; that is to say, objects which support the
.code car
method.
.IP 2.
If
.meta sequence
is any kind of sequence, and
.meta tail-sequence
is any kind of empty sequence, then
.meta sequence
is returned.
.IP 3.
If either argument is an atom that is not a sequence,
.code ldiff
returns
.metn sequence .
.IP 4.
If
.meta sequence
is a list-like sequence, and
.meta tail-sequence
isn't, then the terminating atom of
.meta sequence
is determined. This atom is compared using
.code equal
to the
.meta tail-sequence
object. If they are equal, then a proper list is
returned containing the items of
.meta sequence
excluding the terminating atom.
.IP 5.
If both arguments are vector-like sequences, then
.code ldiff
determines whether
.meta sequence
has a suffix which is
.code equal
to
.metn tail-sequence .
If this is the case, then a sequence is returned, of the same kind as
.metn sequence ,
consisting of the items of
.meta sequence
before that suffix.
If
.meta tail-sequence
is not
.code equal
to a suffix of
.metn sequence ,
then
.meta sequence
is returned.
.IP 6
In all other cases,
.meta sequence
and
.meta tail-sequence
are compared with
.codn equal .
If the comparison is true,
.code nil
is returned, otherwise
.meta sequence
is returned.
.RE

.TP* Examples:

.verb
  ;;; unspecified: the compiler could make
  ;;; '(2 3) a suffix of '(1 2 3),
  ;;; or they could be separate objects.
  (ldiff '(1 2 3) '(2 3)) -> either (1) or (1 2 3)

  ;; b is the (1 2) suffix of a, so the ldiff is (1)
  (let* ((a '(1 2 3)) (b (cdr a)))
    (ldiff a b))
  -> (1)

  ;; Rule 5: strings and vector
  (ldiff "abc" "bc") -> "a"
  (ldiff "abc" nil) -> "abc"
  (ldiff #(1 2 3) #(3)) -> #(1 2)

  ;; Rule 5: mixed vector kinds
  (ldiff "abc" #(#\eb #\ec)) -> "abc"

  ;; Rule 6:
  (ldiff #(1 2 3) '(3)) -> #(1 2 3)

  ;; Rule 4:
  (ldiff '(1 2 3) #(3)) -> '(1 2 3)
  (ldiff '(1 2 3 . #(3)) #(3)) -> '(1 2 3)
  (ldiff '(1 2 3 . 4) #(3)) -> '(1 2 3 . 4)

  ;; Rule 6
  (ldiff 1 2) -> 1
  (ldiff 1 1) -> nil
.brev

.coNP Function @ search
.synb
.mets (search < haystack < needle >> [ testfun <> [ keyfun ]])
.syne
.desc
The
.code search
function determines whether the sequence
.meta needle
occurs as substring
within
.metn haystack ,
under the given comparison function
.meta testfun
and
key function
.metn keyfun .
If this is the case, then the zero-based position of
the leftmost occurrence of
.meta key
within
.meta haystack
is returned. Otherwise
.code nil
is returned to indicate that
.meta key
does not occur within
.metn haystack .
If
.meta key
is empty, then zero is always returned.

The arguments
.meta haystack
and
.meta needle
are sequences. They may not be hash tables.

If
.meta needle
is not empty, then it occurs at some position N within
.meta haystack
if
the first element of
.meta needle
matches the element at position N of
.metn haystack ,
the second element of
.meta needle
matches the element at position N+1 of
.meta haystack
and so forth, for all elements of
.metn needle .
A match between elements
is determined by passing each element through
.metn keyfun ,
and then comparing the resulting values using
.metn testfun .

If
.meta testfun
is supplied, it must be a function which can be
called with two arguments. If it is not supplied, it defaults to
.codn eql .

If
.meta keyfun
is supplied, it must be a function which can be called
with one argument. If it is not supplied, it defaults to
.codn identity .

.TP* Examples:

.verb
  ;; fails because 3.0 doesn't match 3
  ;; under the default eql function
  [search #(1.0 3.0 4.0 7.0) '(3 4)] -> nil

  ;; occurrence found at position 1:
  ;; (3.0 4.0) matches (3 4) under =
  [search #(1.0 3.0 4.0 7.0) '(3 4) =] -> 1

  ;; "even odd odd odd even" pattern
  ;; matches at position 2
  [search #(1 1 2 3 5 7 8) '(2 1 1 1 2) : evenp] -> 2

  ;; Case insensitive string search
  [search "abcd" "CD" : chr-toupper] -> 2

  ;; Case insensitive string search
  ;; using vector of characters as key
  [search "abcd" #(#\eC #\eD) : chr-toupper] -> 2
.brev

.coNP Function @ contains
.synb
.mets (contains < needle < haystack >> [ testfun <> [ keyfun ]])
.syne
.desc
The syntax of the
.code contains
function differs from that of
.codn search :
that the
.meta needle
and
.meta haystack
arguments are reversed. The semantics is identical.

.coNP Function @ rsearch
.synb
.mets (rsearch < haystack < needle >> [ testfun <> [ keyfun ])
.syne
.desc
The
.code rsearch
function is like
.code search
except for two differences.

Firstly, if
.meta needle
matches
.meta haystack
in multiple places,
.code rsearch
returns the right-most matching position rather than
the leftmost.

Secondly, if
.meta needle
is an empty sequence, then
.code rsearch
returns the length of
.codn haystack ,
thereby effectively declaring that the rightmost match for an empty
.meta needle
key occurs at the imaginary position past the element of
.metn haystack .

.coNP Functions @ ref and @ refset
.synb
.mets (ref < sequence << index )
.mets (refset < sequence < index << new-value )
.syne
.desc
The
.code ref
and
.code refset
functions perform array-like indexing into sequences, as well as
objects of type
.code buf
and
.codn carray .

If the
.meta sequence
parameter is a hash, then these functions perform
has retrieval and storage; in that case
.meta index
isn't restricted to an integer value.

If
.meta sequence
is a structure, it supports
.code ref
directly if it has a
.code lambda
method. The
.meta index
argument is passed to that method, and the resulting value is
returned.
If a structure lacks a
.code lambda
method, but has a
.code car
method, then
.code ref
treats it as a list, traversing the structure using
.cod3 car / cdr
operations. In the absence of support for these operations,
the function fails with an error exception.

Similarly, a structure supports
.code refset
directly if it has a
.code lambda-set
method. This gets called with
.meta index
and
.meta new-value
as arguments. Then
.meta new-value
is returned.
If a structure lacks a
.code lambda-set
method, then
.code refset
treats it as a list, traversing the structure using
.cod3 car / cdr
operations, and storing
.meta new-value
using
.codn rplaca .
In the absence of support for these operations,
the function fails with an error exception.

The
.code ref
function retrieves an element of
.metn sequence ,
whereas
.code refset
overwrites an
element of
.meta sequence
with a new value.

If
.meta sequence
is a sequence then
.meta index
argument must be an integer. The first element of the sequence
is indexed by zero. Negative values are permitted,
denoting backward indexing from the end of the sequence, such that
the last element is indexed by -1, the second last by -2 and so on.
See also the Range Indexing section under the
description of the
.code dwim
operator.

If
.meta sequence
is a list, then out-of-range indices, whether positive or negative,
are treated leniently by
.codn ref :
such accesses produce the value
.codn nil ,
rather than an error. For other sequence types, such accesses
are erroneous. For hashes, accesses to nonexistent elements
are treated leniently, and produce
.codn nil .

The
.code refset
function is strict for out-of-range indices over all sequences,
including lists. In the case of hashes, a
.code refset
of a nonexistent key creates the key.

The
.code refset
function returns
.codn new-value .

The following equivalences hold between
.code ref
and
.codn refset ,
and the DWIM bracket syntax, provided that
.meta idx
is a scalar index and
.meta sequence
is a sequence object, rather than a hash.

.verb
  (ref seq idx) <--> [seq idx]

  (refset seq idx new) <--> (set [seq idx] new)
.brev

The difference is that
.code ref
and
.code refset
are first class functions which
can be used in functional programming as higher order functions, whereas the
bracket notation is syntactic sugar, and
.code set
is an operator, not a function.
Therefore the brackets cannot replace all uses of
.code ref
and
.codn refset .

.coNP Function @ update
.synb
.mets (update < sequence << function )
.syne
.desc
The
.code update
function replaces each elements in
.meta sequence
in a hash table, with the result of
.meta function
being applied to that element value.

The
.meta sequence
is returned.

The
.meta sequence
may be a hash table. In that case,
.meta function
is invoked with each hash value, which is replaced with the function's return
value.

.coNP Functions @, remq @ remql and @ remqual
.synb
.mets (remq < object < sequence <> [ key-function ])
.mets (remql < object < sequence <> [ key-function ])
.mets (remqual < object < sequence <> [ key-function ])
.syne
.desc
The
.codn remq ,
.code remql
and
.code remqual
functions produce a new sequence based on
.metn sequence ,
removing the elements whose associated keys are
.codn eq ,
.code eql
or
.code equal
to
.metn object .

The input
.meta sequence
is unmodified, but the returned sequence may share substructure
with it. If no items are removed, it is possible that the return value
is
.meta sequence
itself.

If
.meta key-function
is omitted, then the element keys compared to
.meta object
are the elements themselves.
Otherwise,
.meta key-function
is applied to each element and the resulting value
is that element's key which is compared to
.metn object .

.coNP Functions @, remq* @ remql* and @ remqual*
.synb
.mets (remq* < object << sequence )
.mets (remql* < object << sequence )
.mets (remqual* < object << sequence )
.syne
.desc
The
.codn remq* ,
.code remql*
and
.code remqual*
functions are lazy analogs of
.codn remq ,
.code remql
and
.codn remqual .
Rather than computing the entire new sequence
prior to returning, these functions return a lazy list.

Caution: these functions can still get into infinite looping behavior.
For instance, in
.codn "(remql* 0 (repeat '(0)))" ,
.code remql
will keep consuming
the
.code 0
values coming out of the infinite list, looking for the first item that
does not have to be deleted, in order to instantiate the first lazy value.

.TP* Examples:
.verb
  ;; Return a list of all the natural numbers, excluding 13,
  ;; then take the first 100 of these.
  ;; If remql is used, it will loop until memory is exhausted,
  ;; because (range 1) is an infinite list.

  [(remql* 13 (range 1)) 0..100]
.brev

.coNP Functions @, keepq @ keepql and @ keepqual
.synb
.mets (keepq < object < sequence <> [ key-function ])
.mets (keepql < object < sequence <> [ key-function ])
.mets (keepqual < object < sequence <> [ key-function ])
.syne
.desc
The
.codn keepq ,
.code keepql
and
.code keepqual
functions produce a new sequence based on
.metn sequence ,
removing the items whose keys are not
.codn eq ,
.code eql
or
.code equal
to
.metn object .

The input
.meta sequence
is unmodified, but the returned sequence may share substructure
with it. If no items are removed, it is possible that the return value
is
.meta sequence
itself.

The optional
.meta key-function
is applied to each element from the
.meta sequence
to convert it to a key which is compared to
.metn object .
If
.meta key-function
is omitted, then each element itself of
.meta sequence
is compared to
.metn object .

.coNP Functions @, remove-if @, keep-if @ remove-if* and @ keep-if*
.synb
.mets (remove-if < predicate-function < sequence <> [ key-function ])
.mets (keep-if < predicate-function < sequence <> [ key-function ])
.mets (remove-if* < predicate-function < sequence <> [ key-function ])
.mets (keep-if* < predicate-function < sequence <> [ key-function ])
.syne
.desc
The
.code remove-if
function produces a sequence whose contents are those of
.meta sequence
but with those elements removed which satisfy
.metn predicate-function .
Those elements which are not removed appear in the same order.
The result sequence may share substructure with the input sequence,
and may even be the same sequence object if no items are removed.

The optional
.meta key-function
specifies how each element from the
.meta sequence
is transformed to an argument to
.metn predicate-function .
If this argument is omitted
then the predicate function is applied to the elements directly, a behavior
which is identical to
.meta key-function
being
.codn "(fun identity)" .

The
.code keep-if
function is exactly like
.codn remove-if ,
except the sense of
the predicate is inverted. The function
.code keep-if
retains those items
which
.code remove-if
will delete, and removes those that
.code remove-if
will preserve.

The
.code remove-if*
and
.code keep-if*
functions are like
.code remove-if
and
.codn keep-if ,
but produce lazy lists.

.TP* Examples:
.verb
  ;; remove any element numerically equal to 3.
  (remove-if (op = 3) '(1 2 3 4 3.0 5)) -> (1 2 4 5)

  ;; remove those pairs whose first element begins with "abc"
  [remove-if (op equal [@1 0..3] "abc")
             '(("abcd" 4) ("defg" 5))
             car]
  -> (("defg" 5))

  ;; equivalent, without test function
  (remove-if (op equal [(car @1) 0..3] "abc")
             '(("abcd" 4) ("defg" 5)))
  -> (("defg" 5))
.brev

.coNP Functions @, countqual @ countql and @ countq
.synb
.mets (countq < object << iterable )
.mets (countql < object << iterable )
.mets (countqual < object << iterable )
.syne
.desc
The
.codn countq ,
.code countql
and
.code countqual
functions count the number of objects
in
.meta iterable
which are
.codn eq ,
.code eql
or
.code equal
to
.metn object ,
and return the count.

.coNP Function @ count-if
.synb
.mets (count-if < predicate-function < iterable <> [ key-function ])
.syne
.desc
The
.code count-if
function counts the number of elements of
.meta iterable
which satisfy
.meta predicate-function
and returns the count.

The optional
.meta key-function
specifies how each element from
.meta iterable
is transformed to an argument to
.metn predicate-function .
If this argument is omitted
then the predicate function is applied to the elements directly, a behavior
which is identical to
.meta key-function
being
.codn "(fun identity)" .

.coNP Functions @, posq @ posql and @ posqual
.synb
.mets (posq < object << sequence )
.mets (posql < object << sequence )
.mets (posqual < object << sequence )
.syne
.desc
The
.codn posq ,
.code posql
and
.code posqual
functions return the zero-based position of the
first item in
.meta sequence
which is, respectively,
.codn eq ,
.code eql
or
.code equal
to
.metn object .

.coNP Functions @ pos and @ pos-if
.synb
.mets (pos < key < sequence >> [ testfun <> [ keyfun ]])
.mets (pos-if < predfun < sequence <> [ keyfun ])
.syne
.desc
The
.code pos
and
.code pos-if
functions search through
.meta sequence
for an item which matches
.metn key ,
or satisfies the predicate function
.metn predfun ,
respectively.
They return the zero-based position of the matching item.

The
.meta keyfun
argument specifies a function which is applied to the elements
of
.meta sequence
to produce the comparison key. If this argument is omitted,
then the untransformed elements of
.meta sequence
are examined.

The
.code pos
function's
.meta testfun
argument specifies the test function which
is used to compare the comparison keys from
.meta sequence
to
.metn key .
If this argument is omitted, then the
.code equal
function is used.
The position of the first element
.meta sequence
whose comparison key (as
retrieved by
.metn keyfun )
matches the search (under
.metn testfun )
is
returned. If no such element is found,
.code nil
is returned.

The
.code pos-if
function's
.meta predfun
argument specifies a predicate function
which is applied to the successive comparison keys taken from
.meta sequence
by applying
.meta keyfun
to successive elements. The position of
the first element for which
.meta predfun
yields true is returned. If
no such element is found,
.code nil
is returned.

.coNP Functions @, rposq @, rposql @, rposqual @ rpos and @ rpos-if
.synb
.mets (rposq < object << sequence )
.mets (rposql < object << sequence )
.mets (rposqual < object << sequence )
.mets (rpos < key < sequence >> [ testfun <> [ keyfun ]])
.mets (rpos-if < predfun < sequence <> [ keyfun ])
.syne
.desc
These functions are counterparts of
.codn rposq ,
.codn rposql ,
.codn rposqual ,
.code rpos
and
.code rpos-if
which report position of the right-most matching item,
rather than the left-most.

.coNP Functions @ pos-max and @ pos-min
.synb
.mets (pos-max < sequence >> [ testfun <> [ keyfun ]])
.mets (pos-min < sequence >> [ testfun <> [ keyfun ]])
.syne
.desc
The
.code pos-min
and
.code pos-max
functions implement exactly the same algorithm; they
differ only in their defaulting behavior with regard to the
.meta testfun
argument.  If
.meta testfun
is not given, then the pos-max function defaults
.meta testfun
to the
.code greater
function, whereas
.code pos-min
defaults it to the
.code less
function.

If
.meta sequence
is empty, both functions return
.codn nil .

Without a
.meta testfun
argument, the
.code pos-max
function finds the zero-based
position index of the numerically maximum value occurring in
.metn sequence ,
whereas
.code pos-min
without a
.meta testfun
argument finds the index of the minimum
value.

If a
.meta testfun
argument is given, the two functions are equivalent.
The
.meta testfun
function must be callable with two arguments.
If
.meta testfun
behaves like a greater-than comparison, then
.code pos-max
and
.code pos-min
return the index of the maximum element. If
.meta testfun
behaves like a
.code less-than
comparison, then the functions return
the index of the minimum element.

The
.meta keyfun
argument defaults to the
.code identity
function. Each element
from
.meta sequence
is passed through this one-argument function, and
the resulting value is used in its place.

If a sequence contains multiple equivalent maxima,
whether the position of the leftmost or rightmost such maximum is reported
depends on whether
.meta testfun
compares for strict inequality, or whether it reports true for
equal arguments also. Under the default
.metn testfun ,
which is
.codn less ,
the
.code pos-max
function will return the position leftmost of a duplicate set of maximum
elements. To find the rightmost of the maxima, the
.code lequal
function can be substituted. Analogous reasoning applies to other
test functions.

.coNP Function @ mismatch
.synb
.mets (mismatch < left-seq < right-seq >> [ testfun <> [ keyfun ]])
.syne
.desc
The
.code mismatch
function compares corresponding elements from the sequences
.meta left-seq
and
.metn right-seq ,
returning the position at which the first mismatch occurs.

If the sequences are of the same length, and their corresponding
elements are the same, then
.code nil
is returned.

If one sequence is shorter than the other, and matches a prefix
of the other, then the mismatching position returned is one position
after the last element of the shorter sequence, the same value
as its length. An empty sequence is a prefix of every sequence.

The
.meta keyfun
argument defaults to the
.code identity
function. Each element
from
.meta sequence
is passed to
.meta keyfun
and the resulting value is used in its place.

After being converted through
.metn keyfun ,
items are then compared using
.metn testfun ,
which must accept two arguments, and defaults to
.codn equal .

.coNP Function @ where
.synb
.mets (where < function << iterable )
.syne
.desc
If
.meta iterable
is a sequence, the
.code where
function returns
a lazy list of the numeric indices of those of its elements which satisfy
.metn function .
The numeric indices appear in increasing order.

If
.meta iterable
is a hash, the following special behavior applies:
.code where
returns a lazy list of
of keys which have values which satisfy
.metn function .
These keys are not subject to an order.

.meta function
must be a function that can be called with one argument.
For each element of
.metn iterable ,
.meta function
is called with that element
as an argument.  If a
.cod2 non- nil
value is returned, then the zero-based index of
that element is added to a list. Finally, the list is returned.

.coNP Function @ rmismatch
.synb
.mets (rmismatch < left-seq < right-seq >> [ testfun <> [ keyfun ]])
.syne
.desc
Similarly to
.codn mismatch ,
the
.code rmismatch
function compares corresponding elements from the sequences
.meta left-seq
and
.metn right-seq ,
returning the position at which the first mismatch occurs.
All of the arguments have the same semantics as that of
.codn mismatch .

Unlike
.codn mismatch ,
.code rmismatch
compares the sequences right-to-left, finding the suffix
which they have in common, rather than prefix.

If the sequences match, then
.code nil
is returned. Otherwise, a negative index is returned giving the
mismatching position, regarded from the end. If the sequences
match only in the rightmost element, then -1 is returned. If they
match in two elements then -2 and so forth.

.coNP Functions @ starts-with and @ ends-with
.synb
.mets (starts-with < short-seq < long-seq >> [ testfun <> [ keyfun ]])
.mets (ends-with < short-seq < long-seq >> [ testfun <> [ keyfun ]])
.syne
.desc
The
.code starts-with
and
.code ends-with
functions compare corresponding elements from sequences
.meta short-seq
and
.metn long-seq .

The
.code starts-with
function returns
.code t
if
.meta short-seq
is prefix of
.metn long-seq ;
otherwise, it returns
.codn nil .

The
.code ends-with
function returns
.code t
if
.meta short-seq
is suffix of
.metn long-seq ;
otherwise, it returns
.codn nil .

Element from both sequences are mapped to comparison keys using
.metn keyfun ,
which defaults to
.codn identity .

Comparison keys are compared using
.meta testfun
which defaults to
.codn equal .

.coNP Function @ select
.synb
.mets (select < sequence >> { index-list | << function })
.syne
.desc
The
.code select
function returns a sequence, of the same kind as
.metn sequence ,
which consists of those elements of
.meta sequence
which are identified by
the indices in
.metn index-list ,
which may be a list or a vector.

If
.meta function
is given instead of
.metn index-list ,
then
.meta function
is invoked with
.meta sequence
as its argument. The return value is then taken as
if it were the
.meta index-list
argument .

If
.meta sequence
is a sequence, then
.meta index-list
consists of numeric
indices. The length of the sequence, as reported by the
.code length
function, is added to every
.meta index-list
value which is negative.
The
.code select
function stops collecting values upon encountering an index value which is
greater than or equal to the length of the sequence.
(Rationale: without
this strict behavior,
.code select
would not be able to terminate if
.meta index-list
is infinite.)

If
.meta sequence
is, more specifically, a list-like sequence, then
.meta index-list
must contain monotonically increasing
numeric values, even if no value is out of range, since the
.code select
function
makes a single pass through the list based on the assumption that indices
are ordered. (Rationale: optimization.)
This requirement for monotonicity applies to the values which
result after negative indices are displaced by the sequence length
Also, in this list-like sequence case, values taken from
.meta index-list
which are still negative after being displaced by the sequence length are
ignored.

If
.meta sequence
is a hash, then
.meta index-list
is a list of keys. A new hash is
returned which contains those elements of
.meta sequence
whose keys appear
in
.metn index-list .
All of
.meta index-list
is processed, even if it contains
keys which are not in
.metn sequence .
The nonexistent keys are ignored.

The
.code select
function also supports objects of type
.codn carray ,
in a manner similar to vectors. The indicated elements are extracted
from the input sequence, and a new
.code carray
is returned whose storage is initialized by converting the extracted
values back to the foreign representation.

.coNP Function @ reject
.synb
.mets (reject < sequence >> { index-list | << function })
.syne
.desc
The
.code reject
function returns a sequence, of the same kind as
.metn sequence ,
which consists of all those elements of
.meta sequence
which are not identified by the indices in
.metn index-list ,
which may be a list or a vector.

If
.meta function
is given instead of
.metn index-list ,
then
.meta function
is invoked with
.meta sequence
as its argument. The return value is then taken as
if it were the
.meta index-list
argument .

If
.code sequence
is a hash, then
.meta index-list
represents a list of keys. The
.code reject
function returns a duplicate of the hash, in which
the keys specified in
.meta index-list
do not appear.

Otherwise if
.meta sequence
is a vector-like sequence, then the behavior of
.code reject
may be understood by the following equivalence:

.verb
  (reject seq idx)  -->  (make-like
                           [apply append (split* seq idx)]
                           seq)
.brev

where it is to be understood that
.meta seq
is evaluated only once.

If
.meta sequence
is a list, then, similarly, the following equivalence applies:

.verb
  (reject seq idx)  -->  (make-like
                           [apply append* (split* seq idx)]
                           seq)
.brev

The input sequence is split into pieces at the indicated indices, such that
the elements at the indices are removed and do not appear in the pieces. The
pieces are then appended together in order, and the resulting list is coerced
into the same type of sequence as the input sequence.

.coNP Function @ relate
.synb
.mets (relate < domain-seq < range-seq <> [ default-val ])
.syne
.desc
The
.code relate
function returns a one-argument function which implements the relation formed
by mapping the elements of
.meta domain-seq
to the positionally corresponding elements of
.metn range-seq .
That is to say, the function searches through the sequence
.meta domain-seq
to determine the position where its argument occurs, using
.code equal
as the comparison function.
Then it returns the element from that position in the
.meta range-seq
sequence. This returned function is called the
.IR "relation function" .

If the relation function's argument is not found in
.metn domain-seq ,
then the behavior depends on the optional parameter
.metn default-val .
If an argument is given for
.metn default-val ,
then the relation function returns that value.
Otherwise, the relation function returns its argument.

Note: the
.code relate
function may be understood in terms of the following equivalences:

.verb
  (relate d r)  <-->  (lambda (arg)
                        (iflet ((p (posqual arg d)))
                          [r p]
                          arg))

  (relate d r v)  <-->  (lambda (arg)
                          (iflet ((p (posqual arg d)))
                            [r p]
                            v))
.brev

Note:
.code relate
may return a hash table instead of a function, if such an object
can satisfy the semantics required by the arguments.

.TP* Examples:

.verb
  (mapcar (relate "_" "-") "foo_bar")  ->  "foo-bar"

  (mapcar (relate "0123456789" "ABCDEFGHIJ" "X") "139D-345")
  -> "BJDXXDEF"

  (mapcar (relate '(nil) '(0)) '(nil 1 2 nil 4)) -> (0 1 2 0 4)
.brev

.coNP Function @ in
.synb
.mets (in < sequence < key >> [ testfun <> [ keyfun ]])
.mets (in < hash << key )
.syne
.desc
The
.code in
function tests whether
.meta key
is found inside
.meta sequence
or
.metn hash .

If the
.meta testfun
argument is specified, it specifies the function
which is used to comparison keys from the sequence
to
.metn key .
Otherwise the
.code equal
function is used.

If the
.meta keyfun
argument is specified, it specifies a function which
is applied to the elements of
.meta sequence
to produce the comparison keys. Without this
argument, the elements themselves are taken
as the comparison keys.

If the object being searched is a hash, then if neither of the arguments
.meta keyfun
nor
.meta testfun
is specified,
.code in
performs a hash lookup for
.codn key ,
returning
.code t
if the key is found,
.code nil
otherwise.
If either of
.meta keyfun
or
.meta testfun
is specified, then
.code in
performs an exhaustive search of the hash table, as if it were
a sequence of
.code cons
cells whose
.code car
fields are keys, and whose
.code cdr
keys are values. Thus to search by key, the
.code car
function must be specified as
.metn keyfun .

The
.code in
function returns
.code t
if it finds
.meta key
in
.meta sequence
or
.metn hash ,
otherwise
.codn nil .

.coNP Function @ partition
.synb
.mets (partition < sequence >> { index-list | index | << function })
.syne
.desc
If
.meta sequence
is empty, then
.code partition
returns an empty list, and the
second argument is ignored; if it is
.metn function ,
it is not called.

Otherwise,
.code partition
returns a lazy list of partitions of
.metn sequence .
Partitions are consecutive, non-overlapping, non-empty sub-strings of
.metn sequence ,
of the same kind as
.metn sequence ,
such that if these sub-strings are catenated together in their order
of appearance, a sequence
.code equal
to the original is produced.

If the second argument is of the form
.metn index-list ,
or if an
.meta index-list
was produced from the
.meta index
or
.meta function
arguments, each value in that list must be an integer. Each integer
value which is non-negative specifies the index position
given by its value. Each integer value which is negative
specifies an index position given by adding the length of
.meta sequence
to its value. The sequence index positions thus denoted by
.meta index-list
shall be strictly non-decreasing. Each successive element
is expected to designate an index position at least as high
as all previous elements, otherwise the behavior is unspecified.
Leading index positions which are (still) negative, or zero, are effectively
ignored.

If
.meta index-list
is empty then a one-element list containing the entire
.meta sequence
is returned.

If
.meta index-list
is an infinite lazy list, the function shall terminate if that
list eventually produces an index position which is greater than or equal to
the length of
.metn sequence .

If the second argument is a function, then this function is applied
to
.metn sequence ,
and the return value of this call is then used in place of the
second argument, which must be a single index value, which is then
taken as if it were the
.meta index
argument, or else a list of indices, which are taken as the
.meta index-list
argument.

If the second argument is an atom other than a function, it is assumed to be
an integer index, and is turned into an
.meta index-list
of one element.

After the
.meta index-list
is obtained as an argument, or determined from the
.meta index
or
.meta function
arguments, the
.code partition
function then divides
.meta sequence
according to the indices given by that list.
The first partition begins with the first element of
.metn sequence .
The second partition begins at the first position in
.metn index-list ,
and so on. Indices beyond the length of the sequence are ignored,
as are indices less than or equal to zero.

.TP* Examples:
.verb
  (partition '(1 2 3) 1) -> ((1) (2 3))

  ;; split the string where there is a "b"
  (partition "abcbcbd" (op where (op eql #\eb))) -> ("a" "bc"
                                                    "bc" "bd")
.brev

.coNP Functions @ split and @ split*
.synb
.mets (split < sequence >> { index-list | index | << function })
.mets (split* < sequence >> { index-list | index | << function })
.syne
.desc
If
.meta sequence
is empty, then both
.code split
and
.code split*
return an empty list, and the
second argument is ignored; if it is
.metn function ,
it is not called.

Otherwise,
.code split
returns a lazy list of pieces of
.metn sequence :
consecutive, non-overlapping, possibly empty sub-strings of
.metn sequence ,
of the same kind as
.metn sequence .
A catenation of these pieces in the order they appear would produce
a sequence that is
.code equal
to the original sequence.

The
.code split*
function differs from
.code split
in that the elements indicated by the split indices are removed.

The
.metn index ,
.metn index-list ,
and
.meta function
arguments are subject to the same restrictions and treatment
as the corresponding arguments of the
.code partition
function, with the following difference: the index positions indicated by
.code index-list
are required to be strictly increasing, rather than non-decreasing.

If the second argument is of the form
.metn index-list ,
or if an
.meta index-list
was produced from the
.meta index
or
.meta function
arguments, then the
.code split
function divides
.meta sequence
according to the indices indicated in the list. The first piece always begins
with the first element of
.metn sequence .
Each subsequent piece begins with the position indicated by
an element of
.metn index-list .
Negative indices are ignored.
If
.meta index-list
includes index zero,
then an empty first piece is generated.
If
.meta index-list
includes an index greater than or equal to the length of
.meta sequence
(equivalently, an index beyond the last element of the sequence)
then an additional empty last piece is generated.
The length of
.meta sequence
is added to any negative indices. An index which is still negative
after being thus displaced is discarded.

Note: the principal difference between
.code split
and
.code partition
is that
.code partition
does not produce empty pieces.

.TP* Examples:
.verb
  (split '(1 2 3) 1) -> ((1) (2 3))

  (split "abc" 0) -> ("" "abc")
  (split "abc" 3) -> ("abc" "")
  (split "abc" 1) -> ("a" "bc")
  (split "abc" '(0 1 2 3)) -> ("" "a" "b" "c" "")
  (split "abc" '(1 2)) -> ("a" "b" "c")

  (split "abc" '(-1 1 2 15)) -> ("a" "b" "c")

  ;; triple split at makes two additional empty pieces
  (split "abc" '(1 1 1)) -> ("a" "" "" "bc")

  (split* "abc" 0) -> ("" "bc") ;; "a" is removed

  ;; all characters removed
  (split* "abc" '(0 1 2)) -> ("" "" "" "")
.brev

.coNP Function @ partition*
.synb
.mets (partition* < sequence >> { index-list >> | index <> | function })
.syne
.desc
If
.meta sequence
is empty, then
.code partition*
returns an empty list, and the
second argument is ignored; if it is
.metn function ,
it is not called.

The
.metn index ,
.metn index-list ,
and
.meta function
arguments are subject to the same restrictions and treatment
as the corresponding arguments of the
.code partition
function, with the following difference: the index positions indicated by
.code index-list
are required to be strictly increasing, rather than non-decreasing.

If the second argument is of the form
.metn index-list ,
then
.code partition*
produces a
lazy list of pieces taken from
.metn sequence .
The pieces are formed by deleting from
.meta sequence
the elements at the positions given
in
.metn index-list ,
such that the pieces are the remaining non-empty sub-strings from
between the deleted elements, maintaining their order.

If
.meta index-list
is empty then a one-element list containing the entire
.meta sequence
is returned.

.TP* Examples:
.verb
  (partition* '(1 2 3 4 5) '(0 2 4)) -> ((2) (4))

  (partition* "abcd" '(0 3)) -> "bc"

  (partition* "abcd" '(0 1 2 3)) -> nil
.brev

.coNP Functions @ find and @ find-if
.synb
.mets (find < key < sequence >> [ testfun <> [ keyfun ]])
.mets (find-if < predfun >> { sequence | << hash }  <> [ keyfun ])
.syne
.desc
The
.code find
and
.code find-if
functions search through a sequence for an item which
matches a key, or satisfies a predicate function, respectively.

The
.meta keyfun
argument specifies a function which is applied to the elements
of
.meta sequence
to produce the comparison key. If this argument is omitted,
then the untransformed elements of the
.meta sequence
are searched.

The
.code find
function's
.meta testfun
argument specifies the test function which
is used to compare the comparison keys from
.meta sequence
to the search key.
If this argument is omitted, then the
.code equal
function is used.
The first element from the list whose comparison key (as retrieved by
.metn keyfun )
matches the search (under
.metn testfun )
is returned. If no such element is found,
.code nil
is returned.

The
.code find-if
function's
.meta predfun
argument specifies a predicate function
which is applied to the successive comparison keys pulled from the list
by applying
.meta keyfun
to successive elements. The first element
for which
.meta predfun
yields true is returned. If no such
element is found,
.code nil
is returned.

In the case of
.codn find-if ,
a hash table may be specified instead of a sequence.
The
.meta hash
is treated as if it were a sequence of hash key and hash
value pairs represented as cons cells, the
.code car
slots of which are the hash keys, and the
.code cdr
of which are the hash values.  If the caller doesn't specify a
.meta keyfun
then these cells are taken as their keys.

.coNP Functions @ rfind and @ rfind-if
.synb
.mets (rfind < key < sequence >> [ testfun <> [ keyfun ]])
.mets (rfind-if < predfun >> { sequence | << hash }  <> [ keyfun ])
.syne
.desc
The
.code rfind
and
.code rfind-if
functions are almost exactly like
.code find
and
.code find-if
except that if there are multiple matches for
.meta key
in
.metn sequence ,
they return the right-most element rather than
the leftmost.

In the case of
.code rfind-if
when a
.meta hash
is specified instead of a
.metn sequence ,
the function searches through the hash entries in the same order as
.codn find-if ,
but finds the last match rather than the first.
Note: hashes are inherently not ordered; the relative order of items in
a hash table can change when other items are inserted or deleted.

.coNP Functions @ find-max and @ find-min
.synb
.mets (find-max >> { sequence | << hash } >> [ testfun <> [ keyfun ]])
.mets (find-min >> { sequence | << hash } >> [ testfun <> [ keyfun ]])
.syne
.desc
The
.code find-min
and
.code find-max
function implement exactly the same algorithm; they
differ only in their defaulting behavior with regard to the
.meta testfun
argument.  If
.meta testfun
is not given, then the find-max function defaults it to
the
.code greater
function, whereas
.code find-min
defaults it to the
.code less
function.

Without a
.meta testfun
argument, the
.code find-max
function finds the numerically
maximum value occurring in
.metn sequence ,
whereas
.code pos-min
without a
.meta testfun
argument finds the minimum value.

If a
.meta testfun
argument is given, the two functions are equivalent.
The
.meta testfun
function must be callable with two arguments.
If
.meta testfun
behaves like a greater-than comparison, then
.code find-max
and
.code find-min
both return the maximum element. If
.meta testfun
behaves like a less-than comparison, then the functions return
the minimum element.

The
.meta keyfun
argument defaults to the
.code identity
function. Each element
from
.meta sequence
is passed through this one-argument function, and
the resulting value is used in its place for the purposes of the
comparison. However, the original element is returned.

A hash table may be specified instead of a sequence.
The
.meta hash
is treated as if it were a sequence of hash key and hash
value pairs represented as cons cells, the
.code car
slots of which are the hash keys, and the
.code cdr
of which are the hash values.  If the caller doesn't specify a
.meta keyfun
then these cells are taken as their keys. To find the hash
table's key-value cell with the maximum key, the
.code car
function can be specified as
.metn keyfun .
To find the entry holding the maximum value, the
.code cdr
function can be specified.

If there are multiple equivalent maxima, then under the default
.metn testfun ,
that being
.codn less ,
the leftmost one is reported. See the notes under
.code pos-max
regarding duplicate maxima.

.coNP Functions @, uni @, isec @ diff and @ symdiff
.synb
.mets (uni < iter1 < iter1 >> [ testfun <> [ keyfun ]])
.mets (isec < iter1 < iter1 >> [ testfun <> [ keyfun ]])
.mets (diff < iter1 < iter1 >> [ testfun <> [ keyfun ]])
.mets (symdiff < iter1 < iter2 >> [ testfun <> [ keyfun ]])
.syne
.desc
The functions
.codn uni ,
.codn isec ,
.code diff
and
.code symdiff
treat the sequences
.meta iter1
and
.meta iter2
as if they were sets.

They, respectively, compute the set union, set intersection,
set difference and symmetric difference of
.meta iter1
and
.metn iter2 ,
returning a new sequence.

The arguments
.meta iter1
and
.meta iter2
need not be of the same kind. They may be hash tables.

The returned sequence is of the same kind as
.metn iter1 .
If
.meta iter1
is a hash table, the returned sequence is a list.

For the purposes of these functions, an input which is a hash table
is considered as if it were a sequence of hash key and hash
value pairs represented as cons cells, the
.code car
slots of which are the hash keys, and the
.code cdr
of which are the hash values. This means that if no
.meta keyfun
is specified, these pairs are taken as keys.

Since the input sequences are defined as representing sets, they are assumed
not to contain duplicate elements. These functions are not required, but may,
de-duplicate the sequences.

The union sequence produced by
.code uni
contains all of the elements which occur in both
.meta iter1
and
.metn iter2 .
If a given element occurs exactly once only in
.meta iter1
or exactly once only in
.metn iter2 ,
or exactly once in both sequences, then it occurs exactly once in the union
sequence.  If a given element occurs at least once in either
.metn iter1 ,
.meta iter2
or both, then it occurs at least once in the union sequence.

The intersection sequence produced by
.code isec
contains all of the elements which occur in both
.meta iter1
and
.metn iter2 .
If a given element occurs exactly once in
.meta iter1
and exactly once in
.metn iter2 ,
then in occurs exactly once in the intersection sequence.
If a given element occurs at least once in
.meta iter1
and at least once in
.metn iter2 ,
then in occurs at least once in the intersection sequence.

The difference sequence produced by
.code diff
contains all of the elements which occur in
.meta iter1
but do not occur in
.metn iter2 .
If an element occurs exactly once in
.meta iter1
and does not occur in
.metn iter2 ,
then it occurs exactly once in the difference sequence.
If an element occurs at least once in
.meta iter1
and does not occur in
.metn iter2 ,
then it occurs at least once in the difference sequence.
If an element occurs at least once in
.metn iter2 ,
then it does not occur in the difference sequence.

The symmetric difference sequence produced by
.code symdiff
contains all of the elements of
.meta iter1
which do not occur in
.meta iter2
and
.IR "vice versa" :
it also contains all of the elements of
.meta iter2
which do not occur in
.metn iter1 .

Element equivalence is determined by a combination of
.meta testfun
and
.metn keyfun .
Elements are compared pairwise, and each element of a pair is passed through
.meta keyfun
function to produce a comparison value. The comparison values
are compared using
.metn testfun .
If
.meta keyfun
is omitted, then the
untransformed elements themselves are compared, and if
.meta testfun
is omitted,
then the
.code equal
function is used.

Note: a function similar to
.code diff
named
.code set-diff
exists. This became deprecated starting in \*(TX 184.
For the
.code set-diff
function, the requirement was specified to preserve the original
order of items from
.meta iter1
that survive into the output sequence.
This requirement is not documented for the
.code diff
function, but is
.I "de facto"
honored by the implementation for at as long as the
.code set-diff
synonym continues to be available.
The
.code set-diff
function doesn't support hash tables and is inefficient for vectors and
strings.

Note: these functions are not efficient for the processing of hash tables,
even when both inputs are hashes, the
.meta keyfun
argument is
.codn car ,
and
.meta testfun
matches the equality used by both hash table inputs.
If applicable, the operations
.codn hash-uni ,
.code hash-isec
and
.code hash-diff
should be used instead.

.coNP Functions @, mapcar @, mappend @ mapcar* and @ mappend*
.synb
.mets (mapcar < function << iterable *)
.mets (mappend < function << iterable *)
.mets (mapcar* < function << iterable *)
.mets (mappend* < function << iterable *)
.syne
.desc
When given only one argument, the
.code mapcar
function returns
.codn nil .
.meta function
is never called.

When given two arguments, the
.code mapcar
function applies
.meta function
to each elements of
.meta iterable
and returns a sequence of the resulting values
in the same order as the original values.
The returned sequence is the same kind as
.metn iterable ,
if possible. If the accumulated values cannot be
elements of that type of sequence, then a list is returned.

When additional sequences are given as arguments, this filtering behavior is
generalized in the following way:
.code mapcar
traverses the sequences in parallel,
taking a value from each sequence as an argument to the function. If there
are two lists,
.meta function
is called with two arguments and so forth.
The traversal is limited by the length of the shortest sequence.
The return values of the function are collected into a new sequence which is
returned. The returned sequence is of the same kind as the leftmost
input sequence, unless the accumulated values cannot be elements of that type of
sequence, in which case a list is returned.

The
.code mappend
function works like
.codn mapcar ,
with the following difference.
Rather than accumulating the values returned by the function into a sequence,
mappend expects the items returned by the function to be sequences which
are catenated with
.codn append ,
and the resulting sequence is returned. The returned sequence is of the same
kind as the leftmost input sequence, unless the values cannot be elements
of that type of sequence, in which case a list is returned.

The
.code mapcar*
and
.code mappend*
functions work like
.code mapcar
and
.codn mappend ,
respectively.
However, they return lazy lists rather than generating the entire
output list prior to returning.

.TP* Caveats:

Like
.codn mappend ,
.code mappend*
must "consume" empty lists. For instance,
if the function being mapped puts out a sequence of
.codn nil -s,
then the result must be the empty list
.codn nil ,
because
.code "(append nil nil nil nil ...)"
is
.codn nil .

But suppose that
.code mappend*
is used on inputs which are infinite lazy
lists, such that the function returns
.code nil
values indefinitely.
For instance:

.verb
  ;; Danger: infinite loop!!!
  (mappend* (fun identity) (repeat '(nil))) 
.brev

The
.code mappend*
function is caught in a loop trying to consume
and squash an infinite stream of
.codn nil -s,
and so doesn't return.

.TP* Examples:
.verb
  ;; multiply every element by two
  (mapcar (lambda (item) (* 2 item)) '(1 2 3)) -> (4 6 8)

  ;; "zipper" two lists together
  (mapcar (lambda (le ri) (list le ri)) '(1 2 3) '(a b c))
  -> '((1 a) (2 b) (3 c)))

  ;; like append, mappend allows a lone atom or a trailing atom:
  (mappend (fun identity) 3) -> (3)
  (mappend (fun identity) '((1) 2)) -> (1 . 2)

  ;; take just the even numbers
  (mappend (lambda (item) (if (evenp x) (list x))) '(1 2 3 4 5))
  -> (2 4)
.brev

.coNP Functions @, maprod @ maprend and @ maprodo
.synb
.mets (maprod < function << iterable *)
.mets (maprend < function << iterable *)
.mets (maprodo < function << iterable *)
.syne
.desc
The
.codn maprod ,
.code maprend
and
.code maprodo
functions resemble
.codn mapcar ,
.code mappend
and
.codn mapdo ,
respectively. When given no
.meta iterable
arguments or exactly one
.meta iterable
argument, they behave exactly like those three functions.

When two or more
.meta iterable
arguments are present,
.code maprod
differs from
.code mapcar
in the following way, as do the remaining functions
from their aforementioned counterparts.
Whereas
.code mapcar
iterates over the
.meta iterable
values in parallel, taking successive tuples of element
values and passing them to
.metn function ,
the
.code maprod
function iterates over all
.I combinations
of elements from the sequences: the Cartesian product. The
.code prod
suffix stands for "product".

If one or more
.meta iterable
arguments specify an empty sequence, then the Cartesian product is empty.
In this situation,
.meta function
is not called. The result of the function is then
.code nil
converted to the same kind of sequence as the leftmost
.metn iterable .

The
.code maprod
function collects the values into a list just as
.code mapcar
does. Just like
.codn mapcar ,
it converts the resulting list into the same kind of sequence
as the leftmost
.meta iterable
argument, if possible. For instance, if the resulting list is
a list or vector of characters, and the leftmost
.meta iterable
is a character string, then the list or vector of characters
is converted to a character string and returned.

The
.code maprend
function ("map product through function and append") iterates the
.meta iterable
element combinations exactly like
.codn maprod ,
passing them as arguments to
.metn function .
The values returned by
.meta function
are then treated exactly as by the
.code mappend
function. The return values are expected to be sequences which
are appended together as if by
.codn append ,
and the final result is converted to the same kind of sequence as the leftmost
.meta iterable
if possible.

The
.code maprodo
function, like
.codn mapdo ,
ignores the result of
.meta function
and returns
.codn nil .

The combination iteration gives priority to the rightmost
.metn iterable ,
which means that the rightmost element of each generated tuple varies
fastest: the tuples are traversed in "rightmost major" order.
This is made clear in the examples.

.TP* Examples

.verb
  [maprod list '(0 1 2) '(a b) '(i ii iii)]
  ->
  ((0 a i) (0 a ii) (0 a iii) (0 b i) (0 b ii) (0 b iii)
   (1 a i) (1 a ii) (1 a iii) (1 b i) (1 b ii) (1 b iii)
   (2 a i) (2 a ii) (2 a iii) (2 b i) (2 b ii) (2 b iii))

  ;; Vectors #(#\ea #\ex) #(#\ea #\ey) ... are appended
  ;; together resulting in #(#\ea #\ex #\ea #\ey ...)
  ;; which is converted to a string:

  [maprend vec "ab" "xy"] -> "axaybxby"

  ;; One of the sequences is empty, so the product is an
  ;; empty sequence of the same kind as the leftmost
  ;; sequence argument, thus an empty string:
  [maprend vec "ab" ""] -> ""
.brev

.coNP Function @ mapdo
.synb
.mets (mapdo < function << iterable *)
.syne
.desc
The
.code mapdo
function is similar to
.codn mapcar ,
but always returns
.codn nil .
It is useful
when
.meta function
performs some kind of side effect, hence the "do" in the name,
which is a mnemonic for the execution of imperative actions.

When only the
.meta function
argument is given,
.meta function
is never called,
and
.code nil
is returned.

If a single
.meta iterable
argument is given, then
.code mapdo
iterates over
.metn iterable ,
invoking
.meta function
on each element.

If two or more
.meta iterable
arguments are given, then
.code mapdo
iterates over
the sequences in parallel, extracting parallel tuples of items. These
tuples are passed as arguments to
.metn function ,
which must accept as many
arguments as there are sequences.

.coNP Functions @ transpose and @ zip
.synb
.mets (transpose << iterable )
.mets (zip << iterable *)
.syne
.desc
The
.code transpose
function performs a transposition on
.metn iterable .
This means that the
elements of
.meta iterable
must be iterable.  These iterables are understood to be
columns; transpose exchanges rows and columns, returning a sequence of the rows
which make up the columns.  The returned sequence is of the same kind as
.metn iterable ,
and the rows are also the same kind of sequence as the first column
of the original sequence. The number of rows returned is limited by the
shortest column among the sequences.

All of the input sequences (the elements of
.metn iterable )
must have elements
which are compatible with the first sequence. This means that if the first
element of
.meta iterable
is a string, then the remaining sequences must be
strings, or else sequences of characters, or of strings.

The
.code zip
function takes variable arguments, and is equivalent to calling
.code transpose
on a list of the arguments. The following equivalences hold:

.verb
   (zip . x) <--> (transpose x)

   [apply zip x] <--> (transpose x)
.brev

.TP* Examples:
.verb
  ;; transpose list of lists
  (transpose '((a b c) (c d e))) ->  ((a c) (b d) (c e))

  ;; transpose vector of strings:
  ;; - string columns become string rows
  ;; - vector input becomes vector output
  (transpose #("abc" "def" "ghij")) -> #("adg" "beh" "cfi")

  ;; error: transpose wants to make a list of strings
  ;; but 1 is not a character
  (transpose #("abc" "def" '(1 2 3))) ;; error!

  ;; String elements are catenated:
  (transpose #("abc" "def" ("UV" "XY" "WZ")))
  -> #("adUV" "beXY" "cfWZ")

  ;; Transpose list of ranges
  (transpose (list 1..4 4..8 8..12))
  -> ((1 4 8) (2 5 9) (3 6 10))

  (zip '(a b c) '(c d e)) ->  ((a c) (b d) (c e))
.brev

.coNP Functions @, window-map @ window-mappend and @ window-mapdo
.synb
.mets (window-map < range < boundary < function << sequence )
.mets (window-mappend < range < boundary < function << sequence )
.mets (window-mapdo < range < boundary < function << sequence )
.syne
.desc
The
.code window-map
and
.code window-mappend
functions process the elements of
.meta sequence
by passing arguments derived from each successive element to
.metn function .
Both functions return, if possible, a sequence of the same kind as
.codn sequence ,
otherwise a list.

Under
.codn window-map ,
values returned by
.meta function
are accumulated into a sequence of the same type as
.meta sequence
and that sequence is returned.  Under
.codn window-mappend ,
the values returned by the calls to
.meta function
are expected to be sequence which are appended together to
form the output sequence.

These functions are analogous to
.code mapcar
and
.codn mappend .
Unlike these, they operate only on a single sequence, and over this sequence
they perform a
.IR "sliding window mapping" ,
whose description follows.

The function
.code window-mappend
avoids accumulating a sequence, and instead returns
.codn nil ;
it is analogous to
.codn mapdo .

The argument to the
.meta range
parameter must be a positive integer, not exceeding 512.
This parameter specifies the amount of ahead/behind context on either
side of each element which is processed. It indirectly determines
the window size for the mapping. The window size is twice
.metn range ,
plus one. For instance if range is 2, then the window size is 5:
the element being processed lies at the center of the window, flanked
by two elements on either side, making five.

The
.meta function
argument must specify a function which accepts a number of arguments
corresponding to the window size. For instance if
.meta range
is 2,
making the window size 5,
then
.meta function
must accept 5 arguments. These arguments constitute the sliding
window being processed. Each time
.meta function
is called, the middle argument is the element being processed,
and the arguments surrounding it are its window.

When an element is processed from somewhere in the interior of
a sequence, where it is flanked on either side by at least
.meta range
elements, then the window is populated by those flanking elements
taken from
.metn sequence .

The
.meta boundary
parameter specifies the window contents which are used for the
processing of elements which are closer than
.meta range
to either end of the sequence.  The argument may be a sequence containing
at least twice
.meta range
number of elements (one less than the window size): if it has additional
elements, they are not used. If it is a list, it may be shorter than twice
.metn range .
The argument
may also be one of the two keyword symbols
.code :wrap
or
.codn :reflect ,
described below.

If
.meta boundary
is a sequence, it may be regarded as divided into two pieces of
.meta range
length. If it is a list of insufficient length, then missing elements
are supplied as
.code nil
to make two
.metn range 's
worth of elements. These two pieces then flank
.code sequence
on either end. The left half of
.meta boundary
is effectively prepended to the sequence, and the right half
effectively appended.
When the sliding window extends beyond the boundary of
.meta sequence
near its start or end, the window is populated from these
flanking elements obtained from
.metn boundary .

If
.meta boundary
is the keyword
.codn :wrap ,
then the sequence is effectively flanked by copies of itself on both
ends, repeated enough times to satisfy the window. For instance if
the sequence is
.code "(1 2 3)"
and the window size is 9 due to the value of
.meta range
being 7, then the behavior of
.code :wrap
is as if a
.meta boundary
were specified consisting of
.codn "(3 1 2 3 1 2 3 1)" .
The left flank is
.code "(3 1 2 3)"
and the right flank is
.code "(1 2 3 4)"
formed by repetitions of
.code "(1 2 3)"
surrounding it on either side, extending out to infinity, and chopped to
.metn range .

If
.meta boundary
is the keyword
.codn :reflect ,
then the sequence is effectively flanked by reversed copies of itself
on both ends, repeated enough times to satisfy the window.
For instance if the sequence is
.code "(1 2 3)"
and the window size is 9, then the behavior of
.code :wrap
is as if a
.meta boundary
were specified consisting of
.codn "(1 3 2 1 3 2 1 3)" .

.coNP Function @ interpose
.synb
.mets (interpose < sep << sequence )
.syne
.desc
The
.code interpose
function returns a sequence of the same type as
.metn sequence ,
in which the elements from
.meta sequence
appear with the
.meta sep
value inserted
between them.

If
.meta sequence
is an empty sequence or a sequence of length 1, then a
sequence identical to
.meta sequence
is returned. It may be a copy of
.meta sequence
or it may be
.meta sequence
itself.

If
.meta sequence
is a character string, then the value
.meta sep
must be a character.

It is permissible for
.metn sequence ,
or for a suffix of
.meta sequence
to be a lazy
list, in which case interpose returns a lazy list, or a list with a lazy
suffix.

.TP* Examples:
.verb
  (interpose #\e- "xyz") -> "x-y-z"
  (interpose t nil) -> nil
  (interpose t #()) -> #()
  (interpose #\ea "") -> ""
  (interpose t (range 0 0)) -> (0)
  (interpose t (range 0 1)) -> (0 t 1)
  (interpose t (range 0 2)) -> (0 t 1 t 2)
.brev

.coNP Functions @ reduce-left and @ reduce-right
.synb
.mets (reduce-left < binary-function < list
.mets \ \ \ \ \ \ \ \ \ \ \ \  >> [ init-value <> [ key-function ]])

.mets (reduce-right < binary-function < list
.mets \ \ \ \ \ \ \ \ \ \ \ \ \  >> [ init-value <> [ key-function ]])
.syne
.desc
The
.code reduce-left
and
.code reduce-right
functions reduce lists of operands specified
by
.meta list
and
.meta init-value
to a single value by the repeated application of
.metn binary-function .

An effective list of operands is formed by combining
.meta list
and
.metn init-value .
If
.meta key-function
is specified, then the items of
.meta list
are
mapped to new values through
.metn key-function ,
as if by
.codn mapcar .
If
.meta init-value
is supplied,
then in the case of
.codn reduce-left ,
the effective list of operands is formed by
prepending
.meta init-value
to
.metn list .
In the case of
.codn reduce-right ,
the effective operand list is produced by appending
.meta init-value
to
.metn list .
The
.meta init-value
isn't mapped through
.metn key-function .

The production of the effective list can be expressed like this,
though this is not to be understood as the actual implementation:

.verb
  (append (if init-value-present (list init-value))
          [mapcar (or key-function identity) list]))))
.brev

In the
.code reduce-right
case, the arguments to
.code append
are reversed.

If the effective list of operands is empty, then
.meta binary-function
is called
with no arguments at all, and its value is returned. This is the only
case in which
.meta binary-function
is called with no arguments; in all
remaining cases, it is called with two arguments.

If the effective list contains one item, then that item is returned.

Otherwise, the effective list contains two or more items, and is decimated as
follows.

Note that an
.meta init-value
specified as
.code nil
is not the same as a missing
.metn init-value ;
this means that the initial value is the object
.codn nil .
Omitting
.meta init-value
is the same as specifying a value of
.code :
(the colon symbol).
It is possible to specify
.meta key-function
while omitting an
.meta init-value
argument. This is achieved by explicitly specifying
.code :
as the
.meta init-value
argument.

Under
.codn reduce-left ,
the leftmost pair of operands is removed
from the list and passed as arguments to
.metn binary-function ,
in the same order
that they appear in the list, and the resulting value initializes an
accumulator. Then, for each remaining item in the list,
.meta binary-function
is invoked on two arguments: the current accumulator value, and the next element
from the list. After each call, the accumulator is updated with the return
value of
.metn binary-function .
The final value of the accumulator is returned.

Under
.codn reduce-right ,
the list is processed right to left.  The rightmost
pair of elements in the effective list is removed, and passed as arguments to
.metn binary-function ,
in the same order that they appear in the list. The
resulting value initializes an accumulator. Then, for each remaining item in
the list,
.meta binary-function
is invoked on two arguments:  the
next element from the list, in right to left order, and the current
accumulator value. After each call, the accumulator is updated with the return
value of
.metn binary-function .
The final value of the accumulator is returned.

.TP* Examples:
.verb
  ;;; effective list is (1) so 1 is returned
  (reduce-left (fun +) () 1 nil)  ->  1

  ;;; computes (- (- (- 0 1) 2) 3)
  (reduce-left (fun -) '(1 2 3) 0 nil) -> -6

  ;;; computes (- 1 (- 2 (- 3 0)))
  (reduce-right (fun -) '(1 2 3) 0 nil) -> 2

  ;;; computes (* 1 2 3)
  (reduce-left (fun *) '((1) (2) (3)) nil (fun first)) -> 6

  ;;; computes 1 because the effective list is empty
  ;;; and so * is called with no arguments, which yields 1.
  (reduce-left (fun *) nil)
.brev

.coNP Functions @, some @ all and @ none
.synb
.mets (some < sequence >> [ predicate-fun <> [ key-fun ]])
.mets (all < sequence >> [ predicate-fun <> [ key-fun ]])
.mets (none < sequence >> [ predicate-fun <> [ key-fun ]])
.syne
.desc
The
.codn some ,
.code all
and
.code none
functions apply a predicate test function
.meta predicate-fun
over a list of elements.  If the argument
.meta key-fun
is
specified, then elements of
.meta sequence
are passed into
.metn key-fun ,
and
.meta predicate-fun
is
applied to the resulting values. If
.meta key-fun
is omitted, the behavior is
as if
.meta key-fun
is the identity function. If
.meta predicate-fun
is omitted,
the behavior is as if
.meta predicate-fun
is the identity function.

These functions have short-circuiting semantics and return conventions similar
to the and and or operators.

The some function applies
.meta predicate-fun
to successive values
produced by retrieving elements of
.meta list
and processing them through
.metn key-fun .
If the list is empty, it returns
.codn nil .
Otherwise it returns the
first
.cod2 non- nil
return value returned by a call to
.meta predicate-fun
and
stops evaluating more elements. If
.meta predicate-fun
returns
.code nil
for all
elements, it returns
.metn nil .

The
.code all
function applies
.meta predicate-fun
to successive values
produced by retrieving elements of
.meta list
and processing them through
.metn key-fun .
If the list is empty, it returns
.codn t .
Otherwise, if
.meta predicate-fun
yields
.code nil
for any value, the
.code all
function immediately
returns without invoking
.meta predicate-fun
on any more elements.
If all the elements are processed, then the all function returns
the value which
.meta predicate-fun
yielded for the last element.

The
.code none
function applies
.meta predicate-fun
to successive values
produced by retrieving elements of
.meta list
and processing them through
.metn key-fun .
If the list is empty, it returns
.codn t .
Otherwise, if
.meta predicate-fun
yields
.cod2 non- nil
for any value, the none function
immediately returns nil. If
.meta predicate-fun
yields nil for all
values, the none function returns
.codn t .

.TP* Examples:

.verb
  ;; some of the integers are odd
  [some '(2 4 6 9) oddp] -> t

  ;; none of the integers are even
  [none '(1 3 4 7) evenp] -> t
.brev

.coNP Function @ multi
.synb
.mets (multi < function << sequence *)
.syne
.desc
The
.code multi
function distributes an arbitrary list processing function
.meta multi
over multiple sequences given by the
.meta list
arguments.

The
.meta sequence
arguments are first transposed into a single list of tuples. Each
successive element of this transposed list consists of a tuple of the
successive items from the lists. The length of the transposed list is that
of the shortest
.meta list
argument.

The transposed list is then passed to
.meta function
as an argument.

The
.meta function
is expected to produce a list of tuples, which are transposed
again to produce a list of lists which is then returned.

Conceptually, the input sequences are columns and
.meta function
is invoked on
a list of the rows formed from these columns. The output of
.meta function
is a transformed list of rows which is reconstituted into a list of columns.

.TP* Example:

.verb
  ;; Take three lists in parallel, and remove from all of them
  ;; them the element at all positions where the third list
  ;; has an element of 20.

  (multi (op remove-if (op eql 20) @1 third)
         '(1 2 3)
         '(a b c)
         '(10 20 30))

  -> ((1 3) (a c) (10 30))

  ;; The (2 b 20) "row" is gone from the three "columns".

  ;; Note that the (op remove if (op eql 20) @1 third)
  ;; expression can be simplified using the ap operator:
  ;;
  ;; (op remove-if (ap eql @3 20))
.brev

.coNP Functions @ sort and @ nsort
.synb
.mets (sort < sequence >> [ lessfun <> [ keyfun ]])
.mets (nsort < sequence >> [ lessfun <> [ keyfun ]])
.syne
.desc
The
.code nsort
function destructively sorts
.metn sequence ,
producing a sequence
which is sorted according to the
.meta lessfun
and
.meta keyfun
arguments.

The
.meta keyfun
argument specifies a function which is applied to elements
of the sequence to obtain the key values which are then compared
using the lessfun. If
.meta keyfun
is omitted, the identity function is used
by default: the sequence elements themselves are their own sort keys.

The
.meta lessfun
argument specifies the comparison function which determines
the sorting order. It must be a binary function which can be invoked
on pairs of keys as produced by the key function. It must
return a
.cod2 non- nil
value if the left argument is considered to be lesser
than the right argument. For instance, if the numeric function
.code <
is used
on numeric keys, it produces an ascending sorted order. If the function
.code >
is used, then a descending sort is produced. If
.meta lessfun
is omitted, then it defaults to the generic
.code less
function.

The
.code sort
function has the same argument requirements as
.code nsort
but is non-destructive: it returns a new object, leaving the input
.meta sequence
unmodified, as if a copy of the input object were made using the
function
.code copy
and then that copy were sorted in-place using
.codn nsort .

The
.code sort
and
.code nsort
functions are stable for sequences which are lists. This means that the
original order of items which are considered identical is preserved.
For strings and vectors,
.code sort
is not stable.

The
.code sort
and
.code nsort
functions can be applied to hashes. It produces meaningful behavior
for a hash table which contains
.I N
keys which are the integers from 0 to
.IR "N - 1" .
Such as hash is treated as if it were a vector. The values are sorted
and re-assigned to sorted order to the integer keys.
The behavior of
.code sort
is not specified for hashes whose contents do not conform to this convention.

Note:
.code nsort
was introduced in \*(TX 238. Prior to that version,
.code sort
behaved like
.codn nsort .

.coNP Function @ grade
.synb
.mets (grade < sequence >> [ lessfun <> [ keyfun ]])
.syne
.desc
The
.code grade
function returns a list of integer indices which indicate the position
of the elements of
.meta sequence
in sorted order.

The
.meta lessfun
and
.meta keyfun
arguments behave like those of the
.code sort
function.

The
.meta sequence
object is not modified.

The internal sort performed by
.code grade
is not stable. The indices of any elements considered equivalent under
.code lessfun
may appear in any order in the returned index sequence.

Note: the
.code grade
function is inspired by the "grade up" and "grade down" operators
in the APL language.

.TP* Examples:

.verb
  ;; Order of the 2 3 positions of the "l"
  ;; characters is not specified:

  [grade "Hello"] -> (0 1 2 3 4)
  [grade "Hello" >] -> (4 2 3 1 0)
.brev

.coNP Functions @ shuffle and @ nshuffle
.synb
.mets (shuffle < sequence <> [ random-state ])
.mets (nshuffle < sequence <> [ random-state ])
.syne
.desc
The
.code nshuffle
function pseudo-randomly rearranges the elements of
.metn sequence .
This is performed in place:
.meta sequence
object is modified.

The return value is
.meta sequence
itself.

The rearrangement depends on pseudo-random numbers obtained from the
.code rand
function. The
.meta random-state
argument, if present, is passed to that function.

The
.code nshuffle
function supports hash tables in a manner analogous to the way
.code nsort
supports hash tables; the same remarks apply as in the description
of that function.

The
.code shuffle
function has the same argument requirements and
semantics, but differs from
.code nshuffle
in that it avoids in-place modification of
.metn sequence :
a new, shuffled sequence is returned, as if a copy of
.meta sequence
were made using
.code copy
and then that copy were shuffled in-place and returned.

Note:
.code nshuffle
was introduced in \*(TX 238. Prior to that version,
.code shuffle
behaved like
.codn nshuffle .

.coNP Function @ sort-group
.synb
.mets (sort-group < sequence >> [ keyfun <> [ lessfun ]])
.syne
.desc
The
.code sort-group
function sorts
.meta sequence
according to the
.meta keyfun
and
.meta lessfun
arguments, and then breaks the resulting sequence into groups,
based on the equivalence of the elements under
.metn keyfun .

The following equivalence holds:

.verb
  (sort-group sq lf kf)

  <-->

  (partition-by kf (sort (copy sq) kf lf))
.brev

Note the reversed order of
.meta keyfun
and
.meta lessfun
arguments between
.code sort
and
.codn sort-group .

.coNP Function @ uniq
.synb
.mets (uniq << sequence )
.syne
.desc
The
.code uniq
function returns a sequence of the same kind as
.metn sequence ,
but with
duplicates removed. Elements of
.meta sequence
are considered equal under
the
.code equal
function. The first occurrence of each element is retained,
and the subsequent duplicates of that element, of any, are suppressed,
such that the order of the elements is otherwise preserved.

The
.code uniq
function is an alias for the one-argument case of
.codn unique .
That is to say, this equivalence holds:

.verb
  (uniq s) <--> (unique s)
.brev

.coNP Function @ unique
.synb
.mets (unique < sequence >> [ keyfun <> { hash-arg }* ])
.syne
.desc
The
.code unique
function is a generalization of
.codn uniq .
It returns a sequence of the same kind as
.metn sequence ,
but with duplicates removed.

If neither
.meta keyfun
nor
.metn hash-arg -s
are specified, then elements of sequence are considered equal under the
.code eql
function. The first occurrence of each element is retained,
and the subsequent duplicates of that element, of any, are suppressed,
such that the order of the elements is otherwise preserved.

If
.meta keyfun
is specified, then that function is applied to each element,
and the resulting values are compared for equality.
In other words, the behavior is as if
.meta keyfun
were the
.code identity
function.

If one or more
.metn hash-arg -s
are present, these specify the arguments for the construction of
the internal hash table used by
.codn unique .
The arguments are like those of the
.code hash
function.

.coNP Function @ tuples
.synb
.mets (tuples < length < sequence <> [ fill-value ])
.syne
.desc
The
.code tuples
function produces a lazy list which represents a reorganization
of the elements of
.meta sequence
into tuples of
.metn length ,
where
.meta length
must be a positive integer.

The length of the sequence might not be evenly divisible by the tuple length.
In this case, if a
.meta fill-value
argument is specified, then the last tuple
is padded with enough repetitions of
.meta fill-value
to make it have
.meta length
elements. If
.meta fill-value
is not specified, then the last tuple is left
shorter than
.metn length .

The output of the function is a list, but the tuples themselves are sequences
of the same kind as
.metn sequence .
If
.meta sequence
is any kind of list, they
are lists, and not lazy lists.

.TP* Examples:

.verb
  (tuples 3 #(1 2 3 4 5 6 7 8) 0) -> (#(1 2 3) #(4 5 6)
                                      #(7 8 0))
  (tuples 3 "abc") -> ("abc")
  (tuples 3 "abcd") -> ("abc" "d")
  (tuples 3 "abcd" #\ez) -> ("abc" "dzz")
  (tuples 3 (list 1 2) #\ez) -> ((1 2 #\ez))
.brev

.coNP Function @ partition-by
.synb
.mets (partition-by < function << sequence )
.syne
.desc
If
.meta sequence
is empty, then
.code partition-by
returns an empty list,
and
.meta function
is never called.

Otherwise,
.code partition-by
returns a lazy list of partitions of the sequence
.metn sequence .
Partitions are consecutive, non-empty sub-strings of
.metn sequence ,
of the same kind as
.metn sequence .

The partitioning begins with the first element of
.meta sequence
being placed into a partition.

The subsequent partitioning is done according to
.metn function ,
which is applied
to each element of
.metn sequence .
Whenever, for the next element, the function
returns the same value as it returned for the previous element, the
element is placed into the same partition. Otherwise, the next element
is placed into, and begins, a new partition.

The return values of the calls to
.meta function
are compared using the
.code equal
function.

.TP* Examples:

.verb
  [partition-by identity '(1 2 3 3 4 4 4 5)] -> ((1) (2) (3 3)
                                                 (4 4 4) (5))

  (partition-by (op = 3) #(1 2 3 4 5 6 7)) -> (#(1 2) #(3)
                                               #(4 5 6 7))
.brev

.SS* Open Sequence Traversal

Functions in this category perform efficient traversal of sequences.

There are two flavors of these functions: functions in the
.code iter-begin
group, and functions in the
.code seq-begin
group. The latter are obsolescent.

Application-defined iteration is possible via defining special methods on
structures. An object supports iteration by defining the special method
.code iter-begin
which is different from the
.code iter-begin
function. This special function returns an iterator object which supports
special methods
.codn iter-item ,
.code iter-more
and
.codn iter-step .
Two protocols are supported, one of which is more efficient by eliminating the
.code iter-more
method. Details are specified in the section
.BR "Special Structure Functions" .

.coNP Function @ iter-begin
.synb
.mets (iter-begin << seq )
.syne
.desc
The
.code iter-begin
function returns an iterator object specialized for the task of traversing the
.meta seq
object. The
.meta seq
argument may be any sequence. Additionally, it may be a character, number or
a numeric or character range.

Note: if
.meta seq
is a list-like sequence, then
.code iter-begin
may return
.meta seq
itself as the iterator. Likewise if
.meta seq
is a number.

A range is considered to be a numeric or character range if the
.code from
element is a number or character. The
.code to
is then required to to be either value which is comparable with that number
or character using the
.code <
function, or else it must be one of the two objects
.code t
or
.codn : ,
either of which indicate that the range is unbounded. In this unbounded range
case, the expressions
.code "(iter-begin X..:)"
and
.code "(iter-begin X..t)"
are equivalent to
.codn "(iter-begin X)" .

If
.meta seq
is a structure which supports the
.code iter-begin
method, then that method is called and its return value is returned.

.coNP Function @ iter-more
.synb
.mets (iter-more << iter )
.syne
.desc
The
.code iter-more
function returns
.code t
if there remain more elements to be traversed.
Otherwise it returns
.codn nil .

The
.meta iter
argument must be a valid iterator returned by a call to
.metn iter-begin ,
.meta iter-step
or
.metn iter-reset .

The
.code iter-more
function doesn't change the state of
.metn iter .

If
.code iter
is the object
.code nil
then
.code nil
is returned.
Note: the
.code iter-begin
may return
.code nil
if its argument is
.code nil
or any empty sequence, or an empty range (a range whose
.code to
and
.code from
fields are the same number or character).

If
.meta iter
is a
.code cons
cell, then
.code iter-more
returns
.codn t .

If
.meta iter
is a number, then
.code iter-more
returns
.codn t .
This is the case even if calculating the successor of that number isn't possible
due to floating-point overflow or insufficient system resources.

If
.meta iter
is a character, then
.code iter-more
returns
.code t
if
.meta iter
isn't the highest possible character code, otherwise
.codn nil .

If
.meta iter
was formed from a descending range, meaning that
.code iter-begin
was invoked on a range with a
.code from
fielding exceeding its
.code to
value, then
.code iter-begin
returns true while the current iterator value is greater than the
the limiting value given by the
.code to
field. For an ascending range, it returns true if the current iterator value is
lower than the limiting value. However, note the peculiar semantics of
.code iter-item
with regard to descending range iteration.

If
.meta iter
is a structure, then if it supports an
.code iter-more
method, then that method is called with no arguments, and its return value
is returned. If the structure does not have an
.code iter-more
method, then
.code t
is returned.

.coNP Function @ iter-item
.synb
.mets (iter-item << iter )
.syne
.desc
If the
.code iter-more
function indicates that more items remain to be visited, then
the next item can be retrieved using
.codn iter-item .

The
.meta iter
argument must be a valid iterator returned by a call to
.metn iter-begin ,
.meta iter-step
or
.metn iter-reset .

The
.code iter-more
function doesn't change the state of
.metn iter .

If
.code iter-more
is invoked on an iterator which indicates that no more items
remain to be visited, the return value is
.codn nil .

If
.meta iter
is a
.code cons
cell, then
.code iter-item
returns the
.code car
field of that cell.

If
.meta iter
is a character or number, then
.code iter-item
returns that character or number itself.

If
.meta iter
is based on an ascending numeric or character range, then
.code iter-item
returns the current iteration value, which is initialized by
.code iter-begin
as a copy of the range's
.code from
field. Thus, the range
.code 0..3
traverses the values
.codn 0 ,
.code 1
and
.codn 2 ,
excluding the
.codn 3 .

If
.meta iter
is based on a descending numeric or character range, then
.code iter-item
returns the predecessor of the current iteration value, which is initialized
.code iter-begin
as a copy of the range's
.code from
field.
Thus, the range
.code 3..0
traverses the values
.codn 2 ,
.code 1
and
.codn 0 ,
excluding the
.codn 3 :
exactly the same values are visited as for the range
.code 0..3
only in reverse order.

If
.meta iter
is a structure which supports the
.code iter-item
method, then that method is called and its return value is returned.

.coNP Function @ iter-step
.synb
.mets (iter-step << iter )
.syne
.desc
If the
.code iter-more
function indicates that more items remain to be visited, then the
.code iter-step
function may be used to consume the next item.

The function returns an iterator denoting the traversal of the
remaining items in the sequence.

The
.meta iter
argument must be a valid iterator returned by a call to
.metn iter-begin ,
.meta iter-step
or
.metn iter-reset .

The
.code iter-step
function may return a new object, in which case it avoids
changing the state of
.metn iter ,
or else it may change the state of
.meta iter
and return it.

If the application discontinues the use of
.metn iter ,
and continues the
traversal using the returned iterator, it will work correctly in either
situation.

If
.code iter-step
is invoked on an iterator which indicates that no more items
remain to be visited, the return value is unspecified.

If
.meta iter
is a
.code cons
cell, then
.code iter-step
returns the
.code cdr
field of that cell.

If
.meta iter
is a character or number, then
.code iter-step
returns its successor, as if using the
.code succ
function.

If
.meta iter
is a structure which supports the
.code iter-step
method, then that method is called and its return value is returned.

.coNP Function @ iter-reset
.synb
.mets (iter-reset < iter << seq )
.syne
.desc
The
.code iter-reset
function returns an iterator object specialized for the task of traversing
the sequence
.metn seq .

If it is possible for
.meta iter
to be that object, then the function may adjust the state of
.meta iter
and return it.

If
.code iter-reset
doesn't use
.metn iter ,
then it behaves exactly like
.code iter-begin
being invoked on
.metn seq .

If
.meta seq
is a structure which supports the
.code iter-reset
method, then that method is called and its return value is returned.
Note the reversed arguments. The
.code iter-reset
method is of the
.meta seq
object, not of
.metn iter .
That is to say, the call
.mono
.meti (iter-reset < iter << obj)
.onom
results in the
.mono
.meti << obj .(iter-reset << iter )
.onom
call. If
.meta seq
is a structure which doesn't support
.code iter-reset
then
.meta iter
is ignored,
.code iter-begin
is invoked on
.meta seq
and the result is returned.

.coNP Function @ seq-begin
.synb
.mets (seq-begin << object )
.syne
.desc
The obsolescent
.code seq-begin
function returns an iterator object specialized to the task of traversing
the sequence represented by the input
.metn object .

If
.meta object
isn't a sequence, an exception is thrown.

Note that if
.meta object
is a lazy list, the returned iterator maintains a reference to the
head of that list during the traversal; therefore, generic iteration
based on iterators from
.code seq-begin
is not suitable for indefinite iteration over infinite lists.

.coNP Function @ seq-next
.synb
.mets (seq-next < iter << end-value )
.syne
.desc
The obsolescent
.code seq-next
function retrieves the next available item from the sequence iterated by
.metn iter ,
which must be an object returned by
.codn seq-begin .

If the sequence has no more items to be traversed, then
.meta end-value
is returned instead.

Note: to avoid ambiguities, the application should provide an
.meta end-value
which is guaranteed distinct from any item in the sequence, such as a
freshly allocated object.

.coNP Function @ seq-reset
.synb
.mets (seq-reset < iter << object )
.syne
.desc
The obsolescent
.code seq-reset
re-initializes the existing iterator object
.meta iter
to begin a new traversal over the given
.metn object ,
which must be a value of a kind that would be a suitable argument for
.codn seq-begin .

The
.code seq-reset
function returns
.metn iter .

.SS* Procedural List Construction

\*(TL provides an a structure type called
.code list-builder
which encapsulates state and methods for constructing lists procedurally.
Among the advantages of using
.code list-builder
is that lists can be constructed in the left to right direction without
requiring multiple traversals or reversal. For example,
.code list-builder
naturally combines with iteration or recursion: items visited in an
iterative or recursive process can be collected easily using
.code list-builder
in the order they are visited.

The
.code list-builder
type provides methods for adding and removing items at either end of
the list, making it suitable where a
.I dequeue
structure is required.

The basic workflow begins with the instantiation of a
.code list-builder
object. This object may be initialized with a piece of list material which
begins the to-be-constructed list, or it may be initialized to begin with an
empty list.  Methods such as
.code add
and
.code pend
are invoked on this object to extend the list with new elements.  At any point,
the list constructed so far is available using the
.code get
method, which is also how the final version of the list is eventually
retrieved.

The
.code build
macro is provided which syntactically streamlines the process.
It implicitly creates a
.code list-builder
instance and binds it to a hidden lexical variable.
It then evaluates forms in a lexical scope in which
short-hand macros are available for building the list.

.coNP Structure @ list-builder
.synb
.mets (defstruct list-builder nil
.mets \ \ head tail)
.syne
.desc
The
.code list-builder
structure encapsulates the state for a list building process.
Programs should use the
.code build-list
function for creating an instance of
.codn list-builder .
The
.code head
and
.code tail
slots should be regarded as internal variables.

.coNP Function @ build-list
.synb
.mets (build-list <> [ initial-list ])
.syne
.desc
The
.code build-list
function instantiates and returns an object of struct type
.codn list-builder .

If no
.meta initial-list
argument is supplied, then the object is implicitly
with an empty list.

If the argument is supplied, then it is equivalent
to calling
.code build-list
without an argument to produce an object
.meta obj
the invoking the method call
.mono
.meti << obj .(ncon << initial-list )
.onom
on this object. The object produced by the expression
.meta list
is installed (without being copied) into the
object as the prefix of the list to be constructed.

The
.meta initial-list
argument can be a sequence other than a list.

.TP* Example:

.verb
   ;; build the list (a b) trivially

   (let ((lb (build-list '(a b))))
     lb.(get)
   -> (a b)
.brev

.coNP Methods @ add and @ add*
.synb
.mets << list-builder .(add << element *)
.mets << list-builder .(add* << element *)
.syne
.desc
The
.code add
and
.code add*
methods extend the list being constructed by a
.code list-builder
object by adding individual
elements to it. The
.code add
method adds elements at the tail of the list,
whereas
.code add*
adds elements at the front.

These methods return
.codn nil .

The precise semantics is as follows.
All of the
.meta element
arguments are combined into a list as if by the
.code list
function, and the resulting list combined with the current contents of the
.code list-builder
object as if using the
.code append
function. The resulting list becomes the new contents.

.TP* Examples:

.verb
  ;; Build the list (1 2 3 4)

  (let ((lb (build-list)))
    lb.(add 3 4)
    lb.(add* 1 2)
    lb.(get))
  -> (1 2 3 4)

  ;; Add "c" to "abc"
  ;; same semantics as (append "abc" #\ec)

  (let ((lb (build-list "ab")))
    lb.(add #\ec)
    lb.(get))
  -> "abc"
.brev

.coNP Methods @ pend and @ pend*
.synb
.mets << list-builder .(pend << list *)
.mets << list-builder .(pend* << list *)
.syne
.desc
The
.code pend
and
.code pend*
methods extend the list being constructed by a
.code list-builder
object by adding lists to it. The
.code pend
method catenates the
.code list
arguments together as if by the
.code append
function, then appends the resulting list to
the end of the list being constructed.
The
.code pend*
method is similar, except it prepends the
catenated lists to the front of the list
being constructed.

The
.code pend
and
.code pend*
operations do not mutate the input lists, but may cause the
resulting list to share structure with the input lists.

These functions may mutate the list already contained in
.metn list-builder ;
however, they avoid mutating those parts of the current list
that are shared with inputs that were given in earlier
calls to these functions.

These methods return
.codn nil .

.TP* Example:

.verb
  ;; Build the list (1 2 3 4)

  (let ((lb (build-list)))
    lb.(pend '(3 4))
    lb.(pend* '(1 2))
    lb.(get))
  -> (1 2 3 4)
.brev

.coNP Methods @ ncon and @ ncon*
.synb
.mets << list-builder .(ncon << list *)
.mets << list-builder .(ncon* << list *)
.syne
.desc
The
.code ncon
and
.code ncon*
methods extend the list being constructed by a
.code list-builder
object by adding lists to it. The
.code ncon
method destructively catenates the
.meta list
arguments as if by the
.code nconc
function. The resulting list is appended
to the list being constructed.
The
.code ncon*
method is similar, except it prepends
the catenated lists to the front of the
list being constructed.

These methods may destructively manipulate the list already contained in the
.meta list-builder
object, and likewise may destructively manipulate the input lists.
They may cause the list being constructed to share substructure with the input
lists.

Additionally, these methods may destructively manipulate the list already
contained in the
.meta list-builder
object without regard for shared structure between that list and inputs
given earlier any of the
.codn pend ,
.codn pend* ,
.code ncon
or
.code ncon*
functions.

The
.code ncon*
function can be called with a single argument
which is an atom. This atom will simply be
installed as the terminating atom of the
list being constructed, if the current list is
an ordinary list.

These methods return
.codn nil .

.TP* Example:

.verb
  ;; Build the list (1 2 3 4 . 5)

  (let ((lb (build-list)))
    lb.(ncon* (list 1 2))
    lb.(ncon (list 3 4))
    lb.(ncon 5)
    lb.(get))
  -> (1 2 3 4 . 5)
.brev

.coNP Method @ get
.synb
.mets << list-builder .(get)
.syne
.desc
The
.code get
method retrieves the list constructed so far by a
.code list-builder
object. It doesn't change the state of the object.
The retrieved list may be passed as an argument
into the construction methods on the same object.

.TP* Examples:

.verb
  ;; Build the circular list (1 1 1 1 ...)
  ;; by appending (1) to itself destructively:

  (let ((lb (build-list '(1))))
    lb.(ncon* lb.(get))
    lb.(get))
  -> (1 1 1 1 ...)

  ;; build the list (1 2 1 2 1 2 1 2)
  ;; by doubling (1 2) twice:

  (let ((lb (build-list)))
    lb.(add 1 2)
    lb.(pend lb.(get))
    lb.(pend lb.(get))
    lb.(get))
  -> (1 2 1 2 1 2 1 2)
.brev

.coNP Methods @ del and @ del*
.synb
.mets << list-builder .(del)
.mets << list-builder .(del*)
.syne
.desc
The
.code del
and
.code del*
methods each remove an element from the list and return it.
If the list is empty, they return
.codn nil .

The
.code del
method removes an element from the front of the list, whereas
.code del*
removes an element from the end of the list.

Note: this orientation is opposite to
.code add
and
.codn add* .
Thus
.code del
pairs with
.code add
to produce FIFO queuing behavior.

.coNP Macros @ build and @ buildn
.synb
.mets (build << form *)
.mets (buildn << form *)
.syne
.desc
The
.code build
and
.code buildn
macros provide a shorthand notation for constructing lists using the
.code list-builder
structure. They eliminate the explicit call to the
.code build-list
function to construct the object, and eliminate the explicit
references to the object.

Both of these macros create a lexical environment in which a
.code list-builder
object is implicitly constructed and bound to a hidden variable.
This lexical environment also provides local functions named
.codn add ,
.codn add* ,
.codn pend ,
.codn pend* ,
.codn ncon ,
.codn ncon* ,
.codn get ,
.code del
and
.codn del* ,
which mimic the
.code list-builder
methods, but operate implicitly on this hidden variable, so that
the object need not be mentioned as an argument.
With the exception of
.codn get ,
.code del
and
.codn del* ,
the local functions return
.codn nil ,
like the same-named
.code list-builder
methods.

In this lexical environment, each
.meta form
is evaluated in order.

When the last
.meta form
is evaluated,
.code build
returns the constructed list, whereas
.code buildn
returns the value of the last
.metn form .

If no forms are enclosed, both macros return
.codn nil .

Note: because the local function
.code del
has the same name as a global macro, it is implemented as a
.code macrolet.
Inside a
.code build
or
.codn buildn ,
if
.code del
is invoked with no arguments, then it denotes a call to the
.code list-builder
.code del
method. If invoked with an argument, then it resolves to the global
.code del
macro for deleting a place.

.TP* Examples:

.verb
  ;; Build the circular list (1 1 1 1 ...)
  ;; by appending (1) to itself destructively:

  (build
    (add 1)
    (ncon* (get))) -> (1 1 1 1 ...)

  ;; build the list (1 2 1 2 1 2 1 2)
  ;; by doubling (1 2) twice:

  (build
    (add 1 2)
    (pend (get))
    (pend (get))) -> (1 2 1 2 1 2 1 2)

  ;; build a list by mapping over the local
  ;; add function:

  (build [mapdo add (range 1 3)]) -> (1 2 3)

  ;; breadth-first traversal of nested list;
  (defun bf-map (tree visit-fn)
    (buildn
      (add tree)
      (whilet ((item (del)))
        (if (atom item)
          [visit-fn item]
          (each ((el item))
            (add el))))))

  (let (flat)
    (bf-map '(1 (2 (3 4 (5))) ((6 7) 8)) (do push @1 flat))
     (nreverse flat))
  -> (1 2 8 3 4 6 7 5)
.brev

.SS* Permutations and Combinations

.coNP Function @ perm
.synb
.mets (perm < seq <> [ len ])
.syne
.desc
The
.code rperm
function returns a lazy list which consists of all
length
.meta len
permutations of formed by items taken from
.metn seq .
The permutations do not use any element of
.meta seq
more than once.

Argument
.metn len ,
if present, must be a positive integer, and
.meta seq
must be a sequence.

If
.meta len
is not present, then its value defaults to the length of
.metn seq :
the list of the full permutations of the entire sequence is returned.

The permutations in the returned list are sequences of the same kind as
.codn seq .

If
.meta len
is zero, then a list containing one permutation is returned, and that
permutation is of zero length.

If
.meta len
exceeds the length of
.metn seq ,
then an empty list is returned,
since it is impossible to make a single non-repeating permutation that
requires more items than are available.

The permutations are lexicographically ordered.

.coNP Function @ rperm
.synb
.mets (rperm < seq << len )
.syne
.desc
The
.code rperm
function returns a lazy list which consists of all the repeating
permutations of length
.meta len
formed by items taken from
.metn seq .
"Repeating" means that the items from
.meta seq
can appear more than
once in the permutations.

The permutations which are returned are sequences of the same kind as
.metn seq .

Argument
.meta len
must be a nonnegative integer, and
.meta seq
must be a sequence.

If
.meta len
is zero, then a single permutation is returned, of zero length.
This is true regardless of whether
.meta seq
is itself empty.

If
.meta seq
is empty and
.meta len
is greater than zero, then no permutations are
returned, since permutations of a positive length require items, and the
sequence has no items. Thus there exist no such permutations.

The first permutation consists of
.meta le
repetitions of the first element of
.metn seq .
The next repetition, if there is one, differs from the first
repetition in that its last element is the second element of
.metn seq .
That is to say, the permutations are lexicographically ordered.

.TP* Examples:

.verb
  (rperm "01" 3) -> ("000" "001" "010" "011"
                     "100" "101" "110" "111")

  (rperm #(1) 3) -> (#(1 1 1))

  (rperm '(0 1 2) 2) -> ((0 0) (0 1) (0 2) (1 0)
                         (1 1) (1 2) (2 0) (2 1) (2 2))
.brev

.coNP Function @ comb
.synb
.mets (comb < seq << len )
.syne
.desc
The
.code comb
function returns a lazy list which consists of all
length
.meta len
non-repeating combinations formed by taking items taken from
.metn seq .
"Non-repeating combinations" means that the combinations do not use any
element of
.meta seq
more than once. If
.meta seq
contains no duplicates, then
the combinations contain no duplicates.

Argument
.meta len
must be a nonnegative integer, and
.meta seq
must be a sequence or a hash table.

The combinations in the returned list are objects of the same kind as
.metn seq .

If
.meta len
is zero, then a list containing one combination is returned, and that
combination is of zero length.

If
.meta len
exceeds the number of elements in
.metn seq ,
then an empty list is returned, since it is impossible to make a single
non-repeating combination that requires more items than are available.

If
.meta seq
is a sequence, the returned combinations are lexicographically ordered.
This requirement is not applicable when
.meta seq
is a hash table.

.TP* Example:
.verb
   ;; powerset function, in terms of comb.
   ;; Yields a lazy list of all subsets of s,
   ;; expressed as sequences of the same type as s.

   (defun powerset (s)
     (mappend* (op comb s) (range 0 (length s))))
.brev

.coNP Function @ rcomb
.synb
.mets (rcomb < seq << len )
.syne
.desc
The
.code comb
function returns a lazy list which consists of all
length
.meta len
repeating combinations formed by taking items taken from
.metn seq .
"Repeating combinations" means that the combinations can use
an element of
.meta seq
more than once.

Argument
.meta len
must be a nonnegative integer, and
.meta seq
must be a sequence.

The combinations in the returned list are sequences of the same kind as
.metn seq .

If
.meta len
is zero, then a list containing one combination is returned, and that
combination is of zero length. This is true even if
.meta seq
is empty.

If
.meta seq
is empty, and
.meta len
is nonzero, then an empty list is returned.

The combinations are lexicographically ordered.


.SS* Macros
\*(TL supports structural macros. \*(TX's model of macroexpansion is that
\*(TL code is processed in two phases: the expansion phase and the
evaluation phase. The expansion phase is invoked on Lisp code early during the
processing of source code. For instance when a \*(TX file containing a
.code "@(do ...)"
directive
is loaded, expansion of the Lisp forms are its arguments takes place during the
parsing of the entire source file, and is complete before any of the code in
that file is executed. If the
.code "@(do ...)"
form is later executed,
the expanded forms are then evaluated.

\*(TL also supports symbol macros, which are symbolic forms that stand
for forms, with which they are replaced at macro expansion time.

When Lisp data is processed as code by the
.code eval
function, it is first expanded,
and so processed in its entirety in the expansion phase. Then it is processed
in the evaluation phase.

.NP* Macro parameter lists

\*(TX macros support destructuring, similarly to Common Lisp macros.
This means that macro parameter lists are like function argument lists,
but support nesting. A macro parameter list can specify a nested parameter
list in every place where an argument symbol may appear.  For instance,
consider this macro parameter list:

.verb
  ((a (b c)) : (c frm) ((d e) frm2 de-p) . g)
.brev

The top-level of this nested form has the structure

.mono
.meti \ \  >> ( I : < J < K . << L )
.onom

in which we can identify the major constituent positions as
.metn I ,
.metn J ,
.meta K
and
.metn L .

The constituent at position
.meta I
is the mandatory parameter
.codn "(a (b c))" .
Position
.meta J
holds the optional parameter
.code c
(with default init form
.codn frm ).
At
.meta K
is found the optional parameter
.code "(d e)"
(with default init form
.code frm2
and presence-indicating variable
.codn de-p ).
Finally, the parameter in the dot position
.meta L
is
.codn g ,
which captures trailing arguments.

Obviously, some of the parameters are compound expressions rather
than symbols:
.code "(a (b c))"
and
.codn "(d e)" .
These compounds express nested macro parameter lists.

Nested macro parameter lists recursively match the corresponding structure
in the argument object.  For instance if a simple argument would capture
the structure
.code "(1 (2 3))"
then we can replace the argument with the nested argument list
.code "(a (b c))"
which destructures the
.code "(1 (2 3))"
such that the parameters
.codn a ,
.code b
and
.code c
will end up bound
to
.codn 1 ,
.code 2
and
.codn 3 ,
respectively.

Nested macro parameter lists have all the features of the top-level
macro parameter lists: they can have optional arguments with default
values, use the dotted position, and contain the
.codn :env ,
.code :whole
and
.code :form
special parameters, which are described below.  
In nested parameter lists, the binding strictness is relaxed for optional
parameters. If
.code "(a (b c))"
is optional, and the argument is, say,
.codn (1) ,
then
.code a
gets
.codn 1 ,
and
.code b
and
.code c
receive
.codn nil .

Macro parameter lists also supports three special keywords, namely
.codn :env ,
.code :whole
and
.codn :form .

The parameter list
.code "(:whole x :env y :form z)"
will bind parameter
.code x
to the entire
macro parameter list, bind parameter
.code y
to the macro environment and bind parameter
.code z
to the entire macro form (the original compound form used to invoke the
macro).

The
.codn :env ,
.code :whole
and
.code :form
notations can occur anywhere in a macro parameter list, other than
to the right of the consing dot. They can be used in nested
macro parameter lists also.  Note that in a nested macro
parameter list,
.code :form
and
.code :env
do not change meaning: they bind the same object as they would in
the top-level of the macro parameter list.
However the
.code :whole
parameter inside has a restricted scope in a nested parameter
list: its parameter will capture just that part of the argument material which
matches that parameter list, rather than the entire argument list.

The processing of macro parameter lists omits the feature that when the
keyword symbol
.code :
(colon) given as the argument to an optional parameter, that argument is
treated as a missing argument. This special logic is implemented only
in the function argument passing mechanism, not in the binding of macro
parameters to object structure. If the colon symbol appears in the object
structure and is matched against an optional parameter, it is an
ordinary value. That parameter is considered present, and takes on
that
.code :
keyword symbol as its value.

.TP* "Dialect Note:"

In ANSI Common Lisp, the lambda list keyword
.code &whole
binds its corresponding variable to the entire macro form, whereas
\*(TL's
.code :whole
binds its variable only to the arguments of the macro form.

Note, however, that ANSI CL distinguishes destructuring lambda lists
and macro lambda lists and the
.code &whole
parameter has a different behavior between the two.  Under
.codn destructuring-bind ,
the
.code &whole
parameter receives just the arguments, just like the behavior
of \*(TL's
.code :whole
parameter.

\*(TL does not distinguish destructuring and macro lambda lists;
they are the same and behave the same way. Thus
.code :whole
is treated the same way in macros as in
.code tree-bind
and related binding operators: it binds just the arguments
to the parameter. \*(TL has the special parameter
.code :form
by means of which macros can access their invoking form.
This parameter is also supported in
.code tree-bind
and binds to the entire
.code tree-bind
form.

.coNP Operator @ macro-time
.synb
.mets (macro-time << form *)
.syne
.desc
The
.code macro-time
operator has a syntax similar to the
.code progn
operator. Each
.meta form
is evaluated from left to right, and the resulting value is that of the last
form.

The special behavior of
.code macro-time
is that the evaluation takes place during
the expansion phase, rather than during the evaluation phase.

Also,
.code macro-time
macro-expands each
.meta form
and evaluates it before processing the next
.meta form
in the same way. Thus, for instance, if a
.meta form
introduces a global definition, that definition will be visible not
only during the evaluation of a subsequent
.metn form ,
but also during its macro-expansion time.

During the expansion phase, all
.code macro-time
expressions which occur in a context
that calls for evaluation are evaluated, and replaced by their quoted values.
For instance
.code "(macro-time (list 1 2 3))"
evaluates
.code "(list 1 2 3)"
to the object
.code "(1 2 3)"
and the entire
.code macro-time
form is replaced by that value, quoted:
.codn "'(1 2 3)" .
If the form is evaluated again at evaluation-time, the resulting value will be
that of the quote, in this case
.codn "(1 2 3)" .

.code macro-time
forms do not see the surrounding lexical environment; the see only
global function and variable bindings and macros.

Note:
.code macro-time
supports techniques that require a calculation to be performed in the
environment where the program is being compiled, and inserting the result of
that calculation as a literal into the program source. Possibly, the
calculation can have some useful effect in that environment, or use
as an input information that is available in that environment.
The
.code load-time
operator also inserts a calculated value as a
.I "de facto"
literal into the program, but it performs that calculation in the
environment where the compiled file is being loaded.
The two operators may be considered complementary in this sense.

Consider the source file:

.verb
  (defun host-name-c () (macro-time (uname).nodename))

  (defun host-name-l () (load-time (uname).nodename))
.brev

If this is compiled via
.codn compile-file ,
the
.code uname
call in
.code host-name-c
takes place when it is macro-expanded. Thereafter, the compiled version
of the function returns the name of the machine where the
compilation took place, no matter in what environment it is subsequently
loaded and called.

In contrast, the compilation of
.code host-name-l
arranges for that function's
.code uname
call to take place just one time, whenever the compiled file is loaded.
Each time the function is subsequently called, it will
return the name of the machine where it was loaded, without making
any additional calls to
.codn uname .

The
.code macro-time
operator can occasionally be required in order for some constructs to evaluate
or compile. One way that occurs is when a construct that is being fully
expanded itself defines a macro which is later required in that same construct.
For example:

.verb
  (progn (defmacro mac () 42) (mac))
.brev

This specific example actually works under
.code eval
or file compilation, because in that situation it isn't fully expanded
all at once. When
.code eval
and
.code compile-file
process a top-level form that is a
.codn progn ,
they treat its argument forms as individual, separate top-level forms. In
general, \*(TL is designed in such a way as to not to require, in most ordinary
programs, extra verbiage to tell the compiler or evaluator that certain
definitions are required by macros. However, somewhat unusual situations can
arise which are not handled in this way.

Also,
.codn macro-time ,
or the related
.code @(mdo)
directive, can be occasionally necessary in \*(TX
queries, which are parsed and subject to macro-expansion in their entirety
before being executed.

.coNP Operator @ defmacro
.synb
.mets (defmacro < name
.mets \ \ \ \ \ \ \ \ \  <> ( param * [: << opt-param * ] [. < rest-param ])
.mets \ \  << body-form *)
.syne
.desc
The
.code defmacro
operator is evaluated at expansion time. It defines a
macro-expander function under the name
.metn name ,
effectively creating a new operator.

Note that the above syntax synopsis describes only the canonical
parameter syntax which remains after parameter list macros are
expanded. See the section Parameter List Macros.

Note that the parameter list is a macro parameter list, and not a
function parameter list. This means that each
.meta param
and
.meta opt-param
can be not only a symbol, but it can itself be a parameter list.
The corresponding argument is then treated as a structure which
matches that parameter list.  This nesting of parameter lists
can be carried to an arbitrary depth.

A macro is called like any other operator, and resembles a function.  Unlike in
a function call, the macro receives the argument expressions themselves, rather
than their values.  Therefore it operates on syntax rather than on values.
Also, unlike a function call, a macro call occurs in the expansion phase,
rather than the evaluation phase.

The return value of the macro is the macro expansion. It is substituted in
place of the entire macro call form. That form is then expanded again;
it may itself be another macro call, or contain more macro calls.

A global macro defined using
.code defmacro
may decline to expand a macro form. Declining to expand is achieved by
returning the original unexpanded form, which may be captured using the
.code :form
parameter. When a global macro declines to expand a form, the form is
taken as-is. At evaluation time, it will be treated as a function call.
Note: when a local macro defined by
.code macrolet
declines, more complicated requirements apply; see the description of
.codn macrolet .

.TP* "Dialect Notes:"
A macro in the global namespace introduced by
.code defmacro
may co-exist with a function of the same name introduced by
.codn defun .
This is not permitted in ANSI Common Lisp.

ANSI Common Lisp doesn't describe the concept of declining to expand, except in
the area of compiler macros. Since TXR Lisp allows global macros and functions
of the same name to co-exist, ordinary macros can be used to optimize functions
in a manner similar to Common Lisp compiler macros. A macro can be written
of the same name as a function, and can optimize certain cases of the function
call by expanding them to some alternative syntax. Cases which it doesn't
optimize are handled by declining to expand, in which case the form remains
as the original function call.

.TP* Example:

.verb
  ;; dolist macro similar to Common Lisp's:
  ;;
  ;; The following will print 1, 2 and 3
  ;; on separate lines:
  ;; and return 42.
  ;;
  ;; (dolist (x '(1 2 3) 42)
  ;;   (format t "~s\en"))

  (defmacro dolist ((var list : result) . body)
    (let ((i (my-gensym)))
      ^(for ((i ,list)) (i ,result) ((set i (cdr i)))
         (let ((,var (car i)))
           ,*body))))
.brev

.coNP Operator @ macrolet
.synb
.mets (macrolet >> ({( name < macro-style-params
.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \  << macro-body-form *)}*)
.mets \ \  << body-form *)
.syne
.desc
The
.code macrolet
binding operator extends the macro-time lexical environment
by making zero or more new local macros visible.

The
.code macrolet
symbol is followed by a list of macro definitions.
Each definition is a form which begins with a
.metn name ,
followed by
.meta macro-style-params
which is a macro parameter list, and zero or more
.metn macro-body-form -s.
These macro definitions are similar
to those globally defined by the
.code defmacro
operator, except that they
are in a local environment.

The macro definitions are followed by optional
.metn body-forms .
The macros specified in the definitions are visible to these
forms.

Forms inside the macro definitions such as the
.metn macro-body-form -s,
and initializer forms appearing in the
.meta macro-style-params
are subject
to macro-expansion in a scope in which none of the new macros being
defined are yet visible. Once the macro definitions are themselves
macro-expanded, they are placed into a new macro environment, which
is then used for macro expanding the
.metn body-form -s.

A
.code macrolet
form is fully processed in the expansion phase of a form, and is
effectively replaced by
.code progn
form which contains expanded versions of
.metn body-form -s.
This expanded structure shows no evidence that any
macrolet forms ever existed in it. Therefore, it is impossible for the code
evaluated in the bodies and parameter lists of
.code macrolet
macros to have any visibility to any surrounding lexical variable bindings,
which are only instantiated in the evaluation phase, after expansion is done
and macros no longer exist.

A local macro defined using
.code defmacro
may decline to expand a macro form. Declining to expand is achieved by returning the original
unexpanded form, which may be captured using the
.code :form
parameter. When a local macro declines to expand a form, the macro definition
is temporarily hidden, as if it didn't exist in the lexical scope. If another
macro of the same name is thereby revealed (a global macro or another local macro
at a shallower nesting level), then an expansion is tried with that macro.  If
no such macro is revealed, or if a lexical function binding of that name is
revealed, then no expansion takes place; the original form is taken as-is.
When another macro is tried, the process repeats, resulting in a search which
proceeds as far as possible through outer lexical scopes and finally the
global scope.

.coNP Function @ macro-form-p
.synb
.mets (macro-form-p < obj <> [ env ])
.syne
.desc
The
.code macro-form-p
function returns
.code t
if
.meta obj
represents the syntax of
a form which is a macro form: either a compound macro or a symbol macro.
Otherwise it returns
.codn nil .

A macro form is one that will transform under
.code macroexpand-1
or
.codn macroexpand ;
an object which isn't a macro form will not undergo expansion.

The optional
.meta env
parameter is a macroexpansion environment.
A macroexpansion environment is passed down to macros and can be received
via their special
.code :env
parameter.

.meta env
is used by
.code macro-form-p
to determine whether
.meta obj
is a macro in a lexical macro environment.

If
.meta env
is not specified or is
.codn nil ,
then
.code macro-form-p
only recognizes global macros.

.TP* Example:

.verb
  ;; macro which translates to 'yes if its
  ;; argument is a macro from, or otherwise
  ;; transforms to the form 'no.

  (defmacro ismacro (:env menv form)
    (if (macro-form-p form menv)
     ''yes ''no))

  (macrolet ((local ()))
    (ismacro (local)))    ;; yields yes

  (ismacro (local))       ;; yields no

  (ismacro (ismacro foo)) ;; yields yes
.brev

During macro expansion, the global macro
.code ismacro
is handed the macro-expansion environment 
via
.codn ":env menv" .

When the macro is invoked within the macrolet,
this environment includes the macro-time lexical scope in which the
.code local
macro is defined. So when global checks whether the argument form
.code (local)
is a macro, the conclusion is yes: the (local) form is a macro
call in that environment:
.code macro-form-p
yields
.codn t .

When
.code "(global (local))"
is invoked outside of the macrolet, no local macro is visible is
there, and so
.code macro-form-p
yields
.codn nil .

.coNP Functions @ macroexpand-1 and @ macroexpand
.synb
.mets (macroexpand-1 < obj <> [ env ])
.mets (macroexpand < obj <> [ env ])
.syne
.desc
If
.meta obj
is a macro form (an object for which
.code macro-form-p
returns
.codn t ),
these functions expand the macro form and return the expanded form.
Otherwise, they return
.metn obj .

.code macroexpand-1
performs a single expansion, expanding just the macro
that is referenced by the symbol in the first position of
.metn obj ,
and returns the expansion. That expansion may itself be a macro form.

.code macroexpand
performs an expansion similar to
.codn macroexpand-1 .
If the result is
a macro form, then it expands that form, and keeps repeating this process
until the expansion yields a non-macro-form. That non-macro-form is then
returned.

The optional
.meta env
parameter is a macroexpansion environment.
A macroexpansion environment is passed down to macros and can be received
via their special
.code :env
parameter. The environment they receive is their
lexically apparent macro-time environment in which local macros may be
visible.  A macro can use this environment to "manually" expand some
form in the context of that environment.

.TP* Example:

.verb
  ;; (rem-num x) expands x, and if x begins with a number,
  ;; it removes  the number and returns the resulting
  ;; form. Otherwise, it returns the entire form.

  (defmacro rem-num (:env menv some-form)
    (let ((expanded (macroexpand some-form menv)))
      (if (numberp (car expanded))
        (cdr expanded)
        some-form)))

  (macrolet ((foo () '(1 list 42))
             (bar () '(list 'a)))
    (list (rem-num (foo)) (rem-num (bar))))

  --> ((42) (a))
.brev

The
.code rem-num
macro is able to expand the
.code (foo)
and
.code (bar)
forms it receives as
the
.code some-form
argument, even though these forms use local macro that are only
visible in their local scope. This is thanks to the macro
environment passed to
.codn rem-num .
It is correctly able to work with the
expansions
.code "(1 list 42)"
and
.code "(list 'a)"
to produce
.code "(list 42)"
and
.code "(list 'a)"
which evaluate to
.code 42
and
.code a
respectively.

.coNP Functions @ macroexpand-1-lisp1 and @ macroexpand-lisp1
.synb
.mets (macroexpand-1-lisp1 < obj <> [ env ])
.mets (macroexpand-lisp1 < obj <> [ env ])
.syne
.desc
The
.code macroexpand-1-lisp1
and
.code macroexpand-lisp1
functions closely resemble, respectively,
.code macroexpand-1
and
.codn macroexpand .

The argument and return value syntax and semantics is almost
identical, except for one difference. These functions consider argument
.meta obj
to be syntax in a Lisp-1 evaluation context, such as any argument
position of the
.code dwim
operator, or the equivalent DWIM Brackets notation.

This makes a difference because in a Lisp-1 evaluation context, an
inner function binding is able to shadow an outer symbol macro binding
of the same name.

The requirements about this language area are given in more
detail in the description of the
.code dwim
operator.

Note: the
.code macroexpand-lisp1
function is useful to the implementor of a macro whose semantics requires
one or more argument forms to be treated in a Lisp-1 context, in situations
when such a macro needs to itself expand the material, rather than merely
insert it as-is into the output code template.

.coNP Functions @ expand and @ *expand
.synb
.mets (expand < form <> [ env ])
.mets (expand* < form <> [ env ])
.syne
.desc
The functions
.code expand
and
.code expand*
both perform a complete expansion of
.meta form
in the macro-environment
.metn env ,
and return that expansion.

If
.meta env
is omitted, the expansion takes place in the global environment in
which only global macros are visible.

The returned object is a structure that
is devoid of any macro calls. Also, all
.code macrolet
and
.code symacrolet
blocks in form
.meta form
are removed in the returned structure, replaced by their fully
expanded bodies.

The difference between
.code expand
and
.code expand*
is that
.code expand
suppresses any warning exceptions that are issued during expansion.

.coNP Function @ expand-with-free-refs
.synb
.mets (expand-with-free-refs < form >> [ inner-env <> [ outer-env ]])
.syne
.desc
The
.code expand-with-free-refs
form performs a full expansion of
.metn form ,
as if by the
.code expand
function and returns a list containing that expansion, plus four additional
items which provide information about variable and function references which
occur in
.metn form .

If both
.meta inner-env
and
.meta outer-env
are provided, then it is expected that
.meta inner-env
is lexically nested within
.metn outer-env .

Note: it is not required that
.meta outer-env
be the immediate parent of
.metn inner-env .

Note: a common usage situation is that
.meta outer-env
is the environment of the invocation of a "parent" macro which generates a form
that contains local macros. The bodies of those local macros use
.codn expand-with-free-refs ,
specifying their own environment as
.meta inner-env
and that of their generating "parent" as
.metn outer-env .

In detail, the five items of the returned list are
.mono
.meti >> ( expansion < fv-inner < ff-inner < fv-outer << ff-outer )
.onom
whose descriptions are:
.RS
.meIP < expansion
The full expansion of
.metn form ,
containing no macro invocations, or
.code symacrolet
or
.code macrolet
forms.
.meIP < fv-inner
A list of the free variables which occur in
.meta form
relative to the
.meta inner-env
environment. That is to say, variables that are not bound inside
.meta form
and are not also bound in
.metn inner-env .
If
.meta inner-env
is omitted, then these are the absolutely free variables
occurring in
.metn form .
.meIP < ff-inner
Exactly like
.meta fv-inner
but informing about function bindings rather than variables.
.meIP < fv-outer
A list of the variables which which occur in
.meta form
which would be free if the environments between
.meta inner-env
and
.meta outer-env
(including the former, excluding the latter)
were removed from consideration. A more detailed description of this semantics
is given below. If
.meta outer-env
is omitted, then these are the absolutely free variables
occurring in
.metn form ,
ignoring the
.metn inner-env .
.meIP < ff-outer
Exactly like
.meta fv-outer
but informing about function bindings rather than variables.
.RE

.IP
The semantics of the treatment of
.meta inner-env
and
.meta outer-env
in the calculation of
.meta fv-outer
and
.meta ff-outer
is as follows.  A new environment
.meta diff-env
is calculated from these two environments, and
.meta form
is expanded in this environment. Variables and functions occurring in
.meta form
which are not bound in
.meta diff-env
are listed as
.meta fv-outer
and
.metn ff-outer .

This
.meta diff-env
is calculated as follows. First
.meta diff-env
is initialized as a copy of
.metn outer-env .
Then, all environments below
.meta outer-env
down to
.meta inner-env
are examined for bindings which shadow bindings in
.metn diff-env .
Those shadows are removed from
.metn diff-env .
Therefore, what remains in
.meta diff-env
are those bindings from
.meta outer-env
that are
.I not
shadowed by the environments between
.meta inner-env
and
.metn outer-env .

Within each of the lists of variables returned by
.codn expand-with-free-refs ,
the order of the variables is not specified.

.TP* Example:

Suppose that
.code mac
is a macro which somehow has access to the two indicated lexical environments
in the following code snippet:

.verb
  (let (a c) ;; <- outer-env
    (let (b)
      (let (c) ;; <- inner-env
        (mac (list a b c d)))))
.brev

Suppose that
.code mac
invokes the
.code expand-with-free-refs
function, passing in the
.code "(list a b c d)"
argument form as
.code form
and two macro-time environment objects corresponding to the indicated
environments.

Then the following object shall be a correct return value of
.codn expand-with-free-refs :

.verb
  ((list a b c d) (d) nil (d c b) nil)
.brev

A complete code example of this is given below.

Other correct return values are possible due to permitted variations in the
order of the variables within the four lists. For instance, instead of
.code "(d c b)"
the list
.code "(c b d)"
may appear.

The
.meta fv-inner
list is
.code "(d)"
because this is the only variable that occurs in
.code "(list a b c d)"
which is free with regard to
.metn inner-env .
The
.codn a ,
.code b
and
.code c
variables are not listed because they appear bound inside
.metn inner-env .

The reported
.meta fv-outer
list is
.code "(b c d)"
because the form is considered against
.meta diff-env
which is formed by removing the shadowing bindings from
.metn outer-env .
The difference between
.code "(a c)"
and
.code "(b c)"
is
.code a
and so the form is considered in an environment containing the binding
.code a
which leaves
.code "(b c d)"
free.

The following is a complete code sample demonstrating the above
descriptions:

.verb
  ;; Given this macro:
  (defmacro bigmac (:env out-env big-form)
    ^(macrolet ((mac (:env in-env little-form)
                      ^',(expand-with-free-refs
                            little-form in-env ,out-env)))
      ,big-form))

  (let (a c) ;; <- outer-env, surrounding bigmac
    (bigmac
      (let (b)
        (let (c) ;; <- inner-env, surrounding mac
          (mac (list a b c d))))))

  --> ((list a b c d) (d) nil (d c b) nil)
.brev

Note: this information is useful because a set difference can be calculated
between the two reported sets. The set difference between the
.meta fv-outer
variables
.code "(b c d)"
and the
.meta fv-inner
variables
.code "(d)"
is
.codn "(b c)" .

That set difference
.code "(b c)"
is significant because it precisely informs about the
.I bound
variables which occur in
.code "(list a b c d)"
which appear bound in
.metn inner-env ,
but are not bound due to a binding coming from
.metn outer-env .
In the above example, these are the variables enclosed in the
.code bigmac
macro, but external to the inner
.code mac
macro.

The variable
.code d
is not listed in
.code "(b c)"
because it is not a bound variable.
The variable
.code a
is not in
.code "(b c)"
because though it is bound in
.metn inner-env ,
that binding comes from
.metn outer-env .

The upshot of this logic is that it allows a macro to inspect a form in order
to discover the identities of the variables and functions which are used inside
that form, whose definitions come from a specific, bounded scope surrounding
that form.

.coNP Functions @ lexical-var-p and @ lexical-fun-p
.synb
.mets (lexical-var-p < env << form )
.mets (lexical-fun-p < env << form )
.syne
.desc
These two functions are useful to macro writers. They are intended
to be called from the bodies of macro expanders, such as the bodies of
.code defmacro
or
.code macrolet
forms.  The
.meta env
argument is a macro-time environment, which is available to macros
via the special
.code :env
parameter. Using these functions, a macro can enquire whether
a given
.meta form
is a symbol which has a variable binding or a function binding
in the lexical environment.
This information is known during macro expansion. The macro expander
recognizes lexical function and variable bindings, because these
bindings can shadow macros.

.TP* Example:

.verb
  ;;
  ;; this macro replaces itself with :lexical-var if its
  ;; argument is a lexical variable, :lexical-fun if
  ;; its argument is a lexical function, or with
  ;; :not-lex-fun-var if neither is the case.
  ;;
  (defmacro classify (sym :env e)
    (cond
      ((lexical-var-p e sym) :lexical-var)
      ((lexical-fun-p e sym) :lexical-fun)
      (t :not-lex-fun-var)))

  ;;
  ;; This returns:
  ;;
  ;;   (:lexical-var :not-lex-fun-var :lexical-fun)
  ;;
  (let ((x 1) (y 2))
    (symacrolet ((y x))
      (flet ((f () (+ 2 2)))
        (list (classify x) (classify y) (classify f)))))
.brev

.TP* Note:

These functions do not call
.code macroexpand
on the form. In most cases, it is necessary for the macro writers
to do so. Not that in the above example,  symbol
.code y
is classified as neither a lexical function nor variable.
However, it can be macro-expanded to
.code x
which is a lexical variable.

.coNP Function @ lexical-lisp1-binding
.synb
.mets (lexical-lisp1-binding < env << symbol )
.syne
.desc
The
.code lexical-lisp1-binding
function inspects the macro-time environment
.meta env
to determine what kind of binding, if any, does
.meta symbol
have in that environment, from a Lisp-1 perspective.

That is to say, it considers function bindings, variable bindings
and symbol macro bindings to be in a single name space and finds
the innermost binding of one of these types for
.metn symbol .

If such a binding is found, then the function returns one of
the three keyword symbols
.codn :var ,
.codn :fun ,
or
.codn :symacro .

If no such lexical binding is found, then the function
returns
.codn nil .

Note that a
.code nil
return doesn't mean that the symbol doesn't have a lexical binding.  It could
have an operator macro lexical binding (a macro binding in the function
namespace established by
.codn macrolet ).

.coNP Operator @ defsymacro
.synb
.mets (defsymacro < sym << form )
.syne
.desc
A
.code defsymacro
form introduces a symbol macro. A symbol macro consists of a binding
between a symbol
.meta sym
and and a
.metn form .
The binding denotes the form itself, rather than its value. How the
symbol macro works is that if
.meta sym
occurs as a form in a scope where the symbol macro definition is
in scope,
.meta sym
is replaced by
.metn form .
Immediately after this replacement takes place,
.meta form
itself is then processed for further replacement of macros and
symbol macros.

Symbol macros are also recognized in contexts
where
.meta sym
denotes a place which is the target of an assignment operation
like
.code set
and similar.

A
.code defsymacro
form is implicitly executed at expansion time, and thus need
not be wrapped in a
.code macro-time
form, just like
.codn defmacro .

Note: if a symbol macro expands to itself directly, expansion stops. However,
if a symbol macro expands to itself through a chain of expansions,
runaway expansion-time recursion will occur.

If a global variable exists by the name
.metn sym ,
then
.code defsymacro
first removes that variable from the global environment, and if that
variable is special, the symbol's special marking is removed.
.code defsymacro
doesn't alter the dynamic binding of a special variable. Any such
a binding remains intact.
If
.code defsymacro
is evaluated in a scope in which there is any lexical or dynamic binding
of
.meta sym
in the variable namespace, whether as a variable or macro,
the global symbol macro is shadowed by that binding.

.coNP Operator @ symacrolet
.synb
.mets (symacrolet >> ({( sym << form )}*) << body-form *)
.syne
.desc
The
.code symacrolet
operator binds local, lexically scoped macros that are
similar to the global symbol macros introduced by
.codn defsymacro .

Each
.meta sym
in the bindings list is bound to its corresponding form, creating a
new extension of the expansion-time lexical macro environment.

Each
.meta body-form
is subsequently macro-expanded in this new environment
in which the new symbol macros are visible.

Note: ordinary lexical bindings such as those introduced by let or by
function parameters lists shadow symbol macros. If a symbol
.code x
is bound by nested instances of
.code macrolet
and a
.codn let ,
then the scope enclosed by both
constructs will see whichever of the two bindings is more inner,
even though the bindings are active in completely separate phases of
processing.

From the perspective of the arguments of a
.code dwim
form, lexical function bindings also shadow symbol macros.
This is consistent with the Lisp-1-style name resolution which
applies inside a
.code dwim
form. Lexical operator macros do not shadow
symbol macros under any circumstances.

.coNP Macros @ placelet and @ placelet*
.synb
.mets (placelet >> ({( sym << place )}*) << body-form *)
.mets (placelet* >> ({( sym << place )}*) << body-form *)
.syne
.desc
The
.code placelet
macro binds lexically scoped symbol macros in such
a way that they behave as aliases for places
denoted by place forms.

Each
.meta place
must be an expression denoting a syntactic place. The
corresponding
.meta sym
is established as an alias for the storage location which that place denotes,
over the scope of the
.metn body-form -s.

This binding takes place in such a way that each
.meta place
is evaluated exactly once, only in order to determine its
storage location.  The corresponding
.meta sym
then serves as an alias for that location, over the
scope of the
.metn body-form -s.
This means that whenever
.meta sym
is evaluated, it stands for the value of the storage
location, and whenever a value is apparently stored into
.metn sym ,
it is actually the storage location which receives it.

The
.code placelet*
variant implements an alternative scoping rule, which allows a later
.meta place
form to refer to a
.meta sym
bound to an earlier
.meta place
form. In other words, a given
.meta sym
binding is visible not only to the
.metn body-form -s
but also to
.meta place
forms which occur later.

Note: certain kinds of places, notably
.mono
.meti (force << promise )
.onom
expressions, must be accessed before they can be stored,
and this restriction continues to hold when those
places are accessed through
.code placelet
aliases.

Note:
.code placelet
differs from
.code symacrolet
in that the forms themselves are not aliased, but the storage
locations which they denote.
.code "(symacrolet ((x y)) z)"
performs the syntactic substitution of symbol
.code x
by form
.codn y ,
wherever
.code x
appears inside
.code z
as an evaluated form, and is not shadowed by any inner binding.
Whereas
.code "(placelet ((x y)) z)"
generates code which arranges for
.code y
to be evaluated to a storage location, and syntactically replaces occurrences
of
.code x
with a form which directly denotes that storage location,
wherever
.code x
appears inside
.code z
as an evaluated form, and is not shadowed by any inner binding.
Also,
.code x
is not necessarily substituted by a single, fixed form,
as in the case of
.codn symacrolet .
Rather it may be substituted by one kind of form when it
is treated as a pure value, and another kind of form
when it is treated as a place.

.TP* "Example:"

Implementation of
.code inc
using
.codn placelet :

.verb
  (defmacro inc (place : (delta 1))
    (with-gensyms (p)
      ^(placelet ((,p ,place))
         (set ,p (+ ,p ,delta)))))
.brev

The gensym
.code p
is used to avoid accidental capture of references
emanating from the
.code delta
form.

.coNP Macro @ equot
.synb
.mets (equot << form )
.syne
.desc
The
.code equot
macro ("expand and quote") performs a full expansion of
.code form
in the surrounding macro environment. Then it constructs a
.code quote
form whose argument is the expansion. This quote form is
then returned as the macro replacement for the original
.code equot
form.

.TP* Example:

.verb
  (symacrolet ((a (+ 2 2)))
    (list (quote a) (equot a) a))
  --> (a (+ 2 2) 4)
.brev

Above, the expansion of
.code a
is
.codn "(+ 2 2)" .
Thus the macro call
.code "(equot a)"
expands to
.codn "(quote (+ 2 2))" .
When that is evaluated, it yields
.codn "(+ 2 2)" .

If
.code a
is quoted, then the result is
.codn a :
no expansion or evaluation takes place.
Whereas if
.code a
is presented for evaluation, then not only is it expanded to
.codn "(+ 2 2)" ,
but that expansion is reduced to 4.

The
.code equot
operator is a mongrel of these two semantics: it permits expansion to proceed,
but then suppresses evaluation of the result.

.coNP Operators @ tree-bind and @ mac-param-bind
.synb
.mets (tree-bind < macro-style-params < expr << form *)
.mets (mac-param-bind < context-expr
.mets \ \  < macro-style-params < expr << form *)
.syne
.desc
The
.code tree-bind
operator evaluates
.codn expr ,
and then uses the
resulting value as a counterpart to a macro-style parameter list.
If the value has a tree structure which matches the parameters,
then those parameters are established as bindings, and the
.metn form -s,
if any, are evaluated in the scope of those bindings.  The value
of the last
.meta form
is returned. If there are no forms,
.code nil
is returned.

Note: this operator throws an exception if there is a
structural mismatch between the parameters and the value of
.codn expr .

One way to avoid this exception is to use
.codn tree-case .

The
.code mac-param-bind
operator is similar to
.code tree-bind
except that it takes an extra argument,
.metn context-expr .
This argument is an expression which is evaluated. It is expected to
evaluate to a compound form. If an error occurs during binding, the error
diagnostic message is based on information obtained from this form.
By contrast, the
.code tree-bind
operator's error diagnostic refers to the
.code tree-bind
form, which is cryptic if the binding is used for the implementation
of some other construct, hidden from the user of that construct.

.coNP Operator @ tree-case
.synb
.mets (tree-case < expr >> {( macro-style-params << form *)}*)
.syne
.desc
The
.code tree-case
operator evaluates
.meta expr
and matches it against a succession
of zero or more cases. Each case defines a pattern match, expressed as a macro
style parameter list
.metn macro-style-params .

If the object produced by
.meta expr
matches
.metn macro-style-params ,
then the parameters are bound, becoming local variables, and the
.metn form -s,
if any, are evaluated in order in the environment in which those variables are
visible.  If there are forms, the value of the last
.meta form
becomes the result
value of the case, otherwise the result value of the case is nil.

If the result value of a case is the object
.code :
(the colon symbol), then processing continues with the next case. Otherwise the
evaluation of
.code tree-case
terminates, returning the result value.

If the value of
.meta expr
does not match the
.meta macro-style-params
parameter list of a case, processing continues with the next case.

If no cases match, then
.code tree-case
terminates, returning
.codn nil .

.TP* Example:

.verb
  ;; reverse function implemented using tree-case

  (defun tb-reverse (obj)
    (tree-case obj
      (() ())      ;; the empty list is just returned
      ((a) obj)    ;; one-element list returned
      ((a . b) ^(,*(tb-reverse b) ,a)) ;; car/cdr recursion
      (a a)))     ;; atom is just returned
.brev

Note that in this example, the atom case is placed last, because an
argument list which consists of a symbol is a "catch all" match
that matches any object. We know that it matches an atom, because
the previous
.code "(a . b)"
case matches conses. In general, the order of the cases in
.code tree-case
is important: even more so than the order of cases in a
.code cond
or
.codn caseql .
The one-element list case is unnecessary; it can be removed.

.coNP Macro @ tb
.synb
.mets (tb < macro-style-params << form *)
.syne
.desc
The
.code tb
macro is similar to the
.code lambda
operator but its argument binding is based on a macro-style parameter list.
The name is an abbreviation of
.codn tree-bind .

A
.code tb
form evaluates to a function which takes a variable number of
arguments.

When that function is called, those arguments are taken as a list object which
is matched against
.meta macro-style-params
as if by
.metn tree-bind .
If the match is successful, then the parameters are bound to the
corresponding elements from the argument structure and each successive
.meta form
is evaluated an environment in which those bindings are visible.
The value of the last
.meta form
is the return value of the function. If there are no forms,
the function's return value is
.codn nil .

The following equivalence holds, where
.code args
should be understood to be a globally unique symbol:

.verb
  (tb pattern body ...) <--> (lambda (. args)
                               (tree-bind pattern args body ...))
.brev

.coNP Macro @ tc
.synb
.mets (tc >> {( macro-style-params << form *)}*)
.syne
.desc
The
.code tc
macro produces an anonymous function whose behavior is closely
based on the
.code tree-case
operator. Its name is an abbreviation of
.codn tree-case .

The anonymous function takes a variable number of arguments.
Its argument list is taken to be the value macro is tested
against the multiple pattern clauses of an implicit
.codn tree-case .
The return value of the function is that of the implied
.codn tree-case .

The following equivalence holds, where
.code args
should be understood to be a globally unique symbol:

.verb
  (tc clause1 clause2 ...) <--> (lambda (. args)
                                   (tree-case args
                                      clause1 clause2 ...))
.brev

.coNP Macro @ with-gensyms
.synb
.mets (with-gensyms <> ( sym *) << body-form *)
.syne
.desc
The
.code with-gensyms
evaluates the
.metn body-form -s
in an environment in which each variable name symbol
.meta sym
is bound to a new uninterned symbol ("gensym").

.TP* "Example:"

The code:

.verb
  (let ((x (gensym))
        (y (gensym))
        (z (gensym)))
    ^(,x ,y ,z))
.brev

may be expressed more conveniently using the
.code with-gensyms
shorthand:

.verb
  (with-gensyms (x y z)
    ^(,x ,y ,z))
.brev

.SS* Parameter List Macros

Parameter list macros, also more briefly called
.I "parameter macros"
are an original feature of \*(TL.

If the first element of a function or macro parameter list is a keyword
symbol other than
.codn :env ,
.codn :whole ,
.code :form
or
.code :
(the colon symbol),
it denotes a parameter macro. This keyword symbol is expected to
have a binding in the parameter macro namespace: a global namespace
which associates keyword symbols with parameter list expander
functions.

Expansion of a parameter list macro occurs at macro-expansion
time, when a function's parameter list is traversed by the
macro expander. It takes place as follows.
First, the keyword is removed from the parameter list.
The keyword's binding in the parameter macro namespace is
retrieved. If it doesn't exist, an exception is thrown.
Otherwise, the remaining parameter list is first recursively
processed for more occurrences of parameter macros.
This expansion produces a transformed parameter list,
along with a transformed function body. These two artifacts
are then passed to the transformer function retrieved from
the keyword symbol's binding. The function returns a
further transformed version of the parameter list and
body. These are processed for more parameter macros.
The process terminates when no more expansion is
possible, because a parameter list has been produced
which does not begin with a parameter macro. This
final parameter list and its accompanying body are then
taken in place of the original parameter list and
body.

\*(TL provides a built-in parameter list macro bound to the symbol
.code :key
which endows a function keyword parameters. The implementation is
written entirely using this parameter list macro mechanism, by means
of the
.code define-param-expander
macro.

.coNP Special variable @ *param-macro*
.desc
The variable
.code *param-macro*
holds a hash table which associates keyword symbols with
parameter list expander functions.

The functions are expected to conform to the following
syntax:

.mono
.mets (lambda >> ( params < body < env << form ) << form *)
.onom

The
.meta params
parameter receives the parameter list of the function
which is undergoing parameter expansion. All other
parameter macros have already been expanded.

The
.meta body
parameter receives the list of body forms.
The function is expected to return a
.code cons
cell whose
.code car
contains the transformed parameter list, and whose
.code cdr
contains the transformed list of body forms.
Parameter expansion takes place at macro expansion time.

The
.meta env
parameter receives the macro-expansion-time environment
which surrounds the function being expanded.
Note that this environment doesn't take into account the
parameters themselves; therefore, it is not the correct environment
for expanding macros among the
.meta body
forms. For that purpose, it must be extended with
shadowing entries, the manner of doing which is
undocumented. However
.meta env
may be used directly for expanding init forms
for optional parameters occurring in
.metn params .

The
.meta form
parameter receives the overall function-defining
form that is being processes, such as a
.code defun
or
.code lambda
form. This is intended for error reporting.

.coNP Macro @ define-param-expander
.synb
.mets (define-param-expander < name >> ( pvar < bvar : < evar << fvar )
.mets \ \  << form *)
.syne
.desc
The
.code define-param-expander
macro provides syntax for defining parameter macros. Invocations
of this macro expand to code which constructs an anonymous
function and installs it into the
.code *param-macro*
hash table, under the key given by
.metn name .

The
.meta name
parameter's argument should be a keyword symbol that is valid for use
as a parameter macro name.

The
.metn pvar ,
.metn bvar ,
.meta evar
and
.meta fvar
arguments must be symbols suitable for variable
binding. These symbols define the parameters of the
expander function which shall, respectively, receive
the parameter list, body forms, macro environment
and function form. If
.meta evar
is omitted, a symbol generated by the
.code gensym
function is used. Likewise if
.meta fvar
is omitted.

The
.meta form
arguments constitute the body of the expander.

The
.code define-param-expander
form returns
.metn name .

.TP* Example:

The following example shows the implementation
of a parameter macro
.code :memo
which provides rudimentary memoization.
Using the macro is extremely easy. It is a matter
of simply inserting the
.code :memo
keyword at the front of a function's parameter list.
The function is then memoized.

.verb
  (defvarl %memo% (hash :weak-keys))

  (defun ensure-memo (sym)
    (or (gethash %memo% sym)
        (sethash %memo% sym (hash))))

  (define-param-expander :memo (param body)
    (let* ((memo-parm [param 0..(posq : param)])
           (hash (gensym))
           (key (gensym)))
      ^(,param (let  ((,hash (ensure-memo ',hash))
                      (,key (list ,*memo-parm)))
                 (or (gethash ,hash ,key)
                     (sethash ,hash ,key (progn ,*body)))))))
.brev

The above
.code :memo
macro may be used to define a memoized Fibonacci function
as follows:

.verb
  (defun fib (:memo n)
    (if (< n 2)
      (clamp 0 1 n)
      (+ (fib (pred n)) (fib (ppred n)))))
.brev

All that is required is the insertion of the
.code :memo
keyword.

.coNP Parameter list macro @ :key
.synb
.mets (:key << non-key-param *
.mets \ \  [ -- >> { sym | >> ( sym >> [ init-form <> [ p-sym ]])}* ]
.mets \ \  [ . rest-param ])
.syne
.desc
Parameter list macro
.code :key
injects keyword parameter support into functions and macros.

When
.code :key
appears as the first item in a function parameter list, a special syntax is
recognized in the parameter list. After any required and optional parameters,
the symbol
.code --
(two dashes) may appear. Parameters after this symbol are interpreted
as keyword parameters. After the keyword parameters, a rest parameter
may appear in the usual way as a symbol in the dotted position.

Keyword parameters use the same syntax as optional parameters, except
that if used in a macro parameter list, they do not support
destructuring whereas optional parameters do. That is to say, regardless
whether
.code :key
is used in a function or macro, keyword parameters are symbols.

A keyword parameter takes three possible forms:

.RS
.meIP < sym
A keyword parameter may be specified as a simple symbol
.metn sym .
If the argument for such a keyword parameter is missing,
it takes on the value
.codn nil .
.meIP >> ( sym << init-form )
If the keyword parameter symbol
.meta sym
is enclosed in a list, then the second element of that list
specifies a default value, similarly to the default value for
an optional argument. If the function is called in such a way
that the argument for the parameter is missing, the
.meta init-form
is evaluated and the resulting value is bound to the keyword parameter.
The evaluation takes place in a lexical scope in which the
required and optional parameters are are already visible,
and their values are bound. If there is a
.meta rest-param
it is also visible in this scope, even though in the parameter
list it appears to the left.
.meIP >> ( sym < init-form << p-sym )
The three-element form of the keyword parameter specifies
an additional symbol
.metn p-sym ,
which names an argument that implicitly receives a Boolean
argument indicating the presence of the keyword argument.
If an argument is not passed for the keyword parameter
.metn sym ,
then parameter
.meta sym-p
takes on the value
.codn nil .
If an argument is given for
.metn sym ,
then the
.meta sym-p
argument takes on the value
.codn t .
This mechanism also closely resembles the analogous
one supported in optional arguments. See the previous
paragraph regarding the evaluation scope of
.metn init-form .
.RE

.IP
In a call to a
.codn :key -enabled
function, keyword arguments begin after those arguments which satisfy
all of the required and optional parameters. Keyword arguments consist
of interleaved indicators and values, which are separate arguments.
Thus passing a keyword argument actually requires the passing of two
function arguments: an indicator keyword symbol, followed by the
associated value. The indicator keywords are expected to have the
same symbol name as the defined keyword parameters. For instance, the
indicator-value pair
.code ":xyz 42"
passes the value
.code 42
to a keyword parameter that may be named
.code xyz
in any package: it may be
.code usr:xyz
or
.code mypackage:xyz
and so forth.
Arguments specifying unrecognized keywords are ignored.

If the function has a
.metn rest-param ,
then that parameter receives the keyword arguments as a list.
Since that list contains indicators and values, it is a
.I "de facto"
property list. In detail, the
.code :key
mechanism generates a regular variadic function which receives the keyword
arguments as the trailing argument list. That function
parses the recognized keyword arguments out of the trailing list, and
binds them to the keyword parameter symbols as local variables. If a
.meta rest-param
parameter is defined, then the entire keyword argument list is available
through that parameter, and the keyword argument parsing logic also refers to
the value of that parameter to gain access to the keyword arguments. If
there is no
.meta rest-param
specified, then the
.code :key
macro adds a
.meta rest-param
using a machine-generated symbol. The argument parsing logic then
refers to the value of that symbol.

.TP* Example:

Define a function
.code fun
with two required arguments
.codn "a b" ,
one optional argument
.codn c ,
two keyword arguments
.code foo
and
.codn bar ,
and a rest parameter
.codn klist :

.verb
  (defun fun (:key a b : c -- foo bar . klist)
    (list a b c foo bar klist))

  (fun 1 2 3 :bar 4) -> (1 2 3 nil 4 (:bar 4))
.brev

Define a function with only keyword arguments, with default expressions and
Boolean indicator params:

.verb
  (defun keyfun (:key -- (a 10 a-p) (b 20 b-p))
    (list a a-p b b-p))

  (keyfun :a 3) -> (3 t 20 nil)

  (keyfun :b 4) -> (10 nil 4 t)

  (keyfun :c 4) -> (10 nil 20 nil)

  (keyfun) -> (10 nil 20 nil)
.brev

.SS* Mutation of Syntactic Places
.coNP Macro @ set
.synb
.mets (set >> { place << new-value }*)
.syne
.desc
The
.code set
operator stores the values of expressions in places. It must
be given an even number of arguments.

If there are no arguments, then
.code set
does nothing and returns
.codn nil .

If there are two arguments,
.meta place
and
.metn new-value ,
then
.meta place
is evaluated to determine its storage location, then
.meta new-value
is evaluated to determine the value to be stored there,
and then the value is stored in that location. Finally,
the value is also returned as the result value.

If there are more than two arguments, then
.code set
performs multiple assignments in left to right order.
Effectively,
.code "(set v1 e1 v2 e2 ... vn en)"
is precisely equivalent to
.codn "(progn (set v1 e1) (set v2 e2) ... (set vn en))" .

.coNP Macro @ pset
.synb
.mets (pset >> { place << new-value }*)
.syne
.desc
The syntax of
.code pset
is similar to that of
.codn set ,
and the semantics is similar also in that zero or more places are
assigned zero or more values. In fact, if there are no arguments, or
if there is exactly one pair of arguments,
.code pset
is equivalent to
.codn set .

If there are two or more argument pairs, then all of the arguments
are evaluated first, in left-to-right order.  No store takes place
until after every
.meta place
is determined, and every
.meta new-value
is calculated. During the calculation, the values to be stored
are retained in hidden, temporary locations. Finally, these values
are moved into the determined places. The rightmost value is returned
as the form's value.

The assignments thus appear to take place in parallel, and
.code pset
is capable of exchanging the values of a pair of places, or rotating
the values among three or more places. (However, there are more convenient
operators for this, namely
.code rotate
and
.codn swap ).

.TP* Example:
.verb
  ;; exchange x and y
  (pset x y y x)

  ;; exchange elements 0 and 1; and 2 and 3 of vector v:
  (let ((v (vec 0 10 20 30))
        (i -1))
    (pset [vec (inc i)] [vec (inc i)]
          [vec (inc i)] [vec (inc i)])
     vec)
  -> #(10 0 30 20)
.brev

.coNP Macro @ zap
.synb
.mets (zap < place <> [ new-value ])
.syne
.desc
The
.code zap
macro assigns
.meta new-value
to
.meta place
and returns the previous value of
.metn place .

If
.meta new-value
is missing, then
.code nil
is used.

In more detail, first
.code place
is evaluated to determine the storage location.
Then, the location is accessed to retrieve the
previous value. Then, the
.code new-value
expression is evaluated, and that value is
placed into the storage location.
Finally, the previously retrieved value is returned.

.coNP Macro @ flip
.synb
.mets (flip << place )
.syne
.desc
The
.code flip
macro toggles the Boolean value stored in
.metn place .

If
.meta place
previously held
.codn nil ,
it is set to
.codn t ,
and if it previously held a value other than
.codn nil ,
it is set to
.codn nil .

.coNP Macros @ test-set and @ test-clear
.synb
.mets (test-set << place )
.mets (test-clear << place )
.syne
.desc
The
.code test-set
macro examines the value of
.metn place .
If it is
.code nil
then it stores
.code t
into the place, and returns
.codn t .
Otherwise it leaves
.meta place
unchanged and returns
.codn nil .

The
.code test-clear
macro examines the value of
.metn place .
If it is Boolean true (any value except
.codn nil )
then it stores
.code nil
into the place, and returns
.codn t .
Otherwise it leaves
.meta place
unchanged and returns
.codn nil .

.coNP Macro @ compare-swap
.synb
.mets (compare-swap < place < cmp-fun < cmp-val << store-val )
.syne
.desc
The
.code compare-swap
macro examines the value of
.meta place
and compares it to
.meta cmp-val
using the comparison function given by the function name
.metn cmp-fun .

This comparison takes places as if by evaluating the expression
.meti >> ( cmp-fun < value << cmp-val )
where
.meta value
denotes the current value of
.metn place .

If the comparison is false,
.meta place
is not modified, the
.meta store-val
expression is not evaluated, and the macro returns
.codn nil .

If the comparison is true, then
.code compare-swap
evaluates the
.meta store-val
expression, stores the resulting value into
.meta place
and returns
.codn t .

.coNP Macros @ inc and @ dec
.synb
.mets (inc < place <> [ delta ])
.mets (dec < place <> [ delta ])
.syne
.desc
The
.code inc
macro increments
.meta place
by adding
.meta delta
to its value.
If
.meta delta
is missing, the value used in its place the integer 1.

First the
.meta place
argument is evaluated as a syntactic place to determine the location.
Then, the value currently stored in that location is retrieved.
Next, the
.meta delta
expression is evaluated. Its value is added to the previously retrieved
value as if by the
.code +
function. The resulting value is stored in the place, and returned.

The macro
.code dec
works exactly like
.code inc
except that addition is replaced by subtraction. The similarly defaulted
.meta delta
value is subtracted from the previous value of the place.

.coNP Macros @ pinc and @ pdec
.synb
.mets (pinc < place <> [ delta ])
.mets (pdec < place <> [ delta ])
.syne
.desc
The macros
.code pinc
and
.code pdec
are similar to
.code inc
and
.codn dec .

The only difference is that they return the previous value of
.meta place
rather than the incremented value.

.coNP Macros @ test-inc and @ test-dec
.synb
.mets (test-inc < place >> [ delta <> [ from-val ]])
.mets (test-dec < place >> [ delta <> [ to-val ]])
.syne
.desc
The
.code test-inc
and
.code test-dec
macros provide combined operations which change the value of a place and
provide a test whether, respectively, a certain previous value was
overwritten, or a certain new value was attained. By default, this tested
value is zero.

The
.code test-inc
macro notes the prior value of
.meta place
and then updates it with that value, plus
.metn delta ,
which defaults to 1. If the prior value is
.code eql
to
.meta from-val
then it returns
.codn t ,
otherwise
.codn nil .
The default value of
.meta from-val
is zero.

The
.code test-dec
macro produces a new value by subtracting
.meta delta
from the value of
.metn place .
The argument
.meta delta
defaults to 1. The new value is stored into
.metn place .
If the new value is
.code eql
to
.meta to-val
then
.code t
is returned, otherwise
.codn nil .

.coNP Macro @ swap
.synb
.mets (swap < left-place << right-place )
.syne
.desc
The
.code swap
macro exchanges the values of
.meta left-place
and
.meta right-place
and returns the value which is thereby transferred to
.metn right-place .

First,
.meta left-place
and
.meta right-place
are evaluated, in that order, to determine their locations.
Then the prior values are retrieved, exchanged and stored back.
The value stored in
.meta right-place
is also returned.

If
.meta left-place
and
.meta right-place
are ranges of the same sequence, the behavior is not specified
if the ranges overlap or are of unequal length.

Note: the
.code rotate
macro's behavior is somewhat more specified in this regard.
Thus, although any correct
.code swap
expression can be expressed using
.codn rotate ,
but the reverse isn't true.

.coNP Macro @ push
.synb
.mets (push < item << place )
.syne
.desc
The
.code push
macro places
.meta item
at the head of the list stored in
.meta place
and returns the updated list which is stored back in
.metn place .

First, the expression
.meta item
is evaluated to produce the push value.
Then,
.meta place
is evaluated to determine its storage location.
Next, the storage location is accessed to retrieve the
list value which is stored there. A new object is
produced as if by invoking
.code cons
function on the push value and list value.
This object is stored into the location,
and returned.

.coNP Macro @ pop
.synb
.mets (pop << place )
.syne
.desc
The
.code pop
macro removes an element from the list stored in
.meta place
and returns it.

First,
.meta place
is evaluated to determine the place. The place is accessed to
retrieve the original value. Then a new value is calculated,
as if by applying the
.code cdr
function to the old value. This new value is stored.
Finally, a return value is calculated and returned, as if by applying the
.code car
function to the original value.

.coNP Macro @ pushnew
.synb
.mets (pushnew < item < place >> [ testfun <> [ keyfun ]])
.syne
.desc
The
.code pushnew
macro inspects the list stored in
.metn place .
If the list already contains the item, then
it returns the list. Otherwise it creates a new list
with the item at the front and stores it back
into
.metn place ,
and returns it.

First, the expression
.meta item
is evaluated to produce the push value.
Then,
.meta place
is evaluated to determine its storage location.
Next, the storage location is accessed to retrieve the
list value which is stored there. The list is
inspected to check whether it already contains the push
value, as if using the
.code member
function.  If that is the case, the list
is returned and the operation finishes.
Otherwise, a new object is
produced as if by invoking
.code cons
function on the push value and list value.
This object is stored into the location
and returned.

.coNP Macro @ shift
.synb
.mets (shift << place + << shift-in-value)
.syne
.desc
The
.code shift
macro treats one or more places as a "multi-place shift register".
The values of the places are shifted one place to the left.
The first (leftmost) place receives the value of the second place,
the second receives that of the third, and so on.
The last (rightmost) place receives
.meta shift-in-value
(which is not treated as a place, even if it is a syntactic place form).
The previous value of the first place is returned.

More precisely, all of the argument forms are evaluated left to right, in the
process of which the storage locations of the places are determined,
.meta shift-in-value
is reduced to its value.

The values stored in the places are sampled and saved.

Note that it is not specified whether the places are sampled in a separate
pass after the evaluation of the argument forms, or whether the
sampling is interleaved into the argument evaluation. This affects
the behavior in situations in which the evaluation of any of the
.meta place
forms, or of
.metn shift-in-value ,
has the side effect of modifying later places.

Next, the places are updated by storing the saved value of the second
place into the first place, the third place into the second and so forth,
and the value of
.meta shift-in-value
into the last place.

Finally, the saved original value of the first place is returned.

If any of the places are ranges which index into the same sequence,
and the behavior is not otherwise unspecified due to the issue
noted in an earlier paragraph, the effect upon the multiply-stored
sequence can be inferred from the above-described storage order.
Note that even if stores take place which change the length of
the sequence and move some elements, not-yet-processed stores whose ranges
to refer to these elements are not adjusted.

With regard to the foregoing paragraph, a recommended practice is
that if subranges of the same sequence object are shifted, they be
given to the macro in ascending order of starting index. Furthermore, the
semantics is simpler if the ranges do not overlap.

.coNP Macro @ rotate
.synb
.mets (rotate << place *)
.syne
.desc
Treats zero or more places as a "multi-place rotate register".
If there are no arguments, there is no effect and
.code nil
is returned. Otherwise, the last (rightmost) place receives
the value of the first (leftmost) place. The leftmost place
receives the value of the second place, and so on.
If there are two arguments, this equivalent to
.codn swap .
The prior value of the first place, which is the the value
rotated into the last place, is returned.

More precisely, the
.meta place
arguments are evaluated left to right,
and the storage locations are thereby determined. The storage
locations are sampled, and then the sampled values are
stored back into the locations, but rotated by one place
as described above. The saved original value of the leftmost
.meta place
is returned.

It is not specified whether the sampling of the original values
is a separate pass which takes place after the arguments
are evaluated, or whether this sampling it is interleaved into argument
evaluation. This affects
the behavior in situations in which the evaluation of any of the
.meta place
forms has the side effect of modifying the value stored in
a later
.meta place
form.

If any of the places are ranges which index into the same sequence,
and the behavior is not otherwise unspecified due to the issue
noted in the preceding paragraph, the effect upon the multiply-stored
sequence can be inferred from the above-described storage order.
Note that even if stores take place which change the length of
the sequence and move some elements, not-yet-processed stores whose ranges
to refer to these elements are not adjusted.

With regard to the foregoing paragraph, a recommended practice is
that if subranges of the same sequence object are shifted, they be
given to the macro in ascending order of starting index. Furthermore, the
semantics is simpler if the ranges do not overlap.

.coNP Macro @ del
.synb
.mets (del << place )
.syne
.desc
The
.code del
macro requests the deletion of
.codn place .
If
.code place
doesn't support deletion, an exception is thrown.

First
.code place
is evaluated, thereby determining its location.
Then the place is accessed to retrieve its value.
The place is then subject to deletion. Finally, the
previously retrieved value is returned.

Precisely what deletion means depends on the kind of place.
The built-in places in \*(TL have deletion semantics which are
intended to be unsurprising to the programmer familiar with the
data structure which holds the place.

Generally, if a place denotes the element of a sequence, then deletion of the
place implies deletion of the element, and deletion of the element implies that
the gap produced by the element is closed.  The deleted element is effectively
replaced by its successor, that successor by its successor and so on. If a
place denotes a value stored in a dynamic data set such as a hash table,
then deletion of that place implies deletion of the entry which holds
that value. If the entry is identified by a key, that key is also removed.

.coNP Macro @ lset
.synb
.mets (lset <> { place }+ << sequence-expr )
.syne
.desc
The
.code lset
operator's parameter list consists of one or more places followed
by an expression
.metn sequence-expr .

The macro evaluates
.codn sequence-expr ,
which is expected to produce a sequence.

Successive elements of the resulting list are then assigned to each
successive
.codn place .

If there are fewer elements in the sequence than places, the
unmatched places receive the value
.codn nil .

Excess elements in the sequence are ignored.

An error exception occurs if the sequence is an improper list with fewer
elements than places.

A
.code lset
form produces the value of
.meta sequence-expr
as its result value.

.coNP Macro @ upd
.synb
.mets (upd < place << opip-arg *)
.syne
.desc
The
.code upd
macro evaluates
.meta place
and passes the value as an argument to the operational pipeline
function formed,
as if by the
.code opip
macro, from the
.meta opip-arg
arguments.  The result of this function is then stored back into
.metn place .

The following equivalence holds, except that place
.code p
is evaluated only once:

.verb
  (upd p x y z ...)  <-->  (set p (call (opip x y z ...) p))
.brev

.SS* User-Defined Places and Place Operators
\*(TL provides a number of place-modifying operators such as
.codn set ,
.codn push ,
and
.codn inc .
It also provides a variety of kinds of syntactic places
which may be used with these operators.

Both of these categories are open-ended: \*(TL programs may extend
the set of place-modifying operators, as well as the vocabulary of
forms which are recognized as syntactic places.

Regarding place operators, it might seem obvious that new place operators can
be developed, since they are macros, and macros can expand to uses
of existing place operators. As an example, it may seem that
.code inc
operator could be written as a macro which uses
.codn set :

.verb
  (defmacro new-inc (place : (delta 1))
    ^(set ,place (+ ,place ,delta)))
.brev

However, the above
.code new-inc
macro has a problem: the
.code place
argument form is inserted into two places in the expansion, which
leads to two evaluations. This is visibly incorrect if the place
form contains any side effects. It is also potentially inefficient.

\*(TL provides a framework for writing place update macros which
evaluate their argument forms once, even if they have to access
and update the same places.

The framework also supports the development of new kinds of place forms
as capsules of code which introduce the right kind of material into
the lexical environment of the body of an update macro, to enable
this special evaluation.

.NP* Place-Expander Functions
The central design concept in \*(TL syntactic places are
.IR "place-expander functions" .
Each compound place is defined by up to three place-expander functions,
which are associated with the place via the leftmost operator
symbol of the place form. One place-expander, the
.IR "update expander" ,
is mandatory. Optionally, a place may also provide a
.I "clobber expander"
as well as a
.IR "delete expander" .
An update expander provides the expertise for evaluating a place form once
in its proper run-time context to determine its actual run-time storage
location, and to access and modify the storage location.
A clobber expander provides an optimized mechanism for uses that perform
a one-time store to a place without requiring its prior value.
If a place definition does not supply a clobber expander, then the syntactic
places framework uses the update expander to achieve the functionality.
A delete expander provides the expertise for determining the actual run-time
storage location corresponding to a place, and obliterating it,
returning its prior value.  If a place does not supply a delete expander, then
the place does not support deletion. Operators which require deletion, such as
.code del
will raise an error when applied to that place.

The expanders operate independently, and it is expected that place-modifying
operators choose one of the three, and use only that expander. For example,
accessing a place with an update expander and then overwriting its value
with a clobber expander may result in incorrect code which contains multiple
evaluations of the place form.

The programmer who implements a new place does not write expanders directly,
but rather defines them via the
.codn defplace ,
.code define-accessor
or
.code defset
macro.

The programmer who implements a new place update macro likewise does not
call the expanders directly. Usually, they are invoked via the macros
.codn with-update-expander ,
.code with-clobber-expander
and
.codn with-delete-expander .
These are sufficient for most kind of macros.
In certain complicated cases, expanders may be invoked using the wrapper
functions
.codn call-update-expander ,
.code call-clobber-expander
and
.codn call-delete-expander .
These convenience macros and functions perform certain common chores, like
macro-expanding the place in the correct environment, and choosing the
appropriate function.

The expanders are described in the following sections.

.NP* The Update Expander
.synb
.mets (lambda >> ( getter-sym < setter-sym < place-form
.mets \ \ \ \ \ \ \ \  << body-form ) ...)
.syne
.desc
The update expander is a code-writer. It takes a
.meta body-form
argument, representing code, and returns a larger form which surrounds
this code with additional code.

This larger form returned by the update expander can be regarded as having two
abstract actions, when it is substituted and evaluated in the context where
.meta place-form
occurs.  The first abstract action is to evaluate
.meta place-form
exactly one time, in order to determine the actual run-time location to which
that form refers.
The second abstract action is to evaluate the caller's
.metn body-form -s,
in a lexical environment in which bindings exist for some lexical
functions or (more usually) lexical macros. These lexical macros
are explicitly referenced by the
.metn body-form ;
the update expander just provides their definition, under the names
it is given via the
.meta getter-sym
and
.meta setter-sym
arguments.

The update expander writes local functions or macros under these names: a
getter function and a setter function.  Usually, update expanders write
macros rather than functions, possibly in combination with some lexical
anonymous variables which hold temporary objects. Therefore the getter
and setter are henceforth referred to as macros.

The code being generated is with regard to some concrete instance of
.metn place-form .
This argument is the actual form which occurs in a program. For
instance, the update expander for the
.code car
place might be called with an arbitrary variant of the
.meta place-form
which might look like
.codn "(car (inc (third some-list)))" .

In the abstract semantics, upfront code wrapped around the
.meta body-form
by the update expander provides the logic to evaluate this place to
a location, which is retained in some hidden local context.

The getter local macro named by
.meta getter-sym
must provide the logic for retrieving the value of this place.
The getter macro takes no arguments.
The
.meta body-form
makes free use of the getter function; they may call it multiple times,
which must not trigger multiple evaluations of the original place
form.

The setter local macro named by
.meta setter-sym
must generate the logic for storing a new value into the once-evaluated
version of
.metn place-form .
The setter function takes exactly one argument, whose
value specifies the value to be stored into the place.
It is the caller's responsibility to ensure that the
argument form which produces the value to be stored via the setter is evaluated
only once, and in the correct order.  The setter does not concern itself with
this form. Multiple calls to the setter can be expected to result in multiple
evaluations of its argument. Thus, if necessary, the caller must supply the code
to evaluate the new value form to a temporary variable, and then pass the
temporary variable to the setter. This code can be embedded in
the
.meta body-form
or can be added to the code returned by a call to the update expander.

The setter local macro or function must return the new value which is stored.
That is to say, when
.meta body-form
invokes this local macro or function, it may rely on it yielding the
new value which was stored, as part of achieving its own semantics.

The update expander does not macro-expand
.codn place-form .
It is assumed that the expander is invoked in such a way that the
place has been expanded in the correct environment. In other words, the
form matches the type of place which the expander handles.
If the expander had to macro-expand the place form, it would sometimes have
to come to the conclusion that the place form must be handled by a different
expander. No such consideration is the case: when an expander is called on
a form, that is final; it is certain that it is the correct expander, which
matches the symbol in the
.code car
position of the form, which is not a macro in the context where it occurs.

An update expander is free to assume that any place which is stored
(the setter local macro is invoked on it) is accessed at least once by
an invocation of the getter. A place update macro which relies on an update
expander, but uses only the store macro, might not work properly.
An example of an update expander which relies on this assumption is the
expander for the
.mono
.meti (force << promise )
.onom
place type. If
.meta promise
has not yet been forced, and only the setter is used, then
.meta promise
might remain unforced as its internal value location is updated.
A subsequent access to the place will incorrectly trigger a force,
which will overwrite the value. The expected behavior is that storing
a value in an unforced
.code force
place changes the place to forced state, preempting the evaluation of
the delayed form. Afterward, the promise exhibits the value which was
thus assigned.

The update expander is not responsible for all issues of evaluation order.  A
place update macro may consist of numerous places, as well as numerous
value-producing forms which are not places. Each of the places can provide its
registered update expander which provides code for evaluating just that place,
and a means of accessing and storing the values.  The place update macro must
call the place expanders in the correct order, and generate any additional code
in the correct order, so that the macro achieves its required documented
evaluation order.

.TP* "Example Update Expander Call:"

.verb
  ;; First, capture the update expander
  ;; function for (car ...) places
  ;; in a variable, for clarity.

  (defvar car-update-expander [*place-update-expander* 'car])

  ;; Next, call it for the place (car [a 0]).
  ;; The body form specifies logic for
  ;; incrementing the place by one and
  ;; returning the new value.

  (call car-update-expander 'getit 'setit '(car [a 0])
    '(setit (+ (getit) 1)))

  ;; --> Resulting code:

  (rlet ((#:g0032 [a 0]))
    (macrolet ((getit nil
                 (append (list 'car) (list '#:g0032)))
               (setit (val)
                 (append (list 'sys:rplaca)
                         (list '#:g0032) (list val))))
      (setit (+ (getit) 1))))

  ;; Same expander call as above, with a call to expand added
  ;; to show the fully expanded version of the returned code,
  ;; in which the ;; setit and getit calls have disappeared,
  ;; replaced by their macro-expansions.

  (expand
    (call car-update-expander 'getit 'setit '(car [a 0])
      '(setit (+ (getit) 1))))

  ;; --> Resulting code:

  (let ((#:g0032 [a 0]))
    (sys:rplaca #:g0032 (+ (car #:g0032) 1)))

.brev
The main noteworthy points about the generated code are:
.RS
.IP -
the
.code "(car [a 0])"
place is evaluated by evaluating the embedded form
.code "[a 0]"
and storing storing the resulting object into a hidden local variable.
That's as close a reference as we can make to the
.code car
field.
.IP -
the getter macro expands to code which simply calls the
.code car
function on the cell.
.IP -
the setter uses a system function called
.codn sys:rplaca ,
which differs from
.code rplaca
in that it returns the stored value, rather than the cell.
.RE

.NP* The Clobber Expander
.synb
.mets (lambda >> ( simple-setter-sym < place-form
.mets \ \ \ \ \ \ \ \  << body-form ) ...)
.syne
.desc
The clobber expander is a code-writer similar to the update expander.
It takes a
.meta body-form
argument, and returns a larger form which surrounds this form
with additional program code.

The returned block of code has one main abstract action.
It must arrange for the evaluation of
.meta body-form
in a lexical environment in which a lexical macro or lexical function
exists which has the name requested by the
.meta simple-setter-sym
argument.

The simple setter local macro written by the clobber expander is similar to the
local setter written by the update expander. It has exactly the
same interface, performs the same action of storing a value into
the place, and returns the new value.

The difference is that its logic may be considerably simplified by the
assumption that the place is being subject to exactly one store,
and no access.

A place update macro which uses a clobber expander, and calls it more than
once, break the assumption; doing so may result in multiple evaluations
of the
.metn place-form .

.NP* The Delete Expander
.synb
.mets (lambda >> ( deleter-sym < place-form
.mets \ \ \ \ \ \ \ \  << body-form ) ...)
.syne
.desc
The delete expander is a code-writer similar to clobber expander.
It takes a
.meta body-form
arguments, and returns a larger form which surrounds this form
with additional program code.

The returned block of code has one main abstract action.
It must arrange for the evaluation of
.meta body-form
in a lexical environment in which a lexical macro or lexical function
exists which has the name requested by the
.meta deleter-sym
argument.

The deleter macro written by the clobber expander takes no arguments.
It may be called at most once. It returns the previous value of the
place, and arranges for its obliteration, whatever that means for
that particular kind of place.

.coNP Macro @ with-update-expander
.synb
.mets (with-update-expander >> ( getter << setter ) < place < env
.mets \  << body-form )
.syne
.desc
The
.code with-update-expander
macro evaluates the
.meta body-form
argument, whose result is expected to be a Lisp form.
The macro adds additional code around this code, and the result is returned.
This additional code is called the
.IR "place-access code" .

The
.meta getter
and
.meta setter
arguments must be symbols. Over the evaluation of the
.metn body-form ,
these symbols are bound to the names of local functions which
are provided in the place-access code.

The
.meta place
argument is a form which evaluates to a syntactic place. The generated
place-access code is based on this place.

The
.meta env
argument is a form which evaluates to a macro-expansion-time environment.
The
.code with-update-expander
macro uses this environment to perform macro-expansion on the value of the
.meta place
form, to obtain the correct update expander function for the fully
macro-expanded place.

The place-access code is generated by calling the update expander
for the expanded version of
.codn place .

.TP* "Example:"

The following is an implementation of the
.code swap
macro, which exchanges the contents of two places.

Two places are involved, and, correspondingly, the
.code with-update-expander
macro is used twice, to add two instances of place-update code
to the macro's body.

.verb
  (defmacro swap (place-0 place-1 :env env)
    (with-gensyms (tmp)
      (with-update-expander (getter-0 setter-0) place-0 env
        (with-update-expander (getter-1 setter-1) place-1 env
          ^(let ((,tmp (,getter-0)))
             (,setter-0 (,getter-1))
             (,setter-1 ,tmp))))))
.brev

The basic logic for swapping two places is contained in the code template:

.verb
  ^(let ((,tmp (,getter-0)))
     (,setter-0 (,getter-1))
     (,setter-1 ,tmp))
.brev

The temporary variable named by the
.code gensym
symbol
.code tmp
is initialized by calling the getter function for
.metn place-0 .
Then the setter function of
.meta place-0
is called in order to store the value of
.meta place-1
into
.metn place-0 .
Finally, the setter for
.meta place-1
is invoked to store the previously saved temporary value into
that place.

The name for the temporary variable is provided by the
.code with-gensyms
macro, but establishing the variable is the caller's responsibility;
this is seen as an explicit
.code let
binding in the code template.

The names of the getter and setter functions are similarly provided
by the
.code with-update-expander
macros. However, binding those functions is the responsibility of that
macro. To achieve this, it adds the place-access code to the code generated by
the
.code "^(let ...)"
backquote template.  In the following example macro-expansion, the additional
code added around the template is seen. It takes the form of two
.code macrolet
binding blocks, each added by an invocation of
.codn with-update-expander :

.verb
  (macroexpand '(swap a b))

  -->

  (macrolet ((#:g0036 () 'a)      ;; getter macro for a
             (#:g0037 (val-expr)  ;; setter macro for a
               (append (list 'sys:setq) (list 'a)
                       (list val-expr))))
    (macrolet ((#:g0038 () 'b)     ;; getter macro for b
               (#:g0039 (val-expr) ;; setter macro for b
                 (append (list 'sys:setq) (list 'b)
                         (list val-expr))))
      (let ((#:g0035 (#:g0036)))  ;; temp <- a
        (#:g0037 (#:g0038))       ;; a <- b
        (#:g0039 #:g0035))))      ;; b <- temp
.brev

In this expansion, for example
.code #:g0036
is the generated symbol which forms the value of the
.code getter-0
variable in the
.code swap
macro. The getter is a macro which simply expands to a
.codn a :
straightforward access to the variable a.
The
.code #:g0035
symbol is the value of the
.code tmp
variable. Thus the swap macro's
.mono
^(let ((,tmp (,getter-0))) ...)
.onom
has turned into
.mono
^(let ((#:g0035 (#:g0036))) ...)
.onom

A full expansion, with the
.code macrolet
local macros expanded out:

.verb
  (expand '(swap a b))

  -->

  (let ((#:g0035 a))
    (sys:setq a b)
    (sys:setq b #:g0035))
.brev

In other words, the original syntax
.mono
(,getter-0)
.onom
became
.mono
(#:g0036)
.onom
and finally just
.codn a .

Similarly,
.mono
(,setter-0 (,getter-1))
.onom
became the
.code macrolet
invocations
.mono
(#:g0037 (#:g0038))
.onom
which finally turned into:
.codn "(sys:setq a b)" .

.coNP Macro @ with-clobber-expander
.synb
.mets (with-clobber-expander <> ( simple-setter ) < place < env
.mets \  << body-form )
.syne
.desc
The
.code with-clobber-expander
macro evaluates
.metn body-form ,
whose result is expected to be a Lisp form. The macro adds additional code
around this form, and the result is returned. This additional code is called
the
.IR "place-access code" .

The
.meta simple-setter
argument must be a symbol. Over the evaluation of the
.metn body-form ,
this symbol is bound to the name of a functions which
are provided in the place-access code.

The
.meta place
argument is a form which evaluates to a syntactic place. The generated
place-access code is based on this place.

The
.meta env
argument is a form which evaluates to a macro-expansion-time environment.
The
.code with-clobber-expander
macro uses this environment to perform macro-expansion on the value of the
.meta place
form, to obtain the correct update expander function for the fully
macro-expanded place.

The place-access code is generated by calling the update expander
for the expanded version of
.codn place .

.TP* "Example:"

The following implements a simple assignment statement, similar to
.code set
except that it only handles exactly two arguments:

.verb
  (defmacro assign (place new-value :env env)
    (with-clobber-expander (setter) place env
      ^(,setter ,new-value)))
.brev

Note that the correct evaluation order of
.code place
and
.code new-value
is taken care of, because
.code with-clobber-expander
generates the code which performs all the necessary evaluations of
.codn place .
This evaluation occurs before the code which is generated by
.mono
^(,setter ,new-value)
.onom
part is evaluated, and that code is what evaluates
.codn new-value .

Suppose that a macro were desired which allows assignment to be notated in a right to left
style, as in:

.verb
   (assign 42 a)  ;; store 42 in variable a
.brev

Now, the new value must be evaluated prior to the place, if left to right
evaluation order is to be maintained. The standard
.code push
macro has this property: the push value is on the left, and the place
is on the right.

Now, the code has to explicitly take care of the order, like this:

.verb
  ;; WRONG! We can't just swap the parameters;
  ;; place is still evaluated first, then new-value:

  (defmacro assign (new-value place :env env)
    (with-clobber-expander (setter) place env
      ^(,setter ,new-value)))

  ;; Correct: arrange for evaluation of new-value first,
  ;; then place:

  (defmacro assign (new-value place :env env)
    (with-gensym (tmp)
      ^(let ((,tmp ,new-value))
         ,(with-clobber-expander (setter) place env
           ^(,setter ,tmp)))))
.brev

.coNP Macro @ with-delete-expander
.synb
.mets (with-delete-expander <> ( deleter ) < place < env
.mets \  << body-form )
.syne
.desc
The
.code with-delete-expander
macro evaluates
.metn body-form ,
whose result is expected to be a Lisp form.
The macro adds additional code
around this code, and the resulting code is returned. This additional code is
called the
.IR "place-access code" .

The
.meta deleter
argument must be a symbol. Over the evaluation of the
.metn body-form ,
this symbol is bound to the name of a functions which
are provided in the place-access code.

The
.meta place
argument is a form which evaluates to a syntactic place. The generated
place-access code is based on this place.

The
.meta env
argument is a form which evaluates to a macro-expansion-time environment.
The
.code with-delete-expander
macro uses this environment to perform macro-expansion on the value of the
.meta place
form, to obtain the correct update expander function for the fully
macro-expanded place.

The place-access code is generated by calling the update expander
for the expanded version of
.codn place .

.TP* "Example:"

The following implements the
.code del
macro:

.verb
  (defmacro del (place :env env)
    (with-delete-expander (deleter) place env
      ^(,deleter)))
.brev

.coNP Function @ call-update-expander
.synb
.mets (call-update-expander < getter < setter < place < env
.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \  << body-form )
.syne
.desc
The
.code call-update-expander
function provides an alternative interface for making use of an update
expander, complementary to
.codn with-update-expander .

Arguments
.meta getter
and
.meta setter
are symbols, provided by the caller. These are passed to the update
expander function, and are used for naming local functions in the
generated code which the update expander adds to
.metn body-form .

The
.meta place
argument is a place which has not been subject to macro-expansion.
The
.code call-update-expander
function takes on the responsibility for macro-expanding the place.

The
.meta env
parameter is the macro-expansion environment object required to
correctly expand
.code place
in its original environment.

The
.meta body-form
argument represents the source code of a place update operation.
This code makes references to the local functions whose names
are given by
.meta getter
and
.metn setter .
Those arguments allow the update expander to write these functions
with the matching names expected by
.metn body-form .

The return value is an object representing source code which incorporates
the
.metn body-form ,
augmenting it with additional code which evaluates
.code place
to determine its location, and provides place accessor local functions
expected by the
.metn body-form .

.TP* "Example:"

The following shows how to implement a
.code with-update-expander
macro using
.codn call-update-expander :

.verb
  (defmacro with-update-expander ((getter setter)
                                  unex-place env body)
    ^(with-gensyms (,getter ,setter)
       (call-update-expander ,getter ,setter
                             ,unex-place ,env ,body)))
.brev

Essentially, all that
.code with-update-expander
does is to choose the names for the local functions, and bind them
to the local variable names it is given as arguments. Then it
calls
.codn call-update-expander .

.TP* "Example:"

Implement the swap macro using
.codn call-update-expander :

.verb
  (defmacro swap (place-0 place-1 :env env)
    (with-gensyms (tmp getter-0 setter-0 getter-1 setter-1)
      (call-update-expander getter-0 setter-0 place-0 env
        (call-update-expander getter-1 setter-1 place-1 env
          ^(let ((,tmp (,getter-0)))
             (,setter-0 (,getter-1))
             (,setter-1 ,tmp))))))
.brev

.coNP Function @ call-clobber-expander
.synb
.mets (call-clobber-expander < simple-setter < place < env
.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \  << body-form )
.syne
.desc
The
.code call-clobber-expander
function provides an alternative interface for making use of a clobber
expander, complementary to
.codn with-clobber-expander .

Argument
.meta simple-setter
is a symbol, provided by the caller. It is passed to the clobber
expander function, and is used for naming a local function in the
generated code which the update expander adds to
.metn body-form .

The
.meta place
argument is a place which has not been subject to macro-expansion.
The
.code call-clobber-expander
function takes on the responsibility for macro-expanding the place.

The
.meta env
parameter is the macro-expansion environment object required to
correctly expand
.code place
in its original environment.

The
.meta body-form
argument represents the source code of a place update operation.
This code makes references to the local function whose name
is given by
.metn simple-setter .
That argument allows the update expander to write this function
with the matching name expected by
.metn body-form .

The return value is an object representing source code which incorporates
the
.metn body-form ,
augmenting it with additional code which evaluates
.code place
to determine its location, and provides the clobber local function
to the
.metn body-form .

.coNP Function @ call-delete-expander
.synb
.mets (call-delete-expander < deleter < place < env << body-form )
.syne
.desc
The
.code call-delete-expander
function provides an alternative interface for making use of a delete
expander, complementary to
.codn with-delete-expander .

Argument
.meta deleter
is a symbol, provided by the caller. It is passed to the delete
expander function, and is used for naming a local function in the
generated code which the update expander adds to
.metn body-form .

The
.meta place
argument is a place which has not been subject to macro-expansion.
The
.code call-delete-expander
function takes on the responsibility for macro-expanding the place.

The
.meta env
parameter is the macro-expansion environment object required to
correctly expand
.code place
in its original environment.

The
.meta body-form
argument represents the source code of a place delete operation.
This code makes references to the local function whose name
is given by
.metn deleter .
That argument allows the update expander to write this function
with the matching name expected by
.metn body-form .

The return value is an object representing source code which incorporates
the
.metn body-form ,
augmenting it with additional code which evaluates
.code place
to determine its location, and provides the delete local function
to the
.metn body-form .

.coNP Macro @ define-modify-macro
.synb
.mets (define-modify-macro < name < parameter-list << function-name )
.syne
.desc
The
.code define-modify-macro
macro provides a simplified way to write certain kinds of place update
macros. Specifically, it provides a way to write place update macros
which modify a place by retrieving the previous value, pass it through
a function (perhaps together with some additional arguments), and then store
the resulting value back into the place and return it.

The
.meta name
parameter specifies the name for the place update macro to be written.

The
.meta function-name
parameter must specify a symbol: the name of the update function.

The update macro and update function both take at least one parameter:
the place to be updated, and its value, respectively.

The
.meta parameter-list
specifies the additional parameters for update function, which will also
become additional parameters of the macro. Because it is a
function parameter list, it cannot use the special destructuring features of
macro parameter lists, or the
.code :env
or
.code :whole
special parameters. It can use optional parameters, and may be empty.

The
.code define-modify-macro
macro writes a macro called
.metn name .
The leftmost parameter of this macro is a place, followed by the additional arguments
specified by
.metn parameter-list .
The macro will arrange for the evaluation of the place argument to determine
the place location.  It will then retrieve and save the prior value of the
place, and evaluate the remaining arguments. The prior value of the
place, and the values of the additional arguments, are all passed to
.meta function
and the resulting value is then stored back into the location previously
determined for
.metn place .

.TP* "Example:"

Some standard place update macros are implementable using
.codn define-modify-macro ,
such as
.codn inc .

The
.code inc
macro reads the old value of the place, then passes it through the
.code +
(plus) function, along with an extra argument: the delta value, which
defaults to one. The
.code inc
macro could be written using
.code define-modify-macro
as follows:

.verb
  (define-modify-macro inc (: (delta 1)) +)
.brev

Note that the argument list
.code "(: (delta 1))"
doesn't specify the place, because the place is the implicit leftmost
argument of the macro which isn't given a name. With the above definition
in place, when
.code "(inc (car a))"
is invoked, then
.code "(car a)"
is first reduced to a location, and that location's value is retrieved and
saved. Then the
.code delta
parameter s evaluated to its value, which has defaulted to 1, since
the argument was omitted.
Then these two values are passed to the
.code +
function, and so 1 is added to the value previously retrieved from
.codn "(car a)" .
The resulting sum is then stored back
.code "(car a)"
without evaluating
.code "(car a)"
again.

.coNP Macro @ defplace
.synb
.mets (defplace < place-destructuring-args < body-sym
.mets \ \ \ \ \ \ \ \ \  >> ( getter-sym < setter-sym << update-body )
.mets \ \ \ \ \ \ \ \ \  >> [( ssetter-sym << clobber-body )
.mets \ \ \ \ \ \ \ \ \ \  >> [( deleter-sym << delete-body )]])
.syne
.desc
The
.code defplace
macro is used to introduce a new kind of syntactic place.
It writes the update expander, and optionally clobber and delete
expander functions, from a simpler, more compact specification,
and automatically registers the resulting functions. The compact specification
of a
.code defplace
call contains only code fragments for the expander functions.

The name and syntax of the place is determined by the
.meta place-destructuring-args
argument, which is macro-style parameter list whose structure
mimics that of the the place. In particular, its leftmost symbol
gives the name under which the place is registered.
The
.code defplace
macro provides automatic destructuring of the syntactic place,
so that the expander code fragments can refer to the components
of a place by name.

The
.meta body-sym
parameter must be be a symbol. This symbol will capture the
.meta body-forms
parameter which is passed to the update expander, clobber
expander or delete expander. The code fragments then have
access to the the body forms via this name.

The
.metn getter-sym ,
.metn setter-sym ,
and
.meta update-body
parenthesized triplet specify the update expander fragment.
The
.code defplace
macro will bind
.meta getter-sym
and
.meta setter-sym
to symbols.  The
.meta update-body
must then specify a template of code which evaluates the syntactic place to
determine its storage location, and provides a pair of local functions, using
these two symbols as their name. The template must also insert the
.meta body-sym
forms into the scope of these local functions, and the place determining code.

The
.meta setter-sym
and
.meta clobber-body
arguments similarly specify an optional clobber expander fragment,
as a single optional argument. If specified, the
.meta clobber-body
must generate a local function named using
.meta setter-sym
wrapped around
.meta body-sym
forms.

The
.meta deleter-sym
and
.meta deleter-body
likewise specify a delete expander fragment. If this is omitted,
then the place shall not support deletion.

.TP* "Example:"

Implementation of the place denoting the
.code car
field of
.code cons
cells:

.verb
  (defplace (car cell) body

    ;; the update expander fragment
    (getter setter
      (with-gensyms (cell-sym) ;; temporary symbol for cell
        ^(let ((,cell-sym ,cell)) ;; evaluate place to cell
           ;; getter and setter access cell via temp var
           (macrolet ((,getter ()
                         ^(car ,',cell-sym))
                      (,setter (val)
                         ^(sys:rplaca ,',cell-sym ,val)))

             ;; insert body form from place update macro
             ,body))))

    ;; clobber expander fragment: simpler: no need
    ;; to evaluate cell to temporary variable.
    (ssetter
      ^(macrolet ((,ssetter (val)
                     ^(sys:rplaca ,',cell ,val)))
        ,body))

    ;; deleter: delegate to pop semantics:
    ;; (del (car a)) == (pop a).
    (deleter
      ^(macrolet ((,deleter () ^(pop ,',cell)))
         ,body)))
.brev

.coNP Macro @ defset
.synb
.mets (defset < name < params < new-val-sym << set-form )
.mets (defset < get-fun-sym << set-fun-sym )
.syne
.desc
The
.code defset
macro provides a mechanism for introducing a new kind of syntactic place.
It is simpler to use than
.code defplace
and more concise, but not as general.

The
.code defset
macro is designed for situations in which a function or macro which evaluates
all of its arguments is required to serve as a syntactic place.
It provides two flavors of syntax: the long form, indicated by giving
.code defset
five arguments, and a short form, which uses two arguments.

In the long form of
.codn defset ,
the syntactic place is described by
.meta name
and
.metn params .
The
.code defset
form expresses the request that call to the function or operator named
.meta name
is to be treated as a syntactic place, which has arguments described by
the parameter list
.metn params .

The
.meta set-form
argument specifies an expression which generates the code for storing a new
value to the place.

The
.code defset
macro makes the necessary arrangements such that when an operator form
named by
.meta name
is treated as a syntactic place, then at macro-expansion time, code is
generated to evaluate all of its argument expressions into machine-generated
variables. The names of those variables are automatically bound to the
corresponding symbols given in the
.meta params
argument list of the
.code defset
syntax. Code is also generated to evaluate the expression which gives the
new value to be stored, and that is bound to a generated variable whose
name is bound to the
.code new-val-sym
symbol. Then arrangements are made to invoke the operator named by
.meta name
and to evaluate the
.code set-form
in an environment in which these symbol bindings are visible.
The operator named
.meta name
is invoked using an altered argument list which uses temporary symbols in place
of the original expressions. The task of
.code set-form
is to insert the values of the symbols from
.meta params
and
.meta new-val-sym
into a suitable code templates that will perform the store actions.
The code generated by
.code set-form
must also take on the responsibility of yielding the new value as its result.

If
.meta params
list contains optional parameters, the default value expressions of those
parameters shall be evaluated in the scope of the
.code defset
definition.

The
.meta params
list may specify a rest parameter. In the expansion, this parameter will
capture a list of temporary symbols, corresponding to the list of variadic
argument expressions. For instance if the
.code defset
parameter list for a place
.code g
is
.codn "(a b . c)" ,
featuring the rest parameter
.codn c ,
and its
.meta set-form
is
.code "^(s ,a ,b ,*c)"
and the place is invoked as
.code "(g (i) (j) (k) (l))"
then parameter
.code c
will be bound to a list of gensyms such as
.code "(#:g0123 #:g0124)"
so that the evaluation of
.meta set-form
will yield syntax resembling
.codn "(s #:g0121 #:g0122 #:g0123 #:g0124)" .
Here, gensyms
.code #:g0123
and
.code #:g0124
are understood to be bound to the values of the expressions
.code (k)
and
.codn (l) ,
the two trailing parameters corresponding to the rest parameter
.codn c .

Syntactic places defined by
.code defset
that have a rest parameter may be invoked with improper syntax such as
.codn "(set (g x y . z) v)" .
In this situation, that rest parameter will be bound to the name of
a temporary variable which holds the value of
.code z
rather than to a list of temporary variable names holding the values
of trailing expressions.
The
.code set-form
must be prepared for this situation. In particular, the rest parameter's value
is an atom, then it cannot be spliced in the backquote syntax, except at the
last position of a list.

Although syntactic places defined by
.code defset
perform macro-parameter-like destructuring of the place form, binding
unevaluated argument expressions to the parameter symbols,
nested macro parameter lists are not supported:
.meta params
specifies a function parameter list.

The parameter list may use parameter macros, keeping in mind that
the parameter expansion is applied at the time the
.code defset
form is processed, specifying an expanded parameter list which
receives unevaluated expressions. The
.meta set-form
may refer to all symbols produced by parameter list expansion, other
than generated symbols. For instance, if a parameter list macro
.code :addx
exists which adds the parameter symbol
.code x
to the parameter list, and this
.code :addx
is invoked in the
.meta params
list of a
.codn defset ,
then
.code x
will be visible to the
.metn set-form .

The short, two-argument form of
.code defset
simply specifies the names of two functions or operators:
.code get-fun-sym
names the operator which accesses the place, and
.code set-fun-sym
names the operator which stores a new value into the place.
It is expected that all arguments of these operators are evaluated
expressions, and that the store operator takes one argument more
than the access operator. The operators are otherwise assumed to be
variadic: each instance of a place based on
.code get-fun-sym
individually determines how many arguments are passed to that operator
and to the one named by
.codn set-fun-sym .

The definition
.code "(defset g s)"
means that
.code "(inc (g x y))"
will generate code which ensures that
.code x
and
.code y
are evaluated exactly once, and then those two values are passed as
arguments to
.code g
which returns the current value of the place. That value is then incremented
by one, and stored into the place by calling the
.code s
function/operator with three arguments: the two values that were passed to
.code g
and the new value.  The exact number of arguments is determined by each
individual use of
.code g
as a place; the
.code defset
form doesn't specify the arity of
.code g
and
.codn s ,
only that
.code s
must accept one more argument relative to
.codn g .

The following equivalence holds between the short and long forms:

.verb
   (defset g s)  <-->  (defset g (. r) n ^(g ,*r) ^(s ,*r ,n))
.brev

Note:
the short form of
.code defset
is similar to the
.code define-accessor
macro.

.TP* "Example:"

Implementation of
.code car
as a syntactic place using a long form
.codn defset :

.verb
  (defset car (cell) new
    (let ((n (gensym)))
      ^(rlet ((,n ,new))
         (progn (rplaca ,cell ,n) ,n))))
.brev

Given such a definition, the expression
.code "(inc (car (abc)))"
expands to code closely resembling:

.verb
  (let ((#:g0048 (abc)))
    (let ((#:g0050 (succ (car #:g0048))))
      (rplaca #:g0048 #:g0050)
      #:g0050))
.brev

The
.code defset
macro has arranged for the argument expression
.code (abc)
of
.code car
to be evaluated to a temporary variable
.codn #:g0048 ,
a
.codn gensym .
This, then, holds the
.code cons
cell being operated on.
At macro-expansion time, the variable
.code cell
from the parameter list specified by the
.code defset
is bound to this symbol. The access expression
.code "(car #:0048)"
to retrieve the prior value is automatically generated
by combining the name of the place
.code car
with the gensym to which its argument
.code (abc)
has been evaluated.
The
.code new
variable was bound to the expression giving the new value, namely
.codn "(succ (car #:g0048))" .
The
.meta set-form
is careful to evaluate this only one time, storing its value into
the temporary variable
.codn #:g0050 ,
referenced by the variable
.codn n .
The
.metn set-form 's
.code "(rplaca ,cell ,n)"
fragment thus turned into
.code "(rplaca #:g0048 #:g0050)"
where
.code #:g0048
references the cons cell being operated on, and
.code #:g0050
the calculated new value to be stored into its
.code car
field.
The
.meta set-form
is careful to arrange for the new value
.code #:g0050
to be returned. Those place-mutating operators which yield the new value, such
as
.code set
and
.code inc
rely on this behavior.

.coNP Macro @ define-place-macro
.synb
.mets (define-place-macro < name < macro-style-params
.mets \ \  << body-form *)
.syne
.desc
In some situations, an equivalence exists between two forms, only one
of which is recognized as a place. The
.code define-place-macro
macro can be used to establish a form as a place in terms of a translation to
an equivalent form which is already a place.

The
.code define-place-macro
has the same syntax as
.codn defmacro .
It specifies a macro transformation for a compound form which has the
.meta name
symbol in its leftmost position.

Place macro expansion doesn't use an environment; place macros are in a single
global namespace, special to place macros. There are no lexically scoped place
macros. Such an effect can be achieved by having a place macro expand to
an a form which is the target of a global or local macro, as necessary.

To support place macros, forms which are used as syntactic places are subject
to a modified macro-expansion algorithm:
.RS
.IP 1.
If a place macro exists for a form that is being used as a place, then the
that place macro is invoked to expand the
form, and the expansion is taken in place of the original form. This process
repeats until the form can no longer be expanded as a place macro, or
the place macro declines to expand the form by returning the unexpanded
input.
.IP 2.
A form that has been fully expanded as a place macro is then subject
to a single-round of macro-expansion, as if by
.codn macroexpand-1 ,
which takes place in the original form's lexical environment.
If the form doesn't expand, or the result of expansion is
.code nil
or a
non-symbolic atom, then the process terminates. Otherwise, the
process is repeated from step 1.
.RE

.IP
The
.code define-place-macro
macro does not cause
.meta name
to become
.codn mboundp .

There can exist both an ordinary macro and a place macro of the same name.
In this situation, when the macro call appears as a place form, it is
expanded as a place macro, according to the above steps. When the macro call
appears as an evaluated form, not being used as a place, the form is
expanded using the ordinary macro.

.TP* "Example:"

Implementation of
.code first
in terms of
.codn car :

.verb
  (define-place-macro first (obj)
    ^(car ,obj))
.brev

.coNP Macro @ rlet
.synb
.mets (rlet >> ({( sym << init-form )}*) << body-form *)
.syne
.desc
The macro
.code rlet
is similar to the
.code let
operator. It establishes bindings for one or more
.metn sym -s,
which are initialized using the values of
.metn init-form -s.

Note that the simplified syntax for a variable which initializes to
.code nil
by default is not supported by
.codn rlet ;
that is to say, the syntax
.meta sym
cannot be used in place of the
.meti >> ( sym << init-form )
syntax when
.meta sym
is to be initialized to
.codn nil .

The
.code rlet
macro differs from
.code let
in that
.code rlet
assumes that those
.metn sym -s
whose
.metn init-form -s,
after macro expansion,
are constant expressions
(according to the
.code constantp
function) may be safely implemented as a symbol macro rather than a lexical
variable.

Therefore
.code rlet
is suitable in situations in which simpler code is desired from the output
of certain kinds of machine-generated code, which binds local symbols:
code with fewer temporary variables.

On the other hand,
.code rlet
is not suitable in some situations when true variables are required, which
are assignable, and provide temporary storage.

.TP* "Example:"

.verb
  ;; WRONG! Real storage location needed.
  (rlet ((flag nil))
    (flip flag)) ;; error: flag expands to nil

  ;; Demonstration of constant-propagation
  (let ((a 42))
    (rlet ((x 1)
           (y a))
      (+ x y)))  -->  43

  (expand
    '(let ((a 42))
      (rlet ((x 1)
             (y a))
        (+ x y))))  -->  (let ((a 42))
                           (let ((y a))
                              (+ 1 y)))
.brev

The last example shows that the
.code x
variable has disappeared in the expansion. The
.code rlet
macro turned it into into a
.code symacrolet
denoting the constant 1, which then propagated to the use site,
turning the expression
.code "(+ x y)"
into
.codn "(+ 1 y)" .

.coNP Macro @ slet
.synb
.mets (slet >> ({( sym << init-form )}*) << body-form *)
.syne
.desc
The macro
.code slet
a weaker form of the
.code rlet
macro. Just like
.codn rlet ,
.code slet
reduces bindings initialized by constant expressions
to symbol macros. In addition, unlike
.codn rlet ,
.code slet
also reduces to symbol macros those bindings which
are initialized by symbol expressions (values of variables).

.coNP Macro @ alet
.synb
.mets (alet >> ({( sym << init-form )}*) << body-form *)
.syne
.desc
The macro
.code alet
("atomic" or "all") is a stronger form of the
.code slet
macro. All bindings initialized by constant expressions are
turned to symbol macros. Then, if all of the remaining bindings are
all initialized by symbol expressions, they are also turned to
symbol macros. Otherwise, none of the remaining bindings
are turned to symbol macros.

The
.code alet
macro can be used even in situations when it is possible that the initializing
forms the variables may have side effects through which they affect each
others' evaluations. In this situation
.code alet
still propagates constants via symbol macros, and can eliminate the
remaining temporaries if they can all be made symbol macros for
existing variables: i.e. there doesn't exist any initialization form
with interfering side effects.

.coNP Macro @ define-accessor
.synb
.mets (define-accessor < get-function << set-function )
.syne
.desc
The
.code define-accessor
macro is used for turning a function into an accessor,
such that forms which call the function can be treated
as places.

Arguments to
.code define-accessor
are two symbols, which must name functions. When the
.code define-accessor
call is evaluated, the
.meta get-function
symbol is registered as a syntactic place. Stores to the
place are handled via calls to
.metn set-function .

If
.meta get-function
names a function which takes N
arguments,
.meta set-function
must name a function which takes N+1 arguments.

Moreover, in order for the accessor semantics to be correct
.meta set-function
must treat its rightmost argument as the value being stored,
and must also return that value.

When a function call form targeting
.meta get-function
is treated as a place which is subject
to an update operation (for instance an increment via the
.code inc
macro),
the accessor definition created by
.code define-accessor
ensures that the arguments of
.meta get-function
are evaluated only once, even though the update involves
a call to
.meta get-function
and
.meta set-function
with the same arguments. The argument forms are evaluated to
temporary variables, and these temporaries are used as the
arguments in the calls.

No other assurances are provided by
.codn define-accessor .

In particular, if
.meta get-function
and
.meta set-function
internally each perform some redundant calculation over their arguments,
this cannot be optimized. Moreover, if that calculation has a visible effect,
that effect is observed multiple times in an update operation.

If further optimization or suppression of multiple effects is required,
the more general
.code defplace
macro must be used to define the accessor. It may also be possible to
treat the situation  in a satisfactory way using a
.code define-place-macro
definition, which effectively then supplies inline code whenever a certain form
is used as a place, and that code itself is treated as a place.

Note:
.code define-accessor
is similar to the short form of
.codn defset .

.coNP Special variables @, *place-update-expander* @ *place-clobber-expander* and @ *place-delete-expander*
.desc
These variables hold hash tables, by means of which update expanders,
clobber expanders and delete expanders are registered, as associations
between symbols and functions.

If
.code "[*place-update-expander* 'sym]"
yields a function, then symbol
.code sym
is the basis for a syntactic place. If the expression yields
.codn nil ,
then forms beginning with
.code sym
are not syntactic places. (The situation of a clobber accessor or delete
accessor being defined without an update expander is improper).

.coNP Special variable @ *place-macro*
.desc
The
.code *place-macro*
special variable holds the hash table of associations between
symbols and place macro expanders.

If the expression
.code "[*place-macro* 'sym]"
yields a function, then symbol
.code sym
has a binding as a place macro. If that
expression yields
.codn nil ,
then there is no such binding: compound forms beginning with
.code sym
do not undergo place macro expansion.

.SS* Quasiquote Operator Syntax
.coNP Macro @ qquote
.synb
.mets (qquote << form )
.syne
.desc
The
.code qquote
(quasi-quote) macro operator implements a notation for convenient
list construction.  If
.meta form
is an atom, or a list structure which
does not contain any
.code unquote
or
.code splice
operators, then
.mono
.meti (qquote << form )
.onom
is equivalent to
.mono
.meti (qquote << form ).
.onom

If
.metn form ,
however, is a list structure which contains
.code unquote
or
.code splice
operators, then the substitutions implied by those operators are performed
on
.metn form ,
and the
.code qquote
operator returns the resulting structure.

Note: how the qquote operator actually works is that it is compiled into
code. It becomes a Lisp expression which, when evaluated, computes the
resulting structure.

A
.code qquote
can contain another
.codn qquote .
If an
.code unquote
or
.code splice
operator occurs
within a nested
.codn qquote ,
it belongs to that
.codn qquote ,
and not to the outer one.

However, an unquote operator which occurs inside another one belongs one level
higher. For instance in

.verb
  (qquote (qquote (unquote (unquote x))))
.brev

the leftmost
.code qquote
belongs with the rightmost unquote, and the inner
.code qquote
and
.code unquote
belong together. When the outer
.code qquote
is evaluated,
it will insert the value of
.codn x ,
resulting in the object
.codn "(qquote (unquote [value-of-x]))" .
If this resulting qquote value is evaluated again as Lisp syntax, then it will
yield
.codn [value-of-value-of-x] ,
the value of
.code [value-of-x]
when treated as a Lisp expression and evaluated.

.TP* Examples:

.verb
  (qquote a) -> a

  (qquote (a b c)) -> (a b c)

  (qquote (1 2 3 (unquote (+ 2 2)) (+ 2 3))) -> (1 2 3 4 (+ 2 3))

  (qquote (unquote (+ 2 2))) -> 4
.brev

In the second-to-last example, the
.code "1 2 3"
and the
.code "(+ 2 3)"
are quoted verbatim.
Whereas the
.code "(unquote (+ 2 2))"
operator caused the evaluation of
.code "(+ 2 2)"
and the substitution of the resulting value.

The last example shows that
.meta form
can itself (the entire argument of
.codn qquote )
can be an unquote operator.
However, note:
.code "(quote (splice form))"
is not valid.

Note: a way to understand the nesting behavior is a via a possible model of
quasi-quote expansion which recursively compiles any nested quasi quotes first,
and then treats the result of their expansion. For instance, in the processing
of

.verb
  (qquote (qquote (unquote (unquote x))))
.brev

the
.code qquote
operator first encounters the
embedded
.code "(qquote ...)"
and compiles it to code. During that recursive
compilation, the syntax
.code "(unquote (unquote x))"
is encountered.  The inner quote
processes the outer unquote which belongs to it, and the inner
.code "(unquote x)"
becomes material that is embedded verbatim in the compilation, which will then
be found when the recursion pops back to the outer quasiquote, which will
then traverse the result of the inner compilation and find the
.codn "(unquote x)" .

.TP* "Dialect note:"

In Lisp dialects which have a published quasiquoting operator syntax, there is
the expectation that the quasiquote read syntax corresponds to it. That is to
say, that for instance the read syntax
.code "^(a b ,c)"
is expected translated to
.codn "(qquote b (unquote c))" .

In \*(TL, this is not true! Although
.code "^(b b ,c)"
is translated to a
quasiquoting macro, it is an internal one, not based on the public
.codn qquote ,
.code unquote
and
.code splice
symbols being documented here.

This idea exists for hygiene. The quasiquote read syntax is not confused
by the presence of the symbols
.codn qquote ,
.code unquote
or
.code splice
in the template, since it doesn't treat them specially.

This also allows programmers to use the quasiquote read syntax to construct
quasiquote macros. For instance

.verb
  ^(qquote (unquote ,x)) ;; does not mean ^^,,x !
.brev

To the quasiquote reader, the
.code qquote
and
.code unquote
symbols mean nothing special,
and so this syntax simply means that if the value of
.code x
is
.codn foo ,
the result of evaluating this expression will be
.codn "(qquote (unquote foo))" .

The form's expansion is actually this:

.verb
  (sys:qquote (qquote (unquote (sys:unquote x))))
.brev

the
.code sys:qquote
macro recognizes
.code sys:unquote
embedded in the form, and
the other symbols not in the
.code sys:
package are just static template material.

The
.code sys:quote
macro and its associated
.code sys:unquote
and
.code sys:splice
operators work exactly like their ordinary counterparts. So in effect, \*(TX has
two nearly identical, independent quasi-quote implementations, one of which is
tied to the read syntax, and one of which isn't. This is useful for writing
quasiquotes which write quasiquotes.

.coNP Operator @ unquote
.synb
.mets (qquote (... (unquote << form ) ...))
.mets (qquote (unquote << form ))
.syne
.desc
The
.code unquote
operator is not an operator
.I per
.IR se .
The
.code unquote
symbol has no
binding in the global environment. It is a special syntax that is recognized
within a
.code qquote
form, to indicate forms within the quasiquote which are to be
evaluated and inserted into the resulting structure.

The syntax
.mono
.meti (qquote (unquote << form ))
.onom
is equivalent to
.metn form :
the
.code qquote
and
.code unquote
"cancel out".

.coNP Operator @ splice
.synb
.mets (qquote (... (splice << form ) ...))
.syne
.desc
The
.code splice
operator is not an operator
.I per
.IR se .
The
.code splice
symbol has no
binding in the global environment. It is a special syntax that is recognized
within a
.code qquote
form, to indicate forms within the quasiquote which are to be
evaluated and inserted into the resulting structure.

The syntax
.mono
.meti (qquote (splice << form ))
.onom
is not permitted and raises an exception if evaluated. The
.code splice
syntax must occur within a list, and not in the dotted position.

The
.code splice
form differs from unquote in that
.mono
.meti (splice << form )
.onom
requires that
.meta form
must evaluate to a list. That list is
integrated into the surrounding list.

.SS* Math Library
.coNP Functions @ + and @ -
.synb
.mets (+ << number *)
.mets (- < number << number *)
.mets (* << number *)
.syne
.desc
The
.codn + ,
.code -
and
.code *
functions perform addition, subtraction and multiplication,
respectively.  Additionally, the
.code -
function performs additive inverse.

The
.code +
function requires zero or more arguments. When called with no
arguments, it produces 0 (the identity element for addition), otherwise it
produces the sum over all of the arguments.

Similarly, the
.code *
function requires zero or more arguments. When called
with no arguments, it produces 1 (the identity element for multiplication).
Otherwise it produces the product of all the arguments.

The semantics of
.code -
changes from subtraction to additive inverse
when there is only one argument. The argument is treated as a subtrahend,
against an implicit minuend of zero. When there are two or more
argument, the first one is the minuend, and the remaining are subtrahends.

When there are three or more operands, these operations are performed as if by
binary operations, in a left-associative way. That is to say,
.code "(+ a b c)"
means
.codn "(+ (+ a b) c)" .
The sum of
.code a
and
.code b
is computed first, and then this is added to
.codn c .
Similarly
.code "(- a b c)"
means
.codn "(- (- a b) c)" .
First,
.code b
is subtracted from
.codn a ,
and then
.code c
is subtracted from that result.

The arithmetic inverse is performed as if it were subtraction from integer 0.
That is,
.code "(- x)"
means the same thing as
.codn "(- 0 x)" .

The operands of
.codn + ,
.code -
and
.code *
can be characters, integers (fixnum and bignum), and
floats, in nearly any combination.

If two operands have different types, then one of them is converted to the
type of the one with the higher rank, according to this ranking:
character < integer < float.  For instance if one operand is integer, and the
other float, the integer is converted to a float.

.TP* Restrictions:

Characters are not considered numbers, and participate in these operations in
limited ways. Subtraction can be used to computed the displacement between the
Unicode values of characters, and an integer displacement can be added to a
character, or subtracted from a character.  For instance
.codn "(- #\e9 #\e0) is 9" .
The Unicode value of a character
.code C
can be found using
.codn "(- C #\ex0)" :
the displacement from the NUL character.

The rules can be stated as a set of restrictions:
.RS
.IP 1
Two characters may not be added together.
.IP 2
A character may not be subtracted from an integer (which also rules out
the possibility of computing the additive inverse of a character).
.IP 3
A character operand may not be opposite to a floating point operand
in any operation.
.IP 4
A character may not be an operand of multiplication.
.RE

.PP

.coNP Function @ /
.synb
.mets (/ << divisor )
.mets (/ < dividend << divisor *)
.syne
.desc
The
.code /
function performs floating-point division. Each operands is first
converted to floating-point type, if necessary. In the one-argument
form, the
.meta dividend
argument is omitted. An implicit dividend is present, whose value is
.codn 1.0 ,
such that the one-argument form
.code "(/ x)"
is equivalent to the two-argument form
.codn "(/ 1.0 x)" .

If there are two or more arguments, explicitly or by the above equivalence,
then a cumulative division is performed. The
.meta divisor
value is taken into consideration, and divided by the first
.codn divisor .
If another
.code divisor
follows, then that value is divided by that subsequent divisor.
This process repeats until all divisors are exhausted, and the
value of the last division is returned.

A division by zero throws an exception of type
.codn numeric-error .

.coNP Functions @ sum and @ prod
.synb
.mets (sum < sequence <> [ keyfun ])
.mets (prod < sequence <> [ keyfun ])
.syne
.desc
The
.code sum
and
.code prod
functions operate on an effective sequence of numbers derived from
.metn sequence .

If the
.meta keyfun
argument is omitted, then the effective sequence is the
.meta sequence
argument itself. Otherwise, the effective sequence is understood to be
a projection mapping of the elements of
.meta sequence
through
.meta keyfun
as would be calculated by the
.mono
.meti (mapcar < keyfun << sequence )
.onom
expression.

The
.code sum
function returns the left-associative sum of the elements of
the effective sequence calculated as if using the
.code +
function.  Similarly, the
.code prod
function calculates the left-associative product of the elements of
the sequence as if using the
.code *
function.

If
.meta sequence
is empty then
.code sum
returns
.code 0
and
.code prod
returns
.codn 1 .

If the effective sequence contains one number, then both functions
return that number.

.coNP Functions @ wrap and @ wrap*
.synb
.mets (wrap < start < end << number )
.mets (wrap* < start < end << number )
.syne
.desc
The
.code wrap
and
.code wrap*
functions reduce
.meta number
into the range specified by
.meta start
and
.metn end .

Under
.code wrap
the range is inclusive of the
.meta end
value, whereas under
.code wrap*
it is exclusive.

The following equivalence holds

.verb
  (wrap a b c) <--> (wrap* a (succ b) c)
.brev

The expression
.code "(wrap* x0 x1 x)"
performs the following calculation:

.mono
.mets (+ (mod (- x x0) (- x1 x0)) x0)
.onom

In other words, first
.meta start
is subtracted from
.metn number .
Then the result is reduced modulo the displacement
between
.code start
and
.codn end .
Finally,
.meta start
is added back to that result, which is returned.

.TP* Example:

.verb
  ;; perform ROT13 on the string "nop"
  [mapcar (opip (+ 13) (wrap #\ea #\ez)) "nop"] -> "abc"
.brev

.coNP Functions @ gcd and @ lcm
.synb
.mets (gcd << number *)
.mets (lcm << number *)
.syne
.desc
The
.code gcd
function computes the greatest common divisor: the largest positive
integer which divides each
.metn number .

The
.code lcm
function computes the lowest common multiple: the smallest positive
integer which is a multiple of
each
.metn number .

Each
.meta number
must be an integer.

Negative integers are replaced by their absolute values, so
.code "(lcm -3 -4)"
is
.code 12
and
.code "(gcd -12 -9)"
yields
.codn 3 .

The value of
.code (gcd)
is
.code 0
and that of
.code (lcm)
is 1 .

The value of
.code "(gcd x)"
and
.code "(lcm x)"
is
.codn "(abs x)" .

Any arguments of
.code gcd
which are zero are effectively ignored so that
.code "(gcd 0)"
and
.code "(gcd 0 0 0)"
are both the same as
.code (gcd)
and
.code "(gcd 1 0 2 0 3)"
is the same as
.codn "(gcd 1 2 3)" .

If
.code lcm
has any argument which is zero, it yields zero.

.coNP Function @ divides
.synb
.mets (divides < d << n )
.syne
.desc
The
.code divides
function tests whether integer
.meta d
divides integer
.metn n .
If this is true,
.code t
is returned, otherwise
.codn nil .

The integers 1 and -1 divide every other integer and themselves.
By established convention, every integer, except zero, divides zero.

For other values,
.meta d
divides
.meta n
if division of
.meta n
by
.meta d
leaves no remainder.

.coNP Function @ abs
.synb
.mets (abs << number )
.syne
.desc
The
.code abs
function computes the absolute value of
.metn number .
If
.meta number
is positive, it is returned. If
.meta number
is negative, its additive inverse is
returned: a positive number of the same type with exactly the same magnitude.

.coNP Function @ signum
.synb
.mets (signum << number )
.syne
.desc
The
.code signum
function calculates a representation of the sign of
.meta number
as a numeric value.

If
.meta number
is an integer, then
.code signum
returns -1 if the integer is negative, 1 if the integer is positive,
or else 0.

If
.meta number
is a floating-point value then
.code signum
returns -1.0 if the value is negative, 1.0 if the value is positive or
else 0.0.

.coNP Functions @, trunc @, floor @ ceil and @ round
.synb
.mets (trunc < dividend <> [ divisor ])
.mets (floor < dividend <> [ divisor ])
.mets (ceil < dividend <> [ divisor ])
.mets (round < dividend <> [ divisor ])
.syne
.desc
The
.codn trunc ,
.codn floor ,
.code ceiling
and
.code round
functions perform division of the
.meta dividend
by the
.metn divisor ,
returning an integer quotient.

If the
.meta divisor
is omitted, it defaults to 1.

A zero
.meta divisor
results in an exception of type
.codn numeric-error .

If both inputs are integers,
the result is of type integer.

If all inputs are numbers and at least one of them is
floating-point, the others are converted to floating-point
and the result is floating-point.

The
.code dividend
input may be a range. In this situation, the operation is
recursively distributed over the
.code from
and
.code to
fields of the range, individually matched against the
.metn divisor ,
and the result is a range composed of these two individual
quotients.

When the quotient is a scalar value,
.code trunc
returns the closest integer, in the zero direction,
from the value of the quotient.
The
.code floor
function returns the highest integer which does not exceed
the value of the quotient. That is to say, the division is
truncated to an integer value toward negative infinity.
The
.code ceil
function the lowest integer which is not below the value
of the quotient.
does not exceed the value of
.metn dividend .
That is to say, the division is truncated to an integer
value toward positive infinity. The
.code round
function returns the nearest integer to the quotient.
Exact halfway cases are rounded to the integer away from
zero so that
.code "(round -1 2)"
yields
.code -1
and
.code "(round 1 2)"
yields 1,

Note that for large floating point values, due to the limited
precision, the integer value corresponding to the mathematical
floor or ceiling may not be available.

.TP* "Dialect note:"
In ANSI Common Lisp, the
.code round
function chooses the nearest even integer, rather than
rounding halfway cases away from zero. \*(TX's choice
harmonizes with the semantics of the
.code round
function in the C language.

.coNP Function @ mod
.synb
.mets (mod < dividend << divisor )
.syne
.desc
The
.code mod
function performs a modulus operation. Firstly, the absolute value
of
.meta divisor
is taken to be a modulus. Then a residue of
.meta dividend
with respect to
.meta modulus
is calculated. The residue's sign follows
that of the sign of
.metn divisor .
That is, it is the smallest magnitude
(closest to zero) residue of
.meta dividend
with respect to the absolute
value of
.metn divisor ,
having the same sign as
.metn divisor .
If the operands are integer, the result is an integer. If either operand
is of type float, then the result is a float. The modulus operation is
then generalized into the floating point domain. For instance the expression
.code "(mod 0.75 0.5)"
yields a residue of 0.25 because 0.5 "goes into" 0.75 only
once, with a "remainder" of 0.25.

If
.meta divisor
is zero,
.code mod
throws an exception of type
.codn numeric-error .

.coNP Functions @, trunc-rem @, floor-rem @ ceil-rem and @ round-rem
.synb
.mets (trunc-rem < dividend <> [ divisor ])
.mets (floor-rem < dividend <> [ divisor ])
.mets (ceil-rem < dividend <> [ divisor ])
.mets (round-rem < dividend <> [ divisor ])
.syne
.desc
These functions, respectively, perform the same division operation
as
.codn trunc ,
.codn floor ,
.codn ceil ,
and
.codn round ,
referred to here as the respective target functions.

If the
.meta divisor
is missing, it defaults to 1.

Each function returns a list of two values: a
.meta quotient
and a
.metn remainder .
The
.meta quotient
is exactly the same value as what would be returned by the
respective target function for the same inputs.

The
.meta remainder
value obeys the following identity:

.mono
.mets (eql < remainder (- < dividend >> (* divisor << quotient )))
.onom

If
.meta divisor
is zero, these functions throw an exception of type
.codn numeric-error .

.coNP Functions @, sin @, cos @, tan @, asin @, acos @ atan and @ atan2
.synb
.mets (sin << radians )
.mets (cos << radians )
.mets (tan << radians )
.mets (atan << slope )
.mets (atan2 < y << x )
.mets (asin << num )
.mets (acos << num )
.syne
.desc
These trigonometric functions convert their argument to floating point and
return a float result. The
.codn sin ,
.code cos
and
.code tan
functions compute the sine and
cosine and tangent of the
.meta radians
argument which represents an angle
expressed in radians. The
.codn atan ,
.code acos
and
.code asin
are their respective inverse
functions.  The
.meta num
argument to
.code asin
and
.code acos
must be in the
range -1.0 to 1.0. The
.code atan2
function converts the rectilinear coordinates
.meta x
and
.meta y
to an angle in polar coordinates in the range [0, 2\(*p).

.coNP Functions @, sinh @, cosh @, tanh @, asinh @ acosh and @ atanh
.synb
.mets (sinh << argument )
.mets (cosh << argument )
.mets (tanh << argument )
.mets (atanh << argument )
.mets (asinh << argument )
.mets (acosh << argument )
.syne
.desc
These functions are the hyperbolic analogs of the trigonometric functions
.codn sin ,
.code cos
and so forth. They convert their argument to floating point and
return a float result.

.coNP Functions @, exp @, log @ log10 and @ log2
.synb
.mets (exp << arg )
.mets (log << arg )
.mets (log10 << arg )
.mets (log2 << arg )
.syne
.desc
The
.code exp
function calculates the value of the transcendental number e raised to
the exponent
.metn arg .

The
.code log
function calculates the base e logarithm of
.metn arg ,
which must be a positive value.

The
.code log10
function calculates the base 10 logarithm of
.metn arg ,
which must be a positive value.

The
.code log2
function calculates the base 2 logarithm of
.metn arg ,
which must be a positive value.

.coNP Functions @, expt @ sqrt and @ isqrt
.synb
.mets (expt < base << exponent *)
.mets (sqrt << arg )
.mets (isqrt << arg )
.syne
.desc
The
.code expt
function raises
.meta base
to zero or more exponents given
by the
.meta exponent
arguments.
.code "(expt x)"
is equivalent to
.codn "(expt x 1)" ,
and yields
.code x
for all
.codn x .
For three or more arguments, the operation is right-associative.
That is to say,
.code "(expt x y z)"
is equivalent to
.codn "(expt x (expt y z))" ,
similarly to the way nested exponents work in standard algebraic
notation.

Exponentiation is done pairwise using a binary operation.
If both operands to this binary operation are non-negative integers, then the
result is an integer.

If the exponent is negative, and the base is zero, the situation is
treated as a division by zero: an exception of type
.code numeric-error
is thrown. Otherwise, a negative exponent is converted to floating-point,
if it already isn't, and a floating-point exponentiation is performed.

If either operand is a float, then the other
operand is converted to a float, and a floating point exponentiation
is performed. Exponentiation that would produce a complex number is
not supported.

The
.code sqrt
function produces a floating-point square root of
.metn arg ,
which is converted from integer to floating-point if necessary.  Negative
operands are not supported.

The
.code isqrt
function computes the integer square root of
.metn arg ,
which must be an integer.
The integer square root is a value which is the
greatest integer that is no greater than the real square root of
.metn arg .
The input value must be an integer.

.coNP Function @ exptmod
.synb
.mets (exptmod < base < exponent << modulus )
.syne
.desc
The
.code exptmod
function performs modular exponentiation and accepts only integer
arguments. Furthermore,
.meta exponent
must be a non-negative and
.meta modulus
must be positive.

The return value is
.meta base
raised to
.metn exponent ,
and reduced to the
least positive residue modulo
.metn modulus .

.coNP Function @ square
.synb
.mets (square << argument )
.syne
.desc
The
.code square
function returns the product of
.meta argument
with itself. The following
equivalence holds, except that
.code x
is evaluated only once in the the
.code square
expression:

.verb
  (square x)  <-->  (* x x)
.brev

.coNP Function @ cum-norm-dist
.synb
.mets (cum-norm-dist << argument )
.syne
.desc
The
.code cum-norm-dist
function calculates an approximation to the cumulative normal
distribution function: the integral, of the normal distribution function, from
negative infinity to the
.metn argument .

.coNP Function @ inv-cum-norm
.synb
.mets (inv-cum-norm << argument )
.syne
.desc
The
.code inv-cum-norm
function calculates an approximate to the inverse of the cumulative
normal distribution function.  The argument, a value expected to lie
in the range [0, 1], represents the integral of the normal distribution
function from negative infinity to some domain point
.IR p .
The function calculates the approximate value of
.IR p .
The minimum value returned is -10, and the maximum value returned is 10,
regardless of how closely the argument approaches, respectively,
the 0 or 1 integral endpoints.  For values less than zero, or exceeding 1, the
values returned, respectively, are -10 and 10.

.coNP Functions @ n-choose-k and @ n-perm-k
.synb
.mets (n-choose-k < n << k )
.mets (n-perm-k < n << k )
.syne
.desc
The
.code n-choose-k
function computes the binomial coefficient nCk which
expresses the number of combinations of
.meta k
items that can be chosen from
a set of
.metn n ,
where combinations are subsets.

The
.code n-perm-k
function computes nPk: the number of permutations of size
.meta k
that can be drawn from a set of
.metn n ,
where permutations are sequences,
whose order is significant.

The calculations only make sense when
.meta n
and
.meta k
are nonnegative integers, and
.meta k
does not exceed
.metn n .
The behavior is not specified if these conditions
are not met.

.coNP Functions @, fixnump @, bignump @, integerp @ floatp and @ numberp
.synb
.mets (fixnump << object )
.mets (bignump << object )
.mets (integerp << object )
.mets (floatp << object )
.mets (numberp << object )
.syne
.desc
These functions test the type of
.metn object ,
returning
.code t
if it is an object
of the implied type,
.code nil
otherwise. The
.codn fixnump ,
.code bignump
and
.code floatp
functions return
.code t
if the object is of the basic type
.codn fixnum ,
.code bignum
or
.codn float .
The function
.code integerp
returns true of
.meta object
is either a
.code fixnum
or
a
.codn bignum .
The function
.code numberp
returns
.code t
if
.meta object
is either
a
.codn fixnum ,
.code bignum
or
.codn float .

.coNP Functions @ zerop and @ nzerop
.synb
.mets (zerop << number )
.mets (nzerop << number )
.syne
.desc
The
.code zerop
function tests
.meta number
for equivalence to zero. The argument must be
a number or character. It returns
.code t
for the integer value
.code 0
and for the floating-point
value
.codn 0.0 .
For other numbers, it returns
.codn nil .
It returns
.code t
for the null character
.code #\enul
and
.code nil
for all other characters.

If
.meta number
is a range, then
.code zerop
returns
.code t
if both of the range endpoints individually satisfy
.codn zerop .

The
.code nzerop
function is the logical inverse of
.codn zerop :
it returns
.code t
for those arguments for which
.code zerop
returns
.code nil
and
.IR "vice versa" .

.coNP Functions @ plusp and @ minusp
.synb
.mets (plusp << number )
.mets (minusp << number )
.syne
.desc
These functions test whether a number is positive or negative,
returning
.code t
or
.codn nil ,
as the case may be.

The argument may also be a character. All characters other than
the null character
.code #\enul
are positive. No character is negative.

.coNP Functions @ evenp and @ oddp
.synb
.mets (evenp << integer )
.mets (oddp << integer )
.syne
.desc
The
.code evenp
and
.code oddp
functions require integer arguments.
.code evenp
returns
.code t
if
.meta integer
is even (divisible by two), otherwise it returns
.codn nil .
.code oddp
returns
.code t
if
.meta integer
is not divisible by two (odd), otherwise
it returns
.codn nil .

.coNP Functions @, succ @, ssucc @, sssucc @, pred @ ppred and @ pppred
.synb
.mets (succ << number )
.mets (ssucc << number )
.mets (sssucc << number )
.mets (pred << number )
.mets (ppred << number )
.mets (pppred << number )
.syne
.desc
The
.code succ
function adds 1 to its argument and returns the resulting value.
If the argument is an integer, then the return value is the successor
of that integer, and if it is a character, then the return value
is the successor of that character according to Unicode.

The
.code pred
function subtracts 1 from its argument, and under similar considerations
as above, the result represents the predecessor.

The
.code ssucc
and
.code sssucc
functions add 2 and 3, respectively. Similarly,
.code ppred
and
.code pppred
subtract 2 and 3 from their argument.

.coNP Functions @, > @, < @, >= @ <= and @ =
.synb
.mets (> < object << object *)
.mets (< < object << object *)
.mets (>= < object << object *)
.mets (<= < object << object *)
.mets (= < object << object *)
.syne
.desc
These relational functions compare characters, numbers ranges and sequences of
characters or numbers for numeric equality or inequality. The arguments must be
one or more numbers, characters, ranges, or sequences of these objects,
or, recursively, of sequences.

If just one argument is given, then these functions all return
.codn t .

If two arguments are given then, they are compared as follows.
First, if the numbers do not have the same type, then the one
which has the lower ranking type is converted to the type of
the other, according to this ranking: character < integer < float.
For instance if a character and integer are compared, the character
is converted to integer. Then a straightforward numeric comparison
is applied.

Three or more arguments may be given, in which case the comparison proceeds
pairwise from left to right. For instance in
.codn "(< a b c)" ,
the comparison
.code "(< a b)"
is performed in isolation. If the comparison is false, then
.code nil
is returned, otherwise
the comparison
.code "(< b c)"
is performed in isolation, and if that is false,
.code nil
is returned, otherwise
.code t
is returned.  Note that it is possible for
.code b
to
undergo two different conversions.  For instance in the
.mono
.meti (< < float < character << integer )
.onom
comparison,
.meta character
will first convert to a floating-point representation
of its Unicode value so that it can be compared to
.metn float ,
and if that comparison succeeds, then in the second comparison,
.meta character
will be converted to integer so that it can be compared to
.metn integer .

Ranges may only be compared with ranges. Corresponding
fields of ranges are compared for equality by
.code =
such that
.code "#R(0 1)"
and
.code "#R(0 1.0)"
are reported as equal.
The inequality comparisons are lexicographic, such that the
.code from
field of the range is considered more major than the
.code to
field. For example the inequalities
.code "(< #R(1 2) #R(2 0))"
and
.code "(< #R(1 2) #R(1 3))"
hold.

Sequences may only be compared with sequences, but
mixtures of any kinds of sequences may be compared:
lists with vectors, vectors with strings, and so on.

The
.code =
function considers a pair of sequences of unequal length
to be unequal, reporting
.codn nil .
Sequences are equal if they have the same length
and their corresponding elements are recursively
equal under the
.code =
function.

The inequality functions treat sequences lexicographically.
A pair of sequences is compared by comparing corresponding
elements. The
.code <
function tests each successive pair of corresponding
elements recursively using the
.code <
function. If this recursive comparison reports
.codn t ,
then the function immediately returns
.code t
without considering any more pairs of elements.
Otherwise the same pair of elements is compared again
using the
.code =
function. If that reports false, then the function reports false without
considering any more pairs of elements. Otherwise processing continues with the
next pair, if any.  If all corresponding elements are equal, but the right
sequence is longer,
.code <
returns
.codn t ,
otherwise the function reports
.codn nil .
The
.code <=
function tests each successive pair of corresponding
elements recursively using the
.code <=
function. If this returns
.code nil
then the function returns
.code nil
without considering any more pairs. Otherwise processing continues
with the next pair, if any.
If all corresponding elements satisfy the test, but the
left sequence is longer, then
.code nil
is returned. Otherwise
.code t
is returned.

The inequality relations exhibit symmetry, which means that
the functions
.code >
and
.code >=
functions are equivalent, respectively, to
.code <
and
.code <=
with the order of the argument values reversed. For instance, the expression
.code "(< a b c)"
is equivalent to
.code "(> c b a)"
except for the difference in evaluation order of the
.codn a ,
.code b
and
.code c
operands themselves. Any semantic description of
.code <
or
.code <=
applies, respectively, also to
.code >
or
.code >=
with the appropriate adjustment for argument order reversal.

.coNP Function @ /=
.synb
.mets (/= << number *)
.syne
.desc
The arguments to
.code /=
may be numbers or characters.  The
.code /=
function returns
.code t
if no two of its arguments are numerically equal. That is to say, if there
exist some
.code a
and
.code b
which are distinct arguments such that
.code "(= a b)"
is true, then
the function returns
.codn nil .
Otherwise it returns
.codn t .

.coNP Functions @ max and @ min
.synb
.mets (max < first-arg << arg *)
.mets (min < first-arg << args *)
.syne
.desc
The
.code max
and
.code min
functions determine and return the highest or lowest
value from among their arguments.

If only
.meta first-arg
is given, that value is returned.

These functions are type generic, since they compare arguments
using the same semantics as the
.code less
function.

If two or more arguments are given, then
.code "(max a b)"
is equivalent to
.codn "(if (less a b) b a)" ,
and
.code "(min a b)"
is equivalent to
.codn "(if (less a b) a b)" .
If the operands do not
have the same type, then one of them is converted to the type of the other;
however, the original unconverted values are returned. For instance
.code "(max 4 3.0)"
yields the integer
.codn 4 ,
not
.codn 4.0 .

If three or more arguments are given,
.code max
and
.code min
reduce the arguments in a left-associative manner.
Thus
.code "(max a b c)"
means
.codn "(max (max a b) c)" .

.coNP Function @ clamp
.synb
.mets (clamp < low < high << val )
.syne
.desc
The
.code clamp
function clamps value
.meta val
into the range
.meta low
to
.metn high .

The
.code clamp
function returns
.meta low
if
.meta val
is less than
.metn low .
If
.meta val
is greater than or equal to
.metn low ,
but less than
.metn high ,
then it returns
.metn val .
Otherwise it returns
.metn high .

More precisely,
.code "(clamp a b c)"
is equivalent to
.codn "(max a (min b c))" .

.coNP Function @ bracket
.synb
.mets (bracket < value << level *)
.syne
.desc
The
.code bracket
function's arguments consist of one required
.meta value
followed by
.I n
.meta level
arguments.
The
.meta level
arguments are optional; in other words,
.I n
may be zero.

The
.code bracket
function calculates the
.I bracket
of the
.meta value
argument: a zero-based positional index of the value, in relation to the
.meta level
arguments.

Each of the
.meta level
arguments, of which there may be none, is associated with
an integer index, starting at zero, in left to right order. The
.meta level
arguments are examined in that order. When a
.meta level
argument is encountered which exceeds
.metn value ,
that
.meta level
argument's index is returned.
If
.meta value
exceeds all of the
.meta level
arguments, then
.I n
is returned.

Determining whether
.meta value
exceeds a
.meta level
is performed using the
.code less
function.

.TP* Examples:

.verb
  (bracket 42) -> 0
  (bracket 5 10) -> 0
  (bracket 15 10) -> 1
  (bracket 15 10 20) -> 1
  (bracket 15 10 20 30) -> 1
  (bracket 20 10 20 30) -> 2
  (bracket 35 10 20 30) -> 3
  (bracket "a" "aardvark" "zebra") -> 0
  (bracket "ant" "aardvark" "zebra") -> 1
  (bracket "zebu" "aardvark" "zebra") -> 2
.brev

.coNP Functions @, int-str @ flo-str and @ num-str
.synb
.mets (int-str < string <> [ radix ])
.mets (flo-str << string )
.mets (num-str << string )
.syne
.desc
These functions extract numeric values from character string
.metn string .
Leading whitespace in
.metn string ,
if any, is skipped. If no digits can be successfully extracted, then
.code nil
is returned.  Trailing material which does not contribute to the number is
ignored.

The
.code int-str
function converts a string of digits in the specified
.meta radix
to an integer value. If
.meta radix
isn't specified, it defaults to 10.
Otherwise it must be an integer in the range 2 to 36, or else the character
.codn #\ec .

For radices above 10, letters of the alphabet
are used for digits:
.code A
represent a digit whose value is 10,
.code B
represents 11 and
so forth until
.codn Z .
Upper and lower case letters are recognized.
Any character which is not a digit of the specified radix is regarded
as the start of trailing junk at which the extraction of the digits stops.

When
.meta radix
is specified as the character object
.codn #\ec ,
this indicates that a C-language-style integer constant should be
recognized.  If, after any optional sign, the remainder of
.meta string
begins with the character pair
.code 0x
then that pair is considered removed from the string, and it is treated
as base 16 (hexadecimal).  If, after any optional sign, the remainder of
.meta string
begins with a leading zero not followed by
.codn x ,
then the radix is taken to be 8 (octal). In scanning these formats,
.code int-str
function is not otherwise constrained by C language representational
limitations. Specifically, the input values are taken to be the printed
representation of arbitrary-precision integers and treated accordingly.

The
.code flo-str
function converts a floating-point decimal notation to a nearby
floating point value. The material which contributes to the value
is the longest match for optional leading space, followed by a
mantissa which consists of an optional sign followed by a mixture of at least
one digit, and at most one decimal point, optionally followed by an exponent
part denoted by the letter
.code E
or
.codn e ,
an optional sign and one or more optional exponent digits.
If the value specified by
.meta string
is out of range of the floating-point representation, then
.code nil
is returned.

The
.code num-str
function converts a decimal notation to either an integer as if by
a radix 10 application of
.codn int-str ,
or to a floating point value as if by
.codn flo-str .
The floating point interpretation is chosen if the possibly empty
initial sequence of digits (following any whitespace and optional sign) is
followed by a period, or by
.code e
or
.codn E .

.coNP Functions @ int-flo and @ flo-int
.synb
.mets (int-flo << float )
.mets (flo-int << integer )
.syne
.desc
These functions perform numeric conversion between integer and floating point
type. The
.code int-flo
function returns an integer by truncating toward zero.
The
.code flo-int
function returns an exact floating point value corresponding to
.metn integer ,
if possible, otherwise an approximation using a nearby
floating point value.

.coNP Functions @ tofloat and @ toint
.synb
.mets (tofloat << value )
.mets (toint < value <> [ radix ])
.syne
.desc
These convenience functions convert
.meta value
to floating-point or integer, respectively.

If a floating-point value is passed into tofloat, or an integer value into
toint, then the value is simply returned.

If
.meta value
is a character, then it is treated as a string of length one
containing that character.

If
.meta value
is a string, then it is converted by
.code tofloat
as if by the function
.metn flo-str ,
, and by
.code toint
as if by the function
.codn int-str .

If
.meta value
is an integer, then it is converted by
.code tofloat
as if by the function
.codn flo-int .

If
.meta value
is a floating-point number, then it is converted by
.code toint
as if by the function
.codn int-flo .

.coNP Variables @ fixnum-min and @ fixnum-max
.desc
These variables hold, respectively, the most negative value of the
.code fixnum
integer type, and its most positive value. Integer values
from
.code fixnum-min
to
.code fixnum-max
are all of type
.codn fixnum .
Integers outside of this range are
.code bignum
integers.

.coNP Functions @ tofloatz and @ tointz
.synb
.mets (tofloatz << value )
.mets (tointz < value <> [ radix ])
.syne
.desc
These functions are closely related to, respectively,
.code tofloat
and
.codn toint .
They differ in that these functions return a floating-point
or integer zero, respectively, in some situations
in which those functions would return
.code nil
or throw an error.

Whereas those functions reject a
.meta value
argument of
.codn nil ,
for that same argument
.code tofloatz
function returns 0.0 and
.code tointz
returns 0.

Likewise, in cases when
.code value
contains a string or character which cannot be
converted to a number, and
.code tofloat
and
.code toint
would return
.codn nil ,
these functions return 0.0 and 0, respectively.

In other situations, these functions behave
exactly like
.code tofloat
and
.codn toint .

.coNP Variables @, flo-min @ flo-max and @ flo-epsilon
.desc
These variables hold, respectively: the smallest positive floating-point
value; the largest positive floating-point value; and the difference
between 1.0 and the smallest representable value greater than 1.0.

.code flo-min
and
.code flo-max
define the floating-point range, which consists
of three regions: values from
.code "(- flo-max)"
to
.codn "(- flo-min)" ;
the value 0.0, and values from
.code flo-min
to
.codn flo-max .

.coNP Variable @ flo-dig
.desc
This variable holds an integer representing the number of decimal digits
in a decimal floating-point number such that this number can be converted
to a \*(TX floating-point number, and back to decimal, without a change in any of
the digits. This holds regardless of the value of the number, provided that it
does not exceed the floating-point range.

.coNP Variable @ flo-max-dig
.desc
This variable holds an integer representing the maximum number of
decimal digits required to capture the value of a floating-point number
such that the resulting decimal form will convert back to the same
floating-point number. See also the
.code *print-flo-precision*
variable.

.coNP Variables @ %pi% and @ %e%
.desc
These variables hold an approximation of the mathematical constants \(*p and e.
To four digits of precision, \(*p is 3.142 and e is 2.718. The
.code %pi%
and
.code %e%
approximations are accurate to
.code flo-dig
decimal digits.

.coNP Function @ digits
.synb
.mets (digits < number <> [ radix ])
.syne
.desc
The
.code digits
function returns a list of the digits of
.meta number
represented in the base given by
.metn radix .

The
.meta number
argument must be a non-negative integer, and
.meta radix
must be an integer greater than one.

If
.meta radix
is omitted, it defaults to 10.

The return value is a list of the digits in descending order of significance:
most significant to least significant.
The digits are integers. For instance, if
.meta radix
is 42, then the digits are integer values in the range 0 to 41.

The returned list always contains at least one element, and
includes no leading zeros, except when
.meta number
is zero. In that case, a one-element list containing zero is returned.

.TP* Examples:

.verb
  (digits 1234) -> (1 2 3 4)
  (digits 1234567 1000) -> (1 234 567)
  (digits 30 2) -> (1 1 1 1 0)
  (digits 0) -> (0)
.brev

.coNP Function @ digpow
.synb
.mets (digpow < number <> [ radix ])
.syne
.desc
The
.code digpow
function decomposes the
.meta number
argument into a power series whose terms add up to
.metn number .

The
.meta number
argument must be a non-negative integer, and
.meta radix
must be an integer greater than one.

The returned power series consists of a list of nonnegative
integers.  It is formed from the digits of
.meta number
in the given
.metn radix ,
which serve as coefficients which multiply successive
powers of the
.metn radix ,
starting at the zeroth power (one).

The terms are given in decreasing order of significance:
the term corresponding to the most significant digit of
.metn number ,
multiplying the highest power of
.metn radix ,
is listed first.

The returned list always contains at least one element, and
includes no leading zeros, except when
.meta number
is zero. In that case, a one-element list containing zero is returned.

.verb
  (digpow 1234) -> (1000 200 30 4)
  (digpow 1234567 1000) -> (1000000 234000 567)
  (digpow 30 2) -> (16 8 4 2 0)
  (digpow 0) -> (0)
.brev

.coNP Functions @ poly and @ rpoly
.synb
.mets (poly < arg << coeffs )
.mets (rpoly < arg << coeffs )
.syne
.desc
The
.code poly
and
.code rpoly
functions evaluate a polynomial, for the given numeric argument value
.meta arg
and the coefficients given by
.metn coeffs ,
a sequence of numbers.

If
.meta coeffs
is an empty sequence, it denotes the zero polynomial, whose value
is zero everywhere; the functions return zero in this case.

Otherwise, the
.code poly
function considers
.meta coeffs
to hold the coefficients in the conventional order, namely in order
of decreasing degree of polynomial term. The first element of
.meta coeffs
is the leading coefficient, and the constant term appears as the last element.

The
.code rpoly
function takes the coefficients in opposite order: the first element of
.meta coeffs
gives the constant term coefficient, and the last element gives the
leading coefficient.

Note: except in the case of
.code rpoly
operating on a list or list-like sequence of coefficients,
Horner's method of evaluation is
used: a single result accumulator is initialized with zero, and then for each
successive coefficient, in order of decreasing term degree, the accumulator is
multiplied by the argument, and the coefficient is added. When
.code rpoly
operates on a list or list-like sequence, it makes a single
pass through the coefficients in order, thus taking them in increasing
term degree.  It maintains two accumulators: one for successive powers of
.meta arg
and one for the resulting value. For each coefficient, the power
accumulator is updated by a multiplication by
.meta arg
and then this value is multiplied by the coefficient, and
that value is then added to the result accumulator.

.TP* Examples:

.verb
  ;;           2
  ;; evaluate x  +  2x + 3  for x = 10.
  (poly 10 '(1 2 3)) -> 123

  ;;            2
  ;; evaluate 3x  +  2x + 1  for x = 10.
  (rpoly 10 '(1 2 3)) -> 321
.brev

.coNP Function @ bignum-len
.synb
.mets (bignum-len << arg )
.syne
.desc
The
.code bignum-len
function reports the machine-specific
.I "bignum order"
of the integer or character argument
.metn arg .

If
.meta arg
is a character or
.code fixnum
integer, the function returns zero.

Otherwise
.meta arg
is expected to be a
.code bignum
integer, and the function returns the number of "limbs" used for its
representation, a positive integer.

Note: the
.code bignum-len
function is intended to be of use in algorithms whose performance
benefits from ordering the operations on multiple integer operands
according to the magnitudes of those operands. The function provides an
estimate of magnitude which trades accuracy for efficiency.

.coNP Variables @, flo-near @, flo-down @ flo-up and @ flo-zero
.desc
These variables hold integer values suitable as arguments to the
.code flo-set-round-mode
function, which controls the rounding mode for the results of floating-point
operations.  These variables are only defined on platforms which support
rounding control.

Their values have the following meanings:
.RS
.coIP flo-near
Round to nearest: the result of an operation is rounded to the nearest
representable value.
.coIP flo-down
Round down: the result of an operation is rounded to the nearest representable
value that lies in the direction of negative infinity.
.coIP flo-up
Round up: the result of an operation is rounded to the nearest representable
value that lies in the direction of positive infinity.
.coIP flo-zero
Round to zero: the result of an operation is rounded to the nearest
representable value that lies in the direction of zero.
.RE
.IP

.coNP Functions @ flo-get-round-mode and @ flo-set-round-mode
.synb
.mets (flo-get-round-mode)
.mets (flo-set-round-mode << mode )
.syne
.desc
Sometimes floating-point operations produce a result which
requires more bits of precision than the floating point representation
can provide. A representable floating-point value must be substituted
for the true result and yielded by the operation.

On platforms which support rounding control, these functions are provided for
selecting the decision procedure by which the floating-point representation
is taken.

The
.code flo-get-round-mode
returns the current rounding mode. The rounding mode is represented by
an integer value which is either equal to one of the four variables
.codn flo-near ,
.codn flo-down ,
.code flo-up
and
.codn flo-zero ,
or else some other value specific to the host environment. Initially,
the value is that of
.codn flo-near .
Otherwise, the value returned is that which was stored by the most
recent successful call to
.codn flo-set-round-mode .

The
.code flo-set-round-mode
function changes the rounding mode. The argument to its
.meta mode
parameter may be the value of one of the above four variables,
or else some other value supported by the host environment's
.code fesetround
C library function.

The
.code flo-set-round-mode
function returns
.code t
if it is successful, otherwise the return value is
.code nil
and the rounding mode is not changed.

If a value is is passed to
.code flo-set-round-mode
which is not the value of one of the above
four rounding mode variables, and the function succeeds anyway, then the
rounding behavior of floating-point operations depends on the host
environment's interpretation of that value.

.SS* Bit Operations
In \*(TL, similarly to Common Lisp, bit operations on integers are based
on a concept that might be called "infinite two's-complement".  
Under infinite two's complement, a positive number is regarded as having
a binary representation prefixed by an infinite stream of zero digits (for
example
.code 1
is
.codn ...00001 ).
A negative number
in infinite two's complement is the bitwise negation of its positive counterpart,
plus one: it carries an infinite prefix of 1 digits. So for instance the number
.code -1
is represented by
.codn ...11111111 :
an infinite sequence of
1
bits. There
is no specific sign bit; any operation which produces such an infinite sequence
of 1 digits on the left gives rise to a negative number. For instance, consider the
operation of computing the bitwise complement of the number
.codn 1 .
Since the
number
.code 1
is represented as
.codn ...0000001 ,
its complement is
.codn ...11111110 .
Each one of the
.code 0
digits in the infinite sequence is replaced by
.codn 1 ,
And this leading sequence means that the number
is negative, in fact corresponding to the two's-complement representation of
the value
.codn -2 .
Hence, the infinite digit concept corresponds to an arithmetic
interpretation.

In fact \*(TL's bignum integers do not use a two's complement
representation internally. Numbers are represented as an array which holds a
pure binary number. A separate field indicates the sign: negative,
or non-negative.  That negative numbers appear as two's-complement under the
bit operations is merely a carefully maintained illusion (which makes bit
operations on negative numbers more expensive).

The
.code logtrunc
function, as well as a feature of the
.code lognot
function, allow bit
manipulation code to be written which works with positive numbers only, even if
complements are required. The trade off is that the application has to manage a
limit on the number of bits.

.coNP Functions @, logand @ logior and @ logxor
.synb
.mets (logand << integer *)
.mets (logior << integer *)
.mets (logxor < int1 << int2 )
.syne
.desc
These operations perform the familiar bitwise and, inclusive or, and exclusive
or operations, respectively. Positive values inputs are treated as
pure binary numbers.  Negative inputs are treated as infinite-bit
two's-complement.

For example
.code "(logand -2 7)"
produces
.codn 6 .
This is because
.code -2
is
.code ...111110
in infinite-bit two's-complement.  And-ing this value with
.code 7
(or
.codn ...000111 )
produces
.codn 110 .

The
.code logand
and
.code logior
functions are variadic, and may be called with zero, one,
two, or more input values. If
.code logand
is called with no arguments, it produces
the value -1 (all bits 1). If
.code logior
is called with no arguments it produces
zero. In the one-argument case, the functions just return their argument value.

In the two-argument case, one of the operands may be a character, if the other
operand is a fixnum integer. The character operand is taken to be an integer
corresponding to the character value's Unicode code point value. The resulting
value is regarded as a Unicode code point and converted to a character value
accordingly.

When three or more arguments are specified, the operation's semantics is
that of a left-associative reduction through two-argument invocations,
so that the three-argument case
.code "(logand a b c)"
is equivalent to the expression
.codn "(logand (logand a b) c)" ,
which features two two-argument cases..

.coNP Function @ logtest
.synb
.mets (logtest < int1 << int2 )
.syne
.desc
The
.code logtest
function returns true if
.meta int1
and
.meta int2
have bits in
common. The following equivalence holds:

.verb
  (logtest a b) <--> (not (zerop (logand a b)))
.brev

.coNP Functions @ lognot and @ logtrunc
.synb
.mets (lognot < value <> [ bits ])
.mets (logtrunc < value << bits )
.syne
.desc
The
.code lognot
function performs a bitwise complement of
.metn value .
When the one-argument form of lognot is used, then if
.meta value
is nonnegative,
then the result is negative, and
.IR "vice versa" ,
according to the infinite-bit
two's complement representation. For instance
.code "(lognot -2)"
is
.codn 1 ,
and
.code "(lognot 1)"
is
.codn -2 .

The two-argument form of
.code lognot
produces a truncated complement. Conceptually,
a bitwise complement is first calculated, and then the resulting number is
truncated to the number of bits given by
.metn bits ,
which must be a nonnegative integer. The following equivalence holds:

.verb
  (lognot a b) <--> (logtrunc (lognot a) b)
.brev

The
.code logtrunc
function truncates the integer
.meta value
to the  specified number
of bits. If
.meta value
is negative, then the two's-complement representation
is truncated. The return value of
.code logtrunc
is always a non-negative integer.

.coNP Function @ sign-extend
.synb
.mets (sign-extend < value << bits )
.syne
.desc
The
.code sign-extend
function first truncates the infinite-bit two's complement representation of
the integer
.meta value
to the specified number of bits, similarly to the
.code logtrunc
function. Then, this truncated value is regarded as a
.meta bits
wide two's complement integer. The value of this integer is
calculated and returned.

.TP* Examples:

.verb
  (sign-extend 127 8) -> 127
  (sign-extend 128 8) -> -128
  (sign-extend 129 8) -> -127
  (sign-extend 255 8) -> -1
  (sign-extend 256 8) -> 0
  (sign-extend -1  8) -> -1
  (sign-extend -255 8) -> 0
.brev

.coNP Function @ ash
.synb
.mets (ash < value << bits )
.syne
.desc
The
.code ash
function shifts
.meta value
by the specified number of
.meta bits
producing a
new value.  If
.meta bits
is positive, then a left shift takes place.  If
.meta bits
is negative, then a right shift takes place. If
.meta bit
is zero, then
.meta value
is returned unaltered.  For positive numbers, a left shift by n bits is
equivalent to a multiplication by two to the power of n, or
.codn "(expt 2 n)" .
A right shift by n bits of a positive integer is equivalent to integer
division by
.codn "(expt 2 n)" ,
with truncation toward zero.
For negative numbers, the bit shift is performed as if on the two's-complement
representation. Under the infinite two's-complement representation,
a right shift does not exhaust the infinite sequence of
.code 1
digits which
extends to the left. Thus if
.code -4
is shifted right it becomes
.code -2
because
the bitwise representations of these values are
.code ...111100
and
.codn ...11110 .

.coNP Function @ bit
.synb
.mets (bit < value << bit )
.syne
.desc
The
.code bit
function tests whether the integer or character
.meta value
has a 1 in bit position
.metn bit .
The
.meta bit
argument must be a non-negative integer. A value of zero of
.meta bit
indicates the least significant bit position of
.metn value .

The
.code bit
function has a Boolean result, returning the symbol
.code t
if bit
.meta bit
of
.meta value
is set, otherwise
.codn nil .

If
.meta value
is negative, it is treated as if it had an infinite-bit two's
complement representation. For instance, if value is 
.codn -2 ,
then the bit
function returns
.code nil
for a
.meta bit
value of zero, and
.code t
for all other values,
since the infinite bit two's complement representation of
.code -2
is
.codn ...11110 .

.coNP Function @ mask
.synb
.mets (mask << integer *)
.syne
.desc
The
.code mask
function takes zero or more integer arguments, and produces an integer
value which corresponds a bitmask made up of the bit positions specified by the
integer values.

If
.code mask
is called with no arguments, then the return value is zero.

If
.code mask
is called with a single argument
.meta integer
then the return value is the same as
that of the expression
.codn "(ash 1 <integer>)" :
the value 1 shifted left by
.meta integer
bit positions. If
.meta integer
is zero, then the result is
.codn 1 ;
if
.meta integer
is
.codn 1 ,
the
result is
.code 2
and so forth.  If
.meta value
is negative, then the result is zero.

If
.code mask
is called with two or more arguments, then the result is a bitwise or of
the masks individually computed for each of the values.

In other words, the following equivalences hold:

.verb
  (mask) <--> 0
  (mask a) <--> (ash 1 a)
  (mask a b c ...) <--> (logior (mask a) (mask b) (mask c) ...)
.brev

.coNP Function @ bitset
.synb
.mets (bitset << integer )
.syne
.desc
The
.code bitset
function returns a list of the positions of bits which have a value of
1 in a positive
.meta integer
argument, or the positions of bits which have a value of zero in a negative
.meta integer
argument. The positions are ordered from least to greatest. The least
significant bit has position zero. If
.meta integer
is zero, the empty list
.code nil
is returned.

A negative integer is treated as an infinite bit two's complement
representation.

The argument may be a character.

If
.meta integer
.code x
is non-negative, the following equivalence holds:

.verb
  x  <-->  [apply mask (bitset x)]
.brev

That is to say, the value of
.code x
may be reconstituted by applying the bit positions returned by
.code bitset
as arguments to the
.code mask
function.

The value of a negative
.code x
may be reconstituted from its
.code bitset
as follows:

.verb
  x  <-->  (pred (- [apply mask (bitset x)]))
.brev

also, more trivially, thus:

.verb
  x  <-->  (- [apply mask (bitset (- x))])
.brev

.coNP Function @ width
.synb
.mets (width << integer *)
.syne
.desc
A two's complement representation of an integer consists of a sign bit and a
mantissa field.
The
.code width
function computes the minimum number of bits required for the mantissa portion
of the two's complement representation of the
.meta integer
argument.

For a nonnegative argument, the width also corresponds to the number of bits
required for a natural binary representation of that value.

Two integer values have a width of zero, namely 0 and -1. This means that these
two values can be represented in a one-bit two's complement, consisting of only
a sign bit: the one-bit two's complement bitfield 1 denotes -1, and 0 denotes
0.

Similarly, two integer values have a width of 1: 1 and -2. The two-bit
two's complement bitfield 01 denotes 1, and 10 denotes -2.

The argument may be a character.

.coNP Function @ logcount
.synb
.mets (logcount << integer )
.syne
.desc
The
.code logcount
function considers
.meta integer
to have a two's complement representation. If the integer is positive,
it returns the count of bits in that representation whose value is 1.
If
.meta integer
is negative, it returns the count of zero bits instead. If
.meta integer
is zero, the value returned is zero.

The argument may be a character.

.SS* User-Defined Arithmetic Types

\*(TL makes it possible for the user application program to define structure
types which can participate in arithmetic operations as if they were numbers.
Under most arithmetic functions, a structure object may be used instead of a
number, if that structure object implements a specific method which is required
by that arithmetic function.

The following paragraphs give general remarks about the method conventions.
Not all arithmetic and bit manipulation functions have a corresponding
method, and a small number of functions do not follow these conventions.

In the simplest case of arithmetic functions which are unary, the method
takes no argument other than the object itself. Most unary arithmetic functions
expect a structure argument to have a method which has the same name as that
function. For instance, if
.code x
is a structure, then
.code "(cos x)"
will invoke
.codn "x.(cos)" .
If
.code x
has no
.code cos
method, then an
.code error
exception is thrown. A few unary methods are not named after the corresponding function.
The unary case of the
.code -
function excepts an object to have a method named
.codn neg ;
thus,
.code "(- x)"
invokes
.codn "x.(neg)" .
Unary division requires a method called
.codn recip ;
thus,
.codn "(/ x)" ,
invokes
.codn "x.(recip)" .

When a structure object is used as an argument in a two-argument (binary)
arithmetic function, there are several cases to consider. If the left argument
to a binary function is an object, then that object is expected to support a
binary method. That method is called with two arguments: the object itself, of
course, and the right argument of the arithmetic operation.  In this case, the
method is named after the function. For instance, if
.code x
is an object, then
.code "(+ x 3)"
invokes
.codn "x.(+ 3)" .
If the right argument, and only the right argument, of a binary operation is an
object, then the situation falls into two cases depending on whether the operation
is commutative. If the operation is commutative, then the same method is used
as in the case when the object is the left argument. The arguments are merely reversed.
Thus
.code "(+ 3 x)"
also invokes
.codn "x.(+ 3)" .
If the operation is not commutative, then the object must supply an alternative
method. For most functions, that method is named by a symbol whose name begins
with a
.code r-
prefix.  For instance
.code "(mod x 5)"
invokes
.code "x.(mod 5)"
whereas
.code "(mod 5 x)"
invokes
.codn "x.(r-mod 5)" .
Note: the "r" may be remembered as indicating that the object is the
.B right
argument
of the binary operation or that the arguments are
.BR reversed .
Two functions do not follow the
.code r-
convention. These are
.code -
and
.codn / .
For these, the methods used for the object as a right argument, respectively, are
.code --
and
.codn // .
Thus
.code "(/ 5 x)"
invokes
.code "x.(// 5)"
and
.code "(- 5 x)"
invokes
.codn "x.(-- 5)" .
Several binary functions do not support an object as the right argument. These are
.codn sign-extend ,
.code ash
and
.codn bit .

Variadic arithmetic functions, when given three or more arguments, are regarded
as performing a left-associative decimation of the arguments through a binary
function. Thus for instance
.code "(- 1 x 4)"
is understood as
.code "(- (- 1 x) 4)"
where
.code "x.(-- 1)"
is evaluated first. If that method yields an object
.code o
then
.code "o.(- 4)"
is invoked.

Certain variadic arithmetic functions, if invoked with one argument, just
return that argument: for instance,
.code +
and
.code *
are in this category. A special concession exists in these functions: if
their one and only argument is a structure, then that structure is returned
without any error checking, even if it implements no methods related
to arithmetic.

The following sections describe each of the methods that must be implemented
by an object for the associated arithmetic function to work with that object,
either at all, or in a specific argument position, as the case may be.
These methods are not provided by \*(TL; the application is required to provide
them.

.de bmc
.  coNP Method @ \\$1
.  synb
.  mets << obj .(\\$1 << arg )
.  syne
.  desc
The
.  code \\$1
method is invoked when a structure is used as an argument to the
.  code \\$1
function.

If an object
.  meta obj
is combined with an argument
.  metn arg ,
either as
.  mono
.  meti (\\$1 < obj << arg )
.  onom
or as
.  mono
.  meti (\\$1 < arg << obj )
.  onom
then, effectively, the method call
.  mono
.  meti << obj .(\\$1 << arg )
.  onom
takes place, and its return value is taken as the result
of the operation.
..

.de bmcv
.  coNP Method @ \\$1
.  synb
.  mets << obj .(\\$1 << arg )
.  syne
.  desc
The
.  code \\$1
method is invoked when a structure is used as an argument to the
.  code \\$1
function together with at least one other operand.

If an object
.  meta obj
is combined with an argument
.  metn arg ,
either as
.  mono
.  meti (\\$1 < obj << arg )
.  onom
or as
.  mono
.  meti (\\$1 < arg << obj )
.  onom
then, effectively, the method call
.  mono
.  meti << obj .(\\$1 << arg )
.  onom
takes place, and its return value is taken as the result
of the operation.
..

.de bmnl
.  coNP Method @ \\$1
.  synb
.  mets << obj .(\\$1 << arg )
.  syne
.  desc
The
.  code \\$1
method is invoked when the structure
.  meta obj
is used as the left argument of the
.  code \\$1
function.

If an object
.  meta obj
is combined with an argument
.  metn arg ,
as
.  mono
.  meti (\\$1 < obj << arg )
.  onom
then, effectively, the method call
.  mono
.  meti << obj .(\\$1 << arg )
.  onom
takes place, and its return value is taken as the result
of the operation.
..

.de bmnr
.  coNP Method @ \\$1
.  synb
.  mets << obj .(\\$1 << arg )
.  syne
.  desc
The
.  code \\$1
method is invoked when the structure
.  meta obj
is used as the right argument of the
.  code \\$2
function.

If an object
.  meta obj
is combined with an argument
.  metn arg ,
as
.  mono
.  meti (\\$2 < arg << obj )
.  onom
then, effectively, the method call
.  mono
.  meti << obj .(\\$1 << arg )
.  onom
takes place, and its return value is taken as the result
of the operation.
..

.de umv
.  coNP Method @ \\$1
.  synb
.  mets << obj .(\\$1)
.  syne
.  desc
The
.  code \\$1
method is invoked when the structure
.  meta obj
is used as the sole argument to the
.  code \\$2
function.

If an object
.  meta obj
is passed to the function as
.  mono
.  meti (\\$2 << obj )
.  onom
then, effectively, the method call
.  mono
.  meti << obj .(\\$1)
.  onom
takes place, and its return value is taken as the result
of the operation.
..

.de bma
.  coNP Method @ \\$1
.  synb
.  mets << obj .(\\$1 << arg )
.  syne
.  desc
The
.  code \\$1
method is invoked when the
.  code \\$1
function is invoked with two operands, and the structure
.  meta obj
is the left operand.
The method is also invoked when the
.  code \\$2
function is invoked with two operands, and
.meta obj
is the right operand.

If an object
.  meta obj
is combined with an argument
.  metn arg ,
either as
.  mono
.  meti (\\$1 < obj << arg )
.  onom
or as
.  mono
.  meti (\\$2 < arg << obj )
.  onom
then, effectively, the method call
.  mono
.  meti << obj .(\\$1 << arg )
.  onom
takes place, and its return value is taken as the result
of the operation.
..

.de um
.  coNP Method @ \\$1
.  synb
.  mets << obj .(\\$1)
.  syne
.  desc
The
.  code \\$1
method is invoked when a structure is used as the argument to the
.  code \\$1
function.

If an object
.  meta obj
is passed to the function as
.  mono
.  meti (\\$1 << obj )
.  onom
then, effectively, the method call
.  mono
.  meti << obj .(\\$1)
.  onom
takes place, and its return value is taken as the result
of the operation.
..

.de tmnl
.  coNP Method @ \\$1
.  synb
.  mets << obj .(\\$1 < arg1 << arg2 )
.  syne
.  desc
The
.  code \\$1
method is invoked when the structure
.  meta obj
is used as the left argument of the
.  code \\$1
function.

If an object
.  meta obj
is combined with arguments
.  meta arg1
and
.  metn arg2 ,
as
.  mono
.  meti (\\$1 < obj < arg1 << arg2 )
.  onom
then, effectively, the method call
.  mono
.  meti << obj .(\\$1 < arg1 << arg2 )
.  onom
takes place, and its return value is taken as the result
of the operation.
..

.bmcv +
.bmnl -
.bmnr -- -
.umv neg -
.bmcv *
.bmnl /
.bmnr // /
.umv recip /
.um abs
.um signum
.bmnl trunc
.bmnr r-trunc trunc
.umv trunc1 trunc
.bmnl mod
.bmnr r-mod mod
.bmnl expt
.bmnr r-expt expt
.tmnl exptmod

Note: the
.code exptmod
function doesn't support structure objects in the second and
third argument positions. The
.meta exponent
and
.meta base
arguments must be integers.

.um isqrt
.um square
.bma > <
.bma < >
.bma >= <=
.bma <= >=
.bmc =
.um zerop
.um plusp
.um minusp
.um evenp
.um oddp
.bmnl floor
.bmnr r-floor floor
.umv floor1 floor
.bmnl ceil
.bmnr r-ceil ceil
.umv ceil1 ceil
.bmnl round
.bmnr r-round round
.umv round1 round
.um sin
.um cos
.um tan
.um asin
.um acos
.um atan
.bmnl atan2
.bmnr r-atan2 atan2
.um sinh
.um cosh
.um tanh
.um asinh
.um acosh
.um atanh
.um log
.um log2
.um log10
.um exp
.um sqrt
.bmcv logand
.bmcv logior
.bmnl lognot
.bmnr r-lognot lognot
.umv lognot1 lognot
.bmnl logtrunc
.bmnr r-logtrunc logtrunc
.bmnl sign-extend

Note: the
.code sign-extend
function doesn't support a structure as the right argument,
.metn bits ,
which must be an integer.

.bmnl ash

Note: the
.code ash
function doesn't support a structure as the right argument,
.metn bits ,
which must be an integer.

.bmnl bit

Note: the
.code bit
function doesn't support a structure as the right argument,
.metn bit ,
which must be an integer.

.um width
.um logcount
.um bitset

.SS* Exception Handling

An
.I exception
in \*(TX is a special event in the execution of the program which
potentially results in a transfer of control. An exception is identified by a
symbol, known as the
.IR "exception type" ,
and it carries zero or more arguments, called the
.IR "exception arguments" .

When an exception is initiated, it is said to be
.IR thrown .
This action is initiated by the following functions:
.codn throw ,
.code throwf
and
.codn error ,
and possibly other functions which invoke these.
When an exception is thrown, \*(TX enters into exception processing
mode. Exception processing mode terminates in one of several ways:
.IP -
A
.I catch
is found which matches the exception, and control is transferred
to the catch by a non-local transfer which performs unwinding. Catches are
defined by the
.code catch
macro.
.IP -
A
.I handler
is found which matches the exception, and control is transferred to
the handler by invoking its function. The handler function accepts the
exception by performing a non-local transfer to a destination of its choice, or
else declines to accept the exception by returning.
Handlers are defined by the
.code handler-bind
operator or
.code handle
macro.
.IP -
If no catch or accepting handler is found for an exception derived from
.code error
and
.code *unhandled-hook*
is
.codn nil ,
then a built-in strategy for handling the exception is invoked,
consisting of unwinding, and then printing some informational messages and
terminating.
If the
.code *unhandled-hook*
variable contains a value that isn't
.codn nil ,
then control is transferred to the function stored in the
that variable first; only if that function returns is the above
built-in strategy invoked.
.IP -
If no catch or accepting handler is found for an exception derived from
.codn warning ,
then a warning diagnostic is issued on the
.code *stderr*
stream and a
.code continue
exception is thrown with no arguments. If no catch or handler is found
for that exception, then control returns normally to the site which
threw the warning exception.
.IP -
If no catch or accepting handler is found for an exception that is
neither derived from
.code error
nor from
.codn warning ,
then no control transfer takes place; control returns to the
.code throw
or
.code throwf
function which returns normally, with a return value of
.codn nil .

.PP

.NP* Catches and Handlers

There are two ways by which exceptions are handled: catches and handlers.
Catches and handlers are similar, but different.
A catch is an exit point associated with an active scope. When an exception is
handled by a catch, the form which threw the exception is abandoned, and unwinding
takes place to the catch site, which receives the exception type and arguments.
A handler is also associated with an active scope. However, it is a function,
and not a dynamic exit point.  When an exception is passed to handler,
unwinding does not take place; rather, the function is called. The function then
either completes the exception handling by performing a non-local transfer,
or else declines the exception by performing an ordinary return.

Catches and handlers are identified by exception type symbols. A catch or
handler is eligible to process an exception if it handles a type which is
a supertype of the exception which is being processed. Handles and catches
are found by means of a combined search which proceeds from the innermost
nesting of dynamic scope to the outermost, without performing any unwinding.
When an eligible handler is encountered, its registered function is called, thereby suspending the
search.  If the handler function returns, the search continues from that scope
to yet unvisited outer scopes. When an eligible catch is encountered rather
than a handler, the search terminates and a control transfer takes place to the
catch site. That control transfer then performs unwinding, which requires it to
make a second pass through the same nestings of dynamic scope that had just
been traversed in order to find that catch.

.NP* Handlers and Sandboxing

Because handlers execute in the dynamic context of the exception origin,
without any unwinding having taken place, they expose a potential route
of sandbox escape via the package system, unless special steps are taken.
The threat is that code at the handler site could take advantage of
the current value of the
.code *package*
and
.code *package-alist*
variables established at the exception throw site to gain inappropriate access
to symbols.

For this reason, when a handler is established, the current values of
.code *package*
and
.code *package-alist*
are recorded into the handler frame.
When that handler is later invoked, it executes in a dynamic environment
in which those variables are bound to the previously noted values.

The catch mechanism doesn't do any such thing because the unwinding
which is performed prior to the invocation of a catch implicitly
restores the values of
.B all
special variables to the values they had at the time the frame was
established.

.NP* Exception Type Hierarchy

Exception type symbols are arranged
in an inheritance hierarchy, at whose top the symbol
.code t
is is the supertype of every exception type, and the
.code nil
symbol is at the bottom, the subtype of every exception type.

Keyword symbols may be used as exception types.

Every symbol is its own supertype and subtype. Thus whenever X is known to be a
subtype of Y, it is possible that X is exactly Y.
The
.code defex
macro registers exception supertype/subtype relationships among symbols.

The following tree diagram shows the relationships among \*(TL's built-in
exception symbols. Not shown is the exception symbol
.codn nil ,
subtype of every exception type:

.verb
  t ----+--- warning
        |
        +--- restart ---+--- continue
        |               |
        |               +--- retry
        |               |
        |               +--- skip
        |
        +--- error ---+--- type-error
                      |
                      +--- internal-error
                      |
                      +--- panic
                      |
                      +--- numeric-error
                      |
                      +--- range-error
                      |
                      +--- query-error
                      |
                      +--- file-error -------+--- path-not-found
                      |                      |
                      |                      +--- path-exists
                      |                      |
                      |                      +--- path-permission
                      |
                      +--- process-error
                      |
                      +--- socket-error
                      |
                      +--- system-error
                      |
                      +--- alloc-error
                      |
                      +--- timeout-error
                      |
                      +--- assert
                      |
                      +--- syntax-error
                      |
                      +--- eval-error
.brev

Program designers are encouraged to derive new error exceptions from the
.code error
type. The
.code restart
type is intended to be the root of a hierarchy of exception
types used for denoting restart points: designers are encouraged
to derive restarts from this type.
A catch for the
.code continue
exception should be established around constructs which can throw an
error from which it is possible to recover. That exception provides
the entry point into the recovery which resumes execution.
A catch for
.code retry
should be provided in situations when it is possible and makes sense for a failed
operation to be tried again.
A catch for
.code skip
should be provided in situations when it is possible and sensible to continue
with subsequent operations even though an operation has failed.

.NP* Dialect Notes

Exception handling in \*(TL provides capabilities similar to the condition
system in ANSI Common Lisp. The implementation and terminology differ.

Most obviously, ANSI CL uses the "condition" term, whereas \*(TL uses "exception".

In ANSI CL, a condition is "raised", whereas a \*(TL exception is "thrown".

In ANSI CL, when a condition is raised, a condition object is created. Condition
object are similar to class objects, but are not required to be in the Common Lisp
Object System. They are related by inheritance and can have properties. \*(TL
exceptions are unencapsulated: they consist of a symbol, plus zero or more
arguments. The symbols are related by inheritance.

When a condition is raised in ANSI CL, the dynamic scope is searched for a
handler, which is an ordinary function which receives the condition. No
unwinding or non-local transfer takes place.  The handler can return, in which
case the search continues. Matching the condition to the handler is by
inheritance. Handler functions are bound to exception type names.
If a handler chooses to actually handle a condition (thereby terminating
the search) it must itself perform some kind of dynamic control transfer,
rather than return normally. ANSI CL provides a dynamic control mechanism
known as restarts which is usually used for this purpose. A condition handler
may invoke a particular restart handler. Restart handlers are similar to
exception handlers: they are functions associated with symbols in the
dynamic environment.

In \*(TL, the special behavior which occurs for exceptions derived from
.code error
and those from
.code warning
is built into the exception handling system, and tied to those types.
When an error or warning exception is unhandled, the exception handling system
itself reacts, so the special behaviors occur no matter how these exceptions
are raised.  In ANSI CL, the special behavior for unhandled
.code error
conditions (of invoking the debugger) is implemented only in the
.code error
function;
.code error
conditions signalled other than via that function are not subject to
any special behavior. There is a parallel situation with regard to
warnings: the
ANSI CL
.code warn
function implements a special behavior for unhandled warnings (of emitting
a diagnostic) but warnings not signalled via that function are not
treated that way.
Thus in \*(TL, there is no way to raise an error or warning that is simply
ignored due to being unhandled.

In \*(TL exceptions are a unification of conditions and restarts. From an ANSI CL
perspective, \*(TL exceptions are a lot like CL restarts, except that the
symbols are arranged in an inheritance hierarchy. \*(TL exceptions are used
both as the equivalent of ANSI CL conditions and as restarts.

In \*(TL the terminology "catch" and "handle" is used in a specific way.
To handle an exception means to receive it without unwinding, with the possibility
of declining to handle it, so that the search continues for another handler.
To catch an exception means to match an exception to a catch handler, terminate
the search, unwind and pass control to the handler.

\*(TL provides an operator called
.code handler-bind
for specifying handlers. It has a different syntax from ANSI CL's
.codn handler-bind .
\*(TL provides a macro called
.code handle
which simplifies the use of
.codn handler-bind .
This macro superficially resembles ANSI CL's
.codn handler-case ,
but is semantically different. The most notable difference is that the bodies
of handlers established by
.code handler-bind
execute without any unwinding taking place and may return normally, thereby
declining to take the exception. In other words,
.code handle
has the same semantics as
.codn handler-bind ,
providing only convenient syntax.

\*(TL provides a macro called
.code catch
which has the same syntax as
.code handle
but specifies a catch point for exceptions. If, during an exception search, a
.code catch
clause matches an exception, a dynamic control transfer takes place
from the throw site to the catch site. Then the clause body is executed.
The
.code catch
macro resembles ANSI CL's
.code restart-case
or possibly
.codn handler-case ,
depending on point of view.

\*(TL provides unified introspection over handler and catch frames.
A program can programmatically discover what handler and catches are
available in a given dynamic scope. ANSI CL provides introspection
over restarts only; the standard doesn't specify any mechanism for
inquiring what condition handlers are bound at a given point in
the execution.

.TP* Example:

The following two examples express a similar approach  implemented
using ANSI Common Lisp conditions and restarts, and then using \*(TL
exceptions.

.verb
  ;; Common Lisp
  (define-condition foo-error (error)
    ((arg :initarg :arg :reader foo-error-arg)))

  (defun raise-foo-error (arg)
    (restart-case
      (let ((c (make-condition 'foo-error :arg arg)))
        (error c))
      (recover (recover-arg)
        (format t "recover, arg: ~s~%" recover-arg))))

  (handler-bind ((foo-error
                   (lambda (cond)
                     (format t "handling foo-error, arg: ~s~%"
                             (foo-error-arg cond))
                     (invoke-restart 'recover 100))))
    (raise-foo-error 200))
.brev

The output of the above is:

.verb
  handling foo-error, arg: 200
  recover, arg: 100
.brev

The following is possible \*(TL equivalent for the above Common Lisp example.
It produces identical output.

.verb
  (defex foo-error error)

  (defex recover restart) ;; recommended practice

  (defun raise-foo-error (arg)
    (catch
      (throw 'foo-error arg)
      (recover (recover-arg)
        (format t "recover, arg: ~s\en" recover-arg))))

  (handle
    (raise-foo-error 200)
    (foo-error (arg)
      (format t "handling foo-error, arg: ~s\en" arg)
      (throw 'recover 100)))
.brev

To summarize the differences: exceptions serve as both
conditions and restarts in \*(TX. The same
.code throw
function is used to initiate exception handling for
.code foo-error
and then to transfer control out of the handler
to the recovery code. The handler accepts one exception
by raising another.

When an exception symbol is used for restarting, it is
a recommended practice to insert it into the inheritance
hierarchy rooted at the
.code restart
symbol, either by inheriting directly from
.code restart
or from an exception subtype of that symbol.

.coNP Functions @, throw @ throwf and @ error
.synb
.mets (throw < symbol << arg *)
.mets (throwf < symbol < format-string << format-arg *)
.mets (error < format-string << format-arg *)
.syne
.desc
These functions generate an exception. The
.code throw
and
.code throwf
functions generate
an exception identified by
.metn symbol ,
whereas
.code error
throws an exception of
type
.codn error .
The call
.code "(error ...)"
can be regarded as a shorthand for
.codn "(throwf 'error ...)" .

The
.code throw
function takes zero or more additional arguments. These arguments
become the arguments of a
.code catch
handler which takes the exception. The
handler will have to be capable of accepting that number of arguments.

The
.code throwf
and
.code error
functions generate an exception which has a single
argument: a character string created by a formatted print to a string stream
using the
.code format
string and additional arguments.

Because
.code error
throws an error exception, it does not return. If an error exception
is not handled, \*(TX will issue diagnostic messages and terminate.
Likewise,
.code throw
or
.code throwf
are used to generate an error exception, they do not return.

If the
.code throw
and
.code throwf
functions are used to generate an exception not derived from
.codn error ,
and no handler is found which accepts the exception, they return normally, with
a value of
.codn nil .

.coNP Macros @, catch @ catch* and @ catch**
.synb
.mets (catch < try-expression
.mets \ \  >> {( symbol <> ( arg *) << body-form *)}*)
.mets (catch* < try-expression
.mets \ \  >> {( symbol >> ( type-arg << arg *) << body-form *)}*)
.mets (catch** < try-expression
.mets \ \  >> {( symbol < desc >> ( type-arg << arg *) << body-form *)}*)
.syne
.desc
The
.code catch
macro establishes an exception catching block around
the
.metn try-expression .
The
.meta try-expression
is followed by zero or more
catch clauses. Each catch clause consists of a symbol which denotes
an exception type, an argument list, and zero or more body forms.

If
.meta try-expression
terminates normally, then the catch clauses
are ignored. The catch itself terminates, and its return value is
that of the
.metn try-expression .

If
.meta try-expression
throws an exception which is a subtype of one or more of
the type symbols given in the exception clauses, then the first (leftmost) such
clause becomes the exit point where the exception is handled.
The exception is converted into arguments for the clause, and the clause
body is executed. When the clause body terminates, the catch terminates,
and the return value of the catch is that of the clause body.

If
.meta try-expression
throws an exception which is not a subtype of any of
the symbols given in the clauses, then the search for an exit point for
the exception continues through the enclosing forms. The catch clauses
are not involved in the handling of that exception.

When a clause catches an exception, the number of arguments in the catch must
match the number of elements in the exception.  A catch argument list
resembles a function or lambda argument list, and may be dotted.  For instance
the clause
.code "(foo (a . b))"
catches an exception subtyped from
.codn foo ,
with one or
more elements. The first element binds to parameter
.codn a ,
and the rest, if any,
bind to parameter
.codn b .
If there is only one element,
.code b
takes on the value
.codn nil .

The
.code catch*
macro is a variant of
.code catch
with the following difference: when
.code catch*
invokes a clause, it passes the exception symbol as the leftmost argument
.metn type-arg .
Then the exception arguments follow. In contrast,
only the exception arguments are passed to the clauses of
.codn catch .

The
.code catch**
macro is a further variant, which differs from
.code catch*
by requiring each catch clause to provide a description
.metn desc ,
an expression which evaluates to a character string.
The
.meta desc
expressions are evaluated in left-to-right order prior to the
evaluation of
.metn try-expression .

Also see: the
.code unwind-protect
operator, and the functions
.codn throw ,
.code throwf
and
.codn error ,
as well as the
.code handler-bind
operator and
.code handler
macro.

.coNP Operator @ unwind-protect
.synb
.mets (unwind-protect < protected-form << cleanup-form *)
.syne
.desc
The
.code unwind-protect
operator evaluates
.meta protected-form
in such a way that no matter how the execution of
.meta protected-form
terminates, the
.metn cleanup-form -s
will be executed.

The
.metn cleanup-form -s,
however, are not protected. If a
.meta cleanup-form
terminates via
some non-local jump, the subsequent
.metn cleanup-form -s
are not evaluated.

.metn cleanup-form -s
themselves can "hijack" a non-local control transfer such
as an exception. If a
.meta cleanup-form
is evaluated during the processing of
a dynamic control transfer such as an exception, and that
.meta cleanup-form
initiates its own dynamic control transfer, the original control transfer
is aborted and replaced with the new one.

The exit points for dynamic control transfers are removed as unwinding takes
place. That is to say, at the start of a dynamic control transfer, a search
takes place for the target exit point. That search might skip other exit points
which aren't targets of the control transfer. Those skipped exit points are left
undisturbed and are still visible during unwinding until their individual
binding forms are abandoned. Thus at the time of execution of an
.code unwind-protect
.metn cleanup-form ,
all of the exit points of dynamically surrounding forms are still visible, even
ones which are nearer than the targeted exit point.

.TP* Example:
.verb
  (block foo
    (unwind-protect
      (progn (return-from foo 42)
             (format t "not reached!\en"))
      (format t "cleanup!\en")))
.brev

In this example, the protected
.code progn
form terminates by returning from
block
.codn foo .
Therefore the form does not complete and so the
output
.str not reached!
is not produced. However, the cleanup form
executes, producing the output
.strn cleanup! .


.coNP Macro @ ignerr
.synb
.mets (ignerr << form *)
.syne
.desc
The
.code ignerr
macro operator evaluates each
.meta form
similarly to the
.code progn
operator. If no forms are present, it returns
.codn nil .
Otherwise it evaluates each
.meta form
in turn, yielding the value of the last one.

If the evaluation of any
.meta form
is abandoned due to an exception of type
.codn error ,
the code generated by the
.code ignerr
macro catches this exception. In this situation,
the execution of the
.code ignerr
form terminates without evaluating the remaining
forms, and yields
.codn nil .

.coNP Macro @ ignwarn
.synb
.mets (ignwarn << form *)
.syne
.desc
The
.code ignwarn
macro resembles
.codn ignerr .
It arranges for the evaluation of each
.meta form
in left-to-right order. If all the forms are evaluated, then the
value of the last one is returned. If no forms are present, then
.code nil
is returned.

If any
.meta form
throws an exception of type
.code warning
then this exception is intercepted by a handler established by
.codn ignwarn .
This handler reacts by throwing an exception of type
.codn continue .

The effect is that the warning is ignored, since the handler
doesn't issue any diagnostic, and passes control to the warning's
continue point.

Note: all sites within \*(TX which throw a
.code warning
also provide a nearby catch for a
.code continue
exception, for resuming evaluation at the point where the warning
was issued.

.coNP Operator @ handler-bind
.synb
.mets (handler-bind < function-form < symbol-list << body-form *)
.syne
.desc
The
.code handler-bind
operator establishes a handler for one or more
exception types, and evaluates zero or more
.metn body-form -s
in a dynamic scope in which that handler is visible.

When the
.code handler-bind
form terminates normally, the handler is removed. The value of the
last
.meta body-form
is returned, or else
.code nil
if there are no forms.

The
.meta function-form
argument is an expression which must evaluate to a function. The function
must be capable of accepting the exception arguments. All exceptions functions
require at least one argument, since the leftmost argument in an exception handler
call is the exception type symbol.

The
.meta symbol-list
argument is a list of symbols, not evaluated. If it is empty, then the handler
isn't eligible for any exceptions. Otherwise it is eligible for any exception
whose exception type is a subtype of any of the symbols.

If the evaluation of any
.meta body-form
throws an exception which is not handled within that form, and the handler
is eligible for that exception, then the function is invoked. It receives
the exception's type symbol as the leftmost argument. If the exception has
arguments, they appear as additional arguments in the function call.
If the function returns normally, then the exception search continues.
The handler remains established until the exception is handled in such a way
that a dynamic control transfer abandons the
.code handler-bind
form.

Note: while a handler's function is executing, the handler is disabled.
If the function throws an exception for which the handler is eligible,
the handler will not receive that exception; it will be skipped by the
exception search as if it didn't exist.  When the handler function terminates,
either via a normal return or a nonlocal control transfer, then the handler is
re-enabled.

.coNP Macros @ handle and @ handle*
.synb
.mets (handle < try-expression
.mets \ \  >> {( symbol <> ( arg *) << body-form *)}*)
.mets (handle* < try-expression
.mets \ \  >> {( symbol >> ( type-arg << arg *) << body-form *)}*)
.syne
.desc
The
.code handle
macro is a syntactic sugar for the
.code handler-bind
operator. Its syntax is exactly like that of
.codn catch .
The difference between
.code handle
and
.code catch
is that the clauses in
.code handle
are invoked without unwinding. That is to say,
.code handle
does not establish an exit point for an exception. When control passes to
a clause, it is by means of an ordinary function call and not a dynamic
control transfer. No evaluation frames are yet unwound when this takes place.

The
.code handle
macro establishes a handler, by
.code handler-bind
whose
.meta symbol-list
consists of every
.meta symbol
gathered from every clause.

The handler function established in the generated
.code handler-bind
is synthesized from of all of the clauses, together with dispatch logic which
which passes the exception and its arguments to the first
eligible clause.

The
.meta try-expression
is evaluated in the context of this handler.

The clause of the
.code handle
syntax can return normally, like a function, in which case the handler
is understood to have declined the exception, and exception processing
continues. To handle an exception, the clause of the
.code handle
macro must perform a dynamic control transfer, such returning from a block
via
.code return
or throwing an exception.

The
.code handle*
macro is a variant of
.code handle
with the following difference: when
.code handle*
invokes a clause, it passes the exception symbol as the leftmost argument
.metn type-arg .
Then the exception arguments follow. In contrast,
only the exception arguments are passed to the clauses of
.codn handle .

.coNP Macro @ with-resources
.synb
.mets (with-resources >> ({ sym >> [ init-form <> [ cleanup-form *])}*)
.mets \ \  << body-form *)
.syne
.desc
The
.code with-resources
macro provides a sequential binding construct similar to
.codn let* .
Every
.meta sym
is established as a variable which is visible to the
.metn init-form -s
of subsequent variables, to all subsequent
.metn cleanup-form -s
including that of the same variable,
and to the
.metn body-form -s.

If no
.meta init-form
is supplied, then
.meta sym
is bound to the value
.codn nil .

If an
.meta init-form
is supplied, but no
.metn cleanup-form -s,
then
.meta sym
is bound to the value of the
.metn init-form .

If one or more
.metn cleanup-form -s
are supplied in addition to
.metn init-form ,
they specifies forms to be executed upon the termination of the
.code with-resources
construct.

When an instance of
.code with-resources
terminates, either normally or by a non-local control transfer,
then for each
.meta sym
whose
.meta init-form
had executed, thus causing that
.code sym
to be bound to a value, the
.metn cleanup-form -s
corresponding to
.meta sym
are evaluated in the usual left-to-right order.

The
.metn sym -s
are cleaned up in reverse (right-to-left) order. The
.metn cleanup-form -s
of the most recently bound
.meta sym
are processed first; those of the least recently bound
.meta sym
are processed last.

When the
.code with-resources
form terminates normally, the value of the last
.meta body-form
is returned, or else
.code nil
if no
.metn body-form -s
are present.

.TP* "Example:"

The following expression opens a text file and reads a line from it,
returning that line, while ensuring that the stream is closed
immediately:

.verb
  (with-resources ((f (open-file "/etc/motd") (close-stream f)))
    (whilet ((l (get-line f)))
      (put-line l)))
.brev



.coNP Special variable @ *unhandled-hook*
The
.code *unhandled-hook*
variable is initialized with
.code nil
by default.

It may instead be assigned a function which is capable of taking
three arguments.

When an exception occurs which has no handler, this function is called,
with the following arguments: the exception type symbol, the exception object,
and a third value which is either
.code nil
or else the form which was being evaluated when the exception was thrown.
The call occurs before any unwinding takes place.

If the variable is
.codn nil ,
or isn't a function, or the function returns after being called,
then unwinding takes place, after which some informational messages are printed
about the exception, and the process exits with a failed termination status.

In the case when the variable contains a object other than
.code nil
which isn't a function, a diagnostic message is printed on the
.code *stderr*
stream prior to unwinding.

Prior to the function being called, the
.code *unhandled-hook*
variable is reset to
.codn nil .

Note: the functions
.code source-loc
or
.code source-loc-str
may be applied to the third argument of the
.code *unhandled-hook*
function to obtain more information about the form.

.coNP Macro @ defex
.synb
.mets (defex <> { symbol }*)
.syne
.desc
The macro
.code defex
records hierarchical relationships among symbols, for the purposes
of the use of those symbols as exceptions. It is closely related to the
.code @(defex)
directive in the \*(TX pattern language, performing the same function.

All symbols are considered to be exception subtypes, and every symbol
is implicitly its own exception subtype. This macro does not introduce
symbols as exception types; it only introduces subtype-supertype
relationships.

If
.code defex
is invoked with no arguments, it has no effect.

If arguments are present, they must be symbols.

If
.code defex
is invoked with only one symbol as its argument, it has no effect.

At least two
symbols must be specified for a useful effect to take place.  If exactly two
symbols are specified, then, subject to error checks,
.code defex
makes the left symbol an
.I exception subtype
of the right symbol.

This behavior generalizes to three or more arguments: if three or more symbols
are specified, then each symbol other than the last is registered as a subtype of
the symbol which follows.

If a
.code defex
has three or more arguments, they are processed from left to right.
If errors are encountered during the processing, the correct registrations
already made for prior arguments remain in place.

Every symbol is implicitly considered to be its own exception subtype,
therefore it is erroneous to explicitly register a symbol as its
own subtype.

The symbol
.code nil
is implicitly a subtype of every exception type. Therefore, it is erroneous
to attempt to specify it as a supertype in a registration.
Using
.code nil
as a subtype in a registration is silently permitted, but has no effect.
No explicit registration is recorded between
.code nil
and its successor in the argument list.

The symbol
.code t
is implicitly the supertype of every exception type. Therefore, it
is erroneous to attempt to register it as an exception subtype.
Using
.code t
as a supertype in a registration is also erroneous.

A symbol
.code a
may not be registered as a subtype of a symbol
.code b
if the reverse relationship already exists between those two symbols.

The foregoing rules allow redefinitions to take place, while forbidding cycles
from being created in the exception subtype inheritance graph.

Keyword symbols may be used as exception types.

.coNP Function @ register-exception-subtypes
.synb
.mets (register-exception-subtypes <> { symbol }*)
.syne
.desc
The
.code register-exception-subtypes
function constitutes the underlying implementation for the
.code defex
macro.

The following equivalence applies:

.verb
  (defex a b ...)  <-->  (register-exception-subtypes 'a 'b ...)
.brev

That is, the
.code defex
macro works as if by generating a call to the function, with
the arguments quoted.

The semantics of the function is precisely that of the macro.

.coNP Function @ exception-subtype-p
.synb
.mets (exception-subtype-p < left-symbol << right-symbol )
.syne
.desc
The
.code exception-subtype-p
function tests whether two symbols are in a relationship as exception types,
such that
.meta left-symbol
is a direct or indirect exception subtype of
.metn right-symbol .

If that is the case, then
.code t
is returned, otherwise
.codn nil .

.coNP Function @ exception-subtype-map
.synb
.mets (exception-subtype-map)
.syne
.desc
The
.code exception-subtype-map
function returns a tree structure which captures information
about all registered exception types.

The map appears as an association list which contains an entry
for every exception symbol, paired with that type's supertype path.
The first element in the supertype path is the exception's immediate
supertype. The next element is that type's supertype and so on. The
last element in every path is the grand supertype
.codn t .

For instance, if only the types
.codn a ,
.code b
and
.code c
existed in the system, and were linked according to this inheritance graph:

.verb
  t ----+--- b --- a
        |
        +--- c
.brev

such that the supertype of
.code b
and
.code c
is
.codn t ,
and
.code a
has
.code b
as supertype, then the function might return:

.verb
  ((a b t) (b t) (c t) (t))
.brev

or any other equivalent permutation.

The returned list may share substructure, so that the
.code "(t)"
sublist is shared among all four entries, and
.code "(b t)"
between the first two.

If the program alters the tree structure returned by
.codn exception-map-p ,
the consequences are unspecified; this structure may be the actual object which
represents the type hierarchy.

.coNP Structures @, frame @ catch-frame and @ handle-frame
.synb
.mets (defstruct frame nil)
.mets (defstruct catch-frame frame types desc jump)
.mets (defstruct handle-frame frame types fun)
.syne
.desc
The structure types
.codn frame ,
.code catch-frame
and
.code handle-frame
are used by the
.code get-frames
and
.code find-frame
functions to represent information about the currently established
exception catches (see the
.code catch
macro) and handlers
(see
.code handler-bind
and
.codn handler ).

The
.code frame
type serves as the common base for
.code catch-frame
and
.codn handle-frame .

Modifying any of the slots of these structures has no effect on the
actual frame from which they are derived; the frame structures are only
representation which provides information about frames. They are not
the actual frames themselves.

Both
.code catch-frame
and
.code handle-frame
have a
.code types
slot. This holds the list of exception type symbols which are matched
by the catch or handler.

The
.code desc
slot of a
.code catch-frame
holds a list of the descriptions produced by the
.code catch**
macro. If there are no descriptions, then this member is
.codn nil ,
otherwise it is a list whose elements are in correspondence
with the list in the
.code types
slot.

The
.code jump
slot of a
.code catch-frame
is an opaque
.code cptr
("C pointer")
object which is related to the stack address of the catch
frame. If it is altered, the catch frame object becomes invalid
for the purposes of
.codn invoke-catch .

The
.code fun
slot of a
.code handle-frame
is the registered handler function. Note that all the clauses of a
.code handler
macro are compiled to a single function, which is established via
.codn handler-bind ,
so an instance of the
.code handler
macro corresponds to a single
.codn handle-frame .

.coNP Function @ get-frames
.synb
.mets (get-frames)
.syne
.desc
The
.code get-frames
function inquires the current dynamic environment in order to retrieve
information about established exception catch and handler frames.
The function returns a list, ordered from the inner-most nesting
level to the outer-most nesting, of structure objects derived from the
.code frame
structure type. The list contains two kinds of objects: structures
of type
.code catch-frame
and of type
.codn handle-frame .

These objects are not the frames themselves, but only provide information
about frames. Modifying the slots in these structures has no effect on
the original frames. Also, these structures have their own lifetime and
can endure after the original frames have disappeared. This has implications
for the use of the
.code invoke-catch
function.

The
.code handle-frame
structures have a
.code fun
slot, which holds a function. It may be invoked directly.

A
.code catch-frame
structure may be passed as an argument to the
.code invoke-catch
function.

.coNP Functions @ find-frame and @ find-frames
.synb
.mets (find-frame >> [ exception-symbol <> [ frame-type ]])
.mets (find-frames >> [ exception-symbol <> [ frame-type ]])
.syne
.desc
The
.code find-frame
function locates the first (innermost) instance of a specific kind of
exception frame (a catch frame or a handler frame) which is eligible
for processing an exception of a specific type. If such a frame
is found, it is returned.  The returned frame object is of the same kind as the
objects which comprise the list returned by the function
.codn get-frames .
If such a frame is not found,
.code nil
is returned.

The
.meta exception-symbol
argument specifies a match by exception type: the candidate frame
must specify in its list of matches at least one type which is an exception
supertype of
.metn exception-symbol .
If this argument is omitted, it defaults to
.code nil
which finds any handler that matches at least one type. There is no way to
search for handlers which match an empty set of types; the
.code find-frame
function skips such frames.

The
.meta frame-type
argument specifies which frame type to find. Useful values for this
argument are the structure type names
.code catch-frame
and
.code handle-frame
or the actual structure type objects which these type names denote.
If any other value is specified, the function returns
.codn nil .
If the argument is omitted, it defaults to the type of the
.code catch-frame
structure. That is to say, by default, the function looks for catch
frames.

Thus, if
.code find-frame
is called with no arguments at all it finds the innermost catch frame,
if any exists, or else returns
.codn nil .

The
.code find-frames
function is similar to
.code find-frame
except that it returns all matching frames, ordered from the inner-most nesting
level to the outer-most nesting. If called with no arguments, it returns a
list of the catch frames.

.coNP Function @ invoke-catch
.synb
.mets (invoke-catch < catch-frame < symbol << argument *)
.syne
.desc
The
.code invoke-catch
function abandons the current evaluation context to perform
a non-local control transfer directly to the catch
described by the
.meta catch-frame
argument, which must be a structure of type
.code catch-frame
obtained using any of the functions
.codn get-frames ,
.code find-frames
or
.codn find-frame .

The control transfer is possible only if the catch
frame represented by
.meta catch-frame
structure is still established, and if the structure
hasn't been tampered with.

If a given
.code catch-frame
structure is usable with
.codn invoke-catch ,
then a copy of that structure made with
.code copy-struct
is also usable, denoting the same catch frame.

The
.meta symbol
argument should be an exception symbol. It is passed to the
exception frame, as if it had appeared as the first argument of the
.code throw
function. Similarly, the
.metn argument -s
are passed to the catch frame as if they were the trailing arguments
of a
.codn throw .
The difference between
.code invoke-catch
and
.code throw
is that
.code invoke-catch
targets a specific catch frame as its exit point, rather than searching for a
matching catch or handler frame. That specific frame receives the control.
The frame receives control even if it it is not otherwise eligible for
catching the exception type denoted by
.metn symbol .

.coNP Macro @ assert
.synb
.mets (assert < expr >> [ format-string << format-arg *])
.syne
.desc
The
.code assert
macro evaluates
.metn expr .
If
.meta expr
yields any true value, then
.code assert
terminates normally, and that value is returned.

If instead
.meta expr
yields
.codn nil ,
then
.code assert
throws an exception of type
.codn assert .
The exception carries an informative character string that contains
a diagnostic detailing the expression which yielded
.codn nil ,
and the source location of that expression, if available.

If the
.meta format-string
and possibly additional format arguments are given to
.code assert
then those arguments are used to format additional text which is appended to
the diagnostic message after a separating character such as a colon.

.SS* Static Error Diagnosis

This section describes a number of features related to the diagnosis
of errors during the static processing of program code prior to evaluation.
The material is of interest to developers of macros intended for broad
reuse.

.NP* Error Exceptions

\*(TL uses exceptions of type
.code eval-error
to identify erroneous situations during both transformation of code
and its evaluation. These exceptions have one argument, which is a
character string. If not handled by program code,
.code eval-error
exceptions are specially recognized and treated by the built-in handling logic.
The message is incorporated into diagnostic output which includes
more information which is deduced.

.NP* Warning Exceptions

\*(TL uses exceptions of type
.code warning
to identify certain situations of interest. Ordinary non-deferrable
warnings have a structure identical to errors, except for the exception
symbol. \*(TX's provides built-in "auto continue" handling for warnings. If a warning
exception is not intercepted by a catch or an accepting handler, then a
diagnostic is issued on the
.code *stderr*
stream, after which a
.code continue
exception is thrown with no arguments. If that
.code continue
exception is not handled, then control returns normally to the point that
exception to resume the computation which generated the warning.

Callers which invoke code that may generate warning exceptions are therefore
not required to handle them. However, callers which do handle warning
exceptions expect to be able to throw a
.code continue
exception in order to resume the computation that triggered the warning,
without allowing other handlers to see the exception.

The generation of a warning should thus conform to the following pattern:

.verb
  (catch
    (throw 'warning "message")
    (continue ()))
.brev

.NP* Deferrable Warnings

\*(TX supports a form of diagnostic known as a
.IR "deferrable warning" .
A deferrable warning is distinguished in two ways. Firstly, it is
either of the type
.code defr-warning
or subtyped from that type. The
.code defr-warning
type itself is a direct subtype of
.codn warning .

Secondly, a deferrable warning carries an additional tag argument after the
exception message. A deferrable exception is thrown according to
this pattern:

.verb
  (catch
    (throw 'defr-warning "message" . tag)
    (continue ()))
.brev

\*(TX's built-in exception handling logic reacts specially to the
presence of the tag material in the exception. First, the global
.I "tentative definition list"
is searched for the presence of the tag, using
.code equal
equality. If the tag is found, then the warning is discarded.
If the tag is not found, then the exception argument list is added
to the global
.IR "deferred warning list" .
In either case,
the
.code continue
exception is thrown to resume the computation which threw the warning,
as in the case of an ordinary non-deferrable warning.

The purpose of this mechanism is to suppress warnings which
become superfluous when more of the program code is examined.
For instance, a warning about a call to an undefined function is
superfluous if a definition of that function is supplied later,
yet before that function call is executed.

Deferred warnings accumulate in the deferred warning list
from which they can be removed. The list is purged at various
times such as when a top-level load completes, and the
deferred warnings are released, as if by a call to the
.code release-deferred-warnings
function.

.coNP Functions @ compile-error and @ compile-warning
.synb
.mets (compile-error < context-obj < fmt-string << fmt-arg *)
.mets (compile-warning < context-obj < fmt-string << fmt-arg *)
.syne
.desc
The functions
.code compile-error
and
.code compile-warning
provide a convenient and uniform way for code transforming
functions such as macro-expanders to generate diagnostics.
The
.code compile-error
function throws an exception of type
.codn eval-error .
The
.code compile-warning
function throws an exception of type
.code warning
and internally provides a
.code catch
for the
.code continue
exception which allow a warning handler to resume execution
after the warning. If a handler throws a
.code continue
exception which is caught by
.codn compile-warning ,
then
.code compile-warning
returns
.codn nil .

Because
.code compile-warning
throws a non-error exception, it returns
.code nil
in the event that no catch is found for the exception, and no handler which
accepts it.

The argument conventions are the same for both functions.
The
.meta context-obj
is typically a compound form to which the diagnostic
applies.

The functions produce a diagnostic message which
incorporates the location information and symbol
obtained from
.meta context-obj
and the
.codn format -style
arguments
.meta fmt-string
and its
.metn fmt-arg -s.

.coNP Function @ compile-defr-warning
.synb
.mets (compile-defr-warning < context-obj < tag
.mets \ \  < fmt-string << fmt-arg *)
.syne
.desc
The
.code compile-defr-warning
function throws an exception of type
.code defr-warning
and internally provides a
.code catch
for the
.code continue
exception needed to resume after the warning.

The function produces a diagnostic message which
incorporates the location information and symbol
obtained from
.meta context-obj
and the
.codn format -style
arguments
.meta fmt-string
and its
.metn fmt-arg -s.
This diagnostic message constitutes the first
argument of the exception. The
.meta tag
argument is taken as the second argument.

If the exception isn't intercepted by a catch or by
an accepting handler,
.code compile-defr-warning
returns
.codn nil .
In also returns nil if it catches a
.code continue
exception.

.coNP Function @ purge-deferred-warning
.synb
.mets (purge-deferred-warning << tag )
.syne
.desc
The
.code purge-deferred-warning
removes all warnings marked with
.meta tag
from the deferred list. It also removes all tags
matching
.meta tag
from the tentative definition list.
Tags are compared using the
.code equal
function.

.coNP Function @ register-tentative-def
.synb
.mets (register-tentative-def << tag )
.syne
.desc
The
.code register-tentative-def
function adds
.meta tag
to the list of tentative definitions which are
used to suppress deferrable warnings.

The idea is that a definition of some construct has been seen,
but not yet executed. Thus the construct is not defined, but
it can reasonably be expected that it will be defined;
hence, warnings about its nonexistence can be suppressed.

For example, in the following code, when the expression
.code "(foo)"
is being expanded and transformed, the
.code foo
function does not exist:

.verb
  (progn (defun foo ()) (foo))
.brev

The function won't be defined until the
.code progn
is evaluated. Thus a warning is generated that
.code "(foo)"
refers to an undefined function.
However, this warning is discarded, because the
expander for
.code defun
registers a tentative definition tag for
.codn foo .

When the definition of
.code foo
takes place, the
.code defun
operator will call
.code purge-deferred-warning
which will remove not only all accumulated warnings
related to the undefinedness of
.code foo
but also remove the tentative definition.

Note: this mechanism isn't perfect because it will
still suppresses the warning in situations like

.verb
  (progn (if nil (defun foo ())) (foo))
.brev


.coNP Function @ tentative-def-exists
.synb
.mets (tentative-def-exists << tag )
.syne
.desc
The
.code tentative-def-exists
function checks whether
.meta tag
has been registered via
.code register-tentative-def
and not yet purged by
.codn purge-deferred-warning .

.coNP Function @ defer-warning
.synb
.mets (defer-warning << args )
.syne
.desc
The
.code defer-warning
function attempts to register a deferred warning. The
.meta args
argument corresponds to the arguments which are passed to the
.code throw
function in order to generate a warning exception, not including the exception
symbol.

Args is expected to have at least two elements, the second of which
is a deferred warning tag.

The
.code defer-warning
function returns
.codn nil .

Note: this function is intended for use in exception handlers. The
following example shows a handler which intercepts warnings. It defers
deferrable warnings, and prints ordinary warnings:

.verb
  (handle
    (some-form ..) ;; some code which might generate warnings
    (defr-warning (msg tag) ;; catch deferrable and defer
      (defer-warning (cons msg tag))
      (throw 'continue)) ;; warning processed: resume execution
    (warning (msg)
      (put-line `warning: @msg`) ;; print non-deferrable
      (throw 'continue))) ;; warning processed: resume execution
.brev

.coNP Function @ release-deferred-warnings
.synb
.mets (release-deferred-warnings)
.syne
.desc
The
.code release-deferred-warnings
removes all warnings from the deferred list.
Then, it issues each deferred warning as an ordinary warning.

Note: there is normally no need for user programs to use this
function since deferred warnings are issued automatically.

.coNP Function @ dump-deferred-warnings
.synb
.mets (dump-deferred-warning << stream )
.syne
.desc
The
.code dump-deferred-warnings
empties the list of deferred warnings, and converts each one
into a diagnostic message sent to
sent to
.metn stream .
After the diagnostics are printed, the list of pending warnings
is cleared.

Note: there is normally no need for user programs to use this
function since deferred warnings are issued automatically.

.SS* Delimited Continuations

\*(TL supports delimited continuations, which are integrated with the
.code block
feature. Any named or anonymous block, including the implicit blocks
created around function bodies, can be used as the delimiting
.I prompt
for the capture of a continuation.

A delimited continuation is section of a possible future of the
computation, up to a delimiting prompt,
.I reified
as a first class function.

.TP* Example:

.verb
  (defun receive (cont)
    (format t "cont returned ~a\en" (call cont 3)))

  (defun function ()
    (sys:capture-cont 'abcd (fun receive)))

  (block abcd
    (format t "function returned ~a\en" (function))
    4)

  Output:

  function returned 3
  cont returned 4
  function returned t
.brev

.PP

Evaluation begins with the
.code block
form. This form calls
.code function
which uses
.code sys:capture-cont
to capture a continuation up to the
.code abcd
prompt.  The continuation is passed to the
.code receive
function as an argument.

This captured object represents the continuation of computation
up to that prompt.  It appears as a one-argument function which, when called,
resumes the captured computation. Its argument emerges out of the
.code sys:capture-cont
call as a return value. When the computation eventually returns all
the way to the delimiting prompt, the return value of that prompt
will then appear as the return value of the continuation function.

In this example, the function
.code receive
immediately invokes the continuation function which it receives, passing
it the argument value
.codn 3 .
And so,
evaluation now continues in the resumed future represented by the
continuation. Inside the continuation,
.code sys:capture-cont
appears to return, yielding the value
.codn 3 .
This bubbles up through
.code function
up to the
.code "block abcd"
where a message is printed:
.strn "function returned 3" .

The
.code block
terminates, yielding the value 4. Thereby, the continuation ends, since
it is delimited up to that block.  Control now returns to the
.code receive
function which invoked the continuation, where the function call form
.code "(call cont)"
terminates, yielding the value
.code 4
that was returned by the continuation's delimiting
.code block
form. The message
.str "cont returned 4"
is printed. The
.code receive
function returns normally, returning the value
.code t
which emerged from the
.code format
call. Control is now back in
.code function
where the
.code sys:capture-cont
form terminates and returns the
.codn t .
This bubbles up to
.code block
which prints
.strn "function returned t" .

In summary, a continuation represents, as a function, the subsequent
computation that is to take place starting at some point, up to some
recently established, dynamically enclosing delimiting prompt. When
the continuation is captured, that future doesn't have to take place;
an alternative future can carry out in which that continuation is
available as a function. That alternative future can invoke the continuation at
will.  Invocations (resumptions) of the continuation appear as additional
returns from the capture operator. A resumption of a continuation terminates
when the delimiting prompt terminates, and the continuation yields the
value which emerges from the prompt.

Delimited continuations are implemented by capturing a segment of the
evaluation stack between the prompt and the capture point. When
a continuation is resumed, this saved copy of a stack segment is inserted on
top of the current stack and the procedure context is resumed such
that evaluation appears to emerge from the capture operator.
As the continuation runs to completion, it simply pops these inserted
stack frames naturally. Eventually it pops out of the delimiting prompt,
at which point control ends up at the point which invoked the continuation
function.

The low-level operator for capturing a continuation is
.codn sys:capture-cont .
More expressive and convenient programming with continuations is
provided by the macros
.codn obtain ,
.codn obtain-block ,
.code yield-from
and
.codn yield ,
which create an abstraction which models the continuation as a suspended
procedure supporting two-way communication of data.
A
.code suspend
operator is provided, which is more general. It is identical to the
.code shift
operator described in various computer science literature about
delimited continuations, except that it refers to a specific delimiting
prompt by name.

Continuations raise the issue of what to do about unwinding.
The language Scheme provides the much criticized
.code dynamic-wind
operator which can execute initialization and clean-up code as
a continuation is entered and abandoned. \*(TX takes a simpler,
albeit risky approach. It provides a non-unwinding escape operator
.code sys:abscond-from
for use with continuations. Code which has captured a continuation
can use this operator to escape from the delimiting block without
triggering any unwinding among the frames between the capture point and the
delimiter. When the continuation is restarted, it will then do so
with all of the resources associated with it frames intact.
When the continuation executes normal returns within its context,
the unwinding takes place then.  Thus tidy, "thread-like" use
of continuations is possible with a small measure of coding discipline.
Unfortunately, the absconding operator is dangerous: its use
breaks the language guarantee that clean-up associated with a form is done no
matter how a form terminates.

.NP* Comparison with Lexical Closures

Delimited continuations resemble lexical closures in some ways. Both
constructs provide a way to return to some context whose evaluation
has already been abandoned, and to access some aspects of that context.
However, lexical closures are statically scoped. Closures capture the lexically
apparent scope at a given point, and produce a function whose body has access
to that scope, as well as to some arbitrary arguments. Thus, a lexical scope
is reified as a first-class function. By contrast, a delimited continuation
is dynamic. It captures an an entire segment of a program activation chain,
up to the delimiting prompt. This segment includes scopes which are not
lexically visible at the capture point: the scopes of parent functions.
Moreover, the segment includes not only scopes, but also other aspects of
the evaluation context, such as the possibility of returning to callers,
and the (captured portion of) the original dynamic environment, such as
exception handlers.  That is to say, a lexical closure's body cannot return to
the surrounding code or see any of its original dynamic environment; it can
only inspect the environment, and then return to its own caller.  Whereas a
restarted delimited continuation can continue evaluation of the surrounding
code, return to surrounding forms and parent functions, and access the dynamic
environment. The continuation function returns to its caller when that entire
restarted context terminates, whereas a closure returns to its caller as soon
as the closure body terminates.

.NP* Differences in Compiled vs. Interpreted Behavior

Delimited continuations in \*(TX expose a behavioral difference between
compiled and interpreted code which mutates the values of lexical variables.

When a continuation is captured in compiled code, it captures not only the
bindings of lexical variables, but also potentially their current values
at the time of capture. What this means is that whenever the continuation
is resumed, those variables will appear to have the captured values,
regardless of any mutations that have taken place since. In other words,
the captured future includes those specific values.  This is because in
compiled code, variables are allocated on the stack, which is copied as part of
creating a continuation. Those variables are effectively newly instantiated in
each resumption of the continuation, when the captured stack segment
is reinstated into the stack, and take on those original values.

In contrast, interpretation of code only maintains an
environment pointer on the stack; the lexical environment is a dynamically
allocated object whose contents aren't included in the continuation's
stack segment capture. If the captured variables are modified after the
capture, the continuation will see the updated values: all resumptions of the
continuation share the same instance of the captured environment among
themselves, and with the original context where the capture took place.

An additional complication is that when compiled code captures lexical
closures, captured variables are moved into dynamic storage and then
they become shared: the semantics of the mutation of those variables
is then similar to the situation in interpreted code. Therefore, the
above described non-sharing capture behavior of compiled code is not required
to hold.

In continuation-based code which relies on mutation of lexical variables
created with
.code let
or
.codn let* ,
the macros
.code hlet
and
.code hlet*
can be used instead. These macros create variable bindings whose storage is
always outside of the stack, and therefore the variables will exhibit
consistent

If the affected variables are other kinds of bindings such as
function parameters or variables created with specialized binding
constructs such as
.codn with-stream ,
additional coding changes may be required to get interpreted code
working under compilation.

.coNP Function @ sys:capture-cont
.synb
.mets (sys:capture-cont < name < receive-fun <> [ context-form ])
.syne
.desc
The
.code sys:capture-cont
function captures a continuation, and also serves as the resume point
for the resulting continuation. Which of these two situations is the
case (capture or resumption) is distinguished by the use of the
.meta receive-fun
argument, which must be a function capable of being called with one
argument.

A block named
.meta name
must be visible; the continuation is delimited by the closest
enclosing block of this name.

The optional
.meta context-form
argument should be a compound form. If
.code sys:capture-cont
reports an error, it reports it against this form,
and uses the form's operator symbol as the name of the function which
encountered the error.  If the argument is omitted,
.code sys:capture-cont
uses its own name.

The
.code sys:capture-cont
function captures a continuation, represented as a function.
It immediately calls
.metn receive-fun ,
passing it it the continuation function as an argument.
If
.meta receive-fun
returns normally, then
.code sys:capture-cont
returns whatever value
.meta receive-fun
returns.

Resuming a continuation is done by invoking the continuation function.
When this happens, the entire continuation context is restored by re-creating
its captured evaluation frames on top of the current stack. Inside the
continuation, the
.code sys:capture-cont
function call which captured the continuation now appears to return,
and yields a value. That value is precisely the value which was just
passed to the continuation function moments ago.

The resumed continuation can terminate in one of three ways. Firstly, it can
simply keep executing until it discards all of its evaluation frames below the
delimiting block, and then allows that block to terminate naturally by
evaluating the last form contained in the block.  Secondly, can use
.code return-from
against its delimiting block to explicitly abandon all evaluations in between
and terminate that block. Or it may perform
a non-local control transfer past the delimited block somewhere into the
evaluation frames of the caller. In the first two cases, the termination
of the block turns into an ordinary return from the continuation function, and
the result value of the terminated block becomes the return value of that
function call.  In the last case, the call of the continuation function is
abandoned and unwinding continues through the caller.

If the symbol
.code sys:cont-poison
is passed to the continuation function, the continuation will be
resumed in a different manner: its context will be restored as in the
ordinary resume case, whereupon it will be immediately abandoned by
a nonlocal exit, causing unwinding to take place across all of the
continuation's evaluation frames. The function then returns
.codn nil .

If the symbol
.code sys:cont-free
is passed to the continuation function, the continuation isn't
be resumed at all; rather, the buffer which holds the saved context
of the continuation is released. Thereafter, an attempt to resume
the continuation results in an error exception being thrown.
After releasing the buffer, the function returns
.codn nil .

.TP* Notes:

The continuation function may be used any time after it is produced, and may be
called more than once, regardless of whether the originally captured dynamic
context is still executing. The continuation object may be communicated into
the resumed continuation, which can then use it to call itself, resulting
in multiple nested resumptions of the same continuation. A delimited
continuation is effectively a first class function.

The underlying continuation object produced by
.code sys:capture-cont
stores a copy of the captured dynamic context.  Whenever the continuation
function is invoked, a copy of the captured is reinstated as if it were a new
context.  Thus each apparent return from the
.code sys:capture-cont
inside a resumed continuation is not actually made in the original context, but
in a copy of that context. That context can be resumed multiple times
sequentially or recursively.

Just like lexical closures, continuations do not copy lexical environments;
they capture lexical environments by reference. If a continuation modifies
the values of captured lexical variables, those modifications are visible to
other resumptions of the same continuation, to other continuations which
capture the same environment, to lexical closures which capture the same
environment and to the original context which created that environment, if it
is still active.

Unlike lexical closures, continuations do capture the local bindings
of special variables. That is to say, if
.code *var*
is a special variable, then a lexical closure created inside a
.code "(let ((*var* 42)) ...)"
form will not capture the local re-binding of
.code *var*
which holds 42.  When the closure is invoked and accesses
.codn *var* ,
it accesses whatever value of
.code *var*
is dynamically current, as dictated by the environment which calls the
closure, rather than the capturing environment.

With continuations, the behavior is different. If a continuation
is captured inside a
.code "(let ((*var* 42)) ...)"
form then it does capture the local binding. This is regardless whether
the delimited prompt of the capture is enclosed in this form, or
outside of the form.
The special variable has a binding in a dynamic environment. There is always a
reference to a current dynamic environment associated with every evaluation
context, and a continuation captures that reference.  Because it is a
reference, it means that the binding is shared. That is to say, all
invocations of all continuations which capture the same dynamic environment in
which that
.code "(let ((*var* 42)) ...)"
binding was made share the same binding; if
.code *var*
is modified by assignment, the modification is visible to all those views.

Inside a resumed continuation, a form which binds a special variable such as
.code "(let ((*var* 42)) ...)"
may terminate. As expected, this causes the binding to be removed,
revealing either another local binding of
.code *var*
or the global binding. However, this unbinding only affects only that
that executing continuation; it has no effect inside other instances of the
same continuation or other continuations which capture the same variable.
Unbinding isn't a mutation of the dynamic environment, but may be understood
as merely the restoration of an earlier dynamic environment reference.

.TP* "Example:"

The following example shows an implementation of the
.code suspend
operator.

.verb
  (defmacro suspend (:form form name var . body)
    ^(sys:capture-cont ',name (lambda (,var)
                                (sys:abscond-from ,name ,*body))
                       ',form))
.brev

.coNP Operator @ sys:abscond-from
.synb
.mets (sys:abscond-from < name <> [ value ])
.syne
.desc
The
.code sys:abscond-from
operator closely resembles
.code return-from
and performs the same function: it causes an enclosing block
.meta name
to terminate with
.meta value
which defaults to
.codn nil .

However, unlike
.codn return-from ,
.code sys:abscond-from
does not perform any unwinding.

This operator should never be used for any purpose other than
implementing primitives for the use of delimited continuations.
It is used by the
.code yield-from
and
.code yield
operators to escape out of a block in which a continuation has
been captured. Neglecting to unwind is valid due to the expectation
that control will return into a restarted copy of that context.

.coNP Function @ sys:abscond*
.synb
.mets (sys:abscond* < name <> [ value ])
.syne
.desc
The
.code sys:abscond*
function is similar to the the
.code sys:abscond-from
operator, except that
.code name
is an ordinary function parameter, and so when
.code return*
is used, an argument expression must be specified which evaluates
to a symbol. Thus
.code sys:abscond*
allows the target block of a return to be dynamically computed.

The following equivalence holds between the operator and function:

.verb
  (sys:abscond-from a b)  <-->  (sys:abscond* 'a b)
.brev

Expressions used as
.meta name
arguments to
.code abscond*
which do not simply quote a symbol have no equivalent in
.codn abscond-from .

.coNP Macros @ obtain and @ yield-from
.synb
.mets (obtain << forms *)
.mets (yield-from < name <> [ form ])
.syne
.desc
The
.code obtain
and
.code yield-from
macros closely inter-operate.

The
.code obtain
macro treats zero or more
.metn form -s
as a suspendable execution context called the
.IR "obtain block" .
It is expected that
.metn form -s
establish a block named
.meta name
and return its result value to
.codn obtain .

Without evaluating any of the forms in the obtain block,
.code obtain
returns a function, which takes one optional argument.
This argument, called the
.IR "resume value" ,
defaults to
.code nil
if it is omitted.

The function represents the suspended execution context.

The context is resumed whenever the function is called, and executes
until the next
.code yield-from
statement which references the block named
.metn name .
The function's reply argument is noted.

If the
.code yield-from
specifies a
.meta form
argument, then the execution context suspends, and the resume function
terminates and returns the value of that form. When the function is called
again to resume the context, the
.code yield-from
returns the previously noted resume value (and the new resume
value just passed is noted in its place).

If the
.code yield-from
specifies no
.meta form
argument, then it briefly suspends the execution context only
to retrieve the resume value, without producing an item. Since
no item is produced, the resume function does not return.
The execution context implicitly resumes.

When execution reaches the last form in the obtain block, the
resume value is discarded. The execution context terminates, and
the most recent call to the resume function returns the value of
that last form.

.TP* Notes:

The
.code obtain
macro registers a finalizer against the returned resume function.
The finalizer invokes the function, passing it the symbol
.codn sys:cont-poison ,
thereby triggering unwinding in the most recently captured
continuation. Thus, abandoned
.code obtain
blocks are subject to unwinding when they become garbage.

The
.code yield-from
macro works by capturing a continuation and performing a nonlocal
exit to the nearest block called
.metn name .
It passes a special yield object to that block. The
.code obtain
macro generates code which knows what to do with this special yield
object.

.TP* Examples:

The following example shows a function which recursively
traverses a
.code cons
cell structure, yielding all the
.cod2 non- nil
atoms it encounters. Finally, it returns the object
.codn nil .
The function is invoked on a list,
and the invocation is wrapped in an
.code obtain
block to convert it to a generating function.

The generating function is then called six times
to retrieve the five atoms from the list,
and the final
.code nil
value. These are collected into a list.

This example demonstrates the power of delimited
continuations to suspend and resume a recursive
procedure.

.verb
  (defun yflatten (obj)
    (labels ((flatten-rec (obj)
               (cond
                 ((null obj))
                 ((atom obj) (yield-from yflatten obj))
                 (t (flatten-rec (car obj))
                    (flatten-rec (cdr obj))))))
      (flatten-rec obj)
      nil))

  (let ((f (obtain (yflatten '(a (b (c . d)) e)))))
    (list [f] [f] [f] [f] [f] [f]))
  --> (a b c d e nil)
.brev

The following interactive session log exemplifies two-way communication between
the main code and a suspending function.

Here,
.code mappend
is invoked on a list of symbols representing fruit and vegetable names.
The objective is to return a list containing only fruits.
The
.code lambda
function suspends execution and yields a question out of the
.code map
block. It then classifies
the item as a fruit or not according to the reply it receives. The reply
emerges as a the result value of the
.code yield-from
call.

The
.code obtain
macro converts the block to a generating function. The first call to the
function is made with no argument, because the argument would be ignored
anyway. The function returns a question, asking whether the first item
in the list, the potato, is a fruit.
To answer negatively, the user calls the function again, passing in
.codn nil .
The function returns the next question, which is answered in the
same manner.

When the question for the last item is answered, the function
call yields the final item: the ordinary result of the block, which is the list
of fruit names.

.verb
  1> (obtain
       (block map
         (mappend (lambda (item)
                    (if (yield-from map `is @item a fruit?`)
                      (list item)))
                  '(potato apple banana lettuce orange carrot))))
  #<interpreted fun: lambda (: reply)>
  2> (call *1)
  "is potato a fruit?"
  3> (call *1 nil)
  "is apple a fruit?"
  4> (call *1 t)
  "is banana a fruit?"
  5> (call *1 t)
  "is lettuce a fruit?"
  6> (call *1 nil)
  "is orange a fruit?"
  7> (call *1 t)
  "is carrot a fruit?"
  8> (call *1 nil)
  (apple banana orange)
.brev

The following example demonstrates an accumulator. Values passed to the
resume function are added to a counter which is initially zero.
Each call to the function returns the updated value of the accumulator.
Note the use of
.code "(yield-from acc)"
with no arguments to receive the value passed to the first
call to the resume function, without yielding an item.
The first return value
.code 1
is produced by the
.code "(yield-from acc sum)"
form, not by
.codn "(yield-from acc)" .
The latter only obtains the initial value
.code 1
and uses it to establish the seed value of the accumulator. Without causing
the resume function to terminate and return, control passes into the loop,
which yields the first item, causing the resume function call
.code "(call *1 1)"
to return
.codn 1 :

.verb
  1> (obtain
       (block acc
         (let ((sum (yield-from acc)))
            (while t (inc sum (yield-from acc sum))))))
  #<interpreted fun: lambda (: resume-val)>
  2> (call *1 1)
  1
  3> (call *1 2)
  3
  4> (call *1 3)
  6
  5> (call *1 4)
  10
.brev

.coNP Macro @ obtain-block
.synb
.mets (obtain-block < name << forms *)
.syne
.desc
The
.code obtain-block
macro combines
.code block
and
.code obtain
into a single expression.
The
.metn form -s
are evaluated in a block named
.codn name .

That is to say, the following equivalence holds:

.verb
  (obtain-block n f ...)  <-->  (obtain (block n f ...))
.brev

.coNP Macro @ yield
.synb
.mets (yield <> [ form ])
.syne
.desc
The
.code yield
macro is to
.code yield-from
as
.code return
is to
.codn return-from :
it yields from an anonymous block.

It is equivalent to calling
.code yield-from
using
.code nil
as the block name.

In other words, the following equivalence holds:

.verb
  (yield x)  <-->  (yield-from nil x)
.brev

.TP* Example:

.verb
  ;; Yield the integers 0 to 4 from a for loop, taking
  ;; advantage of its implicit anonymous block:

  (defvarl f (obtain (for ((i 0)) ((< i 5)) ((inc i))
                       (yield i))))

  [f] -> 0
  [f] -> 1
  [f] -> 2
  [f] -> 3
  [f] -> 4
  [f] -> nil
  [f] -> nil
.brev

.coNP Macros @ obtain* and @ obtain*-block
.synb
.mets (obtain* << forms *)
.mets (obtain*-block < name << forms *)
.syne
.desc
The
.code obtain*
and
.code obtain*-block
macros implement a useful variation of
.code obtain
and
.codn obtain-block .

The
.code obtain*
macro differs from
.code obtain
in exactly one regard: prior to returning the function, it invokes
it one time, with the argument value
.codn nil .

Thus, the following equivalence holds

.verb
  (obtain* forms ...)   <-->  (let ((f (obtain forms ...)))
                                (call f)
                                f)
.brev

In other words, the suspended block is immediately resumed, so that it executes
either to completion (in which case its value is discarded), or to its first
.code yield
or
.code yield-from
call (in which case the yielded value is discarded).

Note: the
.code obtain*
macro is useful in creating suspensions which accept data rather than
produce data.

The
.code obtain*-block
macro combines
.code obtain*
and
.code block
in the same manner that
.code obtain-block
combines
.code obtain
and
.codn block .

.TP* Example:

.verb
  ;; Pass three values into suspended block,
  ;; which get accumulated into list.
  (let ((f (obtain*-block nil
             (list (yield nil) (yield nil) (yield nil)))))
    (call f 1)
    (call f 2)
    (call f 3))  ->  (1 2 3)

  ;; Under obtain, extra call is required:
  (let ((f (obtain-block nil
             (list (yield nil) (yield nil) (yield nil)))))
    (call f nil)  ;; execute block to first yield
    (call f 1)    ;; resume first yield with 1
    (call f 2)
    (call f 3))  ->  (1 2 3)
.brev

.coNP Macro @ suspend
.synb
.mets (suspend < block-name < var-name << body-form *)
.syne
.desc
The
.code suspend
operator captures a continuation up to the prompt given by the
symbol
.meta block-name
and binds it to the variable name given by
.metn var-name ,
which must be a symbol suitable for binding variables with
.codn let .

Each
.meta body-form
is then evaluated in the scope of the variable
.metn var-name .

When the last
.meta body-form
is evaluated, a non-local exit takes place to the block
named by
.meta block-name
(using the
.code sys:abscond-from
operator, so that unwinding isn't performed).

When the continuation bound to
.meta var-name
is invoked, a copy of the entire block
.meta block-name
is re-started, and in that copy, the
.code suspend
call appears to return normally, yielding the value which had been
passed to the continuation.

.TP* Example

Define John McCarthy's
.code amb
function using
.code block
and
.codn suspend :

.verb
  (defmacro amb-scope (. forms)
    ^(block amb-scope ,*forms))

  (defun amb (. args)
    (suspend amb-scope cont
      (each ((a args))
        (when (and a (call cont a))
          (return-from amb a)))))
.brev

Use
.code amb
to bind the of
.code x
and
.code y
which satisfy the predicate
.mono
.meti (eql (* x y) 8)
.onom
non-deterministically:

.verb
  (amb-scope
    (let ((x (amb 1 2 3))
          (y (amb 4 5 6)))
      (amb (eql (* x y) 8))
      (list x y)))
  -> (2 4)
.brev

.coNP Macros @ hlet and @ hlet*
.synb
.mets (hlet >> ({ sym | >> ( sym << init-form )}*) << body-form *)
.mets (hlet* >> ({ sym | >> ( sym << init-form )}*) << body-form *)
.syne
.desc
The
.code hlet
and
.code hlet*
macros behave exactly like
.code let
and
.codn let* ,
respectively except that they guarantee that the variable bindings are
allocated in storage which isn't captured by delimited continuations.

The
.code h
in the names stands for "heap", serving as a mnemonic based on the
implementation concept of these bindings being "heap-allocated".

.SS* Regular Expression Library

\*(TX provides a "pure" regular expression implementation based on automata
theory, which equates regular expressions, finite automata and sets of strings.
A regular expression determines whether or not a string of input characters
belongs to a set. \*(TX regular expressions do not support features such
as as "anchoring" a match to the start or end of a string, or capture of
parenthesized sub-expression matches into registers. Parenthesis syntax
denotes only grouping, with no additional meaning.

The semantics of whether a regular expression is used for a substring
search, prefix match, suffix match, string splitting and so forth comes from
the functions which use regular expressions to perform these operations.

.NP* Regular Expressions as Functions
.synb
.mets >> [ regex >> [ start <> [ from-end ]] < string ]
.syne
.desc
A regular expression is callable as a function in \*(TL.
When used this way, it requires a string argument. It searches
the string for the leftmost match for itself, and returns
the matching substring, which could be empty. If no match is
found, it returns
.codn nil .

A regex takes one, two, or three arguments. The required
.meta string
is always the rightmost argument. This allows for convenient
partial application of the optional arguments using
macros in the
.code op
family, and macros in which the
.code op
syntax is implicit.

The optional arguments
.meta start
and
.meta from-end
are treated exactly as their like-named counterparts in the
.code search-regst
function.

.TP* Example:
Keep those elements from a list of strings which match
the regular expression
.codn #/a.*b/ :

.verb
  (keep-if #/a.*b/ '#"abracadabra zebra hat adlib adobe deer")
  --> ("abracadabra" "adlib" "adobe")
.brev

.coNP Functions @, search-regex @ range-regex and @ search-regst
.synb
.mets (search-regex < string < regex >> [ start <> [ from-end ]])
.mets (range-regex < string < regex >> [ start <> [ from-end ]])
.mets (search-regst < string < regex >> [ start <> [ from-end ]])
.syne
.desc
The
.code search-regex
function searches through
.meta string
starting
at position
.meta start
for a match for
.metn regex .

If
.meta start
is omitted, the search starts at position 0. If
.meta from-end
is specified and has a
.cod2 non- nil
value, the search
proceeds in reverse, from the position just beyond the last character of
.metn string ,
toward
.metn start .

if
.meta start
exceeds the length of the string, then
.code search-regex
returns
.codn nil .

If
.meta start
is negative then it indicates positions from the end of the string,
such that -1 is the last character, -2 the second last and so forth.
If the value is so negative that it refers beyond the start of
the string, then the starting position is deemed to be zero.

If
.meta start
is equal to the length of
.metn string ,
and thus refers to the position one character past its
length, then a match occurs at that position if
.meta regex
admits such a match.

The
.code search-regex
function returns
.code nil
if no match is found, otherwise it returns
a cons, whose
.code car
indicates the position of the match, and whose
.code cdr
indicates the length of the match.

If
.meta regex
is capable of matching empty strings, and no other kind of match
is found within
.metn string ,
then search regex reports a zero length match. If
.meta from-end
is false, then this match is reported at
.metn start ,
otherwise it is reported at the position one character beyond
the end of the string.

The
.code range-regex
function is similar to
.codn search-regex ,
except that when
a match is found, it returns a position range, rather than a position
and length. A range object is returned whose
.code from
field indicates the position
of the match, and whose
.code to
indicates the position one element past the
last character of the match. If the match is empty, the two integers
are equal.

Also see the
.code rr
function, which provides an alternative argument syntax for
the semantics of
.codn range-regex .

The
.code search-regst
differs from
.code search-regex
in the representation of the return value in the matching case.
Rather than returning the position and length of the match,
it returns the matching substring of
.metn string .

.coNP Functions @ match-regex and @ match-regst
.synb
.mets (match-regex < string < regex <> [ position ])
.mets (match-regst < string < regex <> [ position ])
.syne
.desc
The
.code match-regex
function tests whether
.meta regex
matches at
.meta position
in
.metn string .

If
.meta position
is not specified, it is taken to be zero. Negative values
of
.meta position
index from the right end of the string such that -1
refers to the last character. Excessively negative
values which index before the first character cause
.code nil
to be returned.

If the regex matches, then the length of the match is returned.
If it does not match, then
.code nil
is returned.

The
.code match-regst
differs from
.code match-regex
in the representation of the return value in the matching case.
Rather than returning the length of the match, it returns
matching substring of
.metn string .

.coNP Functions @ match-regex-right and @ match-regst-right
.synb
.mets (match-regex-right < string < regex <> [ end-position ])
.mets (match-regst-right < string < regex <> [ end-position ])
.syne
.desc
The
.code match-regex-right
function tests whether some substring of
.meta string
which terminates at the character position just before
.meta end-position
matches
.metn regex .

If
.meta end-position
is not specified, it defaults to the length of the string, and the function
performs a right-anchored regex match.

The
.meta end-position
argument can be a negative integer, in which case it denotes
positions from the end of the string, such that -1 refers
to the last character. If the value is excessively negative such
that the position immediately before it is before the start
of the string, then
.code nil
is returned.

If
.meta end-position
is a positive value beyond the length of
.metn string ,
then, likewise,
.code nil
is returned.

If a match is found, then the length of the match is returned.

A more precise way of articulating the role of
.meta end-position
is that for the purposes of matching,
.code string
is considered to terminate just before
.metn end-position :
in other words, that
.meta end-position
is the length of the string. The match is then anchored to the
end of this effective string.

The
.code match-regst-right
differs from
.code match-regst-right
in the representation of the return value in the matching case.
Rather than returning the length of the match, it returns
the matching substring of
.metn string .

.TP* Examples:

.verb
  ;; Return matching portion rather than length thereof.

  (defun match-regex-right-substring (str reg : end-pos)
    (set end-pos (or end-pos (length str)))
    (let ((len (match-regex-right str reg end-pos)))
      (if len
        [str (- end-pos len)..end-pos]
        nil)))

  (match-regex-right-substring "abc" #/c/) -> ""

  (match-regex-right-substring "acc" #/c*/) -> "cc"

  ;; Regex matches starting at multiple positions, but all
  ;; the matches extend past the limit.
  (match-regex-right-substring "acc" #/c*/ 2) -> nil

  ;; If the above behavior is not wanted, then
  ;; we can extract the string up to the limiting
  ;; position and do the match on that.
  (match-regex-right-substring ["acc" 0..2] #/c*/) -> "c"

  ;; Equivalent of above call
  (match-regex-right-substring "ac" #/c*/) -> "c"
.brev

.coNP Function @ regex-prefix-match
.synb
.mets (regex-prefix-match < regex < string <> [ position ])
.syne
.desc
The
.code regex-prefix-match
determines whether the input string might
might be the prefix of a string which matches regular expression
.metn regex .

The result is true if the input string matches
.meta regex
exactly. However, it is also true in situations in which
the input string doesn't match
.metn regex ,
yet can be extended with one or more additional characters beyond the end such
that the extended string
.B does
match.

The
.meta string
argument must be a character string. The function takes the input string to be
the suffix of
.meta string
which starts at the character position indicated by the
.meta position
argument. If that argument is omitted, then
.meta string
is taken as the input in its entirety. Negative values index backwards from
the end of
.meta string
according to the usual conventions elsewhere in the library.

Note: this function is not to be confused for the semantics
of a regex matching a prefix of a string: that capability is
provided by the functions
.codn match-regex ,
.codn m^ ,
.codn r^ ,
.code f^
and
.codn fr^ .

.TP* Examples:

.verb
  ;; The empty string is not a viable prefix match for
  ;; a regex that matches no strings at all:
  (regex-prefix-match #/~.*/ "") -> nil
  (regex-prefix-match #/[]/ "") -> nil

  ;; The empty string is a viable prefix of any regex
  ;; which matches at least one string:
  (regex-prefix-match #// "") -> t
  (regex-prefix-match #/abc/ "") -> t

  ;; This string doesn't match the regex because
  ;; it doesn't end in b, but is a viable prefix:
  (regex-prefix-match #/a*b/ "aa") -> t

  (regex-prefix-match #/a*b/ "ab") -> t

  (regex-prefix-match #/a*b/ "ac") -> nil

  (regex-prefix-match #/a*b/ "abc") -> nil
.brev

.coNP Function @ regsub
.synb
.mets (regsub >> { regex | << function } < replacement << string )
.syne
.desc
The
.code regsub
function operates in two modes, depending on whether
the first argument is a regular expression,
or function.

If the first argument is a regular expression it searches
.meta string
for multiple occurrences of non-overlapping matches for that
.metn regex .
A new string is constructed
similar to
.meta string
but in which each matching region is replaced
with using
.meta replacement
as follows.

The
.meta replacement
object may be a character or a string, in which
case it is simply taken to be the replacement for each match
of the regular expression.

The
.meta replacement
object may be a function of one argument, in
which case for every match which is found, this function is invoked,
with the matching piece of text as an argument. The function's
return value is then taken to be the replacement text.

If the first argument is a function, then it is called, with
.meta string
as its argument. The return value must be either a range
object (see the
.code rcons
function) which indicates the extent of
.meta string
to be replaced, or else
.code nil
which indicates that no replacement is to take place.

.TP* Examples:

.verb
  ;; match every lower case e or o, and replace by filtering
  ;; through the upcase-str function:

  [regsub #/[eo]/ upcase-str "Hello world!"] -> "HEllO wOrld!"

  ;; Replace Hello with Goodbye:
  (regsub #/Hello/ "Goodbye" "Hello world!") -> "Goodbye world!"

  ;; Left-anchored replacement with r^ function:
  (regsub (fr^ #/H/) "J" "Hello, hello!") -> "Jello, hello!"
.brev

.coNP Function @ regexp
.synb
.mets (regexp << obj )
.syne
.desc
The
.code regexp
function returns
.code t
if
.meta obj
is a compiled regular expression
object. For any other object type, it returns
.codn nil .

.coNP Functions @ trim-left and @ trim-right
.synb
.mets (trim-left >> { regex | << prefix } << string )
.mets (trim-right >> { regex | << suffix } << string )
.syne
.desc
The
.code trim-left
and
.code trim-right
functions return a new string, equivalent to
.meta string
with a leading or trailing portion removed.

If the first argument is a regular expression
.metn regex ,
then, respectively,
.code trim-left
and
.code trim-right
find a prefix or suffix of
.meta string
which matches the regular expression.
If there is no match, or if the match is empty, then
.meta string
is returned. Otherwise, a copy of
.meta string
is returned in which the matching characters are removed.
If
.meta regex
matches all of
.meta string
then the empty string is returned.

If the first argument is a character string, then it is treated
as if it were a regular expression match for that literal
sequence of characters. Thus,
.code trim-left
interprets that string as a
.meta prefix
to be removed, and
.code trim-right
as a
.metn suffix .
If
.meta string
starts with
.metn prefix ,
then
.code trim-left
returns a copy of
.meta string
with
.meta prefix
removed. Otherwise,
.meta string
is returned.
Likewise, if
.meta string
ends with
.metn suffix ,
then
.code trim-right
returns a copy of
.meta string
with
.meta suffix
removed. Otherwise,
.meta string
is returned.

.coNP Function @ regex-compile
.synb
.mets (regex-compile < form-or-string <> [ error-stream ])
.syne
.desc
The
.code regex-compile
function takes the source code of a regular expression,
expressed as a Lisp data structure representing an abstract syntax tree, or
else a regular expression specified as a character string, and compiles it to a
regular expression object.

If
.meta form-or-string
is a character string, it is parsed to an
abstract syntax tree first, if by the
.code regex-parse
function.
If the parse is successful (the result is not
.codn nil )
then
the resulting tree structure is compiled by a recursive call to
.codn regex-compile .

The optional
.meta error-stream
argument is passed down to
.code regex-parse
as well as in the recursive call to
.codn regex-compile ,
if that call takes place.

If
.meta error-stream
is specified, it must be a stream. Any error diagnostics are sent to that
stream.

.TP* Examples:

.verb
  ;; the equivalent of #/[a-zA-Z0-9_/
  (regex-compile '(set (#\ea . #\ez) (#\eA . #\eZ)
                       (#\e0 . #\e9) #\e_))

  ;; the equivalent of #/.*/ and #/.+/
  (regex-compile '(0+ wild))
  (regex-compile '(1+ wild))

  ;; #/a|b|c/
  (regex-compile '(or (or #\ea #\eb) #\ec))

  ;; string
  (regex-compile "a|b|c")
.brev

.coNP Function @ regex-source
.synb
.mets (regex-source << regex )
.syne
.desc
The
.code regex-source
function returns the source code of compiled regular expression
.metn regex .

The source code isn't the textual notation, but the Lisp
data structure representing the abstract syntax tree: the
same representation as what is returned by
.codn regex-parse .

.coNP Function @ regex-parse
.synb
.mets (regex-parse < string <> [ error-stream ])
.syne
.desc
The
.code regex-parse
function parses a character string which contains a regular expression and
turns it into a Lisp data structure (the abstract syntax tree representation of
the regular expression).

The regular expression syntax
.code #/RE/
produces the same structure, but as a
literal which is processed at the time \*(TX source code is read; the
.code regex-parse
function performs this parsing at run-time.

If there are parse errors, the function returns
.codn nil .

The optional
.meta error-stream
argument specifies a stream to which error messages
are sent from the parser. By default, diagnostic output goes to the
.code *stdnull*
stream, which discards it. If
.meta error-stream
is specified as
.codn t ,
then the diagnostic output goes to the
.code *stdout*
stream.

If
.code regex-parse
returns a
.cod2 non- nil
value, that structure is then something
which is suitable as input to
.codn regex-compile .

There is a small difference in the syntax accepted by
.code regex-parse
and the syntax of regular expression literals. Any
.code /
(slash) characters occurring in any position within
.meta string
are treated as ordinary characters, not as regular expression delimiters.
The call
.mono
(regex-parse "/a/")
.onom
matches three characters: a slash, followed by the letter "a", followed
by another slash. Note that the slashes are not escaped.

Note: if a
.code regex-parse
call is written using a string literal as the
.meta string
argument, then note that any backslashes which are to be processed
by the regular expression must be doubled up, otherwise they belong
to the string literal:

.verb
  (regex-parse "\e*")  ;; error, invalid string literal escape
  (regex-parse "\e\e*") ;; correct: the \e* literal match for *
.brev

The double backslash in the string literal produces a single backslash
in the resulting string object that is processed by
.codn regex-parse .

.coNP Function @ read-until-match
.synb
.mets (read-until-match < regex >> [ stream <> [ include-match ]])
.syne
.desc
The
.code read-until-match
function reads characters from
.metn stream ,
accumulating them into a string, which is returned.

If an argument is not specified for
.metn stream ,
then the
.code *stdin*
stream is used.

The
.meta include-match
argument is Boolean, indicating whether the delimiting text
matched by
.meta regex
is included in the returned string. It defaults to
.codn nil .

The accumulation of characters is terminated by a match on
.metn regex ,
the end of the stream, or an error.

This means that characters are read from the stream and accumulated while the
stream has more characters available, and while its prefix does not match
.metn regex .

If
.meta regex
matches the stream before any characters are accumulated,
then an empty string is returned.

If the stream ends or an non-exception-throwing error occurs before any
characters are accumulated, the function returns
.codn nil .

When the accumulation of characters terminates by a match on
.metn regex ,
the longest possible matching sequence of characters is
removed from the stream.  If
.meta include-match
is true, that matching text is included in
the returned string. Otherwise, it is discarded.
The next available character in the stream is the first
non-matching character following the matched text.
However, the next available character, as well as some number of
subsequent characters, may originate from the stream's push-back buffer,
rather than from the underlying operating system object,
due to this function's internal use of the
.code unget-char
function. Therefore, the stream position, as would be reported by
.codn seek-stream ,
is unspecified.

.coNP Functions @ scan-until-match and @ count-until-match
.synb
.mets (scan-until-match < regex <> [ stream ])
.mets (count-until-match < regex <> [ stream ])
.syne
.desc
The functions
.code scan-until-match
and
.code count-until-match
read characters from
.meta stream
until a match occurs in the stream for regular expression
.metn regex ,
the stream runs out of characters, or an error occurs.

If the stream runs out of characters, or a non-exception-throwing error
occurs, before a match for
.meta regex
is identified, these functions return
.codn nil .

If a match for
.meta regex
occurs in
.metn stream ,
then
.code count-until-match
returns the number of characters that were read and discarded prior to
encountering the first matching character.
In the same situation, the
.code scan-until-match
function returns a
.code cons
cell whose
.code car
holds the count of discarded characters, that being the same value as what
would be returned by
.codn count-until-match ,
and whose
.code cdr
holds a character string that comprises the text matched by
.metn regex .
The text matched by
.meta regex
is as long as possible, and is removed from the stream.
The next available character in the stream is the first
non-matching character following the matched text.
However, the next available character, as well as some number of
subsequent characters, may originate from the stream's push-back buffer,
rather than from the underlying operating system object,
due to these functions' internal use of the
.code unget-char
function. Therefore, the stream position, as would be reported by
.codn seek-stream ,
is unspecified.

.coNP Functions @, m^$ @ m^ and @ m$
.synb
.mets (m^$ < regex <> [ position ] << string )
.mets (m^ < regex <> [ position ] << string )
.mets (m$ < regex <> [ end-position ] << string )
.syne
.desc
These functions provide functionality similar to the
.meta match-regst
and
.meta match-regst-right
functions, but under alternative interfaces which are more
convenient.

The
.code ^
and
.code $
notation used in their names are an allusion to the
regular expression search anchoring operators found in
familiar POSIX utilities such as
.codn grep .

The
.meta position
argument, if omitted,
defaults to zero, so that the
entire
.meta string
is operated upon.

The
.meta end-position
argument defaults to the length of
.metn string ,
so that the end position coincides with the end of the
string.

If the
.meta position
or
.meta end-position
arguments are negative, they index backwards
from the length of
.meta string
so that -1 denotes the last character.

A value in either parameter which is excessively
negative or positive, such that it indexes before
the start of the string or exceeds its length
results in a failed match and consequently
.code nil
being returned.

The
.code m^$
function tests whether the entire portion of
.meta string
starting at
.meta position
through to the end of the string is in the set of strings
matched by
.metn regex .
If this is true, then that portion of the string is
returned. Otherwise
.code nil
is returned.

The
.code m^
function tests whether the portion of the
.meta string
starting at
.meta position
has a prefix which matches
.metn regex .
If so, then this matching prefix is returned.
Otherwise
.code nil
is returned.

The
.code m$
function tests whether the portion of
.meta string
ending just before
.meta end-position
has a suffix which matches
.metn regex .
If so, then this matching suffix is returned.
Otherwise
.code nil
is returned.

.coNP Functions @, r^$ @, r^ @ r$ and @ rr
.synb
.mets (r^$ < regex <> [ position ] << string )
.mets (r^ < regex <> [ position ] << string )
.mets (r$ < regex <> [ end-position ] << string )
.mets (rr < regex >> [ position <> [ from-end ]] << string )
.syne
.desc
The first three of these functions perform the same operations as,
respectively,
.codn m^$ ,
.code m^
and
.codn m$ ,
with the same argument conventions. They differ
in return value. When a match is found, they
return a range value indicating the extent of
the matching substring within
.meta string
rather than the matching substring itself.

The
.code rr
function performs the same operation as
.code range-regex
with different conventions with regard to argument
order, harmonizing with those of the other three functions above.

The
.meta position
argument, if omitted,
defaults to zero, so that the
entire
.meta string
is operated upon.

The
.meta end-position
argument defaults to the length of
.metn string ,
so that the end position coincides with the end of the
string.

With one exception, a value in either parameter which is excessively negative
or positive, such that it indexes before the start of the string or exceeds its
length results in a failed match and consequently
.code nil
being returned. The exception is that the
.code rr
function permits a negative
.meta position
value which refers before the start of the string; this is effectively
treated as zero.

The
.meta from-end
argument defaults to
.codn nil .

The
.code r^$
function tests whether the entire portion of
.meta string
starting at
.meta position
through to the end of the string is in the set of strings
matched by
.metn regex .
If this is true, then the matching range is returned,
as a range object.

The
.code r^
function tests whether the portion of the
.meta string
starting at
.meta position
has a prefix which matches
.metn regex .
If so, then the matching range is returned, as a range object.
Otherwise
.code nil
is returned.

The
.code r$
function tests whether the portion of
.meta string
ending just before
.meta end-position
has a suffix which matches
.metn regex .
If so, then the matching range is returned.
Otherwise
.code nil
is returned.

The
.code rr
function searches
.meta string
starting at
.meta position
for a match for
.codn regex .
If
.meta from-end
is specified and true, the rightmost
match is reported.
If a match is found, it is reported
as a range.

A regular expression which matches empty
strings matches at the start position,
and every other position, including
the position just after the last
character, coinciding with the length of
.metn string .

Except for the different argument order such that
.meta string
is always the rightmost argument, the
.code rr
function is equivalent to the
.code range-regex
function, such that correspondingly named
arguments have the same semantics.

.coNP Function @ rra
.synb
.mets (rra < regex >> [ start <> [ end ]] << string )
.syne
.desc
The
.code rra
function searches
.meta string
between the
.meta start
and
.meta end
position for matches for the regular expression
.metn regex .

The matches are returned as a list of range objects.

The
.meta start
argument defaults to zero, and
.meta end
defaults to the length of the string (the position one
past the last character).

Negative values of
.meta start
and
.meta end
indicate positions from the end of the string, such that -1
denotes the last character, -2 the second-to-last and so forth.

If
.meta start
is so negative that it refers before the start of
.metn string ,
it is treated as zero. If this situation is true of the
.meta end
argument, then the function returns
.codn nil .

If
.meta start
refers to a character position beyond the length of
.meta string
(two characters or more beyond the end of the string),
then the function returns
.codn nil .
If this situation is true of
.metn end ,
then
.meta end
is is curtailed to the the string length.

The
.code rra
function returns all non-overlapping matches, including
zero length matches. Zero length matches may occur before
the first character of the string, or after the last
character. If so, these are included.

.coNP Functions @, f^$ @ f^ and @ f$
.synb
.mets (f^$ < regex <> [ position ])
.mets (f^ < regex <> [ position ])
.mets (f$ < regex <> [ end-position ])
.syne
.desc
These regular expression functions do not directly
perform regex operations. Rather, they each return
a function of one argument which performs a regex
operation.

The returned functions perform the same operations as,
respectively,
.codn m^$ ,
.code m^
and
.codn m$ .

The following equivalences nearly hold, except that the functions
on the right side produced by
.code op
can accept two arguments when only
.code r
is curried, whereas the functions on the left take only
one argument:

.verb
  [f^$ r]    <-->  (op m^$ r)
  [f^$ r p]  <-->  (op m^$ r p)
  [f^ r]     <-->  (op m^ r)
  [f^ r p]   <-->  (op m^ r p)
  [f$ r]     <-->  (op m$ r)
  [f$ r p]   <-->  (op m$ r p)
.brev

That is to say,
.code f^$
returns a function which binds
.meta regex
and possibly the optional
.metn position .
When this function is invoked, it must be given an argument
which is a string. It performs the same operation as
.code m^$
being called on
.meta regex
and possibly
.metn position .
The same holds between
.code f^
and
.codn m^ ,
and between
.code f$
and
.codn m$ .

.TP* Examples:

.verb
  ;; produce list which contains only strings
  ;; beginning with "cat":
  (keep-if (f^ #/cat/) '#"dog catalog cat fox catapult")
  --> ("catalog" "cat" "catapult")

  ;; map all strings in a list to just their trailing
  ;; digits.
  (mapcar (f$ #/\ed*/) '#"a123 4 z bc465")
  --> ("123" "4" "" "465")

  ;; check that all strings consist of digits after
  ;; the third position.
  (all '#"ABC123 DFE45 12379" (f^$ #/\ed*/ 3))
  --> "79"  ; i.e. true
  (all '#"ABC123 DFE45 12379A" (f^$ #/\ed*/ 3))
  --> nil
.brev

.coNP Functions @, fr^$ @, fr^ @ fr$ and @ frr
.synb
.mets (fr^$ < regex <> [ position ])
.mets (fr^ < regex <> [ position ])
.mets (fr$ < regex <> [ end-position ])
.mets (frr < regex <> [[ start-position ] << from-end ])
.syne
.desc
These regular expression functions do not directly
perform regex operations. Rather, they each return
a function of one argument which performs a regex
operation.

The returned functions perform the same operations as,
respectively,
.codn r^$ ,
.codn r^ ,
.code r$
and
.codn rr .

The following equivalences nearly hold, except that some of the 
functions on the right side produced by op
.code op
can accept additional arguments after the input string,
whereas the functions on the left produced by
.code f^$
.I "et al."
accept only one parameter: the input string.

.verb
  [fr^$ r]     <-->  (op m^$ r)
  [fr^$ r p]   <-->  (op m^$ r p)
  [fr^ r]      <-->  (op m^ r)
  [fr^ r p]    <-->  (op m^ r p)
  [fr$ r]      <-->  (op m$ r)
  [fr$ r p]    <-->  (op m$ r p)
  [frr r]      <-->  (op m$ r)
  [frr r s]    <-->  (op m$ r s)
  [frr r s fe] <-->  (op m$ r s fe)
.brev

That is to say,
.code fr^$
returns a function which binds
.meta regex
and possibly the optional
.metn position .
When this function is invoked, it must be given an argument
which is a string. It performs the same operation as
.code r^$
being called on
.meta regex
and possibly
.metn position ,
and the string.
The same holds between
.code fr^
and
.codn r^ ,
between
.code fr$
and
.codn r$ ,
and between
.code frr
and
.codn rr .

.TP* Examples:

.verb
  ;; Remove leading digits from "123A456",
  ;; other than first digit:
  (regsub (fr^ #/\ed+/ 1) "" "123A456")
  --> "1A456"
.brev

.SS* Hashing Library

A hash table is an object which retains an association between pairs of
objects. Each pair consists of a key and value. Given an object which is
similar to a key in the hash table, it is possible to retrieve the
corresponding value. Entries in a hash table are not ordered in any way, and
lookup is facilitated by hashing: quickly mapping a key object to a numeric
value which is then used to index into one of many buckets where the matching
key will be found (if such a key is present in the hash table).

In addition to keys and values, a hash table contains a storage location
which allows it to be associated with user data.

Important to the operation of a hash table is the criterion by which keys are
considered same. By default, this similarity follows the eql function.  A hash
table will search for a stored key which is
.code eql
to the given search key.
A hash table constructed with the
.codn equal -based
property compares keys using
the
.code equal
function instead.

In addition to storing key-value pairs, a hash table can have a piece of
information associated with it, called the user data.

\*(TX hash tables contain a seed value which permutes the hashing operation,
at least for keys of certain types.  This feature, if the seed is randomized,
helps to prevent software from being susceptible to hash collision
denial-of-service attacks. However, by default, the seed is not randomized.
Newly created hash tables for which a seed value is not specified take their
seed value from the
.code *hash-seed*
special variable, which is initialized to zero. That includes hash tables
created by parsing hash literal syntax.
Security-sensitive programs
requiring protection against collision attacks may use
.code gen-hash-seed
to create a randomized hash seed, and, depending on their specific need, either
store that value in
.codn *hash-seed* ,
or pass the value to hash table constructors like
.codn make-hash ,
or both.
Note: randomization of hash seeding isn't a default behavior because it affects
program reproducibility. The seed value affects the order in which keys are
traversed, which can change the output of programs whose inputs have not
changed, and whose logic is is otherwise deterministic.

A hash table can be traversed to visit all of the keys and data.  The order of
traversal bears no relation to the order of insertion, or to any properties of
the key type.

During an open traversal, new keys can be inserted into a hash table or deleted
from it while a a traversal is in progress. Insertion of a new key during
traversal will not cause any existing key to be visited twice or to be skipped;
however, it is not specified whether the new key will be traversed. Similarly,
if a key is deleted during traversal, and that key has not yet been visited, it
is not specified whether it will be visited during the remainder of the
traversal. These remarks apply not only to deletion via
.code remhash
or the
.code del
operator, but also to wholesale deletion of all keys via
.codn clearhash .

The garbage collection of hash tables supports weak keys and weak values.
If a hash table has weak keys, this means that from the point of view
of garbage collection, that table holds only weak references to the keys
stored in it.  Similarly, if a hash table has weak values, it means that it
holds a weak reference to each value stored. A weak reference is one
which does not prevent the reclamation of an object by the garbage
collector. That is to say, when the garbage collector discovers that the only
references to some object are weak references, then that object is considered
garbage, just as if it had no references to it. The object is reclaimed, and
the weak references "lapse" in some way, which depends on what kind they are.
Hash table weak references lapse by entry removal.  When an object used
as a key in in one or more weak-key hash tables becomes unreachable, those hash
entries disappear. This happens even if the values are themselves reachable.
That is what it means that.
.IR "Vice versa" ,
when an object appearing as a value in
one or more hash table entries in weak-value hash tables becomes unreachable,
those entries disappear, even if the keys are reachable. When a hash table has
both weak keys and weak values, then its entries are removed when either keys
or values become unreachable.  In other words, both the key and value must be
reachable in order to retain the entry.

An open traversal of a hash table is performed by the
.code maphash
function and the
.code dohash
operator. The traversal is open because code supplied by the program
is evaluated for each entry.

The functions
.codn hash-keys ,
.codn hash-values ,
.codn hash-pairs ,
and
.code hash-alist
also perform an open traversal, because they return
lazy lists. The traversal isn't complete until the returned lazy list
is fully instantiated. In the meanwhile, the
\*(TX program can mutate the hash table from which the lazy list
is being generated.

Certain hash operations expose access to the internal key-value association
entries of a hash table, which are represented as ordinary
.code cons
cells. Modifying the
.code car
field of such a cell potentially violates the integrity of the hash table;
the behavior of subsequent lookup and insertion operations becomes unspecified.

Similarly, if an object is used as a key in an
.codn equal -based
hash table, and that object is mutated in such a way that its equality to
other objects under the
.code equal
function is affected or its hash value under
.code hash-equal
is altered, the behavior of subsequent lookup and insertion operations on the
becomes unspecified.

.coNP Functions @ make-hash and @ hash
.synb
.mets (make-hash < weak-keys < weak-vals
.mets \ \ \ \ \ \ \ \ \ \  < equal-based <> [ hash-seed ])
.mets (hash {:weak-keys | :weak-vals |
.mets \ \ \ \ \ \  :eql-based | :equal-based |
.mets \ \ \ \ \ \  :eq-based | :userdata << obj }*)
.syne
.desc
These functions construct a new hash table.

.code make-hash
takes three mandatory Boolean arguments. The
.meta weak-keys
argument specifies whether the hash table shall have weak keys. The
.meta weak-vals
argument specifies whether it shall have weak values, and
.meta equal-based
specifies whether it is
.codn equal -based.
The hash function defaults
all three of these properties to false, and allows them to be overridden to
true by the presence of keyword arguments.

The optional
.meta hash-seed
parameter must be an integer, if specified. Its value perturbs the hashing
function of the hash table, which affects
.code :equal-based
hash tables, when character strings and buffers are used as keys.
If
.meta hash-seed
is omitted, then the value of the
.code *hash-seed*
variable is used as the seed.

It is an error to attempt to construct an
.codn equal -based
hash table which has weak keys.

The
.code hash
function provides an alternative interface. It accepts optional
keyword arguments. The supported keyword symbols are:
.codn :weak-keys ,
.codn :weak-vals ,
.codn :equal-based ,
.code :eql-based
.code :eq-based
and
.code :userdata
which can be specified in any order to turn on the corresponding properties in
the newly constructed hash table.

Only one of
.codn :equal-based ,
.code :eql-based
and
.code :eq-based
may be specified. If specified, then the hash table uses
.codn equal ,
.code eql
or
.code eq
equality, respectively, for considering two keys to be the same key.
If none of these is specified, the
.code hash
function produces an
.code :equal-based
hash table by default.

If
.code :weak-keys
is specified, then
.code :equal-based
may not be specified.

If
.code :userdata
is present, it must be followed by an argument value; that value
specifies the user data for the hash table, which can be retrieved using the
.code hash-userdata
function.

Note: there doesn't exist a keyword for specifying the seed.
This omission is deliberate. These hash construction keywords may appear in the
hash literal
.code #H
syntax. A seed keyword would allow literals to specify their own seed, which
would allow malicious hash literals to be crafted that perpetrate a hash
collision attack against the parser.

.coNP Functions @, hash-construct @ hash-from-pairs and @ hash-from-alist
.synb
.mets (hash-construct < hash-args << key-val-pairs )
.mets (hash-from-pairs < key-val-pairs << hash-arg *)
.mets (hash-from-alist < alist << hash-arg *)
.syne
.desc
The
.code hash-construct
function constructs a populated hash in one step. The
.meta hash-args
argument specifies a list suitable as an argument list in a call to the hash
function.  The
.meta key-val-pairs
is a sequence of pairs, which are two-element
lists representing key-value pairs.

A hash is constructed as if by a call to
.mono
.meti (apply hash << hash-args ),
.onom
then populated
with the specified pairs, and returned.

The
.code hash-from-pairs
function is an alternative interface to the same semantics. The
.meta key-val-pairs
argument is first, and the
.meta hash-args
are passed as trailing variadic arguments, rather than a single list argument.

The
.code hash-from-alist
function is similar to
.codn hash-from-pairs ,
except that the
.meta alist
argument specifies they keys and values as an association list.
The elements of the list are
.code cons
cells, each of whose
.code car
is a key, and whose
.code cdr
is the value.

.coNP Function @ hash-list
.synb
.mets (hash-list < key-list << hash-arg *)
.syne
.desc
The
.code hash-list
function constructs a hash as if by a call to
.mono
.meti [apply hash << hash-args ],
.onom
where
.meta hash-args
is a list of the individual
.meta hash-arg
variadic arguments.

The hash is then populated with keys taken from
.meta key-list
and returned.

The value associated with each key is that key itself.

.coNP Function @ hash-zip
.synb
.mets (hash-zip < key-seq < value-seq << hash-arg *)
.syne
.desc
The
.code hash-zip
function constructs a hash as if by a call to
.mono
.meti (apply hash << hash-args ),
.onom
where
.meta hash-args
is a list of the individual
.meta hash-arg
variadic arguments.

The hash is then populated with keys taken from
.meta key-seq
which are paired with values taken from from
.metn value-seq ,
and returned.

If
.meta key-seq
is longer than
.metn value-seq ,
then the excess keys are ignored, and
.IR "vice versa" .

.coNP Function @ hash-update
.synb
.mets (hash-update < hash << function )
.syne
.desc
The
.code hash-update
function replaces each value in
.metn hash ,
with the value of
.meta function
applied to that value.

The return value is
.metn hash .

.coNP Function @ hash-update-1
.synb
.mets (hash-update-1 < hash < key < function <> [ init ])
.syne
.desc
The
.code hash-update-1
function operates on a single entry in the hash table.

If
.meta key
exists in the hash table, then its corresponding value is passed
into
.metn function ,
and the return value of
.meta function
is then installed
in place of the key's value. The value is then returned.

If
.meta key
does not exist in the hash table, and no
.meta init
argument is given,
then
.code hash-update-1
does nothing and returns
.codn nil .

If
.meta key
does not exist in the hash table, and an
.meta init
argument is given,
then
.meta function
is applied to
.metn init ,
and then
.meta key
is inserted into
.meta hash
with the value returned by
.meta function
as the datum. This value
is also returned.

.coNP Function @ group-by
.synb
.mets (group-by < func < sequence << option *)
.syne
.desc
The
.code group-by
function produces a hash table from
.metn sequence ,
which is a
list or vector. Entries of the hash table are not elements of
.metn sequence ,
but lists of elements of
.metn sequence .
The function
.meta func
is applied to
each element of
.meta sequence
to compute a key. That key is used to determine
which list the item is added to in the hash table.

The trailing arguments
.mono
.meti << option *
.onom
if any, consist of the same keywords
that are understood by the hash function, and determine the properties
of the hash.

.TP* Example:
Group the integers from 0 to 10 into three buckets keyed on 0, 1 and 2
according to the modulo 3 congruence:

.verb
  (group-by (op mod @1 3) (range 0 10)))

  -> #H(() (0 (0 3 6 9)) (1 (1 4 7 10)) (2 (2 5 8)))
.brev

.coNP Function @ group-reduce
.synb
.mets (group-reduce < hash < classify-fun < binary-fun < seq
.mets \ \  >> [ init-value <> [ filter-fun ]])
.syne
.desc
The
.code group-reduce
updates hash table
.meta hash
by grouping and reducing sequence
.metn seq .

The function regards the hash table as being populated with
keys denoting accumulator values. Missing accumulators which
need to be created in the hash table are initialized with
.meta init-value
which defaults to
.codn nil .

The function iterates over
.meta seq
and treats each element according to the following steps:
.RS
.IP 1.
Each element is mapped to a hash key through
.metn classify-fun .
.IP 2.
The value associated with the hash key (the accumulator for that
key) is retrieved. If it doesn't exist,
.meta init-value
is used.
.IP 3.
The function
.meta binary-fun
is invoked with two arguments: the accumulator from step 2, and the
original element from
.metn seq .
.IP 4.
The resulting value from step 3 is stored back into the hash table under the
key from step 2.
.RE

.IP
After the above processing, one more step is performed if the
.meta filter-fun
argument is present. In this case, the hash table is destructively mapped through
.meta filter-fun
before being returned. That is to say, every value in the hash table is
projected through
.meta filter-fun
and stored back in the table under the same key, as if by an invocation the
.mono
.meti (hash-update < hash << filter-fun )
.onom
expression.

.IP
If
.code group-reduce
is invoked on an empty hash table, its net result closely resembles a
.code group-by
operation followed by separately performing a
.code reduce-left
on each value in the hash.

.TP* Examples:

Frequency histogram:

.verb
  [group-reduce (hash) identity (do inc @1)
    "fourscoreandsevenyearsago" 0]
  --> #H(() (#\ea 3) (#\ec 1) (#\ed 1) (#\ee 4) (#\ef 1)
        (#\eg 1) (#\en 2) (#\eo 3) (#\er 3) (#\es 3)
        (#\eu 1) (#\ev 1) (#\ey 1))
.brev

Separate the integers 1-10 into even and odd, and sum these groups:

.verb
  [group-reduce (hash) evenp + (range 1 10) 0]
  -> #H(() (t 30) (nil 25))
.brev

.coNP Functions @ make-similar-hash and @ copy-hash
.synb
.mets (make-similar-hash << hash )
.mets (copy-hash << hash )
.syne
.desc
The
.code make-similar-hash
and copy-hash functions create a new hash object based on
the existing
.meta hash
object.

.code make-similar-hash
produces an empty hash table which inherits all of the
attributes of
.metn hash .
It uses the same kind of key equality, the
same configuration of weak keys and values, and has the same user data (see
the
.code set-hash-userdata
function).

The
.code copy-hash
function is like
.codn make-similar-hash ,
except that instead of
producing an empty hash table, it produces one which has all the same elements
as
.metn hash :
it contains the same key and value objects.

.coNP Function @ inhash
.synb
.mets (inhash < hash < key <> [ init ])
.syne
.desc
The
.code inhash
function searches hash table
.meta hash
for
.metn key .
If
.meta key
is found, then it return the hash table's cons cell which
represents the association between
.meta hash
and
.metn key .
Otherwise, it returns
.codn nil .

If argument
.meta init
is specified, then the function will create
an entry for
.meta key
in
.meta hash
whose value is that of
.metn init .
The cons cell representing that association is returned.

Note: for as long as the
.meta key
continues to exist inside
.metn hash .
modifying the
.code car
field of the returned cons has ramifications for the logical integrity of
the hash; doing so results in unspecified behavior for subsequent
insertion and lookup operations.

Modifying the
.code cdr
field has the effect of updating the association with a new value.

.coNP Accessor @ gethash
.synb
.mets (gethash < hash < key <> [ alt ])
.mets (set (gethash < hash < key <> [ alt ]) << new-value )
.syne
.desc
The
.code gethash
function searches hash table
.meta hash
for key
.metn key .
If the
key is found then the associated value is returned. Otherwise, if
the
.meta alt
argument was specified, it is returned. If the
.meta alt
argument
was not specified,
.code nil
is returned.

A valid
.code gethash
form serves as a place. It denotes either an existing value in a hash
table or a value that would be created by the evaluation of the form.
The
.meta alt
argument is meaningful when
.code gethash
is used as a place, and, if present, is always evaluated whenever the place is
evaluated.
In place update operations, it provides the initial value, which defaults
to
.code nil
if the argument is not specified. For example
.code "(inc (gethash h k d))"
will increment the value stored under key
.code k
in hash table
.code h
by one. If the key does not exist in the hash table, then
the value
.code "(+ 1 d)"
is inserted into the table under that key.
The expression
.code d
is always evaluated, whether or not its value is needed.

If a
.code gethash
place is subject to a deletion, but doesn't exist, it is not an error.
The operation does nothing, and
.code nil
is considered the prior value of the place yielded
by the deletion.

.coNP Function @ sethash
.synb
.mets (sethash < hash < key << value )
.syne
.desc
The
.code sethash
function places a value into
.meta hash
table under the given
.metn key .
If a similar key already exists in the hash table, then that key's
value is replaced by
.metn value .
Otherwise, the
.meta key
and
.meta value
pair is
newly inserted into
.metn hash .

The
.code sethash
function returns the
.meta value
argument.

.coNP Function @ pushhash
.synb
.mets (pushhash < hash < key << element )
.syne
.desc
The
.code pushhash
function is useful when the values stored in a hash table
are lists.  If the given
.meta key
does not already exist in
.metn hash ,
then a list of
length one is made which contains
.metn element ,
and stored in
.meta hash
table under
.metn key .
If the
.meta key
already exists in the hash table, then the corresponding
value must be a list. The
.meta element
value is added to the front of that list,
and the extended list then becomes the new value under
.metn key .

The return value is Boolean. If true, indicates that the hash table entry was
newly created. If false, it indicates that the push took place on an existing
entry.

.coNP Function @ remhash
.synb
.mets (remhash < hash << key )
.syne
.desc
The
.code remhash
function searches
.meta hash
for a key similar to the
.metn key .
If that key is found, then that key and its corresponding value are
removed from the hash table.

If the key is found and removal takes place, then the associated value
is returned. Otherwise
.code nil
is returned.

.coNP Function @ clearhash
.synb
.mets (clearhash << hash )
.syne
.desc
The
.code clearhash
function removes all keys-value pairs from
.metn hash ,
causing it to be empty.

If
.meta hash
is already empty prior to the operation, then
.codn nil ,
is returned.

Otherwise an integer is returned indicating the number of entries
that were purged from
.metn hash .

.coNP Function @ hash-count
.synb
.mets (hash-count << hash )
.syne
.desc
The
.code hash-count
function returns an integer representing the number of
key-value pairs stored in
.metn hash .

.coNP Accessor @ hash-userdata
.synb
.mets (hash-userdata << hash )
.mets (set (hash-userdata << hash ) << new-value )
.syne
.desc
The
.code hash-userdata
function retrieves the user data object associated with
.metn hash .

A hash table can be created with user data using the
.code :userdata
keyword in a hash table literal or in a call to the
.code hash
function, directly, or via other hash-constructing functions which take the
hash construction keywords, such as
.codn group-by .
If a hash table is created without user data, its user
data is initialized to
.codn nil .

Because
.code hash-userdata
is an accessor, a
.code hash-userdata
form can be used as a place. Assigning a value to this place
causes the user data of
.meta hash
to be replaced with that value.

.coNP Function @ get-hash-userdata
.synb
.mets (get-hash-userdata << hash )
.syne
.desc
The
.code get-hash-userdata
function is a deprecated synonym for
.codn hash-userdata .

.coNP Function @ set-hash-userdata
.synb
.mets (set-hash-userdata < hash << object )
.syne
.desc
The
.code set-hash-userdata
replaces, with the
.metn object ,
the user data object
associated with
.metn hash .

.coNP Function @ hashp
.synb
.mets (hashp << object )
.syne
.desc
The
.code hashp
function returns
.code t
if the
.meta object
is a hash table,
otherwise it returns
.codn nil .

.coNP Function @ maphash
.synb
.mets (maphash < hash << binary-function )
.syne
.desc
The
.code maphash
function successively invokes
.meta binary-function
for each entry stored in
.metn hash .
Each entry's key and value are passed as arguments
to
.codn binary-function .

The function returns
.codn nil .

.coNP Function @ hash-revget
.synb
.mets (hash-revget < hash < value >> [ testfun <> [ keyfun ]])
.syne
.desc
The
.code hash-revget
function performs a reverse lookup on
.metn hash .

It searches through the entries stored in
.meta hash
for an entry whose value matches
.metn value .

If such an entry is found, that entry's key is returned.
Otherwise
.code nil
is returned.

If multiple matching entries exist, it is not specified which entry's
key is returned.

The
.meta keyfun
function is applied to each value in
.meta hash
and the resulting value is compared with
.metn value .
The default
.meta keyfun
is the
.code identity
function.

The comparison is performed using
.metn testfun .

The default
.meta testfun
is the
.code eql
function.

.coNP Function @ hash-invert
.synb
.mets (hash-invert < hash >> [ joinfun >> [ unitfun << hash-arg *]])
.syne
.desc
The
.code hash-invert
function calculates and returns an inversion of hash table
.metn hash .
The values in
.meta hash
become keys in the returned hash table. Conversely, the values
in the returned hash table are derived from the keys.

The optional
.meta joinfun
and
.meta unitfun
arguments must be functions, if they are given.
These functions determine the behavior of
.code hash-invert
with regard to duplicate values in
.meta hash
which turn into duplicate keys.
The
.meta joinfun
function must be callable with two arguments, and
.meta joinfun
must accept one argument.
If
.meta joinfun
is omitted, it defaults to the
.code identity*
function;
.meta unitfun
defaults to
.codn identity .

The
.code hash-invert
function constructs a hash table as if by a call to the
.code hash
function, passing the
.meta hash-arg
arguments which determine the properties of the newly created hash.

The new hash table is then populated by iterating over the key-value pairs of
.meta hash
and inserting them as follows:
The key from
.meta hash
is turned into a value
.meta v1
by invoking the
.meta unitfun
function on it, and taking the return value.
The value from
.meta hash
is used as a key to perform a lookup in the new hash table.
If no entry exists, then a new entry is created, whose value is
.metn v1 .
Otherwise if the entry already exists, then the value
.meta v0
of that entry is combined with
.meta v1
by calling the
.meta joinfun
on the arguments
.meta v0
and
.metn v1 .
The entry is updated with the resulting value.

The new hash table is then returned.

.TP* Examples:

.verb
  ;; Invert simple 1 to 1 table:

  (hash-invert #H(() (a 1) (b 2) (c 3)))
  --> #H(() (1 a) (2 b) (3 c))

  ;; Invert table such that the keys of duplicate values
  ;; are accumulated into lists:

  [hash-invert #H(() (1 a) (2 a) (3 c) (5 c) (7 d)) append list]
  --> #H(() (d (7)) (c (3 5)) (a (1 2)))

  ;; Invert table such that keys of duplicate values are summed:

  [hash-invert #H(() (1 a) (2 a) (3 c) (5 c) (7 d)) +]
  --> #H(() (d 7) (c 8) (a 3))
.brev

.coNP Functions @ hash-eql and @ hash-equal
.synb
.mets (hash-eql << object )
.mets (hash-equal < object <> [ hash-seed ])
.syne
.desc
These functions each compute an integer hash value from the internal
representation of
.metn object ,
which satisfies the following properties.
If two objects
.code A
and
.code B
are the same under the
.code eql
function, then
.code "(hash-eql A)"
and
.code "(hash-eql B)"
produce the same integer hash value.  Similarly,
if two objects
.code A
and
.code B
are the same under the
.code equal
function, then
.code "(hash-equal A)"
and
.code "(hash-equal B)"
each produce the same integer hash value.  In all other
circumstances, the hash values of two distinct objects are unrelated, and
may or may not be the same.

Object of struct type may support custom hashing by way of defining
an equality substitution via an
.code equal
method. See the Equality Substitution section under Structures.

The optional
.meta hash-seed
value perturbs the hashing function used by
.code hash-equal
for strings and buffer objects.  This seed value must be a non-negative integer
no wider than 32 bits: that is, in the range 0 to 4294967295.
If the value isn't specified, it defaults to zero.
Effectively, each possible value of the seed specifies a different hashing
function. If two objects
.code A
and
.code B
are the same under the
.code equal
function, then
.code "(hash-equal A S)"
and
.code "(hash-equal B S)"
each produce the same integer hash value for any valid seed value
.codn S .

.coNP Functions @, hash_keys @, hash_values @ hash_pairs and @ hash_alist
.synb
.mets (hash-keys << hash )
.mets (hash-values << hash )
.mets (hash-pairs << hash )
.mets (hash-alist << hash )
.syne
.desc
These functions retrieve the bulk key-value data of hash table
.meta hash
in various ways.
.code hash-keys
retrieves a list of the keys.
.code hash-values
retrieves a list of the values.
.code hash-pairs
retrieves a list of pairs,
which are two-element lists consisting of the key, followed by the value.
Finally,
.code hash-alist
retrieves the key-value pairs as a Lisp association list:
a list of cons cells whose
.code car
fields are keys, and whose
.code cdr
fields are the values. Note that
.code hash-alist
returns the actual entries from the hash table, which are
conses. Modifying the
.code cdr
fields of these conses constitutes modifying the hash values
in the original hash table. Modifying the
.code car
fields interferes with the integrity of the hash table,
resulting in unspecified behavior for subsequent hash insertion
and lookup operations.

These functions all retrieve the keys and values in the
same order. For example, if the keys are retrieved with
.codn hash-keys ,
and the values with
.codn hash-values ,
then the corresponding entries from
each list pairwise correspond to the pairs in
.metn hash .

The list returned by each of these functions is lazy, and hence constitutes
an open traversal of the hash table.

.coNP Operator @ dohash
.synb
.mets (dohash >> ( key-var < value-var < hash-form <> [ result-form ])
.mets \ \  << body-form *)
.syne
.desc
The
.code dohash
operator iterates over a hash table. The
.meta hash-form
expression must
evaluate to an object of hash table type. The
.meta key-var
and
.meta value-var
arguments must be symbols suitable for use as variable names.
Bindings are established for these variables over the scope of the
.metn body-form -s
and the optional
.metn result-form .

For each element in the hash table, the
.meta key-var
and
.meta value-var
variables are set to the key and value of that entry, respectively,
and each
.metn body-form ,
if there are any, is evaluated.

When all of the entries of the table are thus processed, the
.meta result-form
is evaluated, and its return value becomes the return value of the dohash form.
If there is no
.metn result-form ,
the return value is
.codn nil .

The
.meta result-form
and
.metn body-form -s
are in the scope of an implicit anonymous
block, which means that it is possible to terminate the execution of
dohash early using
.mono
.meti (return << value )
.onom
or
.codn (return) .

.coNP Functions @, hash-uni @, hash-diff @ hash-symdiff and @ hash-isec
.synb
.mets (hash-uni < hash1 < hash2  >> [ joinfun >> [ map1fun <> [ map2fun ]]])
.mets (hash-diff < hash1 << hash2 )
.mets (hash-symdiff < hash1 << hash2 )
.mets (hash-isec < hash1 < hash2 <> [ joinfun ])
.syne
.desc
These functions perform basic set operations on hash tables in a nondestructive
way, returning a new hash table without altering the inputs. The arguments
.meta hash1
and
.meta hash2
must be compatible hash tables.  This means that their keys
must use the same kind of equality.

The resulting hash table inherits attributes from
.metn hash1 ,
as if created by the
.code make-similar-hash
function. If
.meta hash1
has userdata, the resulting hash table
has the same userdata. If
.meta hash1
has weak keys, the resulting table has weak
keys, and so forth.

The
.code hash-uni
function performs a set union. The resulting hash contains all of
the keys from
.meta hash1
and all of the keys from
.metn hash2 ,
and their corresponding
values.  If a key occurs both in
.meta hash1
and
.metn hash2 ,
then it occurs only once
in the resulting hash. In this case, if the
.meta joinfun
argument is not given,
the value associated with this key is the one from
.metn hash1 .
If
.meta joinfun
is specified then it is called with two arguments: the respective
data items from
.meta hash1
and
.metn hash2 .
The return value of this function is used
as the value in the union hash.
If
.meta map1fun
is specified it must be a function that can be called with one
argument. All values from
.meta hash1
are projected through this function: the function is applied
to each value, and the function's return value is used
in place of the original value.
Similarly, if
.meta map2fun
is present, specifies a function through which values from
.meta hash2
are projected.

The
.code hash-diff
function performs a set difference. First, a copy of
.meta hash1
is made as if by the
.code copy-hash
function. Then from this copy, all keys which occur
in
.code hash2
are deleted.

The
.code hash-symdiff
function performs a symmetric difference. A new hash is returned which
contains all of the keys from
.meta hash1
that are not in
.meta hash2
and
.IR "vice versa" :
all of the keys from
.meta hash2
that are not in
.metn hash1 .
The keys carry their corresponding values from
.meta hash1
and
.metn hash2 ,
respectively.

The
.code hash-isec
function performs a set intersection. The resulting hash contains
only those keys which occur both in
.meta hash1
and
.metn hash2 .
If
.meta joinfun
is not
specified, the values selected for these common keys are those from
.metn hash1 .
If
.meta joinfun
is specified, then for each key which occurs in both
.meta hash1
and
.metn hash2 ,
it is called with two arguments: the respective data items. The return
value is then used as the data item in the intersection hash.

.coNP Functions @ hash-subset and @ hash-proper-subset
.synb
.mets (hash-subset < hash1 << hash2 )
.mets (hash-proper-subset < hash1 << hash2 )
.syne
.desc
The
.code hash-subset
function returns
.code t
if the keys in
.meta hash1
are a subset of the keys in
.metn hash2 .

The
.code hash-proper-subset
function returns
.code t
if the keys in
.meta hash1
are a proper subset of the keys in
.metn hash2 .
This means that
.meta hash2
has all the keys which are in
.meta hash1
and at least one which isn't.

Note: the return value may not be mathematically meaningful if
.meta hash1
and
.meta hash2
use different equality. In any case, the actual behavior
may be understood as follows. The implementation of
.code hash-subset
tests whether each of the keys in
.meta hash1
occurs in
.meta hash2
using their respective equalities.
The implementation of
.code hash-proper-subset
applies
.code hash-subset
first, as above. If that is true, and the two hashes have the same number of
elements, the result is falsified.

.coNP Functions @, hash-begin @, hash-reset @ hash-next and @ hash-peek
.synb
.mets (hash-begin << hash )
.mets (hash-reset < hash-iter << hash )
.mets (hash-next << hash-iter )
.mets (hash-peek << hash-iter )
.syne
.desc
The
.code hash-begin
function returns a an iterator object capable of retrieving the
entries in stored in
.meta hash
one by one.

The
.code hash-reset
function changes the state of an existing iterator, such that it
becomes prepared to retrieve the entries stored in the newly given
.metn hash ,
which may be the same one as the previously associated hash.
In addition,
.code hash-reset
may be given a
.meta hash
argument of
.codn nil ,
which dissociates it from its hash table.

The
.code hash-next
function's
.meta hash-iter
argument is a hash iterator returned by
.codn hash-begin .
If unvisited entries remain in
.metn hash ,
then
.code hash-next
returns the next one as a cons cell whose
.code car
holds the key and whose
.code cdr
holds the value. That entry is then considered visited by the iterator.
If no more entries remain to be visited,
.code hash-next
returns
.codn nil .
The
.code hash-next
function also returns
.code nil
if the iterator has been dissociated from a hash table by
.codn hash-reset .

The
.code hash-peek
function returns the same value that a subsequent call to
.code hash-next
will return for the same
.metn hash-iter ,
without changing the state of
.metn hash-iter .
That is to say, if a cell representing a hash entry is returned, that entry
remains unvisited by the iterator.

.coNP Macro @ with-hash-iter
.synb
.mets (with-hash-iter >> ( isym < hash-form >> [ ksym <> [ vsym ]])
.mets \ \  << body-form *)
.syne
.desc
The
.code with-hash-iter
macro evaluates
.metn body-form -s
in an environment in which a lexically scoped function is visible.

The function is named by
.meta isym
which must be a symbol suitable for naming functions with
.codn flet .

The
.meta hash-form
argument must be a form which evaluates to a hash table object.

Invocations of the function retrieve successive entries of the hash table
as cons cell pairs of keys and values. The function returns
.code nil
to indicate no more entries remain.

If either of the
.meta ksym
or
.meta vsym
arguments are present, they must be symbols suitable as variable names. They
are bound as variables visible to
.metn body-form -s,
initialized to the value
.codn nil .

If
.meta ksym
is specified, then whenever the function
.meta isym
macro is invoked and retrieves a hash table entry, the
.meta ksym
variable is set to the key. If the function returns
.code nil
then the value of
.meta ksym
is set to
.codn nil .

Similarly, if
.meta vsym
is specified, then the function stores the retrieved
hash value in that variable, or else sets the variable
to
.code nil
if there is no next value.

.coNP Special variable @ *hash-seed*
.desc
The
.code *hash-seed*
special variable is initialized with a value of zero. Whenever a new
hash table is explicitly or implicitly created, it takes its seed from
the value of the
.code *hash-seed*
variable in the current dynamic environment.

The only situation in which
.code *hash-seed*
is not used when creating a new hash table is when
.code make-hash
is called with an argument given for the optional
.meta hash-seed
argument.

Only
.codn equal -based
hash tables make use of their seed, and only for keys which are strings and
buffers.  The purpose of the seed is to scramble the hashing function, to make
a hash table resistant to a type of denial-of-service attack, whereby a
malicious input causes a hash table to be populated with a large number of keys
which all map to the same hash table chain, causing the performance to severely
degrade.

The value of
.code *hash-seed*
must be a non-negative integer, no wider than 32 bits.

.coNP Function @ gen-hash-seed
.synb
.mets (gen-hash-seed)
.syne
.desc
The
.code gen-hash-seed
function returns an integer value suitable for the
.code *hash-seed*
variable, or as the
.code hash-seed
argument of the
.code make-hash
and
.code hash-equal
functions.

The value is derived from the host environment, from information such
as the process ID and time of day.

.SS* Search Tree Library

\*(TL provides binary search trees, which are objects of type
.codn tree .
Trees have a printed notation denoted by the
.code #T
prefix. A tree may be constructed by invoking the
.code tree
function.

Binary search trees differ from hashes in that they maintain items in
order. They also differ from hashes in that they store only elements,
not key-value pairs. Every tree is associated with three
.IR "key abstraction functions" :
It has a
.I "key function"
which is applied to the elements to map each one to a key.
It also has a
.I "less function"
and
.I "equal function"
for comparing keys.

If these three functions are not specified, they respectively default to
.codn identity ,
.code less
and
.codn equal ,
which means that the tree uses its elements as keys directly, and
that they are compared using
.code less
and
.codn equal .
Note: these default functions work for simple elements such as character
strings or numbers, and also structures implementing
.IR "equality substitution" .

The elements are stored inside a tree using tree nodes, which are objects
of type
.codn tnode ,
whose printed notation is introduced by the
.code #N
prefix.

Several tree-related functions take
.code tnode
objects as arguments or return
.code tnode
objects.

.coNP Function @ tnode
.synb
.mets (tnode < key < left << right)
.syne
.desc
The
.code tnode
function allocates, initializes and returns a single tree node.
A tree node has three fields
.metn key ,
.meta left
and
.metn right ,
which are accessed using the functions
.codn key ,
.code left
and
.codn right .

.coNP Function @ tnodep
.synb
.mets (tnodep << value )
.syne
.desc
The
.code tnodep
function returns
.code t
if
.meta value
is a tree node. Otherwise, it returns
.codn nil .

.coNP Accessors @, key @ left and @ right
.synb
.mets (key << node )
.mets (left << node )
.mets (right << node )
.mets (set (car << object ) << new-value )
.mets (set (key << node ) << new-key )
.mets (set (left << node ) << new-left )
.mets (set (right << node ) << new-right )
.syne
.desc
The
.codn key ,
.code left
and
.code right
functions retrieve the corresponding fields of the
.meta node
object, which must be of type
.codn tnode .

Forms based on the
.codn key ,
.code left
and
.code right
symbol are defined as syntactic places.
Assigning a value
.code v
to
.code "(key n)"
using the
.code set
operator, as in
.codn "(set (key n) v)" ,
is equivalent to
.code "(set-key n v)"
except that the value of the expression is
.code v
rather than
.codn n .
Similar statements hold true for
.code left
and
.code right
in relation to
.code set-left
and
.codn set-right .

.coNP Functions @, set-key @ set-left and @ set-right
.synb
.mets (set-key < node << new-key )
.mets (set-left < node << new-left )
.mets (set-right < node << new-right )
.syne
.desc
The
.codn set-key ,
.code set-left
and
.code set-right
functions replace the corresponding fields of
.meta node
with new values.

The
.meta node
argument must be of type
.codn tnode .

These functions all return
.metn node .

.coNP Function @ copy-tnode
.synb
.mets (copy-tnode << node )
.syne
.desc
The
.code copy-tnode
function creates a new
.code tnode
objects, whose
.codn key ,
.code left
and
.code right
fields are copied from
.codn node .

.coNP Function @ tree
.synb
.mets (tree >> [ elems >> [ keyfun >> [ lessfun <> [ equalfun ]]]])
.syne
.desc
The
.code tree
function constructs and returns a new tree object. All arguments are optional.

The
.meta elems
argument specifies a sequence of the elements to be stored in the tree.
If the argument is absent or the sequence is empty, then an empty
tree is created.

The
.meta keyfun
argument specifies the function which is applied to every element
to produce a key. If omitted, the the tree object shall behave as if the
.code identity
function were used, taking the elements themselves to be keys.

The
.meta lessfun
argument specifies the function by which two keys are compared for
inequality. If omitted, the
.code less
function is used. A function used as
.meta lessfun
should take two arguments, produce a Boolean result, and have ordering
properties similar to the
.code less
function.

The
.meta equalfun
argument specifies the function by which two keys are compared for
equality. The default value is the
.code equal
function. A function used as
.meta equalfun
should take two arguments, produce a Boolean result, and have the
properties of an equivalence relation.

These three functions are collectively referred to as the tree's
.IR "key abstraction functions" .

.coNP Function @ treep
.synb
.mets (treep << value )
.syne
.desc
The
.code treep
function returns
.code t
if
.meta value
is a tree. Otherwise, it returns
.codn nil .

.coNP Function @ tree-insert-node
.synb
.mets (tree-insert-node < tree << node )
.syne
.desc
The
.code tree-insert-node
function inserts an existing
.meta node
object into a search tree.

The
.meta tree
object must be of type
.codn tree ,
and
.meta node
must be of type
.codn tnode .

The
.code key
field of the
.meta node
object holds the element that is being inserted. The actual search key
which is associated with this element is determined by applying
.metn tree 's
.meta keyfun
to the the
.metn node 's
.code key
value.

The
.meta node
object must not currently be inserted into any existing tree.
The values stored in the
.code left
and
.code right
fields of
.meta node
are overwritten as required by the semantics of the insertion operation.
Their original values are ignored.

If
.meta tree
already contains node with with a matching key, then
.meta node
replaces that node; that node is deleted from the tree.

The
.code tree-insert-node
function returns the
.meta node
argument.

.coNP Function @ tree-insert-node
.synb
.mets (tree-insert < tree << elem )
.syne
.desc
The
.code tree-insert
function inserts
.meta elem
into
.metn tree .

The
.meta tree
argument must be an object of type
.codn tree .

The
.meta elem
value may be of any type which is semantically compatible with
.metn tree 's
key abstraction functions.

The
.code tree-insert
function allocates a new
.code tnode
as if by invoking
.mono
.meti (tnode < elem nil nil)
.onom
function, and inserts that
.code tnode
as if by using the
.code tree-insert-node
function.

The
.code tree-insert
function returns the newly inserted
.code tnode
object.

.coNP Function @ tree-lookup-node
.synb
.mets (tree-lookup-node < tree << key )
.syne
.desc
The
.code tree-lookup-node
searches
.meta tree
for an element which matches
.metn key .

The
.meta tree
argument must be an object of type
.codn tree .

The
.meta key
argument may be a value of any type.

An element inside
.meta tree
matches
.meta key
if the tree's
.meta keyfun
applied to that element produces a key value which is equal to
.meta key
under the tree's
.meta equalfun
function.

If such an element is found, then
.code tree-lookup-node
returns the tree node which contains that element as its
.meta key
field.

If no such element is found, then
.code tree-lookup-node
returns
.codn nil .

.coNP Function @ tree-lookup
.synb
.mets (tree-lookup < tree << key )
.syne
.desc
The
.code tree-lookup
function finds an element inside
.meta tree
which matches the given
.metn key .

If the element is found, it is returned. Otherwise,
.code nil
is returned.

Note: the semantics of the
.code tree-lookup
function can be understood in terms of
.codn tree-lookup-node .
A possible implementation is this:

.verb
  (defun tree-lookup (tree key)
    (iflet ((node (tree-lookup-node tree key)))
      (key node)))
.brev

.coNP Function @ tree-delete-node
.synb
.mets (tree-delete-node < tree << key )
.syne
.desc
The
.code tree-delete-node
function searches
.meta tree
for an element which matches
.metn key .

The
.meta tree
argument must be an object of type
.codn tree .

The
.meta key
argument may be a value of any type which is semantically compatible with
.metn tree 's
key abstraction functions.

If the matching element is found, then its node is removed from
the tree, and returned.

Otherwise, if a matching element is not found, then
.code nil
is returned.

.coNP Function @ tree-delete
.synb
.mets (tree-delete < tree << key )
.syne
.desc
The
.code tree-delete
function tries to removes from
.meta tree
the element which matches
.metn key .

If successful, it returns that element, otherwise it returns
.codn nil .

Note: the semantics of the
.code tree-delete
function can be understood in terms of
.codn tree-delete-node .
A possible implementation is this:

.verb
  (defun tree-delete (tree key)
    (iflet ((node (tree-delete-node tree key)))
      (key node)))
.brev

.coNP Function @ tree-root
.synb
.mets (tree-root < tree )
.syne
.desc
The
.code tree-root
function returns the root node of
.metn tree ,
which must be a
.code tree
object.

If
.meta tree
is empty, then
.code nil
is returned.

.coNP Function @ tree-clear
.synb
.mets (tree-root < tree )
.syne
.desc
The
.code tree-clear
function deletes all elements from
.metn tree ,
which must be a
.code tree
object.

If
.meta tree
is already empty, then the function returns
.codn nil ,
otherwise it returns an integer which gives the count of the number
of deleted nodes.

.coNP Function @ copy-search-tree
.synb
.mets (copy-search-tree << tree )
.syne
.desc
The
.code copy-search-tree
returns a new tree object which is a copy of
.metn tree .

The
.meta tree
argument must be an object of type
.codn tree .

The returned object has the same key abstraction functions as
.meta tree
and contains the same elements.

The nodes held inside the new tree are freshly allocated,
but their key objects are shared with the original tree.

.coNP Function @ tree-begin
.synb
.mets (tree-begin < tree )
.syne
.desc
The
.code tree-begin
function returns a new object of type
.code tree-iter
which provides in-order traversal of the elements stored in the tree.

The
.meta tree
argument must be an object of type
.codn tree .

Note: the elements are traversed by applying the
.code tree-next
function to the
.code tree-iter
object.

.coNP Function @ tree-next
.synb
.mets (tree-next < iter )
.syne
.desc
The
.code tree-next
function returns the next node in sequence from the tree iterator
.metn iter ,
which must be an object of type
.codn tree-iter .
Note: the
.code tree-begin
function returns such a
.code tree-iter
object.

If there are no more nodes to be visited, the function returns
.codn nil .

If, during the traversal of a tree, nodes are inserted or deleted,
the behavior of
.code tree-next
on
.code tree-iter
object that were obtained prior to the insertion or deletion is
not specified. An attempt to complete the iteration may not successfully
visit all keys that should be visited.

.coNP Special variable @ *tree-fun-whitelist*
.desc
The
.code *tree-fun-whitelist*
variable holds a list of function names
that may be used in the
.code #T
tree literal syntax as the
.metn keyfun ,
.meta lessfun
or
.meta equalfun
operations of a tree. The initial value of this variable is a list which
holds at least the following three symbols:
.codn identity ,
.code less
and
.codn equal .

The application may change the value of this variable, or dynamically
bind it, in order to allow
.code #T
literals to be processed which specify functions other than these three.

.SS* Partial Evaluation and Combinators
.coNP Macros @ op and @ do
.synb
.mets (op << form +)
.mets (do < oper << form *)
.syne
.desc
Like the
.code lambda
operator, the
.code op
macro denotes an anonymous function.
Unlike
.codn lambda ,
the arguments of the function are implicit, or
optionally specified within the expression, rather than as a formal
parameter list which precedes a body.

The
.meta form
arguments of
.code op
are implicitly turned into a DWIM expression,
which means that argument evaluation follows Lisp-1 rules.  (See the
.code dwim
operator).

The argument forms of
.code op
are arbitrary expressions, within which special
conventions is permitted regarding the use of certain implicit variables:
.RS
.meIP >> @ num
A number preceded by a
.code @
is, syntactically, a metanumber. If it appears inside
.code op
as an expression, it behaves as a positional argument, whose
existence it implies. For instance
.code @2
means that the function shall have at least two arguments,
the second argument of which is be substituted in place of the
.codn @2 .
.code op
generates a function which has a number of required arguments equal to the
highest value of
.meta num
appearing in a
.mono
.meti >> @ num
.onom
construct in the body. For instance
.code "(op car @3)"
generates a three-argument function (which passes its third
argument to
.codn car ,
returning the result, and ignores its first two arguments).
There is no way to use
.code op
to generate functions which have optional arguments.  The positional
arguments are mutable; they may be assigned.
.meIP < @rest
If the meta-symbol
.meta @rest
appears in the
.code op
syntax as an expression, it explicitly denotes and evaluates to the list of
trailing arguments. Like the metanumber positional arguments, it
may be assigned.
.meIP < @rec
If the meta-symbol
.meta @rec
appears in the
.code op
syntax as an expression, it denotes a mutable variable which is bound to the
function itself which is generated by that
.code op
expression.
.meIP >> @( rec ...)
If this syntax appears inside
.codn op ,
it specifies a recursive call the function.
.RE

.IP
Functions generated by
.code op
are always variadic; they always take additional arguments after
any required ones, whether or not the
.meta @rest
syntax is used.

If the body does not contain
any
.meta @num
or
.meta @rest
syntax, then
.code @rest
is implicitly inserted.  What this means is that, for example, since
the form
.code "(op foo)"
does not contain any implicit positional arguments like
.codn @1 ,
and does not contain
.codn @rest ,
it is actually a shorthand for
.codn "(op foo . @rest)" :
a function which applies all of its arguments to
.codn foo .
If the body does contain at least one
.meta @num
or
.metn @rest ,
then
.meta @rest
isn't implicitly inserted. The notation
.code "(op foo @1)"
denotes a function which takes any number of arguments, and ignores
all but the first one, which is passed to
.codn foo .

The
.code do
operator is similar to
.code op
op, with the following three differences:
.RS
.IP 1.
The first argument of
.codn do ,
namely
.metn oper ,
is an operator. This argument is not processed for the presence of
implicit variables. Thus for instance
.code "(do @1 ...)"
is invalid. By contrast,
.code "(op @1 ...)"
is possible and make sense under the right circumstances.
The
.meta oper
argument may be the name of a macro or special operator, whereas
.code op
doesn't support the invocation of macros or special operators.
For instance
.code "(do let ((x @1)) (+ x 1))"
is possible.
.IP 2.
The
.meta form
arguments of
.code do
are not implicitly treated as DWIM expressions,
but as ordinary expressions.
.IP 3.
When
.code do
syntax doesn't contain any references to implicit variables (metanumbers or
.codn @rest )
then a variadic function is generated which requires one argument.
That argument is added to the form. Thus for instance
.code "(do set x)"
effectively serves as a shorthand for
.codn "(do set x @1)" .
The corresponding defaulting behavior in
.code op
is that a variadic function is generated which requires no arguments.
All of the available arguments are applied. Thus
.code "(op f x)"
is effectively a shorthand for
.codn "(op f x . @rest)" .
.RE
.IP
Because it accepts operators,
.code do
can be used with imperative constructs
which are not functions, like set: like set: for instance
.code "(do set x)"
produces an anonymous function which, if called with one argument, stores that
argument into
.codn x .

The actions of
.code op
and
.code do
be understood by these examples, which convey how the syntax is
is rewritten to lambda.  However, note that the real translator
uses generated symbols for the arguments, which are not equal to any
symbols in the program.

.verb
  (op) -> invalid

  (op +) -> (lambda rest [+ . rest])

  (op + foo) -> (lambda rest [+ foo . rest])

  (op @1 @2) -> (lambda (arg1 arg2 . rest) [arg1 arg2])

  (op @1 . @rest) -> (lambda (arg1 . rest) [arg1 . @rest])

  (op @1 @rest) -> (lambda (arg1 . rest) [arg1 @rest])

  (op @1 @2) -> (lambda (arg1 arg2 . rest) [arg1 arg2])

  (op foo @1 (@2) (bar @3)) -> (lambda (arg1 arg2 arg3 . rest)
                                  [foo arg1 (arg2) (bar arg3)])

  (op foo @rest @1) -> (lambda (arg1 . rest) [foo rest arg1])

  (do + foo) -> (lambda (arg1 . rest) (+ foo arg1))

  (do @1 @2) -> (lambda (arg1 arg2 . rest) (@1 arg2)) ;; invalid!

  (do foo @rest @1) -> (lambda (arg1 . rest) (foo rest arg1))
.brev

Note that if argument
.meta @n
appears in the syntax, it is not necessary
for arguments
.meta @1
through
.meta @n-1
to appear. The function will have
.code n
arguments:

.verb
  (op @3) -> (lambda (arg1 arg2 arg3 . rest) [arg3])
.brev

The
.code op
and
.code do
operators can be nested, in any combination. This raises the
question: if an expression like
.codn @1 ,
.code @rest
or
.code @rec
occurs in an
.code op
that is nested
within an
.codn op ,
what is the meaning?

An expression with a single
.code @
always belongs with the inner-most op or do
operator. So for instance
.code "(op (op @1))"
means that an
.code "(op @1)"
expression is nested
within an outer
.code op
expression that contains no references to its implicit variables.
The
.code @1
belongs to the inner op.

There is a way for an inner
.code op
to refer to the implicit variables of an outer one. This is
expressed by adding an extra
.code @
prefix for every level of escape. For example in
.code "(op (op @@1))"
the
.code @@1
belongs to the outer
.codn op :
it is the same as
.code @1
appearing in the outer
.codn op .
That is to say,
in the expression
.codn "(op @1 (op @@1))" ,
the
.code @1
and
.code @@1
are the same thing:
both are parameter 1 of the lambda function generated by the outer
.codn op .
By contrast, in the expression
.code "(op @1 (op @1))"
there are two different parameters:
the first
.code @1
is argument of the outer function, and the second
.code @1
is the first argument of the inner function. If there
are three levels of nesting, then three
.code @
meta-prefixes are needed to insert
a parameter from the outermost
.code op
into the innermost
.codn op .

Note that the implicit variables belonging to an
.code op
can be used in the dot position of a function call, such as:

.verb
  [(op list 1 . @1) 2] -> (1 . 2)
.brev

This is a consequence of the special transformations described
in the paragraph
.B "Dot Position in Function Calls"
in the subsection
.B "Additional Syntax"
of the
.BR "TXR Lisp"
section.

The
.code op
syntax works in conjunction with quasiliterals which are nested within it.
The metanumber notation as well as
.code @rest
are recognized without requiring an additional
.code @
escape, which is effectively optional:

.verb
  (apply (op list `@1-@rest`) '(1 2 3)) -> "1-2 3"

  (apply (op list `@@1-@@rest`) '(1 2 3)) -> "1-2 3"
.brev

Though they produce the same result, the above two examples differ in that
.code @rest
embeds a metasymbol into the quasiliteral structure, whereas
.code @@rest
embeds the Lisp expression
.code @rest
into the quasiliteral. Either way, in the scope of
.codn op ,
.code @rest
undergoes the macro-expansion which renames it to the machine-generated
function argument symbol of the implicit function denoted by the
.code op
macro form.

This convenient omission of the
.code @
character isn't supported for reaching the arguments of an outer
.code op
from a quasiliteral within a nested
.codn op :

.verb
  ;; To reach @@1, @@@1 must be written.
  ;; @@1 Lisp expression introduced by @.
  (op ... (op ... `@@@1`))
.brev

.TP* Examples:

.verb
  (let ((c 0))
    (mapcar (op cons (inc c)) '(a b c)))
  --> ((1 . a) (2 . b) (3 . c))

  (reduce-left (op + (* 10 @1) @2) '(1 2 3)) --> 123
.brev
.coNP Macro @ lop
.synb
.mets (lop << form +)
.syne
.desc
The
.code lop
macro is variant of
.code op
with special semantics.

The
.meta form
arguments support the same notation as those of the
.code op
operator.

If only one
.meta form
is given then
.code lop
is equivalent to
.codn op .

If two or more
.meta form
arguments are present, then
.code lop
generates a variadic function which inserts all of its trailing
arguments between the first and second
.metn form -s.

That is to say, trailing arguments coming into the anonymous function
become the left arguments of the function or function-like object
denoted by the first
.meta form
and the remaining
.metn form -s
give additional arguments. Hence the name
.codn lop ,
which stands for \(dqleft-inserting
.codn op \(dq.

This left insertion of the trailing arguments takes place regardless of whether
.code @rest
occurs in any
.metn form .

The
.meta form
syntax determines the number of required arguments of the
generated function, according to the highest-valued meta-number. The trailing
arguments which are inserted into the left position are any arguments in excess
of the required arguments.

The
.code lop
macro's expansion can be understood via the following equivalences,
except that in the real implementation, the symbols
.code rest
and
.code arg1
through
.code arg3
are replaced with hygienic, unique symbols.

.verb
  (lop f)  <-->  (op f)   <-->   (lambda (. rest) [f . rest])

  (lop f x y)  <-->  (lambda (. rest)
                       [apply f (append rest [list x y])])

  (lop f x @3 y)  <-->  (lambda (arg1 arg2 arg3 . rest)
                          [apply f
                                 (append rest
                                         [list x arg3 y])])
.brev

.TP* Examples:

.verb
  (mapcar (lop list 3) '(a b c)) --> ((a 3) (b 3) (c 3))

  (mapcar (lop list @1) '(a b c)) --> ((a) (b) (c))

  (mapcar (lop list @1) '(a b c) '(d e f))
  --> ((d a) (e b) (f c))

.brev

.coNP Macro @ ldo
.synb
.mets (ldo < oper << form *)
.syne
.desc
The
.code ldo
macro provides a shorthand notation for uses of the
.code do
macro which inserts the first argument of the anonymous function
as the leftmost argument of the specified operator.

The
.code ldo
syntax can be understood in terms of these equivalences:

.verb
  (ldo f)  <-->  (do f @1)
  (ldo f x)  <-->  (do f @1 x)
  (ldo f x y)  <-->  (do f @1 x y)
  (ldo f x @2 y)  <-->  (do f @1 x @2 y)
.brev

The implicit argument
.code @1
is always inserted as the leftmost argument of the operator
specified by the first form.

.TP* Example:

.verb
  ;; push elements of l1 onto l2.
  (let ((l1 '(a b c)) l2)
    (mapdo (ldo push l2) l1)
    l2)
  --> (c b a)
.brev

.coNP Macros @, ap @, ip @ ado and @ ido.
.synb
.mets (ap << form +)
.mets (ip << form +)
.mets (ado << form +)
.mets (ido << form +)
.syne
.desc
The
.code ap
macro is based on the
.code op
macro and has identical argument
conventions.

The
.code ap
macro analyzes its arguments and produces a function
.metn f ,
in exactly the same same way as the
.code op
macro.  However, instead of returning
.metn f ,
directly, it returns a different function
.metn g ,
which is a one-argument function  which accepts a list,
and then applies the list as arguments to
.metn f .

In other words, the following equivalence holds:

.verb
  (ap form ...) <--> (apf (op form ...))
.brev

The
.code ap
macro nests properly with
.code op
and
.codn do ,
in any combination, in regard to the
.meta ...@@n
notation.

The
.code ip
macro is similar to the
.code ap
macro, except that it is based
on the semantics of the function
.code iapply
rather than
.codn apply ,
according
to the following equivalence:

.verb
  (ip form ...) <--> (ipf (op form ...))
.brev

The
.code ado
and
.code ido
macros are related to do macro in the same way that
.code ap
and
.code ip
are related to
.codn op .
They produce a one-argument function which works
as if by applying its arguments to the function generated by do,
according to the following equivalence:

.verb
  (ado form ...) <--> (apf (do form ...))

  (ido form ...) <--> (ipf (do form ...))
.brev

See also: the
.code apf
and
.code ipf
functions.

.TP* Example:

.verb
  ;; Take a list of pairs and produce a list in which those pairs
  ;; are reversed.

  (mapcar (ap list @2 @1) '((1 2) (a b)))   ->   ((2 1) (b a))
.brev

.coNP Macros @ opip and @ oand
.synb
.mets (opip << clause *)
.mets (oand << clause *)
.syne
.desc
The
.code opip
and
.code oand
operators make it possible to chain together functions which are expressed
using the
.code op
syntax. (See the
.code op
operator for more information).

Both macros perform the same transformation except that
.code opip
translates its arguments to a call to the
.code chain
function, whereas
.code oand
translates its arguments in the same way to a call to the
.code chand
function.

More precisely, these macros perform the following rewrites:

.verb
  (opip arg1 arg2 ... argn) -> [chain {arg1} {arg2} ... {argn}]
  (oand arg1 arg2 ... argn) -> [chand {arg1} {arg2} ... {argn}]
.brev

where the above
.code {arg}
notation denotes the following transformation applied to each argument:

.verb
  (function ...) -> (op function ...)
  (operator ...) -> (do operator ...)
  (macro ...)    -> (do macro ...)
  (dwim ...)     -> (dwim ...)
  [...]          -> [...]
  (qref ...)     -> (qref ...)
  (uref ...)     -> (uref ...)
  .slot          -> .slot
  .(method ...)  -> .(method ...)
  atom           -> atom
.brev

In other words, compound forms whose leftmost symbol is a macro or operator
are translated to the
.code do
notation. Compound forms denoting function calls are translated to the
.code op
notation. Compound forms which are
.code dwim
invocations, either explicit or via the DWIM brackets notation, are
used without transformation. Used without transformation also are forms
denoting struct slot access, either explicitly using
.code uref
or
.code qref
or the respective dot notations, as well as any atom forms.

Note: the
.code opip
and
.code oand
macros use their macro environment in determining whether a form is a
macro call, thereby respecting lexical scoping.

.TP* Example:
Take each element from the list
.code "(1 2 3 4)"
and multiply it by three, then add 1.
If the result is odd, collect that into the resulting list:

.mono
(mappend (opip (* 3)
               (+ 1)
               [iff oddp list])
         (range 1 4))
.onom

The above is equivalent to:

.mono
(mappend (chain (op * 3)
                (op + 1)
                [iff oddp list])
         (range 1 4))
.onom

The
.code "(* 3)"
and
.code "(+ 1)"
terms are rewritten to
.code "(op * 3)"
and
.codn "(op + 1)" ,
respectively, whereas
.code "[iff oddp list]"
is passed through untransformed.

.coNP Macro @ ret
.synb
.mets (ret << form )
.syne
.desc
The
.code ret
macro's
.meta form
argument is treated similarly to the second and subsequent arguments of the
.code op
operator.

The
.code ret
macro produces a function which takes any number of arguments,
and returns the value specified by
.metn form .

.meta form
can contain
.code op
meta syntax like
.code @n
and
.codn @rest .

The following equivalence holds:

.verb
  (ret x) <--> (op identity x))
.brev

Thus the expression
.code "(ret @2)"
returns a function similar to
.codn "(lambda (x y . z) y)" ,
and the expression
.code "(ret 42)"
returns a function similar to
.codn "(lambda (. rest) 42)" .

.coNP Macro @ aret
.synb
.mets (aret << form )
.syne
.desc
The
.code aret
macro's
.meta form
argument is treated similarly to the second and subsequent arguments of the
.code op
operator.

The
.code aret
macro produces a function which takes any number of arguments,
and returns the value specified by
.metn form .

.meta form
can contain
.code ap
meta syntax like
.meta @n
and
.codn @rest .

The following equivalence holds:

.verb
  (aret x) <--> (ap identity x))
.brev

Thus the expression
.code "(aret @2)"
returns a function similar to
.codn "(lambda (. rest) (second rest))" ,
and the expression
.code "(aret 42)"
returns a function similar to
.codn "(lambda (. rest) 42)" .

.coNP Function @ dup
.synb
.mets (dup << func )
.syne
.desc
The
.code dup
function returns a one-argument function which calls the two-argument
function
.meta func
by duplicating its argument.

.TP* Example:

.verb
  ;; square the elements of a list
  (mapcar [dup *] '(1 2 3)) -> (1 4 9)
.brev

.coNP Function @ flipargs
.synb
.mets (flipargs << func )
.syne
.desc
The
.code flipargs
function returns a two-argument function which calls the two-argument
function
.meta func
with reversed arguments.

.coNP Functions @ chain and @ chand
.synb
.mets (chain << func *)
.mets (chand << func *)
.syne
.desc
The
.code chain
function accepts zero or more functions as arguments, and returns
a single function, called the chained function, which represents the chained
application of those functions, in left to right order.

If
.code chain
is given no arguments, then it returns a variadic function which
ignores all of its arguments and returns
.codn nil .

Otherwise, the first function may accept any number of arguments. The second
and subsequent functions, if any, must accept one argument.

The chained function can be called with an argument list which is acceptable
to the first function. Those arguments are in fact passed to the first
function. The return value of that call is then passed to the second
function, and the return value of that call is passed to the third function
and so on. The final return value is returned to the caller.

The
.code chand
function is similar, except that it combines the functionality of
.code andf
into chaining. The difference between
.code chain
and
.code chand
is that
.code chand
immediately terminates and returns
.code nil
whenever any of the functions returns
.codn nil ,
without calling the remaining functions.

.TP* Example:

.verb
  (call [chain + (op * 2)] 3 4) -> 14
.brev

In this example, a two-element chain is formed from the
.code +
function
and the function produced by
.code "(op * 2)"
which is a one-argument
function that returns the value of its argument multiplied by two.
(See the definition of the
.code op
operator).

The chained function is invoked using the
.code call
function, with the arguments
.code 3
and
.codn 4 .
The chained evaluation begins by passing
.code 3
and
.code 4
to
.codn + ,
which yields
.codn 7 .
This
.code 7
is then passed to the
.code "(op * 2)"
doubling function, resulting in
.codn 14 .

A way to write the above example without the use of the DWIM brackets and the
op operator is this:

.verb
  (call (chain (fun +) (lambda (x) (* 2 x))) 3 4)
.brev

.coNP Function @ juxt
.synb
.mets (juxt << func *)
.syne
.desc
The
.code juxt
function accepts a variable number of arguments which are functions.  It
combines these into a single function which, when invoked, passes its arguments
to each of these functions, and collects the results into a list.

Note: the juxt function can be understood in terms of the following reference
implementation:

.verb
  (defun juxt (funcs)
    (lambda (. args)
      (mapcar (lambda (fun)
                (apply fun args))
              funcs)))
.brev

The
.code callf
function generalizes
.code juxt
by allowing the combining function to be specified.

.TP* Example:

.verb
   ;; separate list (1 2 3 4 5 6) into lists of evens and odds,
   ;; which end up juxtaposed in the output list:

   [(op [juxt keep-if remove-if] evenp)
    '(1 2 3 4 5 6)] -> ((2 4 6) (1 3 5))

   ;; call several functions on 1, collecting their results:
   [[juxt (op + 1) (op - 1) evenp sin cos] 1]'
   -> (2 0 nil 0.841470984807897 0.54030230586814)
.brev

.coNP Functions @ andf and @ orf
.synb
.mets (andf << func *)
.mets (orf << func *)
.syne
.desc
The
.code andf
and
.code orf
functions are the functional equivalent of the
.code and
and
.code or
operators. These functions accept multiple functions and return a new function
which represents the logical combination of those functions.

The input functions should have the same arity. Failing that, there should
exist some common argument arity with which each of these can be invoked. The
resulting combined function is then callable with that many arguments.

The
.code andf
function returns a function which combines the input functions with
a short-circuiting logical conjunction. The resulting function passes its
arguments to the functions successively, in left to right order. As soon as any
of the functions returns
.codn nil ,
then nil is returned immediately, and the
remaining functions are not called.  Otherwise, if none of the functions return
.codn nil ,
then the value returned by the last function is returned. If the list of
functions is empty, then
.code t
is returned.  That is,
.code (andf)
returns a function
which accepts any arguments, and returns
.codn t .

The
.code orf
function combines the input functions with a short-circuiting logical
disjunction. The function produced by
.code orf
passes its arguments down to the
functions successively, in left to right order.  As soon as any function
returns a
.cod2 non- nil
value, that value is returned and the remaining functions are
not called. If all functions return
.codn nil ,
then
.code nil
is returned. The expression
.code (orf)
returns a function which accepts any arguments and returns
.codn nil .

.coNP Function @ notf
.synb
.mets (notf << function )
.syne
.desc
The
.code notf
function returns a function which is the Boolean negation
of
.metn function .

The returned function takes a variable number of arguments. When
invoked, it passes all of these arguments to
.meta function
and then inverts the result as if by application of the
.codn not .

.coNP Functions @ iff and @ iffi
.synb
.mets (iff < condfun >> [ thenfun <> [ elsefun ]])
.mets (iffi < condfun < thenfun <> [ elsefun ])
.syne
.desc
The
.code iff
function is the functional equivalent of the
.code if
operator. It accepts
functional arguments and returns a function.

The resulting function takes its arguments, if any, and applies them to
.metn condfun .
If
.meta condfun
yields true, then the arguments are passed to
.meta thenfun
and the
resulting value is returned. Otherwise the arguments are passed to
.meta elsefun
and the resulting value is returned.

If
.meta thenfun
is omitted then
.code identity
is used as default. This omission is not permitted by
.codn iffi ,
only
.codn iff .

If
.meta elsefun
needs to be called, but is omitted, then
.code nil
is returned.

The
.code iffi
function differs from
.code iff
only in the defaulting behavior with respect
to the
.meta elsefun
argument. If
.meta elsefun
is omitted in a call to
.code iffi
then the default function is
.codn identity .
This is useful in situations when one value is to be
replaced with another one when the condition is true, otherwise
preserved.

The following equivalences hold between
.code iffi
and
.codn iff :

.verb
  (iffi a b c)            <--> (iff a b c)

  (iffi a b)              <--> (iff a b identity)

  [iffi a b nilf]         <--> [iff a b]

  [iffi a identity nilf]  <--> [iff a]
.brev

The following equivalences illustrate
.code iff
with both optional arguments omitted:

.verb
  [iff a]  <--->  [iff a identity nilf]  <--->  a
.brev

.coNP Functions @ tf and @ nilf
.synb
.mets (tf << arg *)
.mets (nilf << arg *)
.syne
.desc
The
.code tf
and
.code nilf
functions take zero or more arguments, and ignore them.
The
.code tf
function returns
.codn t ,
and the
.code nilf
function returns
.codn nil .

Note: the following equivalences hold between these functions and the
.code ret
operator, and
.code retf
function.

.verb
  (fun tf) <--> (ret t) <--> (retf t)
  (fun nilf) <--> (ret nil) <--> (ret) <--> (retf nil)
.brev

In Lisp-1-style code,
.code tf
and
.code nilf
behave like constants which can replace uses of
.code "(ret t)"
and
.codn "(ret nil)" :

.verb
  [mapcar (ret nil) list] <--> [mapcar nilf list]
.brev

.TP* Example:

.verb
  ;; tf and nilf are useful when functions are chained together.
  ;; test whether (trunc n 2) is odd.

  (defun trunc-n-2-odd (n)
    [[chain (op trunc @1 2) [iff oddp tf nilf]] n])
.brev

In this example, two functions are chained together, and
.code n
is passed
through the chain such that it is first divided by two via the
function denoted by
.code "(op trunc @1 2)"
and then the result is passed into the
function denoted by
.codn "[iff oddp tf nilf]" .
The
.code iff
function passes its argument into
.codn oddp ,
and if
.code oddp
yields true, it passes the same argument to
.codn tf .
Here
.code tf
proves its utility by ignoring that value and returning
.codn t .
If the argument (the divided value) passed into
.code iff
is even, then iff passes it into the
.code nilf
function, which ignores the value and returns
.codn nil .

.coNP Function @ retf
.synb
.mets (retf << value )
.syne
.desc
The
.code retf
function returns a function. That function can take zero or
more arguments. When called, it ignores its arguments and returns
.metn value .

See also: the
.code ret
macro.

.TP* Example:

.verb
  ;; the function returned by (retf 42)
  ;; ignores 1 2 3 and returns 42.
  (call (retf 42) 1 2 3) -> 42
.brev

.coNP Functions @ apf and @ ipf
.synb
.mets (apf < function << arg *)
.mets (ipf < function << arg *)
.syne
.desc
The
.code apf
function returns a one-argument function whose argument conventions
are similar to those of the
.code apply
function: it accepts one or more arguments, the last of which should
be a list.  When that function is called, it applies these arguments to
.meta function
as if by
.codn apply .
It then returns whatever
.meta function
returns.

If one or more additional
.metn arg -s
are passed to
.codn apf ,
then these are stored in the function which is returned.
When the function is invoked, it prepends all of these stored
arguments to those that it is being given, and the resulting combined
arguments are applied. Thus the
.metn arg -s
become the leftmost arguments of
.metn function .

The
.code ipf
function is similar to
.codn apf ,
except that the argument conventions of the function returned by
.code ipf
are based on
.codn iapply ,
and that function applies arguments as if by
.code iapply
rather than
.codn apply .

See also: the
.code ap
macro.

.TP* Example:

.verb
  ;; Function returned by [apf +] accepts the
  ;; (1 2 3) list and applies it to +, as
  ;; if (+ 1 2 3) were called.

  (call [apf +] '(1 2 3)) -> 6
.brev

.coNP Function @ callf
.synb
.mets (callf < main-function << arg-function *)
.syne
.desc
The
.code callf
function returns a function which applies its arguments to each
.metn arg-function ,
juxtaposing the return values of these calls to form arguments
which are then passed to
.metn main-function .
The return value of
.meta main-function
is returned.

The following equivalence holds, except for the order of evaluation of
arguments:

.verb
  (callf fm f0 f1 f2 ...) <--> (chain (juxt f0 f1 f2 ...)
                                      (apf fm))
.brev

.TP* Example:

.verb
  ;; Keep those pairs which are two of a kind

  (keep-if [callf eql first second] '((1 1) (2 3) (4 4) (5 6)))
  -> ((1 1) (4 4))
.brev

The following equivalence holds between
.code juxt
and
.codn callf :

.verb
  [juxt f0 f1 f2 ...]  <-->  [callf list f0 f1 f2 ...]:w
.brev

Thus,
.code juxt
may be regarded as a specialization of
.code callf
in which the main function is implicitly
.codn list .

.coNP Function @ mapf
.synb
.mets (mapf < main-function << arg-function *)
.syne
.desc
The
.code mapf
function returns a function which distributes its arguments
into the
.metn arg-function -s.
That is to say, each successive argument of the returned
function is associated with a successive
.metn arg-function .

Each
.meta arg-function
is called, passed the corresponding argument. The return
values of these functions are then passed as arguments
to
.meta main-function
and the resulting value is returned.

If the returned function is called with fewer arguments than there
are
.metn arg-function -s,
then only that many functions are used. Conversely, if the function is
called with more arguments than there are
.metn arg-function -s,
then those arguments are ignored.

The following equivalence holds:

.verb
  (mapf fm f0 f1 ...) <--> (lambda (. rest)
                              [apply fm [mapcar call
                                                (list f0 f1 ...)
                                                rest]])
.brev

.TP* Example:

.verb
  ;; Add the squares of 2 and 3
  [[mapf + [dup *] [dup *]] 2 3] -> 13

.brev

.SS* Input and Output (Streams)
\*(TL supports input and output streams of various kinds, with
generic operations that work across the stream types.

In general, I/O errors are usually turned into exceptions. When the description
of error reporting is omitted from the description of a function, it can be
assumed that it throws an error.

.coNP Special variables @, *stdout* @, *stddebug* @, *stdin* @ *stderr* and @ *stdnull*
.desc
These variables hold predefined stream objects. The
.codn *stdin* ,
.code *stdout*
and
.code *stderr*
streams closely correspond to the underlying operating system streams.
Various I/O functions require stream objects as arguments.

The
.code *stddebug*
stream goes to the same destination as
.codn *stdout* ,
but is a separate object which can be redirected independently, allowing
debugging output to be separated from normal output.

The
.code *stdnull*
stream is a special kind of stream called a null stream.
This stream is not connected to any device or file.  It is similar to
the
.code /dev/null
device on Unix, but does not involve the operating system.

.coNP Special variables @ *print-flo-format* and @ *pprint-flo-format*
.desc
The
.code *print-flo-format*
variable determines the conversion format which is applied when
a floating-point value is converted to decimal text by the
functions
.codn print ,
.codn prinl ,
and
.codn tostring .

The default value is
.codn "~s" .

The related variable
.code *pprint-flo-format*
similarly determines the conversion format applied to floating-point
values by the functions
.codn pprint ,
.codn pprinl ,
and
.codn tostringp .

The default value is
.codn "~a" .

The format string in either variable must specify the consumption of
exactly one
.code format
argument.

The conversion string may use embedded width and precision values:
for instance,
.code "~3,4f"
is a valid value for
.code *print-flo-format*
or
.codn *pprint-flo-format* .

.coNP Special variable @ *print-flo-precision*
.desc
The
.code *print-flo-precision*
special variable specifies the default floating-point printing
precision which is used when the
.code ~a
or
.code ~s
conversion specifier of the
.code format
function is used for printing a floating-point value, and no precision
is specified.

Note that since the default value of the variable
.code *print-flo-format*
is the string
.codn "~s" ,
the
.code *printf-flo-precision*
variable, by default, also determines the precision which applies when
floating-point values are converted to decimal text by the functions
.codn print ,
.codn pprint ,
.codn prinl ,
.codn pprinl ,
.code tostring
and
.codn tostringp .

The default value of
.code *print-flo-precision*
is that of the
.code flo-dig
variable.

Note: to print floating-point values in such a way that their values
can be precisely recovered from the printed representation, it is
recommended to override
.code *print-flo-precision*
to the value of the
.code flo-max-dig
variable.

.coNP Special variable @ *print-flo-digits*
.desc
The
.code *print-flo-precision*
special variable specifies the default floating-point printing
precision which is used when the
.code ~f
or
.code ~e
conversion specifier of the
.code format
function is used for printing a floating-point value, and no precision
is specified.

Its default value is
.codn 3 .

.coNP Special variable @ *print-base*
.desc
The
.code *print-base*
variable controls the base (radix) used for printing integer values.
It applies when the functions
.codn print ,
.codn pprint ,
.codn prinl ,
.codn pprinl ,
.code tostring
and
.code tostringp
process an integer value.
It also applies when the
.code ~a
and
.code ~s
conversion specifiers of the
.code format
function are used for printing an integer value.

The default value of the variable is
.codn 10 .

Meaningful values are:
.codn 2 ,
.codn 8 ,
.code 10
and
.codn 16 .

When base 16 is selected, hexadecimal digits are printed as upper-case
characters.

.coNP Special variable @ *print-circle*
.desc
The
.code *print-circle*
variable is a Boolean which controls whether the circle notation is
in effect for printing aggregate objects: conses, ranges, vectors, hash tables
and structs. The initial value of this variable is
.codn nil :
circle notation printing is disabled.

The circle notation works for structs also, including structs which have
user-defined
.code print
methods. When a
.code print
method calls functions which print objects, such as
.codn print ,
.code pprinl
or
.code format
on the same stream, the detection of circularity and substructure sharing
continues in these recursive invocations.

However, there are limitations in the degree of support for circle notation
printing across
.code print
methods. Namely, a
.code print
method of a struct
.meta S
must not procure and submit for printing objects which are not part of the
ordinary structure that is reachable from the (static or instance) slots of
.metn S ,
if those objects have already been printed prior to invoking the
.code print
method, and have been printed without a
.code #=
circle notation label.  The "ordinary structure that is reachable from the
slots" denotes structure that is directly reachable by traversing conses,
ranges, vectors, hashes and struct slots: all printable aggregate objects.

.coNP Function @ format
.synb
.mets (format < stream-designator < format-string << format-arg *)
.syne
.desc
The
.code format
function performs output to a stream given by
.metn stream-designator ,
by interpreting the actions implicit in a
.metn format-string ,
incorporating material pulled from additional arguments given by
.mono
.meti << format-arg *.
.onom
Though the function is simple to invoke, there is complexity in format string
language, which is documented below.

The
.meta stream-designator
argument can be a stream object, or one of the values
.code t
or
.codn nil .
The value
.code t
serves as a shorthand for
.codn *stdout* .
The value
.code nil
means that the function will send output into a newly instantiated string
output stream, and then return the resulting string.

.TP* "Format string syntax:"

Within
.metn format-string ,
most characters represent themselves. Those
characters are simply output. The character
.code ~
(tilde) introduces formatting
directives, which are denoted by a single character, usually a letter.

The special sequence
.code ~~
(tilde-tilde) encodes a single tilde. Nothing is
permitted between the two tildes.

The syntax of a directive is generally as follows:

.mono
.mets <> ~[ width ] <> [, precision ] < letter
.onom

In other words, the
.code ~
(tilde) character, followed by a
.meta width
specifier, a
.meta precision
specifier introduced by a comma,
and a
.metn letter ,
such that
.meta width
and
.meta precision
are independently optional: either or both may be omitted.
No whitespace is allowed between these elements.

The
.meta letter
is a single alphabetic character which determines the
general action of the directive. The optional width and precision
are specified as follows:

.RS
.meIP < width
The width specifier consists of an optional
.code <
(left angle bracket) character or
.code ^
(caret)
character followed by an optional width specification.

If the leading
.code <
character is present, then the printing will be left-adjusted within
this field. If the
.code ^
character is present, the printing will be centered within the field.
Otherwise it will be right-adjusted by default.

The width can be specified as a decimal integer with an optional leading
minus sign, or as the character
.codn * .
The
.code *
notation means that instead of digits, the value of the next argument is
consumed, and expected to be an integer which specifies the width. If the
width, specified either way, is negative, then the field will be left-adjusted.
If the value is positive, but either the
.code <
or
.code ^
prefix character is present in the width
specifier, then the field is adjusted according to that character.

The padding calculations for alignment and centering take into account
character display width, as defined by the
.code display-width
function. For instance, a character string containing four Chinese
characters (kanji) has a display width of 8, not 4.

The width specification does not restrict the printed portion of a datum.
Rather, for some kinds of conversions, it is the precision specification that
performs such truncation.  A datum's display width (or that of its printed
portion, after such truncation is applied) can equal or exceed the specified
field width.  In this situation it overflows the field: the printed portion is
rendered in its entirety without any padding applied on either side for
alignment or centering.

.meIP < precision
The precision specifier is introduced by a leading comma. If this comma appears
immediately after the directive's
.code ~
character, then it means that
.meta width
is being omitted; there is only a precision field.

The precision specifier may begin with these optional characters:
.RS
.coIP 0
(the "leading zero flag"),
.coIP +
(print a sign for positive values")
.IP space
(print a space in place of a positive sign).
.RE

The precision specifier itself is either a decimal integer that does not
begin with a zero digit, or the
.code *
character.

The precision field's components have a meaning which depends on the type of
object printed and the conversion specifier.

For integer arguments, the precision value specifies the minimum number of digits
to print.  If the precision field has a leading zero flag, then the integer is
padded with zeros to the required number of digits, otherwise the number is
padded with spaces instead of zeros.  If zero or space padding is present, and
a leading positive or negative sign must be printed, then it is placed before
leading zeros, or after leading spaces, as the case may be.

For floating-point values, the meaning of the precision value depends on which
specific conversion specifier
.cod1 ( f ,
.codn e ,
.code a
or
.codn s )
is used. The details are
documented in the description of each of these, below. The leading zero flag is
also taken into account for floating-point values, and treated uniformly by
these directives.  If the flag is present, then the printed value's integer
part will be padded with leading zeros up to the width of the field such that
one character of unused space remains in the field, in case a positive or
negative sign needs also to be rendered.

For integer or floating-point arguments, if the precision specifier has a
.code +
sign
among the special characters, then a
.code +
sign is printed for positive numbers. If
the precision specifier has a leading space instead of a
.code +
sign, then the
.code +
sign is rendered as a space for positive numbers. If there is no leading space
or
.codn + ,
then a sign character is omitted for positive numbers. Negative
numbers are unconditionally prefixed with a
.code -
sign.

For all other objects, the precision specifies the maximum number of
print positions to occupy, taking into account the display width of each
character of the printed representation of the object, as according
to the
.code display-width
function.  The object's printed representation is truncated, if necessary, to
the maximum number of characters which will not exceed the specified number of
print positions.

.RE

.TP* "Format directives:"
.RS
Format directives are case sensitive, so that for example
.code ~x
and
.code ~X
have a
different effect, and
.code ~A
doesn't exist whereas
.code ~a
does. They are:

.coIP a
Prints any object in an aesthetic way, as if by the
.code pprint
function.
The aesthetic notation violates read-print consistency: this notation
is not necessarily readable if it is implanted in \*(TX source code.
The field width specifier is honored, including the left-right adjustment
semantics.

When this specifier is used for floating-point values, the precision specifies
the maximum number of total significant figures, which do not include any
digits in the exponent, if one is printed. Numbers are printed in exponential
notation if their magnitude is small, or else if their exponent exceeds their
precision. If the precision is not specified, then it is obtained from
the
.code *print-flo-precision*
special variable, whose default value is the same as that of the
.code flo-dig
variable.
Floating point values which are integers are
printed without a trailing
.code .0
(point zero).
The
.code +
flag in the precision is honored for rendering an explicit
.code +
sign on non-negative values.
If a leading zero is specified in the precision, and a nonzero width is
specified, then the printed value's integer part will be padded with leading
zeros up to one less than the field width. These zeros are placed before the
sign.

.coIP s
Prints any object in a standard way, as if by the
.code print
function.  Objects for
which read-print consistency is possible are printed in a way such that
if their notation is implanted in \*(TX source, they are readable.
The field width specifier is honored, including the left-right adjustment
semantics. The precision field is treated similarly to the
.code ~a
format directive, except that non-exponentiated floating point numbers that
would be mistaken for integers include a trailing
.code .0
for the sake of read-print
consistency. Objects truncated by precision may not have read-print
consistency. For instance, if a string object is truncated, it loses its
trailing closing quote, so that the resulting representation is no longer
a properly formed string object. For integer objects, the
.code *print-base*
variable is honored. Effectively, an integer is printed by the
.code s
directive as if by the
.codn b ,
.codn o ,
.codn d ,
or
.code x
directive, depending on the value of the variable.

.coIP d
Requires an argument of integer or character type type. The integer
value or character code is printed in decimal.

.coIP x
Requires an argument of character or integer type. The integer value or
character code is printed in hexadecimal, using lower-case letters
for the digits
.code a
through
.codn f .
Width and precision semantics
are as described for the
.code a
format directive, for integers.

.coIP X
Like the
.code x
directive, but the hexadecimal digits
.code a
through
.code f
are rendered in upper case.

.coIP o
Like the
.code x
directive, but octal is used instead of hexadecimal.

.coIP b
Like the
.code x
directive, but binary is used instead of hexadecimal.

.coIP f
The
.code f
directive prints numbers in a fixed point decimal notation, with
a fixed number of digits after the decimal point. It requires a numeric
argument. (Unlike
.codn x ,
.code X
and
.codn o ,
it does not allow an argument of character type).
The precision specifier gives the number of digits past the decimal point.
The number is rounded off to the specified precision, if necessary.
Furthermore, that many digits are always printed, regardless of the actual
precision of the number or its type.  If it is omitted, then the value
is obtained from the special variable
.codn *print-flo-digits* ,
whose default value is three: three digits past the decimal point. A precision
of zero means no digits pas the decimal point, and in this case the decimal
point is suppressed (regardless of whether the numeric argument is
floating-point or integer).

.coIP e
The
.code e
directive prints numbers in exponential notation. It requires
a numeric argument. (Unlike
.codn x ,
.code X
and
.codn o ,
it does not allow an argument of character type).
The precision specifier gives the number of digits past the decimal point
printed in the exponential notation, not counting the digits in the exponent.
Exactly that many digits are printed, regardless of the precision of the
number.  If the precision is omitted, then the number of digits after the
decimal point is obtained from the value of the special variable
.codn *print-flo-digits* ,
whose default value is three. If the precision is zero, then a decimal portion
is truncated off entirely, including the decimal point.

.coIP p
The
.code p
directive prints a numeric representation in hexadecimal of the bit pattern
of the object, which is meaningful to someone familiar with the internals
of \*(TX.  If the object is a pointer to heaped data, that value
has a correspondence to its address.

.coIP !
The
.code !
directive establishes hanging indentation, and turns on the stream's
indentation mode. Subsequent lines printed within the execution of the
same
.code format
call will be automatically indented. If no width is specified, then
the directive sets the hanging indentation to the current printing
column position. If a width is specified, then it represents an offset
(positive or negative). If the
.code <
prefix character is present, the hanging indentation is set to the
specified offset relative to the current printing column.
If the
.code <
prefix is present on the width field, then the offset is applied
relative to the indentation which was saved on entry into the
.code format
function.

The indentation mode and indentation column are automatically restored to their
previous values when
.code format
function terminates, naturally or via an exception or non-local jump.

The effect of a precision field (even if zero) combined with the
.code !
directive is currently not specified, and reserved for future extension.
The precision field is processed syntactically, and no error occurs, however.
.RE

.coNP Function @ fmt
.synb
.mets (fmt < format-string << format-arg *)
.syne
.desc
The
.code fmt
function provides a shorthand for formatting to a string, according
to the following equivalence which holds between
.code fmt
and
.codn format :

.verb
  (fmt s arg ...)  <-->  (format nil s arg ...)
.brev

.coNP Functions @, print @, pprint @, prinl @, pprinl @ tostring and @ tostringp
.synb
.mets (print < obj >> [ stream <> [ pretty-p ]])
.mets (pprint < obj <> [ stream ])
.mets (prinl < obj <> [ stream ])
.mets (pprinl < obj <> [ stream ])
.mets (tostring << obj )
.mets (tostringp << obj )
.syne
.desc
The
.code print
and
.code pprint
functions render a printed character representation of the
.meta obj
argument into
.metn stream .

If the
.meta stream
argument is not supplied, then
the destination is the stream currently stored in the
.code *stdout*
variable.

If Boolean argument
.meta pretty-p
is not supplied or is explicitly specified as
.codn nil ,
then the
.code print
function renders in a way which strives for read-print
consistency: an object is printed in a notation which is recognized as
a similar object of the same kind when it appears in \*(TX source code.
Floating-point objects are printed as if using the
.code format
function, with formatting controlled by the
.code *print-flo-format*
variable.

If
.meta pretty-p
is true, then
.code print
does not strive for read-print consistency.
Strings are printed by sending their characters to the output
stream, as if by the
.code put-string
function, rather than being rendered in the string literal notation
consisting of double quotes, and escape sequences for control
characters.  Likewise, character objects are printed via
.code put-char
rather than the
.code #\e
notation. Buffer objects are printed by sending their bytes to the
output stream using
.code put-byte
rather than being rendered in the
.code #b
notation.
Symbols are printed without their package prefix, except that
symbols from the keyword package are still printed with the leading colon.
Floating-point objects are printed as if using the
.code format
function, with formatting controlled by the
.code *pprint-flo-format*
variable.

When aggregate objects like conses, ranges and vectors are printed,
the notations of these objects themselves are unaffected by the
.code pretty-p
flag; however, that flag is distributed to the elements.

The
.code print
function returns
.metn obj .

The
.code pprint
("pretty print") function is equivalent to
.codn print ,
with the
.meta pretty-p
argument hard-coded true.

The
.code prinl
function ("print and new line") behaves like a call to
.code print
with
.meta pretty-p
defaulting to
.codn nil ,
followed by issuing a newline characters to the stream.

The
.code pprinl
function ("pretty print and new line") behaves like
.code pprint
followed by issuing a newline to the stream.

The
.code tostring
and
.code tostringp
functions are like
.code print
and
.codn pprint ,
but they do not accept a stream argument. Instead they print to a freshly
instantiated string stream, and return the resulting string.

The following equivalences hold between calls to the
.code format
function and calls to the above functions:

.verb
  (format stream "~s" obj)  <-->  (print obj stream)
  (format t "~s" obj)       <-->  (print obj)
  (format t "~s\en" obj)     <-->  (prinl obj)
  (format nil "~s" obj)     <-->  (tostring obj)
.brev

For
.codn pprint ,
.code tostringp
and
.codn pprinl ,
the equivalence is produced by using
.code ~a
in format rather than
.codn ~s .

.TP* Notes:
For floating-point numbers, the above description of the behavior in
terms of the format specifiers
.code ~s
and
.code ~a
only applies with respect to the default values of the variables
.code *print-flo-format*
and
.codn *pprint-flo-format* .

For characters, the print function behaves as follows: most control
characters in the Unicode
.code C0
and
.code C1
range are rendered using the
.code #\ex
notation,
using two hex digits. Codes in the range
.code D800
to
.codn DFFF ,
and the codes
.code FFFE
and
.code FFFF
are printed in the
.code #\exNNNN
with four hexadecimal digits, and
character above this range are printed using the same notation, but with six
hexadecimal digits. Certain characters in the
.code C0
range are printed using
their names such as
.code #\enul
and
.codn #\ereturn ,
which are documented
in the Character Literals section.
The
.code DC00
character is printed as
.codn #\epnul .
All other characters are printed as
.mono
.meti >> #\e char
.onom
where
.meta char
is the actual character.

Caution: read-print consistency is affected by trailing material. If additional
digits are printed immediately after a number without intervening whitespace,
they extend that number. If hex digits are printed after the character
.codn x ,
which is rendered as
.codn #\ex ,
they look like a hex character code.

.coNP Function @ tprint
.synb
.mets (tprint < obj <> [ stream ])
.syne
.desc
The
.code tprint
function prints a representation of
.meta obj
on
.metn stream .

If the stream argument is not supplied, then
the destination is the stream currently stored in the
.code *stdout*
variable.

For all object types except lists and vectors,
.code tprint
behaves like
.codn pprinl .

If
.code obj
is a list or vector, then
.code tprint
recurses: the
.code tprint
function is applied to each element.  An empty list or vector
results in no output at all.  This effectively means that an arbitrarily nested
structure of lists and vectors is printed flattened, with one element on each
line.

.coNP Function @ display-width
.synb
.mets (display-width << char )
.mets (display-width << string )
.syne
.desc
The
.code display-width
function calculates the number of places occupied by the printed representation
of
.meta char
or
.meta string
on a monospace display which renders certain characters, such as the East Asian
kanji and other characters, using two places.

For a
.meta string
argument, this value is the sum of the individual display width of the
string's constituent characters. The display width of an empty string is zero.

Control characters are assigned a display width of zero, regardless of
their display control semantics, if any.

Characters marked by Unicode as being wide or full width, have a display
width of two. Other characters have a display width of one.

.coNP Function @ streamp
.synb
.mets (streamp << obj )
.syne
.desc
The
.code streamp
function returns
.code t
if
.meta obj
is any type of stream.  Otherwise it returns
.codn nil .

.coNP Function @ real-time-stream-p
.synb
.mets (real-time-stream-p << obj )
.syne
.desc
The
.code real-time-streamp-p
function returns
.code t
if
.meta obj
is a stream marked as
"real-time".  If
.meta obj
is not a stream, or not a stream marked as "real-time",
then it returns
.codn nil .

Only certain kinds of streams accept the real-time attribute: file streams and
tail streams. This attribute controls the semantics of the application of
.code lazy-stream-cons
to the stream.  For a real-time stream,
.code lazy-stream-cons
returns a stream with "naive" semantics which returns data as soon as it is
available, at the cost of generating spurious
.code nil
item when the stream
terminates. The application has to recognize and discard that
.code nil
item.
The ordinary lazy streams read ahead by one line and suppress this extra
item, so their representation is more accurate.

When \*(TX starts up, it automatically marks the
.code *stdin*
stream as real-time, if it is connected to a TTY device (a device for which
the POSIX function
.code isatty
reports true). This is only supported on platforms that have this function.
The behavior is overridden by the
.code -n
command line option.

.coNP Function @ open-file
.synb
.mets (open-file < path <> [ mode-string ])
.syne
.desc
The
.code open-file
function creates a stream connected to the file
which is located at the given
.metn path ,
which is a string.

The
.meta mode-string
argument is a string which uses the same
conventions as the mode argument of the C language
.code fopen
function, with greater permissiveness, and some extensions.

The syntax of mode-string is described by the following
grammar. Note that it permits no whitespace characters:

.mono
.mets < mode-string := [ < mode ] [ < options ]
.mets < mode := { < selector [ + ] | + }
.mets < selector := { r | w | a | m }
.mets < options := { b | l | u | i | n | < digit | < redirection }
.mets < digit := { 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }
.onom

If the
.meta mode-string
argument is omitted, the behavior is the same as an empty
mode string.

The
.meta mode
part of the mode string generates the following possibilities:
.RS
.meIP empty
If the
.meta mode
is missing, then a default mode is implied. The default
is specific to the particular stream-opening function. In
the case of
.codn open-file ,
the default mode is
.codn r .
.coIP +
A
.meta mode
consisting of just the
.code +
character is equivalent to
.codn r+ .
.coIP r
This
.meta mode
means that the file is opened for reading.
.coIP r+
The file is opened for reading and writing.  It is not created
if it doesn't exist.
.coIP w
The file is opened for writing. If it exists, it is truncated
to zero length. If it doesn't exist, it is created.
.coIP w+
The file is opened for reading and writing. If it exists, it
is truncated to zero length. If it doesn't exist, it is created.
.coIP m
The file is opened for modification. This is the same as
.code w
except that the file is not truncated if it exists.
.coIP m+
The file is opened for reading and modification. This is the same as
.code w+
except that the file is not truncated if it exists.
.coIP a
The file is opened for writing. If it doesn't exist, it is
created. If it exists, the current position is advanced to
one byte past the end of the file, so that newly written data
are appended.
.coIP a+
The file is opened for reading and writing. If it doesn't exist,
it is created. The read position is at the beginning of the file,
but writes are appended to the end regardless of the position.
.RE
.IP
The meanings of the option characters are:
.RS
.coIP b
The file is opened in binary mode: no line ending translation takes place.
In the absence of this option, files are opened in text mode, in which newline
characters in the stream are an abstract indication of the end of a line,
translate to a system-specific way of terminating lines in text files.
.coIP l
Specifies that the stream will be line buffered.  This means that an implicit
flush operation takes place whenever the newline character is output.
.coIP u
Specifies that the stream will be unbuffered.  It is erroneous for both
.code l
and
.code u
to be specified.
.coIP i
Specifies that the stream will have the real-time
property set. For a description of the semantics, see the
.code real-time-stream-p
function. Briefly, this property affects the semantics of lazy lists which draw
input from the stream.
In addition, for a stream opened for writing or reading and writing, the
.code i
mode letter specifies that the stream will be line buffered, unless
specified as unbuffered with
.codn u .
.coIP n
Specifies that the operation shall not block.
.meIP digit
A decimal digit specifies the the stream buffer size
as binary exponential buffer size order, such that
.code 0
specifies 1024 bytes,
.code 1
specifies 2048 and so forth up to
.code 9
specifying 524288 bytes. If no such digit is specified, then the
stream uses a default buffer size. It is erroneous for the
size order digit to be present together with the option
.codn u .
.meIP redirection
This option refers to a special syntax that only has an effect
in mode strings that are passed to the
.code open-process
function; the syntax performs I/O redirections in the child process
created by that function, and is described in that function's
documentation.
.RE

.coNP Function @ open-tail
.synb
.mets (open-tail < path >> [ mode-string <> [ seek-to-end-p ]])
.syne
.desc
The
.code open-tail
function creates a tail stream connected to the file which is
located at the given
.metn path .
The
.meta mode-string
argument is a string which uses
the same conventions as the mode argument of the C language
.code fopen
function. If this argument is omitted, then
.str r
is used.
See the
.code open-file
function for a discussion of modes.

The
.code seek-to-end-p
argument is a Boolean which determines whether the initial
read/write position is at the start of the file, or just past the end.
It defaults to
.codn nil .
This argument only makes a difference if the file exists
at the time
.code open-tail
is called. If the file does not exist, and is later
created, then the tail stream will follow that file from the beginning.  In
other words,
.meta seek-to-end-p
controls whether the tail stream reads all the
existing data in the file, if any, or whether it reads only newly added data
from approximately the time the stream is created.

A tail stream has special semantics with regard to reading at the end
of file. A tail stream never reports an end-of-file condition; instead
it polls the file until more data is added. Furthermore, if the file
is truncated, or replaced with a smaller file, the tail stream follows
this change: it automatically opens the smaller file and starts reading from
the beginning (the
.meta seek-to-end-p
flag only applies to the initial open).
In this manner, a tail stream can dynamically growing rotating log files.

Caveat: since a tail stream can re-open a new file which has the same
name as the original file, it behave incorrectly if the program
changes the current working directory, and the path name is relative.

.coNP Function @ open-directory
.synb
.mets (open-directory << path )
.syne
.desc
The
.code open-directory
function tries to create a stream which reads the
directory given by the string argument
.metn path .
If a filesystem object exists
under the path, is accessible, and is a directory, then the function
returns a stream. Otherwise, a file error exception is thrown.

The resulting stream supports the get-line operation. Each call to the
.code get-line
operation retrieves a string representing the next directory
entry. The value
.code nil
is returned when there are no more directory entries.
The
.code .
and
.code ..
entries in Unix filesystems are not skipped.

.coNP Function @ make-string-input-stream
.synb
.mets (make-string-input-stream << string )
.syne
.desc
The
.code make-string-input-stream
function produces an input stream object. Character read operations on the
stream object read successive characters from
.metn string .
Output operations and byte operations are not supported.

.coNP Function @ make-string-byte-input-stream
.synb
.mets (make-string-byte-input-stream << string )
.syne
.desc
The
.code make-string-byte-input-stream
function produces an input stream object. Byte read operations on
this stream object read successive byte values obtained by encoding
.meta string
into UTF-8. Character read operations are not supported, and neither
are output operations.

.coNP Function @ make-strlist-input-stream
.synb
.mets (make-strlist-input-stream << list )
.syne
.desc
The
.code make-strlist-input-stream
function produces an input stream object based on a list of strings.
Through the character read operations invoked on this stream,
the list of strings appears as a list of newline-terminated lines.
Output operations and byte operations are not supported.

.coNP Function @ make-string-output-stream
.synb
.mets (make-string-output-stream)
.syne
.desc
The
.code make-string-output-stream
function, which takes no arguments, creates a string output stream.
Data sent to this stream is accumulated into a string object.
String output streams supports both character and byte output operations.
Bytes are assumed to represent a UTF-8 encoding, and are decoded in order
to form characters which are stored into the string.

If an incomplete UTF-8 code is output, and a character output operation then
takes place, that code is assumed to be terminated and is decoded as invalid
bytes.  The UTF-8 decoding machine is reset and ready for the start of a new
code.

The
.code get-string-from-stream
function is used to retrieve the accumulated string.

If the null character is written to a string output stream, the behavior
is unspecified. \*(TX strings cannot contain null bytes. A the pseudo-null
character
.codn #\exDC00 ,
also notated
.codn #\epnul ,
will produce a null byte when converted to UTF-8 and thus serves as an
effective internal representation of the null character in external data.

.coNP Function @ get-string-from-stream
.synb
.mets (get-string-from-stream << stream )
.syne
.desc
The
.meta stream
argument must be a string output stream. This function finalizes
the data sent to the stream and retrieves the accumulated character string.

If a partial UTF-8 code has been written to
.metn stream ,
and then this
function is called, the byte stream is considered complete and the partial
code is decoded as invalid bytes.

After this function is called, further output on the stream is not possible.

.coNP Function @ make-strlist-output-stream
.synb
.mets (make-strlist-output-stream)
.syne
.desc
The
.code make-strlist-output-stream
function is similar to
.codn make-string-output-stream .
However, the stream object produced by this function does not produce a string,
but a list of strings.  The data is broken into multiple strings by newline
characters written to the stream. Newline characters do not appear in the
string list. Also, byte output operations are not supported.

.coNP Function @ get-list-from-stream
.synb
.mets (get-list-from-stream << stream )
.syne
.desc
The
.code get-list-from-stream
function returns the string list which has accumulated inside
a string output stream given by
.metn stream .
The string output stream is
finalized, so that further output is no longer possible.

.coNP Macro @ with-in-string-stream
.synb
.mets (with-in-string-stream >> ( stream-var << string )
.mets \ \  << body-form *)
.syne
.desc
The
.code with-in-string-stream
macro binds the symbol
.meta stream-var
as a variable, initializing it with a newly created
string input stream. The string input stream is
constructed from
.meta string
as if by the
.mono
.meti (make-string-input-stream << string )
.onom
expression.

Then it evaluates the
.metn body-form -s
in the scope of the variable.

The value of the last
.meta body-form
is returned, or else
.code nil
if no forms are present.

The
.meta stream-var
argument must be a bindable symbol,
as defined by the
.code bindable
function.

The
.meta string
argument must be a form
which evaluates to a character string value.

.coNP Macro @ with-in-string-byte-stream
.synb
.mets (with-in-string-byte-stream >> ( stream-var << string )
.mets \ \  << body-form *)
.syne
.desc
The
.code with-in-string-byte-stream
macro binds the symbol
.meta stream-var
as a variable, initializing it with a newly created
string byte input stream. The string input stream is
constructed from
.meta string
as if by the
.mono
.meti (make-string-byte-input-stream << string )
.onom
expression.

Then it evaluates the
.metn body-form -s
in the scope of the variable.

The value of the last
.meta body-form
is returned, or else
.code nil
if no forms are present.

The
.meta string
argument must be a form
which evaluates to a character string value.

.coNP Macro @ with-out-string-stream
.synb
.mets (with-out-string-stream <> ( stream-var ) << body-form *)
.syne
.desc
The
.code with-out-string-stream
macro binds the symbol specified
by the
.meta stream-var
argument as a variable, initializing it
with a newly created string output stream. The output
stream is created as if by the
.code make-string-output-stream
function.

Then it evaluates
.metn body-form -s
in the scope of that variable.

After these forms are evaluated, the string is extracted
from the string output stream, as if by the
.code get-string-from-stream
function, and returned as the result value
of the form.

.coNP Macro @ with-out-strlist-stream
.synb
.mets (with-out-strlist-stream <> ( stream-var ) << body-form *)
.syne
.desc
The
.code with-out-strlist-stream
macro binds the symbol specified
by the
.meta stream-var
argument as a variable, initializing it
with a newly created string list output stream. The output
stream is created as if by the
.code make-strlist-output-stream
function.

Then it evaluates
.metn body-form -s
in the scope of that variable.

After these forms are evaluated, the string list is extracted
from the string output stream, as if by the
.code get-strlist-from-stream
function, and returned as the result value
of the form.

.coNP Function @ make-byte-input-stream
.synb
.mets (make-byte-input-stream << obj )
.syne
.desc
The
.code make-byte-input-stream
creates a stream which supports the
.code get-byte
operation for traversing a byte-wise representation of
.metn obj .

The function serves as a generic interface for calling one of
several other stream constructing functions based on the
type of the
.meta obj
argument.

The
.meta obj
argument must be either a buffer, in which case
.code make-byte-input-stream
behaves like
.codn make-buf-stream ,
or else a string, in which case the function behaves like
.codn make-string-byte-input-stream .

Note: the repertoire of types handled by
.code make-byte-input-stream
may expand in future language versions.

.coNP Function @ close-stream
.synb
.mets (close-stream < stream <> [ throw-on-error-p ])
.syne
.desc
The
.code close-stream
function performs a close operation on
.metn stream ,
whose meaning is depends on the type of the stream. For some types of streams,
such as string streams, it does nothing. For streams which are connected
to operating system files or devices, will perform a close of the underlying
file descriptor, and dissociate that descriptor from the stream. Any buffered
data is flushed first.

.code close-stream
returns a Boolean true value if the close has occurred without
errors, otherwise
.codn nil .

For most streams, "without errors" means that any buffered output data is
flushed successfully.

For command and process pipes (see open-command and open-process), success also
means that the process terminates normally, with a successful error code, or an
unsuccessful one. An abnormal termination is considered an error, as
as is the inability to retrieve the termination status, as well as the situation
that the process continues running in spite of the close attempt.
Detecting these situations is platform specific.

If the
.meta throw-on-error-p
argument is specified, and isn't
.codn nil ,
then the
function throws an exception if an error occurs during the close operation
instead of returning
.codn nil .

.coNP Macro @ with-stream
.synb
.mets (with-stream >> ( stream-var << init-form )
.mets \ \  << body-form *)
.syne
.desc
The
.code with-stream
binds the variable whose name is given by the
.meta stream-var
argument, and macro arranges for the evaluation of
.metn body-form -s
in the scope of that variable.

The variable is initialized with the value produced
by the evaluation of
.meta init-form
which must be an expression which evaluates to a stream.

After each
.meta body-form
is evaluated, the stream is closed, as if by the
.mono
.meti (close-stream << stream-var )
.onom
expression.

The value of the last
.meta body-form
then becomes the result value of the form,
or else
.code nil
if these forms are absent.

If the evaluation of the
.metn body-form -s
is abandoned, the stream is still closed. That is to say,
the closure of the stream is a protected action, as if by
the
.code unwind-protect
operator.

.coNP Functions @, get-error @ get-error-str and @ clear-error
.synb
.mets (get-error << stream )
.mets (get-error-str << stream )
.mets (clear-error << stream )
.syne
.desc
When a stream operation fails, the
.code get-error
and
.code get-error-str
functions may be used to inquire about a more detailed cause of the error.

Not all streams support these functions to the same extent. For instance,
string input streams have no persistent state. The only error which occurs
is the condition when the string has no more data.

The
.code get-error
inquires
.meta stream
about its error condition.

The function returns
.code nil
to indicate there is no error condition,
.code t
to indicate an end-of-data condition,
or else a value which is specific to the stream type indicating the
specific error type.

Note: for some streams, it is possible for the
.code t
value to be returned even though no operation has failed; that is to say, the
streams "know" they are at the end of the data even though no read operation
has failed. Code which depends on this will not work with streams which
do not thus indicate the end-of-data
.IR "a priori" ,
but by means of a read operation which fails.

The
.code get-error-str
function returns a text representation of the error code. The
.code nil
error code is represented as the string
.codn "no error" ;
the
.code t
error code as
.code "eof"
and other codes have a stream-specific representation.

The
.code clear-error
function removes the error situation from a stream. On some streams, it does
nothing. If an error has occurred on a stream, this function should be called
prior to re-trying any I/O or positioning operations.
The return value is the previous error code, or
.code nil
if there was no error, or the operation is not supported on the stream.

.coNP Functions @, get-line @ get-char and @ get-byte
.synb
.mets (get-line <> [ stream ])
.mets (get-char <> [ stream ])
.mets (get-byte <> [ stream ])
.syne
.desc
These fundamental stream functions perform input.  The
.meta stream
argument
is optional. If it is specified, it should be an input stream which supports
the given operation. If it is not specified, then the
.code *stdin*
stream is used.

The
.code get-char
function pulls a character from a stream which supports character
input.  Streams which support character input also support the
.code get-line
function which extracts a line of text delimited by the end of the stream or a
newline character and returns it as a string. (The newline character does not
appear in the string which is returned).

Character input from streams based on bytes requires UTF-8 decoding, so that
get-char actually may read several bytes from the underlying low level
operating system stream.

The
.code get-byte
function bypasses UTF-8 decoding and reads raw bytes from
any stream which supports byte input. Bytes are represented as integer
values in the range 0 to 255.

Note that if a stream supports both byte input and character input, then mixing
the two operations will interfere with the UTF-8 decoding.

These functions return
.code nil
when the end of data is reached.  Errors are
represented as exceptions.

See also:
.code get-lines

.coNP Function @ get-string
.synb
.mets (get-string >> [ stream >> [ count <> [ close-after-p ]]])
.syne
.desc
The
.code get-string
function reads characters from a stream, and assembles them into
a string, which is returned. If the
.meta stream
argument is omitted, then the
.code *stdin*
stream is used.

The stream is closed after extracting the data, unless
.meta close-after-p
is specified as
.codn nil .
The default value of this argument is
.codn t .

If the
.meta count
argument is missing, then all of the characters from the
stream are read and assembled into a string.

If present, the
.meta count
argument should be a positive integer indicating
a limit on how many characters to read. The returned string will be no
longer than
.metn count ,
but may be shorter.

.coNP Functions @ unget-char and @ unget-byte
.synb
.mets (unget-char < char <> [ stream ])
.mets (unget-byte < byte <> [ stream ])
.syne
.desc
These functions put back, into a stream, a character or byte which was
previously read.  The character or byte must match the one which was most
recently read. If the
.meta stream
argument is omitted, then the
.code *stdin*
stream is used.

If the operation succeeds, the byte or character value is returned.
A
.code nil
return indicates that the operation is unsupported.

Some streams do not support these operations; some support
only one of them.   In general, if a stream supports
.codn get-char ,
it supports
.codn unget-char ,
and likewise for
.code get-byte
and
.codn unget-byte .

Streams may require a pushed back byte or character to match
the character which was previously read from that stream
position, and may not allow a byte or character to be pushed
back beyond the beginning of the stream.

Space may be available for only one byte of pushback under the
.code unget-byte
operation.

The number of characters that may be pushed back by
.code unget-char
is not limited.

Pushing both a byte and a character, in either order, is also unsupported.
Pushing a byte and then reading a character, or pushing a character and
reading a byte, are unsupported mixtures of operations.

If the stream is binary, then pushing back a byte decrements its position,
except if the position is already zero. At that point, the position becomes
indeterminate.

The behavior of pushing back immediately after a
.code seek-stream
positioning operation is unspecified.

.coNP Functions @, put-string @, put-line @ put-char and @ put-byte
.synb
.mets (put-string < string <> [ stream ])
.mets (put-line >> [ string <> [ stream ]])
.mets (put-char < char <> [ stream ])
.mets (put-byte < byte <> [ stream ])
.syne
.desc
These functions perform output on an output stream. The
.meta stream
argument
must be an output stream which supports the given operation. If it is omitted,
then
.code *stdout*
is used.

The
.code put-char
function writes a character given by
.code char
to a stream. If the
stream is based on bytes, then the character is encoded into UTF-8 and multiple
bytes are written. Streams which support
.code put-char
also support put-line, and
.codn put-string .

The
.code put-string
function writes the characters of a string out to
the stream as if by multiple calls to put-char. The
.meta string
argument
may be a symbol, in which case its name is used as the string.

The
.code put-line
function is like
.codn put-string ,
but also writes an additional newline
character. The string is optional in
.codn put-line ,
and defaults to the empty string.

The
.code put-byte
function writes a raw byte given by the
.meta byte
argument
to
.metn stream ,
if
.meta stream
supports a byte write operation. The byte
value is specified as an integer value in the range 0 to 255.

All these functions return
.codn t .
On failure, they do not return, but throw exceptions of type
.codn file-error .

.coNP Functions @ put-strings and @ put-lines
.synb
.mets (put-strings < sequence <> [ stream ]])
.mets (put-lines < sequence <> [ stream ]])
.syne
.desc
These functions assume
.meta sequence
to be a sequence of strings, or of
symbols, or a mixture thereof. These strings are sent to the stream.  The
.meta stream
argument must be an output stream.  If it is omitted, then
.code *stdout*
is used.

The
.code put-strings
function iterates over
.meta sequence
and writes each element
to the stream as if using the
.code put-string
function.

The
.code put-lines
function iterates over
.code sequence
and writes each element
to the stream as if using the
.code put-line
function.

Both functions return
.codn t .

.coNP Function @ flush-stream
.synb
.mets (flush-stream <> [ stream ])
.syne
.desc
The
.code flush-stream
function is meaningful for output streams which accumulate data
which is passed on to the operating system in larger transfer units.
Calling
.code flush-stream
causes all accumulated data inside
.meta stream
to be passed
to the operating system. If called on streams for which this function is not
meaningful, it does nothing, and returns
.codn nil .

If
.meta stream
is omitted, the current value of
.code *stdout*
is used.

.coNP Function @ seek-stream
.synb
.mets (seek-stream < stream < offset << whence )
.syne
.desc
The
.code seek-stream
function is meaningful for file streams. It changes the
current read/write position within
.metn stream .
It can also be used to determine the current position: see the notes about the
return value below. 

The
.meta offset
argument is a positive or negative integer which gives a
displacement that is measured from the point identified by the
.meta whence
argument.

Note that for text files, there isn't necessarily a 1:1 correspondence between
characters and positions due to line-ending conversions and conversions
to and from UTF-8.

The
.meta whence
argument is one of three keywords: :from-start, :from-current
and :from-end. These denote the start of the file, the current position
and the end of the file.

If
.meta offset
is zero, and
.meta whence
is
.codn :from-current ,
then
.code seek-stream
returns the current absolute position within the
stream, if it can successfully obtain it. Otherwise, it
returns
.code t
if it is successful.

If a character has been successfully put back into a text stream with
.code unget-char
and is still pending, then the position value is unspecified. If a
byte has been put back into a binary stream with
.codn unget-byte ,
and the previous position wasn't zero, then the position is decremented by one.

On failure, it throws an exception of type
.codn stream-error .

.coNP Function @ truncate-stream
.synb
.mets (truncate-stream < stream <> [ length ])
.syne
.desc
The
.code truncate-stream
causes the length of the underlying file associated with
.meta stream
to be set to
.meta length
bytes.

The stream must be a file stream, and must be open for writing.

If
.meta length
is omitted, then it defaults to the current position, retrieved
as if by invoking the
.code seek-stream
with an
.meta offset
argument of zero and
.meta whence
argument of
.codn :from-current .
Hence, after the
.code truncate-stream
operation, that position is one byte past the end of the file.

.coNP Functions @ stream-get-prop and @ stream-set-prop
.synb
.mets (stream-get-prop < stream << indicator )
.mets (stream-set-prop < stream < indicator << value )
.syne
.desc
These functions get and set properties on a stream. Only certain properties
are meaningful with certain kinds of streams, and the meaning depends on
the stream. If two or more stream types support a property of the same name, it
is expected that the property has the same or similar meaning for both
streams to the maximum extent that similarity is possible.

The
.code stream-set-prop
function sets a property on a stream. The
.meta indicator
argument is a symbol, usually a keyword symbol, denoting the property,
and
.meta value
is the property value. If the stream understands and accepts the
property, the function returns
.codn t .
Otherwise it returns
.codn nil .

The
.code stream-get-prop
function inquires about the value of a property on a
stream. If the stream understands the property, then it returns its current
value.  If the stream does not understand a property, nil is returned, which is
also returned if the property exists, but its value happens to be
.codn nil .

The
.code :name
property is widely supported by streams of various types. It associates
the stream with a name. This property is not always modifiable.

File, process and stream socket I/O streams have a
.code :fd
property which can be accessed, but not modified. It retrieves
the same value as the
.code fileno
function.

The "real time"
property supported by these streams, connected with the
.code real-time-stream-p
function, also appears as the
.code :real-time
property.

I/O streams also have a property called
.code :byte-oriented
which, if set, suppresses the decoding of UTF-8 on character input. Rather,
each byte of the file corresponds directly to one character. Bytes
in the range 1 to 255 correspond to the character code points U+0001
to U+00FF. Byte value 0 is mapped to the code point U+DC00.

The logging priority of the
.code *stdlog*
syslog stream is controlled by the
.code :prio
property.

If
.meta stream
is a catenated stream (see the function
.codn make-catenated-stream )
then these functions transparently operate on the current head stream of the
catenation.

.coNP Functions @ make-catenated-stream and @ cat-streams
.synb
.mets (make-catenated-stream << stream *)
.mets (cat-streams << stream-list )
.syne
.desc
The
.code make-catenated-stream
function takes zero or more arguments which
are input streams of the same type, and combines
them into a single virtual stream called a catenated stream.

The
.code cat-streams
function takes a single list of input streams of
the same type, and similarly combines them into a catenated stream.

A catenated stream does not support seeking operations or output,
regardless of the capabilities of the streams in the list.

If the stream list is not empty, then the leftmost element of the
list is called the head stream.

The
.codn get-char ,
.codn get-byte ,
.codn get-line ,
.code unget-char
and
.code unget-byte
functions delegate
to the corresponding operations on the head stream, if it exists.
If the stream list is empty, they return
.code nil
to the caller.

If the
.codn get-char ,
.code get-byte
or
.code get-line
operation on the head stream yields
.codn nil ,
and there are more lists in the stream, then the stream is closed, removed from
the list, and the next stream, if any, becomes the head list. The operation is
then tried again.  If any of these operations fail on the last list, it is not
removed from the list, so that a stream remains in place which can take the
.code unget-char
or
.code unget-byte
operations.

In this manner, the catenated streams appear to be a single stream.

Note that the operations can fail due to being unsupported. It is
the caller's responsibility to make sure all of the streams in the list
are compatible with the intended operations.

If the stream list is empty then an empty catenated stream is produced.
Input operations on this stream yield
.codn nil ,
and the
.code unget-char
and
.code unget-byte
operations throw an exception.

.coNP Function @ catenated-stream-p
.synb
.mets (catenated-stream-p << obj )
.syne
.desc
The
.code catenated-stream-p
function returns
.code t
if
.meta obj
is a catenated stream. Otherwise it returns
.codn nil .

.coNP Function @ catenated-stream-push
.synb
.mets (catenated-stream-push < new-stream << cat-stream )
.syne
.desc
The
.code catenated-stream-push
function pushes
.meta new-stream
to the front of the stream list inside
.metn cat-stream .

If an
.code unget-byte
or
.code unget-char
operation was successfully performed on
.meta cat-stream
previously to a call to
.codn catenated-stream-push ,
those operations were forwarded to the front stream.
If those bytes or characters are still pending,
they are pending inside that stream, and thus
are logically preceded by the contents
of
.metn new-stream .

.coNP Functions @ open-files and @ open-files*
.synb
.mets (open-files < path-list >> [ alternative-stream <> [ mode-string ]])
.mets (open-files* < path-list >> [ alternative-stream <> [ mode-string ]])
.syne
.desc
The
.code open-files
and
.code open-files*
functions create a list of streams by invoking
the
.code open-file
function on each element of
.metn path-list .
By default, the mode string
.str r
is passed to
.codn open-file ;
if the
.meta mode-string
argument specified, it overrides this default. In that situation,
the specified mode should permit reading.

These streams are turned
into a catenated stream as if applied as arguments to
.codn make-catenated-stream .

The effect is that multiple files appear to be catenated together into a single
input stream.

If the optional
.meta alternative-stream
argument is supplied, then if
.meta path-list
is empty,
.meta alternative-stream
is returned instead of an empty catenated stream.

The difference between
.code open-files
and
.code open-files*
is that
.code open-files
creates all of the
streams up-front. So if any of the paths cannot be opened, the operation throws.
The
.code open-files*
variant is lazy: it creates a lazy list of streams out of the
path list. The streams are opened as needed: before the second stream is opened,
the program has to read the first stream to the end, and so on.

.TP* Example:

Collect lines from all files that are given as arguments on the command line. If
there are no files, then read from standard input:

.verb
   @(next (open-files *args* *stdin*))
   @(collect)
   @line
   @(end)
.brev

.coNP Function @ abs-path-p
.synb
.mets (abs-path-p << path )
.syne
.desc
The
.code abs-path-function
tests whether the argument
.meta path
is an absolute path, returning a
.code t
or
.code nil
indication.

The function behaves in the same manner on all platforms, implementing
a platform-agnostic definition of
.IR "absolute path" ,
as follows.

An absolute path is a string which either begins with a slash or backslash
character, or which begins with an alphanumeric word, followed by a colon,
followed by a slash or backslash.

The empty string isn't an absolute path.

Examples of absolute paths:

.verb
  /etc
  c:/tmp
  ftp://user@server
  disk0:/home
  Z:\eUsers
.brev

Examples of strings which are not absolute paths:

.mono
.mets >> ( the < empty << string )
  .
  abc
  foo:bar/x
  $:\eabc
.onom

.coNP Function @ pure-rel-path-p
.synb
.mets (pure-rel-path-p << path )
.syne
.desc
The
.code pure-rel-path-p
function tests whether the string
.meta path
represents a
.IR "pure relative path" ,
which is defined as a path which isn't absolute according to
.codn abs-path-p ,
which isn't the string
.str .
(single period),
which doesn't begin with a period followed by a slash or backslash,
and which doesn't begin with alphanumeric word
terminated by a colon.

The empty string is a pure relative path.

Other examples of pure relative paths:

.verb
  abc.d
  .tmp/bar
  1234
  x
  $:/xyz
.brev

Examples of strings which are not pure relative paths:

.verb
  .
  /
  /etc
  ./abc
  .\e
  foo:
  $:\eabc
.brev

.coNP Functions @ dir-name and @ base-name
.synb
.mets (dir-name << path )
.mets (base-name < path <> [ suffix ])
.syne
.desc
The
.code dir-name
and
.code base-name
functions calculate, respective, the directory part and
base name part of a path name.

The calculation is performed in a platform-dependent way, using the
characters in the variable
.code path-sep-chars
as path component separators.

Both functions first remove from any further consideration all superfluous
trailing occurrences of the directory separator characters from
.codn path .
Thus input such as
.str "a////"
is reduced to just
.strn "a" ,
and
.str "///"
is reduced to
.strn "/" .

The resulting trimmed path is the
.I "effective path" .

If the effective path is an empty string, then
.code dir-name
returns
.str "."
and
.code base-name
returns the empty string.

If the effective path is not empty, and contains no path separator
characters, then
.code dir-name
returns
.str "."
and
.code base-name
returns the effective path.

Otherwise, the effective path is divided into two parts: the
.I "raw directory prefix"
and the remainder.

The raw directory prefix is the maximally long prefix of the effective
path which ends in a separator character.

The
.code dir-name
function returns the raw directory prefix, if that prefix consists of
nothing but a single directory separator character. Otherwise it
returns the raw directory prefix, with the trailing path separator
removed.

The
.code base-name
function returns the remaining part of the effective path, after
the raw directory prefix.

If the
.meta suffix
argument is given to
.codn base-name ,
then the returned base name is adjusted as follows. If the base
name ends in
.meta suffix
then a trimmed version of the base name is returned instead, with that suffix
removed. This adjustment isn't performed if it would result in an empty
string being returned.

.coNP Function @ path-cat
.synb
.mets (path-cat < dir-path << rel-path )
.syne
.desc
The
.code path-cat
function joins the directory path name given by the character
string argument
.meta dir-path
with the relative path name given by
.metn rel-path ,
returning the joined path.

The function is related to the functions
.code dir-name
and
.code base-name
in the following way: if
.meta p
is some path denoting an object in the file system, then
.code "(path-cat (dir-name p) (base-name p))"
produces a path
.meta p*
which denotes the same object. The paths
.meta p
and
.meta p*
might not be equivalent strings.

The
.code path-cat
function ensures that paths are joined without superfluous
path separator characters, regardless of whether
.meta dir-path
ends in a separator.

If a separator must be added, the character
.code /
(forward slash) is always used, even on platforms where
.code \e
(backslash) is also a pathname separator, and even if either argument includes
backslashes.

The
.code path-cat
function eliminates trivial occurrences of the
.code .
(dot) path component. It preserves trailing separators in the following
way: if
.meta rel-path
ends in a path separator character, then the returned string shall
end in that character; and if
.meta rel-path
vanishes entirely because it is equivalent to the dot, then the returned
string is
.meta dir-name
itself.

.TP* Examples:

.verb
  (path-cat "" "")    -->  ""
  (path-cat "" ".")   -->  ""
  (path-cat "." "")   -->  ""
  (path-cat "." ".")  -->  ""

  (path-cat "abc" ".")  -->  "abc"
  (path-cat "." "abc")  -->  "abc"

  (path-cat "./" ".")   -->  "./"
  (path-cat "."  "./")  -->  "./"

  (path-cat "abc/" ".")  -->  "abc/"
  (path-cat "./" "abc")  -->  "abc"

  (path-cat "/" ".")    --> "/"

  (path-cat "/" "abc")  --> "/abc"

  (path-cat "ab/cd" "ef")  --> "ab/cd/ef"
.brev


.coNP Variable @ path-sep-chars
.desc
The
.code path-sep-chars
variable holds a string consisting of the characters which the underlying
operating system recognizes as path name separators.

If a particular of these characters is considered preferred on
the host platform, that character is placed in the first position of
.codn path-sep-chars .

Altering the value of this variable has no effect on any \*(TL library
function.

.coNP Functions @ read and @ iread
.synb
.mets (read >> [ source
.mets \ \ \ \ \ \  >> [ err-stream >> [ err-retval >> [ name <> [ lineno ]]]]])
.mets (iread >> [ source
.mets \ \ \ \ \ \ \  >> [ err-stream >> [ err-retval >> [ name <> [ lineno ]]]]])
.syne
.desc
The
.code read
function converts text denoting \*(TL structure, into the
corresponding data structure. The
.meta source
argument may be either a character
string, or a stream.  If it is omitted, then
.code *stdin*
is used as the stream.

The source must provide the text representation of one complete \*(TL object.

Multiple calls to read on the same stream will extract successive objects
from the stream. To parse successive objects from a string, it is necessary
to convert it to a string stream.

The optional
.meta err-stream
argument can be used to specify a stream to which
parse errors diagnostics are sent. If absent, the diagnostics are suppressed.

The optional
.meta name
argument can be used to specify the file name which is used for reporting
errors. If this argument is missing, the name is taken from the name
property of the
.meta source
argument if it is a stream, or else the word
.code string
is used as the name if
.meta source
is a string.

The optional
.code lineno
argument, defaulting to 1, specifies the starting line number. This,
like the
.meta name
argument, is used for reporting errors.

If there are no parse errors, the function returns the parsed data
structure. If there are parse errors, and the
.meta err-retval
parameter is
present, its value is returned. If the
.meta err-retval
parameter
is not present, then an exception of type
.code syntax-error
is thrown.

The
.code iread
function ("interactive read") is similar to
.code read
except that it parses a modified version of the syntax. The modified
syntax does not support the application of the dot and dotdot operators
on a top-level expression. For instance, if the input is
.code a.b
or
.code "a .. b"
then
.code iread
will only read the
.code a
token whereas
.code read
will read the entire expression.

This modified syntax allows
.code iread
to return immediately when an expression is recognized, which is the
expected behavior if the input is being read from an interactive terminal.
By contrast,
.code read
waits for more input after seeing a complete expression, because of the
possibility that the expression will be further extended by means of the dot or
dotdot operators. An explicit end-of-input signal must be given from the
terminal to terminate the expression.

The special variable
.code *rec-source-loc*
controls whether these functions record source location info similarly to
.codn load .
Note: if these functions are used to scan data which is evaluated as Lisp code,
it may be useful to set
.code *rec-source-loc*
true in order to obtain better diagnostics. However, source location recording
incurs a performance and storage penalty.

.coNP Function @ record-adapter
.synb
.mets (record-adapter < regex >> [ stream <> [ include-match ]])
.syne
.desc
The
.code record-adapter
function returns a new stream object which acts as an
.I adapter
to the existing
.metn stream .

If an argument is not specified for
.metn stream ,
then the
.code *std-input*
stream is used.

With the exception of
.metn get-line ,
all operations on the returned adapter transparently delegate to the original
.meta stream
object.

When the
.code get-line
function is used on the adapter, it behaves differently. A string is
extracted from
.metn stream ,
and returned. However, the string isn't a line delimited by a newline
character, but rather a record delimited by
.metn regex .
This record is extracted as if by a call to the
.code read-until-match
function, invoked with the
.metn regex ,
.meta stream
and
.meta include-match
arguments.

All behavior which is built on the
.code get-lines
function is affected by the record-delimiting semantics of a record adapter's
.code get-line
implementation. Notably, the
.code get-lines
and
.code lazy-stream-cons
functions return a lazy list of delimited records rather than of lines.

.SS* Stream Output Indentation
\*(TL streams provide support for establishing hanging indentations
in text output. Each stream which supports output has a built-in state variable
called indentation mode, and another variable indicating the current
indentation amount. When indentation mode is enabled, then prior to the
first character of every line, the stream prepends the indentation: space
characters equal in number to the current indentation value.
This logic is implemented by the
.code put-char
and
.code put-string
functions, and all functions based on these. The
.code put-byte
function does not interact with indentation. The column position tracking
will be incorrect if byte and character output are mixed, affecting
the placement of indentation.

Indentation mode takes on four numeric values, given by the four
variables
.codn indent-off ,
.codn indent-data ,
.code indent-code
and
.codn indent-foff .
As far as stream output is concerned, the code and data modes
represented by
.code indent-code
and
.code indent-data
behave
the same way: both represent the "indentation turned on" state.
The difference between them influences the behavior of the
.code width-check
function. This function isn't used by any lower-level stream output
routines. It is used by the object printing functions like
.code print
and
.code pprint
to break up long lines.
The
.code indent-off
and
.code intent-foff
modes are also treated the same way by lower level stream output,
indicating "indentation turned off". The modes are distinguished
by
.code print
and
.code pprint
in the following way:
.code indent-off
is a "soft" disable which allows these object-printing routines
to temporarily turn on indentation while traversing aggregate objects.
Whereas the
.code indent-foff
("force off") value is a "hard" disable: the object-printing routines will not
enable indentation and will not break up long lines.

.coNP Variables @, indent-off @, indent-data @ indent-code and @ indent-foff
.desc
These variables hold integer values representing output stream
indentation modes. The value of
.code indent-off
is zero.

.coNP Functions @ get-indent-mode and @ set-indent-mode
.synb
.mets (get-indent-mode << stream )
.mets (set-indent-mode < stream << new-mode )
.mets (test-set-indent-mode < stream < compare-mode << new-mode )
.syne
.desc
These functions retrieve and manipulate the stream indent mode.
The
.code get-indent-mode
retrieves the current indent mode of
.metn stream .
The
.code set-indent-mode
function sets the indent mode of
.meta stream
to
.meta new-mode
and returns the previous mode.

Note: it is encouraged to save and restore the indentation mode,
and in a way that is exception safe.
If a block of code sets up indentation on a stream such as
.code *stdout*
and is terminated by an exception, the indentation will remain in
effect and affect subsequent output. The
.code with-resources
macro or
.code unwind-protect
operator may be used.

.coNP Functions @ test-set-indent-mode and @ test-neq-set-indent-mode
.synb
.mets (test-set-indent-mode < stream < compare-mode << new-mode )
.mets (test-neq-set-indent-mode < stream < compare-mode << new-mode )
.syne
.desc
The
.code test-set-indent-mode
function sets the indent mode of
.meta stream
to
.meta new-mode
if, and only if,
its current mode is equal to
.metn compare-mode .
Whether or not it changes the mode, it returns the previous mode.

The
.code test-neq-set-indent-mode
only differs in that it sets
.meta stream
to
.meta new-mode
if, and only if,
the current mode is
.B not
equal to
.metn compare-mode .

.coNP Functions @, get-indent @ set-indent and @ inc-indent
.synb
.mets (get-indent << stream )
.mets (set-indent < stream << new-indent )
.mets (inc-indent < stream << indent-delta )
.syne
.desc
These functions manipulate the indentation value of the stream.
The indentation takes effect the next time a character is output
following a newline character.

The
.code get-indent
function retrieves the current indentation amount.

The
.code set-indent
function sets
.metn stream 's
indentation to the value
.meta new-indent
and returns the previous value.
Negative values are clamped to zero.

The
.code inc-indent
function sets
.metn stream 's
indentation relative to the current printing column position,
and returns the old value.
The indentation is calculated by adding
.meta indent-delta
to the current column position.
If a negative indentation results, it is clamped to zero.

.coNP Function @ width-check
.synb
.mets (width-check < stream << alt-char )
.syne
.desc
The
.code width-check
function examines the state of the stream, taking into consideration
the current printing column position, the indentation state,
the indentation amount and an internal "force break" flag. It makes a decision
either to introduce a line break by printing a newline character, or else to
print the
.meta alt-char
character.

If a decision is made not to emit a line break, but
.meta alt-char
is
.codn nil ,
then the function has no effect at all.

The return value is
.code t
if the function has issued a line break, otherwise
.codn nil .

.coNP Function @ force-break
.synb
.mets (force-break << stream )
.syne
.desc
If the
.code force-break
function is called on a stream, it sets an internal "force break" flag which
affects the future behavior of
.codn width-check .
The
.code width-check
function examines this flag. If the flag is set,
.code width-check
clears it, and issues a line break without considering any other
conditions.

The
.metn stream 's
.code force-break
flag is also cleared whenever a newline character is output.

The
.code force-break
function returns
.codn stream .

Note: the
.code force-break
is involved in line breaking decisions. Whenever a list or list-like syntax is
being printed, whenever an element of that syntax is broken into multiple
lines, a break is forced after that element, in order to avoid output
which resembles the following diagonally-creeping pattern:

.verb
  (a b c (d e f
          g h i) j (k l
                    m n) o)
.brev

but instead is rendered in a more horizontally compact pattern:

.verb
  (a b c (d e f
          g h i)
   j (k l
      m n)
   o)
.brev

When the printer prints
.code "(d e f g h i)"
it uses the
.code width-check
function between the elements; that function issues the
break between the
.code f
and
.codn g .
The printer monitors the return value of
.codn width-check ;
it knows that since one of the calls returned
.codn t ,
the object had been broken into two or more lines. It then calls
.code force-break
after printing the last element
.code i
of that object.  Then, due to the force flag, the outer recursion of the
printer which is printing
.code "(a b c ...)"
will experience a break when it calls
.code width-check
before printing
.codn j .

Custom
.code print
methods defined on structure objects can take advantage of
.code width-check
and
.code force-break
in the same way so that application-defined output integrates
with the formatting algorithm.

.SS* Stream Output Limiting

Streams have two properties which are used by the The \*(TL object printer to
optionally truncate the output generated by aggregate objects.

A stream can specify a maximum length for aggregate objects via the
.code set-max-length
function. Using the
.code set-max-depth
function, the maximum depth can also be specified.

This feature is
useful when diagnostic output is being produced, and the objects involved are
so large that the diagnostic output overwhelms the output device or the user,
so as to become uninformative. Output limiting also prevents the printer's
non-termination on infinite, lazy structures.

It is recommended that functions which operate on streams passed in as
parameters save and restore these parameters, if they need to manipulate them,
for instance using
.codn with-resources :

.verb
  (defun output-function (arg stream)
    ;; temporarily impose maximum width and depth
    (with-resources ((ml (set-max-length stream 42)
                         (set-max-length stream ml))
                     (mw (set-max-depth stream 12)
                         (set-max-depth stream mw)))
      (prinl arg stream)
      ...))
.brev

.coNP Function @ set-max-length
.synb
.mets (set-max-length < stream << value )
.syne
.desc
The
.code set-max-length
function establishes the maximum length for aggregate object printing.
It affects the printing of lists, vectors, hash tables, strings
as well as quasiliterals and quasiword list literals (QLLs).

The default value is 0 and this value means that no limit is imposed.
Otherwise, the value must be a positive integer.

When the list, vector or hash table object being printed has more
elements than the maximum length, then elements are printed only up to
the maximum count, and then the remaining elements are summarized by
printing the
.code ...
(three dots) character sequence as if it were an additional element.
This sequence is an invalid token; it cannot be read as input.

When a character string is printed, any positive value of
the maximum length which is less than 15 is considered to be 15.
The maximum length specifies the number of characters of the
a string which are output.

If a string which exceeds the maximum length is being printed
with read-print consistency, as by the
.code print
function, then only a prefix of the string is printed, limited
to the maximum number of characters.  Then, the literal syntax is
closed using the character sequence
.code \e...\(dq
(backslash, dot, dot, dot, double quote)
whose leading invalid escape sequence
.code \e.
(backslash, dot) ensures that the truncated object is not readable.

If a string which exceeds the maximum length is being printed
without read-print consistency, as by the
.code pprint
function, then only a prefix of the string is printed, limited
to the maximum number of characters. Then the
character sequence
.code ...
is emitted.

Quasiliterals are treated using a combination of behaviors.  Elements of a
quasiliteral are literal sequence of text, and embedded variables and
expressions.  The maximum length specifies both the maximum number of elements
in the quasiliteral, and the maximum number of characters in any element which
is a sequence of text. When either limit is exceeded, the quasiliteral
is immediately terminated with the sequence
.code \e...`
(escaped dot, dot, dot, backtick). The maximum limit is applied to
the units of text cumulatively, rather than individually. As in the case of
string literals, smaller limit values than 15 are treated as 15,
but only for the cumulative text length limit. For limiting the number of
elements, the count is used as-is.

When a QLL is printed, the space-separated elements
of the literal are individually subject to the maximum length limit as if
they were independent quasiliterals. Furthermore, the sequence of these
elements is subject to the maximum length. If there are more elements in the
QLL, then the sequence
.code \e...`
(escaped dot, dot, dot, backtick) is emitted and thus the QLL ends.

The
.code set-max-length
function returns the previous value.

.coNP Function @ set-max-depth
.synb
.mets (set-max-depth < stream << value )
.syne
.desc
The
.code set-max-length
function establishes the maximum depth for the printing of nested
objects. It affects the printing of lists, vectors, hash tables
and structures.  The default value is 0 and this value means that no limit is
imposed.  Otherwise, the value must be a positive integer.

The depth of an object not enclosed in any object is zero. The depth of the
element of an aggregate is one greater than the depth of the aggregate itself.
For instance, given the list
.code "(1 (2 3))"
the list itself has depth 0, the atom
.code 1
has depth 1, as does the sublist
.codn "(2 3)" ,
and the
.code 2
and
.code 3
atoms have depth 2.

When an object is printed whose depth exceeds the maximum depth, then three dot
character sequence
.code ...
is printed instead of that object. This notation is an invalid token; it cannot be
read as input.

Additionally, when a vector, list, hash table or structure is printed which itself
doesn't exceed the maximum depth, but whose elements do exceed, then that object
is summarized, respectively, as
.codn "(...)" ,
.codn "#(...)" ,
.code "H#(...)"
and
.codn "S#(...)" ,
rather than repeating the
.code ...
sequence for each of its elements.

The
.code set-max-depth
function returns the previous value.

.SS* Coprocesses
.coNP Functions @ open-command and @ open-process
.synb
.mets (open-command < system-command <> [ mode-string ])
.mets (open-process < program < mode-string <> [ argument-list ])
.mets (open-subprocess < program < mode-string
.mets \ \  >> [ argument-list <> [ function ]])
.syne
.desc
These functions spawn external programs which execute concurrently
with the \*(TX program. Both functions return a unidirectional stream for
communicating with these programs: either an output stream, or an input
stream, depending on the contents of
.metn mode-string .

In
.codn open-command ,
the
.meta mode-string
argument is optional, defaulting to
the value
.str r
if it is missing.  See the
.code open-file
function for a discussion of modes.
The
.code open-command
function is implemented using POSIX
.codn popen .
Those elements of
.meta mode-string
which are applicable to
.code popen
are passed to it, and hence their semantics follows from
their processing in that function.

The
.code open-command
function accepts, via the
.meta system-command
string parameter, a
system command, which is in a system-dependent syntax. On a POSIX system, this
would be in the POSIX Shell Command Language.

The
.code open-process
function specifies a program to invoke via the
.meta command
argument. This is subject to the operating system's search strategy.
On POSIX systems, if it is an absolute or relative path, it is treated as
such, but if it is a simple base name, then it is subject to searching
via the components of the PATH environment variable. If open-process
is not able to find
.metn program ,
or is otherwise unable to execute
the program, the child process will exit, using the value of the C variable
.code errno
as its exit status. This value can be retrieved via
.codn close-stream .

The
.meta argument-list
argument is a list of strings which specifies additional
optional arguments to be passed passed to the program. The
.meta program
argument
becomes the first argument, and
.meta argument-string
become the second and
subsequent arguments. If
.meta argument-strings
is omitted, it defaults to empty.

If a coprocess is open for writing
.mono
.meti >> ( mode-string
.onom
is specified as
.strn w ),
then
writing on the returned stream feeds input to that program's standard input
file descriptor. Indicating the end of input is performed by closing the
stream.

If a coprocess is open for reading
.mono
.meti >> ( mode-string
.onom
is specified as
.strn r ),
then
the program's output can be gathered by reading from the returned stream.
When the program finishes output, it will close the stream, which can be
detected as normal end of data.

The standard input and error file descriptors of an input coprocess
are obtained from the streams stored in the
.code *stdin*
and
.code *stderr*
special variables, respectively. Similarly, the standard output and error
file descriptors of an output coprocess are obtained from the
.code *stdout*
and
.code *stderr*
special variables.  These variables must contain streams on which the
.code fileno
function is meaningful, otherwise the operation will fail.
What this functionality means is that re-binding the special variables
for standard streams has the effect of redirection. For example,
the following two expressions achieve the same effect of creating
a stream which reads the output of the
.code cat
program, which reads and produces the contents of the file
.codn text-file .

.verb
  ;; redirect input by rebinding *stdin*
  (let ((*stdin* (open-file "text-file")))
    (open-command "cat"))

  ;; redirect input using POSIX shell redirection syntax
  (open-command "cat < text-file")
.brev

The following is erroneous:

.verb
  ;; (let ((*stdin* (make-string-input-stream "abc")))
       (open-command "cat"))
.brev

A string input or output stream doesn't have an operating system file
descriptor; it cannot be passed to a coprocess.

The streams
.codn *stdin* ,
.code *stdout*
and
.code *stderr*
are not synchronized with their underlying file descriptors prior to
the execution of a coprocess. It is up to the program to ensure that
previous output to
.code *stdout*
or
.code *stderr*
is flushed, so that the output of the coprocess isn't re-ordered
with regard to output produced by the program. Similarly,
input buffered in
.code *stdin*
is not available to the coprocess, even though it has not
yet been read by the program. The program is responsible for preventing this
situation also.

If a coprocess terminates abnormally or unsuccessfully, an exception is raised.

On platforms which have the
.code fork
function, the
.meta mode-string
argument of
.code open-process
supports a special
.meta redirection
syntax. This syntax specifies I/O redirections which are done in the
context of the child process, before the specified program is executed.
Instances of the syntax are considered options; if
.meta mode-string
specifies a mode such as
.code r
that mode must precede the redirections. Redirections may be mixed with
other options.

Up to four redirections may be specified using one
of two forms: a short form or the long form. If more than four
redirections are specified, the
.meta mode-string
is considered ill-formed.

The short form of the syntax consists of three characters: the prefix
character
.codn > ,
a single decimal digit indicating the file descriptor to be redirected,
and then a third character which is either another digit, or else one of the
two characters
.code n
or
.codn x .
If the third character is a digit, it indicates the target file descriptor
of the redirection. For instance
.code >21
indicates that file descriptor 2 is to be redirected to 1 (so that material
written to standard error goes to the same destination as that written
to standard output).
If the third character is
.codn n ,
it means that the file descriptor will be redirected to the file
.codn /dev/null .
For instance,
.code >2n
indicates that descriptor 2 (standard error) will be redirected to
the null device. If the third character is
.codn x ,
it indicates that the file descriptor shall be closed. For instance
.code >0x
means to close descriptor 0 (standard input).

The long form of the syntax allows file descriptors that require more
than one decimal digit. It consists of the same prefix character
.code >
which is immediately followed by an open parenthesis
.codn ( .
The parenthesis is immediately followed by one or more digits which
give the to-be-redirected file descriptor. This is followed by
one or more whitespace characters, and then either another multi-digit decimal file descriptor
or one of the two letters
.code n
or
.codn x .
This second element must be immediately followed by the closing
parenthesis
.codn ) .
Thus
.code >21
and
.code >2n
may be written in the long form, respectively, as
.code ">(2 1)"
and
.codn ">(2 n)" ,
while
.code ">(32 47)"
has no short form equivalent.
Multiple redirections may be specified, in any mixture of the long and
short form. For instance
.code "r>21>0n>(27 31)"
specifies a process pipe that is open for reading, capturing the
output of the process. In that process, standard error is redirected
to standard output, standard input is connected to the null device,
and descriptor 27 is redirected to descriptor 31.

Note: on platforms which don't have a
.code fork
function, the implementation of
.code open-process
is simulated via
.code open-command
and therefore does not support the redirection syntax; it is parsed
and ignored.

The
.code open-subprocess
function is a variant of
.code open-process
that is available on platforms which have a
.code fork
function. This function has all the same argument conventions and semantics as
.codn open-process ,
adding the
.meta function
argument. If this argument isn't
.codn nil ,
then it must specify a function which can be called with no arguments.
This function is called in the child process after any redirections are
established, just before the program specified by the
.meta program
argument is executed. Moreover, the
.code open-subprocess
function allows
.meta program
to be specified as
.code nil
in which case
.meta function
must be specified. When
.meta function
returns, the child process terminates as if by a call to
.code exit*
with an argument of zero.

.SS* I/O-Related Convenience Functions

The functions in this group create a stream, perform an I/O operation
on it, and ensure that it is closed, in one convenient operation. They
operate on files or command streams.

Several other functions in this category exist, which operate with buffers.
They are documented in the Buffer Functions subsection under the
FOREIGN FUNCTION INTERFACE section.

.coNP Functions @, file-get @ file-get-string and @ file-get-lines
.synb
.mets (file-get << name )
.mets (file-get-string << name )
.mets (file-get-lines << name )
.syne
.desc
The
.code file-get
function opens a text stream over the file indicated by the string argument
.meta name
for reading, reads the printed representation of a  \*(TL object from it,
and returns that object, ensuring that the stream is closed.

The
.code file-get-string
is similar to
.code file-get
except that it reads the entire file as a text stream and returns
its contents in a single character string.

The
.code file-get-lines
function opens a text stream over the file indicated by
.meta name
and returns produces a lazy list of strings representing the lines
of text of that file as if by a call to the
.code get-lines
function, and returns that list. The stream remains open until the
list is consumed to the end, as indicated in the description of
.codn get-lines .

.coNP Functions @, file-put @ file-put-string and @ file-put-lines
.synb
.mets (file-put < name << obj )
.mets (file-put-string < name << string )
.mets (file-put-lines < name << list )
.syne
.desc
The
.codn file-put ,
.code file-put-string
and
.code file-put-lines
functions open a text stream over the file indicated by the string argument
.metn name ,
write the argument object into the file in their specific manner,
and then close the file.

If the file doesn't exist, it is created.
If it exists, it is truncated to zero length and overwritten.

The
.code file-put
function writes a printed representation of
.meta obj
using the
.code prinl
function. The return value is that of
.codn prinl .

The
.code file-put-string
function writes
.meta string
to the stream using the
.code put-string
function. The return value is that of
.codn put-string .

The
.code file-put-lines
function writes
.meta list
to the stream using the
.code put-lines
function. The return value is that of
.codn put-lines .

.coNP Functions @, file-append @ file-append-string and @ file-append-lines
.synb
.mets (file-append < name << obj )
.mets (file-append-string < name << string )
.mets (file-append-lines < name << list )
.syne
.desc
The
.codn file-append ,
.code file-append-string
and
.code file-append-lines
functions open a text stream over the file indicated by the string argument
.metn name ,
write the argument object into the stream in their specific manner,
and then close the stream.

These functions are close counterparts of, respectively,
.codn file-get ,
.code file-append-string
and
.codn file-append-lines .

These functions behave differently when the indicated file
already exists. Rather than being truncated and overwritten,
the file is extended by appending the new data to its end.

.coNP Functions @, command-get @ command-get-string and @ command-get-lines
.synb
.mets (command-get << cmd )
.mets (command-get-string << cmd )
.mets (command-get-lines << cmd )
.syne
.desc
The
.code command-get
function opens text stream over an input command pipe created for
the command string
.metn cmd ,
as if by the
.code open-command
function.  It reads the printed representation of a  \*(TL object from it, and
returns that object, ensuring that the stream is closed.

The
.code command-get-string
is similar to
.code command-get
except that it reads the entire file as a text stream and returns
its contents in a single character string.

The
.code command-get-lines
function opens a text stream over an input command pipe created for the
command string
.meta cmd
and returns produces a lazy list of strings representing the lines
of text of that file as if by a call to the
.code get-lines
function, and returns that list. The stream remains open until the
list is consumed to the end, as indicated in the description of
.codn get-lines .

.coNP Functions @, command-put @ command-put-string and @ command-put-lines
.synb
.mets (command-put < cmd << obj )
.mets (command-put-string < cmd << string )
.mets (command-put-lines < cmd << list )
.syne
.desc
The
.codn command-put ,
.code command-put-string
and
.code command-put-lines
functions open an output text stream over an output command pipe created
for the command specified in the string argument
.metn cmd ,
as if by the
.code open-command
function.
They write the argument object into the stream in their specific manner,
and then close the stream.

The
.code command-put
function writes a printed representation of
.meta obj
using the
.code prinl
function. The return value is that of
.codn prinl .

The
.code command-put-string
function writes
.meta string
to the stream using the
.code put-string
function. The return value is that of
.codn put-string .

The
.code command-put-lines
function writes
.meta list
to the stream using the
.code put-lines
function. The return value is that of
.codn put-lines .

.SS* Buffer streams
A stream type exists which allows
.code buf
objects to be manipulated through the stream interface.
A buffer stream is created using the
.code make-buf-stream
function, which can either attach the stream to an existing buffer,
or create a new buffer that can later be retrieved from the stream
using
.codn get-buf-from-stream .

Operations on the buffer stream treat the underlying buffer much like if it
were a memory-based file. Unless the underlying buffer is a "borrowed buffer"
referencing the storage belonging to another object
(such as the buffer object produced by the
.code buf-d
FFI type's get semantics) the stream operations can change the buffer's size.
Seeking beyond the end of the buffer an then writing one or more bytes
extends the buffer's length, filling the newly allocated area with zero bytes.
The
.code truncate-stream
function is supported also.
Buffer streams also support the
.code :byte-oriented
property.

Macros
.code with-out-buf-stream
and
.code with-in-buf-stream
are provided to simplify the steps involved in using buffer streams
in some common scenarios. Note that in spite of the naming of these
macros there is only one buffer stream type, which supports bidirectional I/O.

.coNP Function @ make-buf-stream
.synb
.mets (make-buf-stream <> [ buf ])
.syne
.desc
The
.code make-buf-stream
function return a new buffer stream. If the
.meta buf
argument is supplied, it must be a
.code buf
object. The stream is then associated with this object.
If the argument is omitted, a buffer of length zero is created and associated
with the stream.

.coNP Function @ get-buf-from-stream
.synb
.mets (get-buf-from-stream << buf-stream )
.syne
.desc
The
.code get-buf-from-stream
returns the buffer object associated with
.meta buf-stream
which must be a buffer stream.

.coNP Macros @ with-out-buf-stream and @ with-in-buf-stream
.synb
.mets (with-out-buf-stream >> ( var <> [ buf-expr ])
.mets \ \  << body-form *)
.mets (with-in-buf-stream >> ( var << buf-expr )
.mets \ \  << body-form *)
.syne
.desc
The
.code with-out-buf-stream
and
.code with-in-buf-stream
macros both bind variable
.meta var
to an implicitly created buffer stream, and evaluate zero or more
.metn body-form -s
in the environment where the variable is visible.

The
.meta buf-expr
argument, which may be omitted in the use of the
.code with-out-buf-stream
macro, must be an expression which evaluates to a
.code buf
object.

The
.meta var
argument must be a symbol suitable for naming a variable.

The implicitly allocated buffer stream is connected
to the buffer specified by
.meta buf-expr
or, when
.meta buf-expr
is omitted, to a newly allocated buffer.

The code generated by the
.code with-out-buf-stream
macro, if it terminates normally, yields the buffer object
as its result value.

The
.code with-in-buf-stream
returns the value of the last
.metn body-form ,
or else
.code nil
if no forms are specified.

.TP* Examples:
.verb
  (with-out-buf-stream (*stdout* (make-buf 24))
    (put-string "Hello, world!"))
  -> #b'48656c6c6f2c2077 6f726c6421000000 0000000000000000'

  (with-out-buf-stream (*stdout*) (put-string "Hello, world!"))
  -> #b'48656c6c6f2c2077 6f726c6421'
.brev

.SS* Foreign Pointers

.coNP The @ cptr type

Objects of type
.code cptr
are Lisp values which contain a foreign pointer ("C pointer"). This data type
is used by the
.code dlopen
function and is generally useful in conjunction with the Foreign Function
Interface (FFI).  An arbitrary pointer emanating from a foreign function
can be captured as a
.code cptr
value, which can be passed back into foreign code. For this purpose, there
exits also a matching FFI type called
.codn cptr .

The
.code cptr
type supports a symbolic type tag, which defaults to
.codn nil .
The type tag plays a role in FFI. The FFI
.code cptr
type supports a tag attribute. When a
.code cptr
object is converted to a foreign pointer under the control of the FFI
type, and that FFI type has a tag other than
.codn nil ,
the object's tag must exactly match that of the FFI type, or the conversion
throws an error. In the reverse direction, when a foreign pointer is
converted to a
.code cptr
object under control of the FFI
.code cptr
type, the object inherits the type tag from the FFI type.

.coNP Function @ cptr-int
.synb
.mets (cptr-int < integer <> [ type-symbol ])
.syne
.desc
The
.code cptr-int
function converts
.meta integer
into a pointer in a system-specific way
which is consistent with the system's addressing structure. Then it returns
that pointer contained in a
.code cptr
object.

The
.meta integer
parameter must be an integer which is in range for a pointer value.
Note: this range is wider than the
.code fixnum
range; a portion of the range of
.code bignum
integers can denote pointers.

The
.meta type-symbol
argument should be a symbol. If omitted, it defaults to
.codn nil .
This symbol becomes the
.code cptr
object's type tag.

.coNP Function @ cptr-obj
.synb
.mets (cptr-obj < object <> [ type-symbol ])
.syne
.desc
The
.code cptr-obj
function converts
.meta object
object directly to a
.codn cptr .

The
.meta object
argument may be of any type.

The raw representation of
.meta object
is simply stored in a new instance of
.code cptr
and returned.

The
.meta type-symbol
argument should be a symbol. If omitted, it defaults to
.codn nil .
This symbol becomes the
.code cptr
object's type tag.

The lifetime of the returned
.code cptr
object is independent from that of
.metn object .
If the lifetime of
.meta object
reaches its end before that of the
.codn cptr ,
the pointer stored inside the
.code cptr
becomes invalid.

.coNP Function @ int-cptr
.synb
.mets (int-cptr << cptr )
.syne
.desc
The
.code int-cptr
function retrieves the pointer value of the
.meta cptr
object as an integer.

If an integer
.meta n
is in a range convertible to
.code cptr
type, then the expression
.mono
.meti (int-cptr (cptr-int << n ))
.onom
reproduces
.metn n .

.coNP Function @ cptr-buf
.synb
.mets (cptr-buf < buf <> [ type-symbol ])
.syne
.desc
The
.code cptr-buf
returns a
.code cptr
object which holds a pointer to a buffer object's storage
area. The
.meta buf
argument must be of type
.codn buf .

The
.meta type-symbol
argument should be a symbol. If omitted, it defaults to
.codn nil .
This symbol becomes the
.code cptr
object's type tag.

The lifetime of the returned
.code cptr
object is independent from that of
.metn buf .
If the lifetime of
.meta buf
reaches its end before that of the
.codn cptr ,
the pointer stored inside the
.code cptr
becomes invalid.

.coNP Function @ cptr-cast
.synb
.mets (cptr-cast < type-symbol << cptr )
.syne
.desc
The
.code cptr-cast
function produces a new
.code cptr
object which has the same pointer as
.meta cptr
but whose type is given by
.metn type-symbol .

Casting
.meta cptr
objects with
.code cptr-cast
circumvents the safety mechanism which
.code cptr
type tagging provides.

.coNP Function @ cptr-zap
.synb
.mets (cptr-zap << cptr )
.syne
.desc
The
.code cptr-zap
function changes the pointer value of the
.meta cptr
object to the null pointer.

The
.meta cptr
argument must be of
.code cptr
type.

The return value is
.meta cptr
itself.

Note: it is recommended to use
.code cptr-zap
when the program has taken some action which invalidates the pointer value
stored in a
.code cptr
object, where a risk exists that the value may be subsequently misused.

.coNP Function @ cptr-free
.synb
.mets (cptr-free << cptr )
.syne
.desc
The
.code cptr-free
function passes the
.meta cptr
object's pointer to the C library
.code free
function. After this action, it behaves exactly like
.codn cptr-zap .

The
.meta cptr
argument must be of
.code cptr
type.

The return value is
.meta cptr
itself.

Note: this function is unsafe. If the pointer didn't originate from the
.code malloc
family of memory allocation functions, or has already been freed, or
copies of the pointer exist which are still in use, the consequences are
likely catastrophic.

.coNP Function @ cptrp
.synb
.mets (cptrp << value )
.syne
.desc
The
.code cptrp
function tests whether
.meta value
is a
.codn cptr .
It returns
.code t
if this is the
case,
.code nil
otherwise.

.coNP Function @ cptr-type
.synb
.mets (cptr-type << cptr )
.syne
.desc
The
.code cptr-type
function retrieves the
.meta cptr
object's type tag.

.coNP Function @ cptr-get
.synb
.mets (cptr-get < cptr <> [ type ])
.syne
.desc
The
.code cptr-get
function extracts a Lisp value by converting a C object
at the memory location denoted by
.metn cptr ,
according to the FFI type
.metn type .
The external representation at the specified memory location is
is scanned according to the
.meta type
and converted to a Lisp value which is returned.

If the
.meta type
argument is specified, it must be a FFI type object.
If omitted, then the
.code cptr
object's type tag is interpreted as a FFI type symbol and resolved to
a type; the resulting type, if one is found is substituted for
.metn type .
If the lookup fails an error exception is thrown.

The
.meta cptr
object must be of type
.code cptr
and point to a memory area suitably aligned for, and large
enough to hold a foreign representation of
.metn type ,
at the byte offset indicated by the
.meta offset
argument.

If
.meta cptr
is a null pointer, an exception is thrown.

The
.code cptr-get
operation is similar to the "get semantics" performed by FFI
in order to extract the return value of foreign function
calls, and by the FFI callback mechanism to extract the
arguments coming into a callback.

The
.meta type
argument may not be a variable length type, such as an array of
unspecified size.

Note: the
.code cptr-get
and
.code cptr-out
is useful in simplifying the interaction with "semi-opaque" foreign objects:
objects which serve as a API handles that are treated as opaque pointers in API
argument calls, but which expose some internal members that the application
must access directly. The
.code cptr
objects pass through the foreign API without undergoing conversion,
as usual. The application uses these two functions to perform conversion as
necessary. Under this technique, the description of the foreign object need not
be complete. Structure members which occur after the last member that the
application is interested in need not be described in the FFI type.

.coNP Function @ cptr-put
.synb
.mets (cptr-put < cptr < obj <> [ type ])
.syne
.desc
The
.code cptr-put
function converts a Lisp value into a C representation,
which is stored at the memory location denoted by
.metn cptr ,
according to the FFI type
.metn type .
The function's return value is
.metn obj .

If the
.meta type
argument is specified, it must be a FFI type object.
If omitted, then the
.code cptr
object's type tag is interpreted as a FFI type symbol and resolved to
a type; the resulting type, if one is found is substituted for
.metn type .
If the lookup fails an error exception is thrown.

The
.meta obj
argument must be an object compatible with the conversions
implied by
.metn type .

The
.meta cptr
object must be of type
.code cptr
and point to a memory area suitably aligned for, and large
enough to hold a foreign representation of
.metn type ,
at the byte offset indicated by the
.meta offset
argument.

If
.meta cptr
is a null pointer, an exception is thrown.

It is assumed that
.meta obj
is an object which was returned by an earlier call to
.codn cptr-get ,
and that the
.meta cptr
and
.meta type
arguments are the same objects that were used in that call.

The
.code cptr-out
function performs the "out semantics" encoding action, similar
to the treatment applied to the arguments of a callback prior to
returning to foreign code.

.coNP Variable @ cptr-null
.desc
The
.code cptr-null
variable holds a null pointer as a
.code cptr
instance.

Two
.code cptr
objects may be compared for equality using the
.code equal
function, which tests whether their pointers are equal.

The
.code cptr-null
variable compares
.code equal
to values which have been subject to
.code cptr-zap
or
.codn cptr-free .

A null
.code cptr
may be produced by the expression
.codn "(cptr-obj nil)" ;
however, this creates a freshly allocated object on each evaluation.

The expression
.code "(cptr-int 0)"
also produces a null pointer on all platforms where \*(TX is found.

.coNP Function @ cptr-size-hint
.synb
.mets (cptr-size-hint < cptr << bytes )
.syne
.desc
The
.code cptr-size-hint
function indicates to the garbage collector that the given
.meta cptr
object is associated with
.meta bytes
of foreign memory that are otherwise invisible to the garbage collector.

Note: this function should be used if the foreign memory is indirectly
managed by the
.meta cptr
object in cooperation with the garbage collector. Specifically,
.meta cptr
should have a finalizer registered against it which will liberate the
foreign memory.

.SS* User-Defined Streams

In \*(TL, stream objects aren't structure types, and therefore lie outside of
the object-oriented programming system. However, \*(TL supports a delegation
mechanism which allows a structure which provides certain methods to be used as
a stream.

The function
.code make-struct-delegate-stream
takes as an argument the instance of a structure, which is
referred to as the
.IR "stream interface object" .
The function returns a stream object such that when
stream operations are invoked on this stream, it delegates these
operations to methods of the stream interface object.

A structure type called
.code stream-wrap
is provided, whose instances can serve as stream interface objects.
This structure has a slot called
.meta stream
which holds a stream, and it provides all of the methods required for
the delegation mechanism used by
.codn make-struct-delegate-stream .
This
.code stream-wrap
operations simply invoke the ordinary stream operations on the
.meta stream
slot. The
.code stream-wrap
type can be used as a base class for a derived class which intercepts
certain operations on a stream (by defining the corresponding methods) while
allowing other operations to transparently pass to the stream (via the
base methods inherited from
.codn stream-wrap ).

.coNP Function @ make-struct-delegate-stream
.synb
.mets (make-struct-delegate-stream << object )
.syne
.desc
The
.code make-struct-delegate-stream
function returns a stream whose operations depend on the
.metn object ,
a stream interface object.

The
.meta object
argument must be a structure which implements certain
subsets of, or all of, the following methods:
.codn put-string ,
.codn put-char ,
.codn put-byte ,
.codn get-line ,
.codn get-char ,
.codn get-byte ,
.codn unget-char ,
.codn unget-byte ,
.codn put-buf ,
.codn fill-buf ,
.codn close ,
.codn flush ,
.codn seek ,
.codn truncate ,
.codn get-prop ,
.codn set-prop ,
.codn get-error ,
.codn get-error-str ,
.code clear-error
and
.codn get-fd .

Implementing
.code get-prop
is mandatory, and that method must support the
.code :name
property.

Failure to implement some of the other methods will impair the use of certain
stream operations on the object.

.coNP Method @ put-string
.synb
.mets << stream .(put-string str)
.syne
.desc
The
.code put-string
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code put-string
stream I/O function.

.coNP Method @ put-char
.synb
.mets << stream .(put-char chr)
.syne
.desc
The
.code put-char
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code put-char
stream I/O function.

.coNP Method @ put-byte
.synb
.mets << stream .(put-byte byte)
.syne
.desc
The
.code put-byte
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code put-byte
stream I/O function.

.coNP Method @ get-line
.synb
.mets << stream .(get-line)
.syne
.desc
The
.code get-line
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code get-line
stream I/O function.

.coNP Method @ get-char
.synb
.mets << stream .(get-char)
.syne
.desc
The
.code get-char
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code get-char
stream I/O function.

.coNP Method @ get-byte
.synb
.mets << stream .(get-byte)
.syne
.desc
The
.code get-byte
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code get-byte
stream I/O function.

.coNP Method @ unget-char
.synb
.mets << stream .(unget-char chr)
.syne
.desc
The
.code unget-char
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code unget-char
stream I/O function.

.coNP Method @ unget-byte
.synb
.mets << stream .(unget-byte byte)
.syne
.desc
The
.code unget-byte
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code unget-byte
stream I/O function.

.coNP Method @ put-buf
.synb
.mets << stream .(put-buf buf pos)
.syne
.desc
The
.code put-buf
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code put-buf
stream I/O function.

Note: there is a severe restriction on the use of the
.meta buf
argument. The buffer object denoted by the
.meta buf
argument may be specially allocated and have a lifetime
which is scoped to the method invocation. The
.code put-buf
method shall not permit the
.meta buf
object to be used beyond the duration of the method
invocation.

.coNP Method @ fill-buf
.synb
.mets << stream .(fill-buf buf pos)
.syne
.desc
The
.code fill-buf
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code fill-buf
stream I/O function.

Note: there is a severe restriction on the use of the
.meta buf
argument. The buffer object denoted by the
.meta buf
argument may be specially allocated and have a lifetime
which is scoped to the method invocation. The
.code fill-buf
method shall not permit the
.meta buf
object to be used beyond the duration of the method
invocation.

.coNP Method @ close
.synb
.mets << stream .(close offs whence)
.syne
.desc
The
.code close
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code close-stream
stream I/O function.

.coNP Method @ flush
.synb
.mets << stream .(flush offs whence)
.syne
.desc
The
.code flush
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code flush-stream
stream I/O function.

.coNP Method @ seek
.synb
.mets << stream .(seek offs whence)
.syne
.desc
The
.code seek
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code seek-stream
stream I/O function.

.coNP Method @ truncate
.synb
.mets << stream .(truncate len)
.syne
.desc
The
.code truncate
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code truncate-stream
stream I/O function.

.coNP Method @ get-prop
.synb
.mets << stream .(get-prop sym)
.syne
.desc
The
.code get-prop
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code get-prop
stream I/O function.

.coNP Method @ set-prop
.synb
.mets << stream .(set-prop sym nval)
.syne
.desc
The
.code set-prop
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code set-prop
stream I/O function.

.coNP Method @ get-error
.synb
.mets << stream .(get-error)
.syne
.desc
The
.code get-error
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code get-error
stream I/O function.

.coNP Method @ get-error-str
.synb
.mets << stream .(get-error-str)
.syne
.desc
The
.code get-error-str
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code get-error-str
stream I/O function.

.coNP Method @ clear-error
.synb
.mets << stream .(clear-error)
.syne
.desc
The
.code clear-error
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code clear-error
stream I/O function.

.coNP Method @ get-fd
.synb
.mets << stream .(get-fd)
.syne
.desc
The
.code get-fd
method is implemented on a stream interface object.
It should behave in a manner consistent with the
description of the
.code fileno
stream I/O function.

.coNP Structure @ stream-wrap
.synb
.mets (defstruct stream-wrap nil
.mets \ \ stream
.mets \ \ (:method put-string (me str)
.mets \ \ \ \ (put-string str me.stream))
.mets \ \ (:method put-char (me chr)
.mets \ \ \ \ (put-char chr me.stream))
.mets \ \ (:method put-byte (me byte)
.mets \ \ \ \ (put-byte byte me.stream))
.mets \ \ (:method get-line (me)
.mets \ \ \ \ (get-line me.stream))
.mets \ \ (:method get-char (me)
.mets \ \ \ \ (get-char me.stream))
.mets \ \ (:method get-byte (me)
.mets \ \ \ \ (get-byte me.stream))
.mets \ \ (:method unget-char (me chr)
.mets \ \ \ \ (unget-char chr me.stream))
.mets \ \ (:method unget-byte (me byte)
.mets \ \ \ \ (unget-byte byte me.stream))
.mets \ \ (:method put-buf (me buf pos)
.mets \ \ \ \ (put-buf buf pos me.stream))
.mets \ \ (:method fill-buf (me buf pos)
.mets \ \ \ \ (fill-buf buf pos me.stream))
.mets \ \ (:method close (me)
.mets \ \ \ \ (close-stream me.stream))
.mets \ \ (:method flush (me)
.mets \ \ \ \ (flush-stream me.stream))
.mets \ \ (:method seek (me offs whence)
.mets \ \ \ \ (seek-stream me.stream offs whence))
.mets \ \ (:method truncate (me len)
.mets \ \ \ \ (truncate-stream me.stream len))
.mets \ \ (:method get-prop (me sym)
.mets \ \ \ \ (stream-get-prop me.stream sym))
.mets \ \ (:method set-prop (me sym nval)
.mets \ \ \ \ (stream-set-prop me.stream sym nval))
.mets \ \ (:method get-error (me)
.mets \ \ \ \ (get-error me.stream))
.mets \ \ (:method get-error-str (me)
.mets \ \ \ \ (get-error-str me.stream))
.mets \ \ (:method clear-error (me)
.mets \ \ \ \ (clear-error me.stream))
.mets \ \ (:method get-fd (me)
.mets \ \ \ \ (fileno me.stream)))
.syne
.desc
The
.code stream-wrap
class provides a trivial implementation of a stream interface.
It has a single slot,
.code stream
which should be initialized with a stream object.
Each methods of
.metn stream-wrap ,
shown in its entirety in the above Syntax section, simply
invoke the corresponding stream I/O library functions, passing
the method arguments, and the value of the
.code stream
slot to that function, and consequently returning whatever that function
returns.

Note: the
.code stream-wrap
function is intended to useful as an inheritance base. A user-defined
structure can inherit from
.code stream-wrap
and provide its own versions of some of the methods, thereby intercepting
those operations to customize the behavior.

For instance, a function equivalent to the
.code record-adapter
function could be implemented by constructing an object derived from
.code stream-wrap
which overrides the behavior of the
.code get-line
method, and then using the
.code make-struct-delegate-stream
to return a stream based on this object.

.TP* Example:
.verb
   ;;; Implementation of my-record-adapter,
   ;;; a function resembling
   ;;; the record-adapter implementation

   (defstruct rec-input stream-wrap
     regex
     include-match-p

     ;; get-line overridden to use regex-based
     ;; extraction using read-until-match
     (:method get-line (me)
       (read-until-match me.regex me.stream
                         me.include-match-p))))

   (defun my-record-adapter (regex stream include-match-p)
     (let ((recin (new rec-input
                       stream stream
                       regex regex
                       include-match-p include-match-p)))
      (make-struct-delegate-stream recin)))
.brev

.SS* Symbols and Packages
\*(TL has a package system inspired by the salient features of ANSI Common
Lisp, but substantially simpler.

Each symbol has a name, which is a string.

A package is an object which serves as a container of symbols; the package
associates the name strings with symbols.

A symbol which exists inside a package is said to be interned in that package.
A symbol can be interned in more than one package.

A symbol may also have a home package. A symbol which has a home package
is always interned in that package.

A symbol which has a home package is called an
.IR "interned symbol" .

A symbol which is interned in one or more packages, but has no home package,
is a
.IR "quasi-interned symbol" .
When a quasi-interned symbol is printed, if it is not interned in
the package currently held in the
.code *package*
variable, it will appear in uninterned notation denoted by a
.code #:
prefix, even though it is interned in one or more packages.
This is because in any situation when a symbol is printed with a package
prefix, that prefix corresponds to the name of its home package.
The reverse isn't true: when a symbol token is read bearing a package
prefix, the token denotes any interned symbol in the indicated package,
whether or not the package is the home package of that symbol.

Packages are held in a global list which can be used to search for a package by
name. The
.code find-package
function performs this lookup.  A package may be
deleted from the list with the
.code delete-package
function, but it continues
to exist until the program loses the last reference to that package.
When a package is deleted with
.codn delete-package ,
its symbols are uninterned from all other packages.

An existing symbol can be brought into a package via the
.code use-sym
function, causing it to be interned in that package. A symbol which thus exists
inside a package which is not its home package is called a
.IR "foreign symbol" ,
relative to that package.
The contrasting term with
.I "foreign symbol"
is
.IR "local symbol" ,
which refers to a symbol, relative to a package, which is interned in that
package and that package is also its home. Every symbol interned in
a package is either foreign or local.

If a foreign symbol is introduced into a package, and has the same name
as an existing local symbol, the local symbol continues to exist, but
is hidden: it is not accessible via a name lookup on that package.
While hidden, a symbol loses its home package and is thus
degraded to either quasi-interned or uninterned status, depending
on whether that symbol is interned in other packages.

When a foreign symbol is removed from a package via
.codn unuse-sym ,
then if a hidden symbol exists in that package of the same name,
that hidden symbol is re-interned in that package and re-acquires
that package as its home package, becoming an interned symbol again.

Finally, packages have a
.IR "fallback package list" :
a list of associated packages, which may be empty. The fallback package
list is manipulated with the functions
.code package-fallback-list
and
.codn set-package-fallback-list ,
and with the
.code :fallback
clause of the
.code defpackage
macro.  The fallback package list plays a role only in three situations:
one in the \*(TL parser, one in the printer, and one in the interactive
listener. Besides that, two library functions refer to it:
.code intern-fb
and
.codn find-symbol-fb .

The parser situation involving the fallback list occurs when the
\*(TL parser resolves an unqualified symbol token: a symbol token not carrying
a package prefix. Such a symbol name is resolved against the current package
(the package currently stored in the
.code *package*
special variable). If a symbol matching the token
is not found in the current package, then the packages in its fallback
package list are searched for the symbol.  The first matching symbol which is
found in the fallback list is returned.  If no matching symbol is found in the
fallback list, then the token is interned as a new symbol is interned in the
current package.  The packages in the current package's fallback list may
themselves have fallback lists. Those fallback lists are not involved; no such
recursion takes place.

The printer situation involving the fallback list is as follows.
If a symbol is being printed in a machine-readable way (not "pretty"),
has a home package and is not a keyword symbol, then a search takes place
through the current package and its fallback list. If the symbol is found
in any of those places, and if those places are devoid of any symbols
which have the same name, thus causing ambiguity, then the symbol is printed
without a package prefix.

The listener situation involving the fallback list is a follows.
When tab completion is used on a symbol without a package
prefix, the listener searches for completions not only in the current
package, but in the fallback list also.

.TP* "Dialect Notes:"

The \*(TL package system doesn't support the ANSI Common Lisp
concept of package use, replacing that concept with fallback packages.

Though the
.code use-package
and
.code unuse-package
functions exist and are similar to the ones in ANSI CL,
they actually operate on individual foreign symbols, bringing
them in or removing them, respectively. These functions effectively
iterate over the local symbols of the used or unused package, and invoke
.code use-sym
or
.codn unuse-sym ,
respectively.

The \*(TL package system consequently doesn't support the concept
of shadowing symbols, and conflicts do not exist.  When a foreign symbol is
introduced into a package which already has a symbol by that name, that symbol
is silently removed from that package if it is itself foreign, or else hidden
if it is local.

The \*(TL package system also doesn't feature the concept of
internal and external symbols. The rationale is that this distinction
divides symbols into subsets in a redundant way. Packages are already
subsets of symbols. A module can use two packages to simulate private
symbols. An example of this is given in the Package Examples section below.

The \*(TL fallback package list mechanism resembles ANSI CL package use,
and satisfies similar use scenarios. However, this mechanism does not cause
a symbol to be considered visible in a package. If a package
.code foo
contains no symbol
.codn bar ,
but one of the packages in
.codn foo 's
fallback list does contain
.codn bar ,
that symbol is nevertheless not considered visible in
.codn foo .
The syntax
.code foo:bar
will not resolve.
The fallback mechanism only comes into play when a package is installed
as the current package in the
.code *package*
variable. It then allows unqualified symbol references to refer across
the fallback list.

.NP* Package Examples
The following example illustrates a simple scenario of a module
whose identifies are in a package, and which also has private identifiers
in a private package.

.verb
  ;; Define three packages.
  (defpackage mod-priv
    (:fallback usr))

  (defpackage mod)

  (defpackage client
    (:fallback mod usr)
    (:use-from mod-priv other-priv))

  ;; Switch to mod-priv package
  (in-package mod-priv)

  (defun priv-fun (arg)
    (list arg))

  ;; Another function with a name in the mod-priv package.
  (defun other-priv (arg)
    (cons arg arg))

  ;; Define a function in mod; a public function.
  ;; Note that we don't have to change to the mod package,
  ;; to define functions with names in that package.
  ;; We rely on interning being allowed for the qualified
  ;; mod:public-fun syntax.
  (defun mod:public-fun (arg)
    (priv-fun arg)) ;; priv-fun here is mod-priv:priv-fun

  ;; Switch to client package
  (in-package client)

  (priv-fun) ;; ERROR: refers to client:priv-fun, not defined
  (mod:priv-fun) ;; ERROR: mod-priv:priv-fun not used in mod
  (mod-priv:priv-fun 3) ;; OK: direct reference via qualifier
  (public-fun 3) ;; OK: mod:public-fun symbol via fallback
  (other-priv 3) ;; OK: foreign symbol mod-priv:other-priv
                 ;; present in client due to :use-from
.brev

The following example shows how to create a package called
.code custom
in which the
.code +
symbol from the
.code usr
package is replaced with a local symbol. A function is
then defined using the local symbol, which allows strings
to be catenated with
.codn + :

.verb
  (defpackage custom
    (:fallback usr)
    (:local + - * /))

  (defmacro outside-macro (x) ^(+ ,x 42))

  (in-package custom)

  (defun binary-+ (: (left 0) (right 0))
    (if (and (numberp left) (numberp right))
      (usr:+ left right)
      `@left@right`))

  (defun + (. args)
    [reduce-left binary-+ args])

  (+) -> 0
  (+ 1) -> 1
  (+ 1 "a") -> "1a"
  (+ 1 2) -> 3
  (+ "a") -> "a"
  (+ "a" "b" "c") -> "abc"

  ;; macro expansions using usr:+ are not affected
  (outside-macro "a") -> ;; error: + invalid operands "a" 42
.brev

.NP* Packages and the Extraction Language
The \*(TX extraction language has a syntax in which certain Lisp symbolic
expressions denoting directives
.code "@(collect ...)"
or
.code "@(end)"
behave as if they were the tokens of a phrase structure.  As a matter of
implementation, these are processed specially in the parser and lexical
analyzer, and are not read in the same way as ordinary Lisp forms.

On the other hand, some directives are not this way. For instance the
.codn "@(bind ...)" ,
syntax is processed as a true Lisp expression, in which the
.code bind
token is subject to the usual rules for interning a symbol, sensitive to
.code *package*
in the usual way.

The following notes describe the treatment of "special" directives that are
involved in phrase structure syntax. It applies to all directives which head
off a block that must be terminated by
.codn "@(end)" ,
all "punctuation" directives like
.code "@(and)"
or
.code "@(end)"
and all sub-phrase indicators like
.code "@(last)"
or
.codn "@(elif)" .

Firstly, each such directive may have a package prefix on its main symbol, yet
is still recognized as the same token. That is to say,
.code "@(foo:collect)"
is still treated by the tokenizer and parser as the
.code "@(collect)"
token, regardless of the package prefix, and regardless of whether
.code foo:end
is the same symbol as the
.code usr:end
symbol.

However, this doesn't mean that any
.code foo:collect
is allowed to denote the
.code collect
directive.

A qualified symbol such as
.code foo:collect
must correspond to (be the same object as) precisely one of two symbols:
either the same-named symbol in the
.code usr
package, or else the same-named symbol in the
.code keyword
package. If this condition isn't satisfied, the situation is a syntax
error. Note that this check uses the original
.code usr
and
.code keyword
packages, not the packages which are currently named
.str "usr"
or
.str "keyword"
in the current
.codn *package-alist* .

A check is also performed for an unqualified symbol.
An unqualified symbol like
.code collect
must also resolve, in the context of the current value of the
.code *package*
variable, to the same named-symbol in either the original
.code usr
or
.code keyword
package. Thus if the current package isn't
.codn usr ,
and
.code "@(collect)"
is being processed, the current package must be such that
.code collect
resolves to
.codn usr:collect .
either because that symbol is present in the current pack via
import, or else visible via the fallback list.

These rules are designed to approximate what the behavior would be
if these directives were actually scanned as Lisp forms in the usual
way and then recognized as phrase structure tokens according to
the identity of their leading symbol. The additional restriction is added that
that the directive symbol names are treated as reserved. If there exists a
user-defined pattern function called
.code mypackage:end
it may not be invoked using the syntax
.codn "@(mypackage:end)" ,
which is erroneous; though it is invocable indirectly via the
.code "@(call)"
directive.

.NP* Package Library Conventions
Various functions in the package and symbol area of the library have a
.meta package
parameter.  When the argument is optional, it defaults to the current
value of the
.code *package*
special variable.

If specified, the argument may be a character string, which is taken as the
name of a package. It may also be a symbol, in which case the symbol's name,
which is a character string, is used. Thus the objects
.codn :sys ,
.codn usr:sys ,
.code abc:sys
and
.str sys
all refer to the same package, the system package which is named
.strn sys .

A
.code package
parameter may also simply be a package object.

Some functions, like
.code use-package
and
.code unuse-package
functions accept a list of packages as their first argument.
This may be a list of objects which follow the above conventions:
strings, symbols or package objects.
Also, instead of a list, an atom may be passed: a string, symbol
or package object. It is treated as a singleton list consisting
of that object.

.coNP Variables @, user-package @ keyword-package and @ system-package
.desc
These variables hold predefined packages. The
.code user-package
contains all of the public symbols in the \*(TL library.
The
.code keyword-package
holds keyword symbols, which are printed with
a leading colon. The
.code system-package
is for internal symbols, helping
the implementation avoid name clashes with user code in some situations.

These variables shouldn't be modified.  If they are modified, the consequences
are unspecified.

The names of these packages, respectively, are
.strn usr ,
.strn sys ,
and
.strn keyword .

.coNP Special variable @ *package*
.desc
This variable holds the current package. The global value of this variable
is initialized to a package called
.strn pub .
The
.code pub
package has the
.code usr
package in its fallback list; thus when
.code pub
is current, all of the
.code usr
symbols, comprising the content of the \*(TL library, are visible.

All forms read and evaluated from the \*(TX command line, in the interactive listener,
from files via
.code load
or
.code compile-file
or from the \*(TX pattern language are processed in this default
.code pub
package, unless arrangement are made to change to a different package.

The current package is used as the default package for interning symbol tokens
which do not carry the colon-delimited package prefix.

The current package also affects printing. When a symbol is printed whose
home package matches the current package, it is printed without a package
prefix. (Keyword symbols are always printed with the colon prefix, even if the
keyword package is current.)

.coNP Function @ make-sym
.synb
.mets (make-sym << name )
.syne
.desc
The
.code make-sym
function creates and returns a new symbol object. The argument
.metn name ,
which must be a string, specifies the name of the symbol.  The symbol
does not belong to any package (it is said to be "uninterned").

Note: an uninterned symbol can be interned into a package with the
.code rehome-sym
function. Also see the
.code intern
function.

.coNP Function @ gensym
.synb
.mets (gensym <> [ prefix ])
.syne
.desc
The
.code gensym
function is similar to make-sym. It creates and returns a new
symbol object. If the
.meta prefix
argument is omitted, it defaults to
.strn g .
Otherwise it must be a string.

The difference between
.code gensym
and
.code make-sym
is that
.code gensym
creates the name
by combining the prefix with a numeric suffix.

The numeric suffix is a decimal digit string, taken from the value of
the variable
.codn *gensym-counter* ,
after incrementing it.

Note: the variation in name is not the basis of the uniqueness assurance
offered by
.code make-sym
and
.codn gensym ;
the basis is that the returned symbol is a freshly instantiated object.
.code make-sym
still returns unique symbols even if repeatedly called with the same
string.

.coNP Special variable @ *gensym-counter*
.desc
This variable is initialized to 0. Each time the
.code gensym
function is called,
it is incremented. The incremented value forms the basis of the numeric
suffix which
.code gensym
uses to form the name of the new symbol.

.coNP Function @ make-package
.synb
.mets (make-package < name <> [ weak ])
.syne
.desc
The
.code make-package
function creates and returns a package named
.metn name ,
where
.meta name
is a string. It is an error if a package by that name exists already.
Note: ordinary creation of packages for everyday program modularization
should be performed with the
.code defpackage
macro rather than by direct use of
.codn make-package .

If the
.meta weak
parameter is given an argument which is a Boolean true, then the resulting
package holds symbols weakly, from a garbage collection point of view.  If the
only reference to a symbol is that which occurs inside the weak package, then
that symbol may be removed from the package and reclaimed by the garbage
collector.

Note: weak packages address the following problem. The application creates a
package for the purpose of reading Lisp data. Symbols occurring in that data
therefore are interned into the package. Subsequently, the application retains
references to some of the symbols, discarding the others.  If the package isn't
weak, then because the application is retaining some of the symbols, and those
symbols hold a reference to the package, and the package holds a reference to
all symbols that were interned in it, all of the symbols are retained. If a
weak package is used, then the uninterested symbols are eligible for garbage
collection.

.coNP Function @ delete-package
.synb
.mets (delete-package << package )
.syne
.desc
The
.code delete-package
breaks the association between a package and its name.
After
.codn delete-package ,
the
.meta package
object continues to exist, but cannot be found using
.codn find-package .

Furthermore,
.code delete-package
iterates over all remaining packages. For each remaining package
.metn p ,
it performs the semantic action of the
.mono
.meti (unuse-package < package << p)
.onom
expression. That is to say, all of the remaining packages
are scrubbed of any foreign symbols which are the local symbols
of the deleted
.metn package .

.coNP Function @ merge-delete-package
.synb
.mets (merge-delete-package dst-package <> [ src-package ])
.syne
.desc
The
.code merge-delete-package
iterates over all of the local symbols of
.meta src-package
and rehomes each symbol into
.metn dst-package .
Then, it deletes
.metn src-package .

Note: the local symbols are identified as if using
.codn package-local-symbols ,
rehoming is performed as if using
.codn rehome-sym ,
and deleting
.meta src-package
is performed as if using
.codn delete-package .

.coNP Function @ packagep
.synb
.mets (packagep << obj )
.syne
.desc
The
.code packagep
function returns
.code t
if
.meta obj
is a package, otherwise it returns
.codn nil .

.coNP Function @ find-package
.synb
.mets (find-package << name )
.syne
.desc
The argument
.meta name
should be a string. If a package called
.meta name
exists,
then it is returned. Otherwise
.code nil
is returned.

.coNP Special variable @ *package-alist*
.desc
The
.code *package-alist*
variable contains the master association list
which contains an entry about each existing
package.

Each element of the list is a cons cell
whose
.code car
field is the name of a package and whose
.code cdr
is a package object.

Note: the \*(TL application can overwrite or re-bind this
variable to manipulate the active package list.  This is
useful for
.IR sandboxing :
safely evaluating code that is obtained as an input
from an untrusted source, or calculated from such an input.

The contents of
.code *package-alist*
have security implications because textual source code
can refer to any symbol in any package by invoking
a package prefix. For instance, even if the
.code open
function's name is not available in the current package
(established by the
.code *package*
variable) that symbol can easily be obtained using the
syntax
.codn usr:open .

However, the entire
.code usr
package itself can be removed from
.codn *package-alist* .
In that situation, the syntax
.code usr:open
is no longer valid.

At the same time, selected symbols from the original
.code usr
can be nevertheless made available via some intermediate
package, which is present in
.code *package-alist*
and which contains a subset of the
.code usr
symbols that has been curated for safety. That curated package may even
be called
.codn usr ,
so that if for instance
.code cons
is present in that package, it may be referred to as
.code usr:cons
in the usual way.

.coNP Function @ package-alist
.synb
.mets (package-alist)
.syne
.desc
The
.code package-alist
function retrieves the value of
.codn *package-alist* .

Note: this function is obsolescent. There is no reason to use it
in new code instead of just accessing
.code *package-alist*
directly.

.coNP Function @ package-name
.synb
.mets (package-name << package )
.syne
.desc
The
.code package-name
function retrieves the name of a package.

.coNP Function @ package-symbols
.synb
.mets (package-symbols <> [ package ])
.syne
.desc
The
.code package-symbols
function returns a list of all the symbols
which are interned in
.metn package .

.coNP Functions @ package-local-symbols and @ package-foreign-symbols
.synb
.mets (package-local-symbols <> [ package ])
.mets (package-foreign-symbols <> [ package ])
.syne
.desc
The
.code package-local-symbols
function returns a list of all the symbols
which are interned in
.metn package ,
and whose home package is that package.

The
.code package-foreign-symbols
function returns a list of all the symbols which
are interned in
.metn package ,
which do not have that package as their home package,
or do not have a home package at all.

The union of the local and foreign symbols contains exactly
the same elements as the list returned by
.codn package-symbols :
the symbols interned in a package are partitioned into
local and foreign.

.coNP Functions @ package-fallback-list and @ set-package-fallback-list
.synb
.mets (package-fallback-list << package )
.mets (set-package-fallback-list < package << package-list )
.syne
.desc
The
.code package-fallback-list
returns the current
.I "fallback package list"
associated with
.metn package .

The
.code set-package-fallback-list
replaces the fallback package list of
.meta package
with
.metn package-list .

The
.meta package-list
argument must be a list which is a mixture of symbols, strings or
package objects. Strings are taken to be package names, which must
resolve to existing packages. Symbols are reduced to strings via
.codn symbol-name .

.coNP Functions @ intern and @ intern-fb
.synb
.mets (intern < name <> [ package ])
.syne
.desc
The argument
.meta name
must be a string. The optional argument
.meta package
must be a package. If
.meta package
is not supplied, then the value
taken is that of
.codn *package* .

The
.code intern
function searches
.meta package
for a symbol called
.metn name .
If that symbol is found, it is returned. If that symbol is not found,
then a new symbol called
.meta name
is created and inserted into
.metn package ,
and that symbol is returned. In this case, the package becomes the
symbol's home package.

The
.code intern-fb
function is very similar to
.code intern
except that if the symbol is not found in
.meta package
then the packages listed in the fallback list of
.meta package
are searched, in order. Only these packages themselves are searched,
not their own fallback lists. If a symbol called
.meta name
is found, the search terminates and that symbol is returned.
Only if nothing is found in the fallback list will
.code intern-fb
create a new symbol and insert it into
.metn package ,
exactly like
.codn intern .

.coNP Function @ unintern
.synb
.mets (unintern < symbol <> [ package ])
.syne
.desc
The
.code unintern
function removes
.meta symbol
from
.metn package .

The
.code nil
symbol may not be removed from the
.code usr
package; an error exception is thrown in this case.

If
.code symbol
isn't
.codn nil ,
then
.meta package
is searched to determine whether it contains
.meta symbol
as an interned symbol (either local or foreign), or a hidden symbol.

If
.meta symbol
is a hidden symbol, then it is removed from the hidden symbol store.
Thereafter, even if a same-named foreign symbol is removed from the
package via
.code unuse-sym
or
.codn unuse-package ,
those operations will no longer restore the hidden symbol to interned
status. In this case,
.meta unintern
returns the hidden symbol that was removed from the hidden store.

If
.meta symbol
is a foreign symbol, then it is removed from the package. If the package
has a hidden symbol of the same name, that hidden symbol is re-interned
in the package, and the package once again becomes its home package.
In this case,
.meta symbol
is returned.

If
.meta symbol
is a local symbol, the symbol is removed from the package.
In this case also,
.meta symbol
is returned.

If
.meta symbol
is not found in the package as either an interned or hidden
symbol, then the function has no effect and returns
.codn nil .

.coNP Functions @ find-symbol and @ find-symbol-fb
.synb
.mets (find-symbol < name >> [ package <> [ notfound-val ]])
.mets (find-symbol-fb < name >> [ package <> [ notfound-val ]])
.syne
.desc
The
.code find-symbol
and
.code find-symbol-fb
functions search
.meta package
for a symbol called
.metn name .
That argument must be a character string.

If the
.meta package
argument is omitted, the parameter defaults to the
current value of
.codn *package* .

If the symbol is found in
.meta package
then it is returned.

If the symbol is not found in
.metn package ,
then the function
.code find-symbol-fb
also searches the packages listed in the fallback list of
.meta package
are searched, in order. Only these packages themselves are searched,
not their own fallback lists. If a symbol called
.meta name
is found, the search terminates and that symbol is returned.

The function
.code find-symbol
only searches
.metn package ,
ignoring its fallback list.

If a symbol called
.meta name
isn't found, then these functions return
.meta notfound-val
is returned, which defaults to
.codn nil .

Note: an ambiguous situation exists when
.meta notfound-val
is a symbol, such as its default value
.codn nil ,
because if that symbol is successfully found,
it is indistinguishable from
.metn notfound-val .

.coNP Function @ rehome-sym
.synb
.mets (rehome-sym < symbol <> [ package ])
.syne
.desc
The arguments
.meta symbol
and
.meta package
must be a symbol and package object,
respectively, and
.meta symbol
must not be the symbol
.codn nil .

The
.code rehome-sym
function moves
.meta symbol
into
.metn package .
If
.meta symbol
is already interned in a package, it is first removed from that package.

If a symbol of the same name exists in
.metn package ,
that symbol is first removed
from
.metn package .

Also, if a symbol of the same name exists in the hidden symbol store of
.metn package ,
that hidden symbol is removed.

Then
.code symbol
is interned into
.metn package ,
and
.meta package
becomes its home package, making it a local symbol of
.metn package .

Note: if
.code symbol
is currently the hidden symbol of some package, it is not removed
from the hidden symbol store of that package. This is a degenerate
case. The implication is that if that hidden symbol is ever
restored in that package, it will once again have that package as
its home package, and consequently it will turn into a foreign
symbol of
.metn package .

.coNP Function @ symbolp
.synb
.mets (symbolp << obj )
.syne
.desc
The
.code symbolp
function returns
.code t
if
.meta obj
is a symbol, otherwise it returns
.codn nil .

.coNP Function @ symbol-name
.synb
.mets (symbol-name << symbol )
.syne
.desc
The
.code symbol-name
function returns the name of
.metn symbol .

.coNP Function @ symbol-package
.synb
.mets (symbol-package << symbol )
.syne
.desc
The
.code symbol-package
function returns the home package of
.metn symbol .
If
.meta symbol
has no home package, it returns
.codn nil .

.coNP Function @ keywordp
.synb
.mets (keywordp << obj )
.syne
.desc
The
.code keywordp
function returns
.code t
if
.meta obj
is a keyword symbol, otherwise it
returns
.codn nil .

.coNP Function @ bindable
.synb
.mets (bindable << obj )
.syne
.desc
The
.code bindable
function returns
.code t
if
.meta obj
is a bindable symbol, otherwise it returns
.codn nil .

All symbols are bindable, except for keyword symbols, and the
special symbols
.code t
and
.codn nil .

.coNP Function @ use-sym
.synb
.mets (use-sym < symbol <> [ package ])
.syne
.desc
The
.code use-sym
function brings an existing
.code symbol
into
.metn package .

In all cases, the function returns
.codn symbol .

If
.meta symbol
is already interned in
.metn package ,
then the function has no effect.

Otherwise
.meta symbol
is interned in
.metn package .

If a symbol having the same name as
.meta symbol
already exists in
.metn package ,
then it is replaced.
If that replaced symbol is a local symbol of
.metn package ,
then the replaced symbol turns into a hidden symbol associated
with the package. It is placed into a special hidden symbol store
associated with
.meta package
and is stripped of its home package, becoming quasi-interned or uninterned.

An odd case is possible whereby
.meta symbol
is already a hidden symbol of
.metn package .
In this case, the hidden symbol replaces some foreign symbol and
is interned in
.metn package .
Thus it simultaneously exists as both an interned
foreign symbol and as a hidden symbol of
.metn package .

.coNP Function @ unuse-sym
.synb
.mets (unuse-sym < symbol <> [ package ])
.syne
.desc
The
.code unuse-sym
function removes
.meta symbol
from
.metn package .

If
.meta symbol
is not interned in
.metn package ,
the function does nothing and returns
.codn nil .

If
.meta symbol
is a local symbol of
.metn package ,
an error is thrown: a package cannot "unuse" its own symbol. Removing
a symbol from its own home package requires the
.code unintern
function.

Otherwise
.meta symbol
is a foreign symbol interned in
.meta package
and is removed.

If the package has a hidden symbol of the same name as
.metn symbol ,
that symbol is re-interned into
.meta package
as a local symbol. In this case, that previously hidden symbol is
returned.

If the package has no hidden symbol matching the removed
.metn symbol ,
then
.meta symbol
itself is returned.

.coNP Functions @ use-package and @ unuse-package
.synb
.mets (use-package < package-list <> [ package ])
.mets (unuse-package < package-list <> [ package ])
.syne
.desc
The
.meta use-package
and
.meta unuse-package
are convenience functions which perform a mass import of symbols from one
package to another, or a mass removal, respectively.

The
.code use-package
function iterates over all of the local symbols of the packages in
.metn package-list .
For each symbol
.metn s ,
it performs the semantic action implied by the
.mono
.meti (use-sym < s << package )
.onom
expression.

Similarly
.code unuse-package
iterates
.meta package-list
in the same way, performing, effectively, the semantic action
of the
.mono
.meti (unuse-sym < s << package )
.onom
expression.

The
.meta package-list
argument must be a list which is a mixture of symbols, strings or
package objects. Strings are taken to be package names, which must
resolve to existing packages. Symbols are reduced to strings via
.codn symbol-name .

.coNP Macro @ defpackage
.synb
.mets (defpackage < name << clause *)
.syne
.desc
The
.code defpackage
macro provides a convenient means to create a package and establish its
properties in a single construct. It is intended for the ordinary situations
in which packages support the organization of programs into modules.

The
.code name
argument, giving the package name, may be a symbol or a character string.
If it is a symbol, then the symbol's name is taken to be name for the
package.

If a package called
.code name
already exists, then
.code defpackage
selects that package for further operations. Otherwise, a new,
empty package is created. In either case, this package is referred
to as the
.I "present package"
in the following descriptions.

The
.code name
may be optionally followed by one or more clauses, which are processed
in the order that they appear. Each clause is a compound form headed
by a keyword.
The supported clauses are as follows:
.RS
.meIP (:fallback << package-name *)
The
.code :fallback
clause specifies the packages to comprise the fallback list of
the present package. If this clause is omitted, or if it is present
with not
.meta package-name
arguments, then the present package has an empty fallback list.
Each
.meta package-name
may be a string or symbol naming an existing package. It is permitted
for the present package itself to appear in its own fallback list.
This is useful for creating a package with a non-empty fallback list
which doesn't actually provide access to any other package.
.meIP (:use << package-name *)
The
.code :use
clause specifies packages whose local symbols are to be interned
into the present package as foreign symbols. Each
.meta package-name
may be a string or symbol naming an existing package.
The list of package names is processed as if by a call to
.codn use-package .
.meIP (:use-syms << symbol *)
The
.code :use-syms
clause specifies individual symbols to be interned in the present package.
The arguments are symbols.
.meIP (:use-from < package-name << symbol-name *)
The
.code :use-from
clause specifies the names of local symbols in a package denoted by
.meta package-name
to be used in the present package. All arguments of
.code :use-from
are either strings or symbols which are reduced to strings by mapping
to their names. Each
.meta symbol-name
is interned in the package identified by
.metn package-name ,
which may have the effect of creating that symbol.
This symbol is expected to be a local symbol of that package. If
that is so, the symbol is brought into the present package via
.codn use-symbol .
Otherwise if the symbol is foreign to package identified by
.metn package-name ,
then an error exception is thrown.
.meIP (:local << symbol-name *)
The
.code :local
clause specifies the names of symbols to be interned in the new package
as local symbols. Each
.meta symbol-name
argument must be either a character string or a symbol. If it is a symbol, its
name is taken, thereby reducing the argument to a character string.
The arguments are processed in the order in which they appear. Each name is
first interned in the newly created package using the
.code intern
function. Then, if the resulting symbol is foreign to the package, it is
removed with
.code unuse-sym
and the name is interned again.
.RE

.coNP Macro @ in-package
.synb
.mets (in-package << name )
.syne
.desc
The
.code in-package
macro causes the
.code *package*
special variable to take on the package denoted by
.metn name .
The macro checks, at expansion time, that
.meta name
is either a string or symbol. An error is thrown if
this isn't the case.

The
.meta name
argument expression isn't evaluated, and so must not be quoted.

The code generated by the macro performs a search for the
package. If the package is not found at the time when
the macro's expansion is evaluated, an error is thrown.

.SS* Pseudo-random Numbers
.coNP Special variable @ *random-state*
.desc
The
.code *random-state*
variable holds an object which encapsulates the state
of a pseudo-random number generator. This variable is the default argument
value for the
.code random-fixnum
and
.codn "random functions" ,
for the convenience of writing programs which are not concerned about the
management of random state.

On the other hand, programs can create and manage random states, making it
possible to obtain repeatable sequences of pseudo-random numbers which do not
interfere with each other. For instance objects or modules in a program can
have their own independent streams of random numbers which are repeatable,
independently of other modules making calls to the random number functions.

When \*(TX starts up, the
.code *random-state*
variable is initialized with
a newly created random state object, which is produced as if by
the call
.codn "(make-random-state 42)" .

.coNP Special variable @ *random-warmup*
.desc
The
.code *random-warmup*
special variable specifies the value which is used by
.code make-random-state
in place of a missing
.meta warmup-period
argument.

To "warm up" a pseudo-random number generator (PRNG) means to obtain some
values from it which are discarded, prior to use.  The number of values
discarded is the
.IR "warm-up period" .

The WELL512a PRNG used in \*(TX produces 32-bit values, natively. Thus each
warm-up iteration retrieves and discards a 32-bit value. The PRNG has
a state space consisting of a vector of sixteen 32-bit words, making
the state space 4096 bits wide.

Warm up is required because PRNG-s, in particular PRNG-s with large state
spaces and long periods, produce fairly predictable sequences of values in the
beginning, before transitioning into chaotic behavior. This problem is worse
for low complexity seeds, such as small integer values.

The sequences are predictable in two ways. Firstly, some initial values
extracted from the PRNG may exhibit patterns ("problem 1"). Secondly, the initial values
from sequences produced from similar seeds (for instance consecutive integers)
may be similar or identical ("problem 2").

.TP* Notes:

The default value of
.code *random-warmup*
is only 8.  This is insufficient to
ensure good initial PRNG behavior for seeds even as large as 64 bits or more.
That is to say, even if as many as eight bytes' worth of true random bits are
used as the seed, the PRNG will exhibit predictable behaviors, and a poor
distribution of values.

Applications which critically depend on good PRNG behavior should choose
large warm-up periods into the hundreds or thousands of iterations.
If a small warm-up period is used, it is recommended to use larger seeds
which initialize more of the 4096 bit state space.

\*(TX's PRNG implementation addresses "problem 1" first problem by padding the
unseeded portions of the state space with random values (from a static table
that doesn't change). For instance, if the integer 1 is used to seed the space,
then one 32 bit word of the space is set to the value 1. The remaining 15 are
populated from the random table. This helps to ensure that a good PRNG sequence
is obtained immediately. However, it doesn't address "problem 2": that
similar seed values generate similar sequences, when the warm-up period is
small. For instance, if 65536 different random state objects are created, from
each of the 16-bit seeds in the range [0, 65536), and then a random 16-bit
value is extracted from each state, only 1024 unique values result.

.coNP Function @ make-random-state
.synb
.mets (make-random-state >> [ seed <> [ warmup-period ])
.syne
.desc
The
.code make-random-state
function creates and returns a new random state,
an object of the same kind as what is stored in the
.code *random-state*
variable.

The seed, if specified, must be either an integer value, an
existing random state object, or a vector returned from a call
to the function
.codn random-state-get-vec .

Note that the sign of the seed is ignored, so that negative seed
values are equivalent to their additive inverses.

If seed is not specified, then
.code make-random-state
produces a seed based
on some information in the process environment, such as current
time of day. It is not guaranteed that two calls to
.code (make-random-state)
that are separated by less than some minimum increment of real time produce
different seeds.  The minimum time increment depends on the platform.

On a platform with a millisecond-resolution real-time clock, the minimum
time increment is a millisecond. Calls to make-random-state less than
a millisecond apart may predictably produce the same seed.

If an integer seed is specified, then the integer value is mapped to a
pseudo-random sequence, in a platform-independent way.

If an existing random state is specified as a seed, then it is duplicated. The
returned random state object is a distinct object which is in the same
state as the input object. It will produce the same remaining pseudo-random
number sequence, as will the input object.

If a vector is specified as a seed, then a random state is constructed
which duplicates the random state object which was captured in that vector
representation by the
.code random-state-get-vec
function.

The
.meta warm-up-period
argument specifies the number of values which are immediately obtained and
discarded from the newly-seeded generator before it is returned.
Warm-up is not performed when
.meta seed
is an existing random state object, and this argument is ignored in that
case. If the parameter is required, but the argument is missing, then
the value of the
.code *random-warmup*
special variable is used. This variable has a default value which may be too
small for serious applications of pseudo-random numbers; see the Notes under
.codn *random-warmup* .

.coNP Function @ random-state-p
.synb
.mets (random-state-p << obj )
.syne
.desc
The
.code random-state-p
function returns
.code t
if
.meta obj
is a random state, otherwise it
returns
.codn nil .

.coNP Function @ random-state-get-vec
.synb
.mets (random-state-get-vec <> [ random-state ])
.syne
.desc
The
.code random-state-get-vec
function converts a random state into a vector of integer values.
If the
.meta random-state
argument, which must be a random state object, is omitted,
then the value of the
.code *random-state*
is used.

.coNP Functions @, random-fixnum @ random and @ rand
.synb
.mets (random-fixnum <> [ random-state ])
.mets (random < random-state << modulus )
.mets (rand < modulus <> [ random-state ])
.syne
.desc
All three functions produce pseudo-random numbers, which are positive integers.

The numbers are obtained from a WELL512a PRNG, whose state is stored in the
random state object.

The
.code random-fixnum
function produces a random fixnum integer: a reduced range
integer which fits into a value that does not have to be heap-allocated.

The
.code random
and
.code rand
functions produce a value in the range [0,
.metn modulus ).
They differ only in the order of arguments. In the
.code rand
function, the random state
object is the second argument and is optional. If it is omitted, the global
.code *random-state*
object is used.

The
.meta modulus
argument must be a positive integer. If
.meta modulus
is 1, then the function returns zero without altering the state of the
pseudo-random number generator.

.coNP Function @ random-float
.synb
.mets (random-float <> [ random-state ])
.syne
.desc
The
.code random-float
function produces a pseudo-random floating-point value in the range [0.0, 1.0).

The numbers are obtained from a WELL512a PRNG, whose state is stored in the
random state object given by the argument to the optional
.meta random-state
parameter, which defaults to the value of
.codn *random-state* .

.SS* Time
.coNP Functions @, time @ time-usec and @ time-nsec
.synb
.mets (time)
.mets (time-usec)
.mets (time-nsec)
.syne
.desc
The
.code time
function returns the number of seconds that have elapsed since
midnight, January 1, 1970, in the UTC timezone: a point in
time called
.IR "the epoch" .

The
.code time-usec
function returns a cons cell whose
.code car
field holds the seconds measured in the same way, and whose
.code cdr
field extends the precision by giving
number of microseconds as an integer value between 0 and 999999.

The
.code time-nsec
function is similar to
.code time-usec
except that the returned cons cell's
.code cdr
field gives a number of nanoseconds as an integer value
between 0 and 999999999.

Note: on hosts where obtaining nanosecond precision is not available, the
.code time-nsec
function obtains a microseconds value instead, and multiplies
it by 1000.

.coNP Functions @ time-string-local and @ time-string-utc
.synb
.mets (time-string-local < time << format )
.mets (time-string-utc < time << format )
.syne
.desc
These functions take the numeric time returned by the
.code time
function, and convert it to a textual representation in a flexible way,
according to the contents of the
.meta format
string.

The
.code time-string-local
function converts the time to the local timezone of
the host system. The
.code time-string-utc
function produces time in UTC.

The
.meta format
argument is a string, and follows exactly the same conventions as
the format string of the C library function
.codn strftime .

The
.meta time
argument is an integer representing seconds obtained from the
time function or from the
.code car
field of the cons returned by the
.code time-usec
function.

.coNP Functions @ time-fields-local and @ time-fields-utc
.synb
.mets (time-fields-local << time )
.mets (time-fields-utc << time )
.syne
.desc
These functions take the numeric time returned by the time function,
and convert it to a list of seven fields.

The
.code time-string-local
function converts the time to the local timezone of
the host system. The
.code time-string-utc
function produces time in UTC.

The fields returned as a list consist of six integers, and a Boolean value.
The six integers represent the year, month, day, hour, minute and second.
The Boolean value indicates whether daylight savings time is in effect
(always
.code nil
in the case of
.codn time-fields-utc ).

The
.meta time
argument is an integer representing seconds obtained from the
.code time
function or from the
.code time-usec
function.

.coNP Structure @ time
.synb
.mets (defstruct time nil
.mets \ \  year month day hour min sec dst
.mets \ \  gmtoff zone)
.syne
.desc
The
.code time
structure represents a time broken down into individual fields.
The structure almost directly corresponds to the
.code "struct tm"
type in the ISO C language.  There are differences.
Whereas the
.code "struct tm"
member
.code tm_year
represents a year since 1900, the
.code year
slot of the
.code time
structure represents the absolute year, not relative to 1900.
Furthermore, the
.code month
slot represents a one-based numeric month, such that 1 represents
January, whereas the C member
.code tm_mon
uses a zero-based month.  The
.code dst
slot is a \*(TL Boolean value. The slots
.codn hour ,
.codn min ,
and
.code sec
correspond directly to
.codn tm_hour ,
.codn tm_min ,
and
.codn tm_sec .

The slot
.code gmtoff
represents the number of seconds east of UTC, and
.code zone
holds a string giving the abbreviated time zone name.
On platform where the C type
.code "struct tm"
has fields corresponding to these slots, values for
these slots are calculated and stored into them by the
.code time-struct-local
and
.code time-struct-utc
functions, and also the related
.code time-local
and
.code time-utc
methods. On platform where the corresponding fields are not
present in the C language
.codn "struct tm" ,
these slots are unaffected by those functions,
retaining the default initial value
.code nil
or a previously stored value, if applicable.
Lastly, the values of
.code gmtoff
and
.code zone
are not ignored by functions which accept a
.code time
structure as a source of input values.

.coNP Functions @ time-struct-local and @ time-struct-utc
.synb
.mets (time-struct-local << time )
.mets (time-struct-utc << time )
.syne
.desc
These functions take the numeric time returned by the time function,
and convert it to an instance of the
.code time
structure.

The
.code time-struct-local
function converts the time to the local timezone of
the host system. The
.code time-struct-utc
function produces time in UTC.

The
.meta time
argument is an integer representing seconds obtained from the
.code time
function or from the
.code time-usec
function.

.coNP Functions @, time-parse @ time-parse-local and @ time-parse-utc
.synb
.mets (time-parse < format << string )
.mets (time-parse-local < format << string )
.mets (time-parse-utc < format << string )
.syne
.desc
The
.code time-parse
function scans a time description in
.meta string
according to the specification given in the
.meta format
string. If the scan is successful, a structure
of type
.code time
is returned, otherwise
.codn nil .

The
.meta format
argument follows the same conventions as the POSIX
C library function
.codn strptime .

Prior to obtaining the time from
.meta format
and
.meta string
the returned structure is created and initialized
with a time which represents time 0 ("the epoch")
if interpreted in the UTC timezone as by the
.meta time-utc
method.

The
.code time-parse-local
and
.code time-parse-utc
functions return an integer time value: the same value
that would be returned by the
.code time-local
and
.code time-utc
methods, respectively, when applied to the structure
object returned by
.codn time-parse .
Thus, these equivalences hold:

.verb
  (time-parse-local f s)  <-->  (time-parse f s).(time-local)
  (time-parse-utc f s)  <-->  (time-parse f s).(time-utc)
.brev

Note: the availability of these three functions
depends on the availability of
.codn strptime .

.coNP Methods @ time-local and @ time-utc
.synb
.mets << time-struct .(time-local)
.mets << time-struct .(time-utc)
.syne
.desc
The
.code time
structure has two methods called
.code time-local
and
.codn time-utc .

The
.code time-local
function considers the slots of the
.code time
structure instance
.meta time-struct
to be local time, and returns its integer representation
as the number of seconds since the epoch.

The
.code time-utc
function is similar, except it considers
the slots of
.meta time-struct
to be in the UTC time zone.

Note: these functions work by converting the slots into arguments
which are applied to
.code make-time
or
.codn make-time-utc .

.coNP Method @ time-string
.synb
.mets << time-struct .(time-string << format )
.syne
.desc
The
.code time
structure has a method called
.codn time-string .

This method accepts a
.meta format
string argument, which it uses to convert
the fields to a character string representation
which is returned.

The
.meta format
argument is a string, and follows exactly the same conventions as
the format string of the C library function
.codn strftime .

.coNP Method @ time-parse
.synb
.mets << time-struct .(time-parse < format << string )
.syne
.desc
The
.code time-parse
method scans a time description in
.meta string
according to the specification given in the
.meta format
string.

If the scan is successful, the structure
is updated with the parsed information, and
the remaining unmatched portion of
.meta string
is returned. If all of
.meta string
is matched, then an empty string is returned.
Slots of
.meta time-struct
which are originally
.code nil
are replaced with zero, even if these
zero values are not actually parsed from
.metn string .

If the scan is unsuccessful, then
.code nil
is returned and the structure is not
altered.

The
.meta format
argument follows the same conventions as the POSIX
C library function
.codn strptime .

Note: the
.code time-parse
method may be unavailable if the host system does not
provide the
.code strptime
function. In this case, the
.code time-parse
static slot of the
.code time
struct is
.codn nil .

.coNP Functions @ make-time and @ make-time-utc
.synb
.mets (make-time < year < month < day
.mets \ \ \ \ \ \ \ \ \ \  < hour < minute < second << dst-advice )
.mets (make-time-utc < year < month < day
.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \  < hour < minute < second << dst-advice )
.syne
.desc
The
.code make-time
function returns a time value, similar to the one returned by the
.code time
function.  The
.code time
value is constructed not from the system clock, but
from a date and time specified as arguments. The
.meta year
argument is a calendar year, like 2014.
The
.meta month
argument ranges from 1 to 12.
The
.meta hour
argument is a 24-hour time, ranging from 0 to 23.
These arguments represent a local time, in the current time zone.

The
.meta dst-advice
argument specifies whether the time is expressed in
daylight savings time (DST). It takes on three possible values:
.codn nil ,
the keyword
.codn :auto ,
or else the symbol
.codn t .
Any other value has the same interpretation as
.codn t .

If
.meta dst-advice
is
.codn t ,
then the time is assumed to be expressed in DST.
If the argument is
.codn nil ,
then the time is assumed not to be in DST.
If
.meta dst-advice
is
.codn :auto ,
then the function tries to determine whether
DST is in effect in the current time zone for the specified date and time.

The
.code make-time-utc
function is similar to
.codn make-time ,
except that
it treats the time as UTC rather than in the local time zone.
The
.meta dst-advice
argument is supported by
.code make-time-utc
for function
call compatibility with
.codn make-time .
It may or may not have any effect
on the output (since the UTC zone by definition doesn't have daylight
savings time).

.SS* Data Integrity

.coNP Function @ crc32-stream
.synb
.mets (crc32-stream < stream >> [ nbytes <> [ crc-prev ]])
.syne
.desc
The
.code crc32-stream
calculates the CRC-32 sum over the bytes read from
.metn stream ,
starting at the stream's current position.

If the
.meta nbytes
argument is specified, it should be a nonnegative
integer. It gives the number of bytes which should be read
and included in the sum. If the argument is omitted, then bytes are read
until the end of the stream.

The optional
.meta crc-prev
argument defaults to zero. It is fully documented under the
.code crc32
function.

The
.code crc32-stream
functions returns the calculated CRC-32 as a non-negative integer.

.coNP Function @ crc32
.synb
.mets (crc32 < obj <> [ crc-prev ])
.syne
.desc
The
.code crc32
function calculates the CRC-32 sum over
.metn obj ,
which may be a character string or a buffer.

If
.meta obj
is a buffer, then the sum is calculated over all of the bytes contained
in that buffer, according to its current length.

If
.meta obj
is a character string, then the sum is calculated over the bytes
which constitute its UTF-8 representation.

The optional
.meta crc-prev
argument defaults to zero. If specified, it should be a nonnegative integer in
the 32 bit range. This argument is useful when a single CRC-32 must be
calculated in multiple operations over several objects. The first call should
specify a value of zero, or omit the argument. To continue the checksum,
each subsequent call to the function should pass as the
.meta crc-prev
argument the CRC-32 obtained from the previous call.

The
.code crc32
function returns the calculated CRC-32 as a non-negative integer.

.TP* Examples:

.mono
  ;; Single operation
  (crc32 "ABCD") --> 3675725989

  ;; In two steps, demonstrating crc-prev argument:
  (crc32 "CD" (crc32 "AB")) -> 3675725989
.onom

.coNP Functions @ sha256-stream and @ md5-stream
.synb
.mets (sha256-stream < stream >> [ nbytes <> [ buf ]])
.mets (md5-stream < stream >> [ nbytes <> [ buf ]])
.syne
.desc
The
.code sha256-stream
calculates the NIST SHA-256 digest over the bytes read from
.metn stream ,
starting at the stream's current position.

The
.code md5-stream
function calculates the MD5 digest, using the
RSA Data Security, Inc. MD5 Message-Digest Algorithm.

If the
.meta nbytes
argument is specified, it should be a nonnegative
integer. It gives the number of bytes which should be read
and included in the digest. If the argument is omitted, then bytes are read
until the end of the stream.

If the
.meta buf
argument is omitted, the digest value is returned as a new,
buffer object. This buffer is 32 bytes long in the case of SHA-256,
holding a 256-bit digest, and 16 bytes long in the case of MD5,
holding a 128-bit digest.
If the
.meta buf
argument is specified, it must be a buffer that is at least 16 bytes long
in the case of MD5, and at least 32 bytes long in the case of SHA-256.
The hash is placed into that buffer, which is then returned.

.coNP Functions @ sha256 and @ md5
.synb
.mets (sha256 < obj <> [ buf ])
.mets (md5 < obj <> [ buf ])
.syne
.desc
The
.code sha256
function calculates the NIST SHA-256 digest over
.metn obj ,
which may be a character string or a buffer.

Similarly, the
.code md5
functions calculates the MD5 digest over
.metn obj ,
using the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

If
.meta obj
is a buffer, then the digest is calculated over all of the bytes contained
in that buffer, according to its current length.

If
.meta obj
is a character string, then the digest is calculated over the bytes
which constitute its UTF-8 representation.

If the
.meta buf
argument is omitted, the digest value is returned as a new,
buffer object. This buffer is 32 bytes long in the case of SHA-256,
holding a 256-bit digest, and 16 bytes long in the case of MD5,
holding a 128-bit digest.
If the
.meta buf
argument is specified, it must be a buffer that is at least 16 bytes long
in the case of MD5, and at least 32 bytes long in the case of SHA-256.
The hash is placed into that buffer, which is then returned.

.coNP Functions @, sha256-begin @ sha256-hash and @ sha256-end
.synb
.mets (sha256-begin)
.mets (sha256-hash < ctx << obj )
.mets (sha256-end < ctx <> [ buf ])
.syne
.desc
The three functions
.codn sha256-begin ,
.code sha256-hash
and
.code sha256-end
implement a stateful computation of SHA256 digest which allows multiple input
sources to contribute to the result. Furthermore, the context object may be
serially re-used for calculating multiple digests.

The
.code sha256-begin
function, which takes no arguments, returns a new SHA256 digest-producing
context object.

The
.code sha256-hash
updates the state of the SHA256 digest object
.meta ctx
by including
.meta obj
into the digest calculation. The
.meta obj
argument may be: a character or character string, whose UTF-8 representation is
digested; a buffer object, whose contents are digested; or an integer,
representing a byte value in the range 0 to 255 included in the digest.
The
.code sha256-hash
function may be called multiple times to include any mixture of
strings and buffers into the digest calculation.

The
.code sha256-end
function finalizes the digest calculation and returns the digest in
a buffer. If the
.meta buf
argument is omitted, then a new 32-byte buffer is created for this
purpose. Otherwise,
.meta buf
must specify a
.code buf
object that is at least 32 bytes long. The digest is stored into this
buffer and that the buffer is returned.

The
.code sha256-end
function additionally resets the
.meta ctx
object into the initial state of a newly created context object, so
that it may be used for another digest session.

.coNP Functions @, md5-begin @ md5-hash and @ md5-end
.synb
.mets (md5-begin)
.mets (md5-hash < ctx << obj )
.mets (md5-end < ctx <> [ buf ])
.syne
.desc
The three functions
.codn md5-begin ,
.code md5-hash
and
.code md5-end
implement a stateful computation of MD5 digest which allows multiple input
sources to contribute to the result. Furthermore, the context object may be
serially re-used for calculating multiple digests.

The
.code md5-begin
function, which takes no arguments, returns a new MD5 digest-producing
context object.

The
.code md5-hash
updates the state of the MD5 digest object
.meta ctx
by including
.meta obj
into the digest calculation. The
.meta obj
argument may be: a character or character string, whose UTF-8 representation is
digested; a buffer object, whose contents are digested; or an integer,
representing a byte value in the range 0 to 255 included in the digest.
The
.code md5-hash
function may be called multiple times to include any mixture of
strings and buffers into the digest calculation.

The
.code md5-end
function finalizes the digest calculation and returns the digest in
a buffer. If the
.meta buf
argument is omitted, then a new 16-byte buffer is created for this
purpose. Otherwise,
.meta buf
must specify a
.code buf
object that is at least 16 bytes long. The digest is stored into this
buffer and that the buffer is returned.

The
.code md5-end
function additionally resets the
.meta ctx
object into the initial state of a newly created context object, so
that it may be used for another digest session.

.SS* The Awk Utility

The \*(TL library provides a macro called
.code awk
which is inspired by the Unix utility Awk. The macro implements
a processing paradigm similar to that of the utility: it scans
one or more input streams, which are divided into records or fields,
under the control of user-settable regular-expression-based delimiters.
The records and fields are matched against a sequence of programmer-defined
conditions (called "patterns" in the original Awk), which have associated
actions. Like in Awk, the default action is to print the current record.

Unlike Awk, the
.code awk
macro is a robust, self-contained language feature which can be used
anywhere where a \*(TL expression is called for, cleanly nests
with itself and can produce a return value when done. By contrast,
a function in the Awk language, or an action body, cannot instantiate
a local Awk processing machine.

The
.code awk
macro implements some of the most important Awk
conventions and semantics, in Lisp syntax, while eschewing others.
It does not implement implement the Awk convention that
variables become defined upon first mention; variables must be
defined to be used. It doesn't implement Awk's weak type system.
A character string which looks like a number isn't a number,
and an empty string or undefined variable doesn't serve as zero
in arithmetic expressions enclosed in the macro.
All expression evaluation within
.code awk
is the usual \*(TL evaluation.

The
.code awk
macro also does not provide a library of functions corresponding to
those in the Awk library, nor does it provide counterparts various
global variables in Awk such as the
.code ENVIRON
and
.code PROCINFO
arrays, or
.code RSTART
and
.codn RLENGTH .
Such features of Awk are extraneous to its central paradigm.

.coNP Macro @ awk
.synb
.mets (awk >> {( condition << action *)}*)
.syne
.desc
The
.code awk
macro processes one or more input sources, which may be streams or
files. Each input source is scanned into records, and each record
is broken into fields. For each record, the sequence of condition-action
clauses (except for certain special clauses) is processed. Every
.meta condition
is evaluated, and if it yields true, the corresponding
.metn action -s
are evaluated.

The
.meta condition
and
.meta action
forms are understood to be in a scope in which certain local
identifiers exist in the variable namespace as well as in the function
namespace. These are called
.I "awk functions"
and
.IR "awk macros" .

If
.meta condition
is one of the following keyword symbols, then it is a special clause,
with special semantics:
.codn :name ,
.codn :let ,
.codn :inputs ,
.codn :output ,
.codn :begin ,
.codn :set ,
.codn :end ,
.codn :begin-file ,
.code :set-file
and
.codn :end-file .
These clause types are explained below.
In such a clause, the
.meta action
expressions are not necessarily forms to be evaluated; the treatment
of these expressions depends on the clause.  Otherwise, if
.meta condition
is not one of the above keyword symbols, the clause is an ordinary
condition-action clause, and
.meta condition
is a \*(TL expression, evaluated to determine a Boolean value
which controls whether the
.meta action
forms are evaluated. In every ordinary condition-action clause which
contains no
.meta action
forms, the
.code awk
macro substitutes the single action equivalent to the form
.codn "(prn)" :
a call to the local awk function
.codn prn .
The behavior of this macro, when called with no arguments, as above,
is to print the current
record (contents of the variable
.codn rec )
followed by the output record terminator from the variable
.codn ors .

While the processing loop in
.code awk
scans an input source, it also binds the special variable
.code *stdin*
to the open stream associated with that source. This binding is
in effect across all ordinary clauses, as well as across the
special clauses
.code :begin-file
and
.codn :end-file .

The following is a description of the special clauses:
.RS
.meIP (:name << sym )
The
.code :name
clause establishes the name of the implicit block contained
within the expansion of the
.code awk
macro. Forms enclosed in the macro can use
.code return-from
to abandon the
.code awk
form, specifying this symbol as the argument.

If the
.code :name
form is omitted, the implicit block is named
.codn awk .

It is an error for two or more
.code :name
forms to appear.

The
.code :name
clause must have an argument which is a symbol;
the symbol
.code nil
is not permitted.

.meIP (:let >> { sym | >> ( sym << init-form )}*)
Regardless of what order they appear in relation to
other clauses in the same
.code awk
macro,
.code :let
clauses are evaluated first before the macro takes any other action. The
argument forms of this clause are variables or variable-init forms. They are
treated the same way as analogous forms in the
.code let*
special form. Note that these are not enclosed in an extra list
as they are in the that form. The bindings established by the
.code :let
clause have a scope which extends over all the other clauses in the
.code awk
macro.

If multiple
.code :let
clauses are present, they are effectively consolidated into
a single clause, in the order they appear.

Note that the lexical variables, functions and macros established by the
.code awk
macro
(called, respectively,
.IR "awk macros" ,
.I "awk functions"
and
.IR "awk variables" )
are in an inner scope relative to
.code :let
bindings. For instance if
.code :let
creates a binding for a variable called
.codn fs ,
that variable will be visible only to subsequent forms appearing
in the same
.code :let
clause or later
.code :let
clauses, and also visible in
.code :inputs
and
.code :output
clauses.
In
.codn :begin ,
.codn :set ,
.codn :end ,
and ordinary clauses, it will be shadowed by the
.code awk
variable
.codn fs ,
which holds the field separator regular expression or string.
.meIP (:inputs << source-form *)
The
.code :inputs
clause is evaluated by the
.code awk
macro after processing the
.code :let
clauses. Each
.meta source-form
is evaluated and the values of these forms are gathered into a list.
This list then comprises the list of input sources for the
.code awk
processing task.

Each input source must be one of three kinds of objects.
It may be a stream object, which must be capable of character
input. It may be a list of strings, which
.code awk
will convert to an input stream as if by the
.code make-strlist-input-stream
function.
Or else it must be a character
string, which denotes a filesystem path name which
.code awk
will open for reading.

If the
.code :inputs
clause is omitted, then a defaulting behavior occurs for obtaining
the list of input sources. If the special variable
.code *args*
isn't the empty list, then
.code *args*
is taken as the input sources. Otherwise, the
.code *stdin*
stream is taken as the one and only input source.

If the
.code awk
macro uses
.code *args*
via the above defaulting behavior, it copies
.code *args*
and sets that variable to
.codn nil .
This is done in order that if
.code awk
is used from the \*(TX command line, for example using the
.code -e
command line option, after
.code awk
terminates, \*(TX will not try to open the next argument
as a script file or treat it as an option.
Note: programs which want
.code awk
not to modify
.code *args*
can explicitly specify
.code *args*
as the argument to the
.code :inputs
keyword, rather than allow
.code *args*
to be used through the defaulting behavior. Only the
defaulting behavior consumes the arguments by overwriting
.code *args*
with
.codn nil .

It is an error to specify more than one
.code :inputs
clause.
.meIP (:output << output-form )
The
.code :output
clause is processed just after the
.code :inputs
clause. It must have exactly one argument, which is an expression
that evaluates to a string, or else to an output stream.
If it evaluates to a string, then that string is used as the name
of a file to open for writing, and the resulting stream
is taken in place of that string.

The
.code :output
clause, if present, has the effect of creating a local binding for the
.code *stdout*
special variable.
This new value of
.code *stdout*
is visible to all forms within the macro.
If a
.code :let
clause is present, it establishes bindings
in a scope which is nested within the scope established
by
.codn :output .
Therefore,
.metn init-form -s
in the
.code :let
may refer to the new value of
.code *stdout*
established by
.codn :output .
Furthermore,
.code :let
can rebind
.codn *stdout* ,
causing the definition provided by
.code :output
to be shadowed.

In the case when the
.code :output
argument is a string such that a new stream is opened
on the file, the
.code awk
macro will close that stream when it finishes executing.
Moreover, that stream is treated uniformly as a member of
the set of streams that are implicitly managed by the
redirection macros in the same
.code awk
macro invocation. In brief, the implication is that if
.code :output
creates a stream for the file path name
.str "out.txt"
and somewhere in the same
.code awk
macro, there is a redirection of the form, or equivalent to
.mono
(-> "out.txt")
.onom
then this redirection shall refer to the same stream
that was established by
.codn :output .
Note also that in this example situation, the expression
.mono
(-> "out.txt" :close)
.onom
has the effect of closing the
.code :output
stream.

.meIP (:begin << form *)
All
.code :begin
clauses are processed in the order in which they appear, before
input processing begins.
Each
.code form
is evaluated. These forms have in their scope the awk local variables
and macros.
.meIP (:set >> { place << new-value }*)
The
.code :set
clause provides a shorthand which allows the frequently occurring pattern
.code "(:begin (set ...))"
to be condensed to
.codn "(:set ...)" .
.meIP (:end << form *)
All
.code :end
clauses are processed, in the order in which they appear,
when the input processing loop terminates.
This termination occurs when all records
from all input sources are either processed or skipped, or else
by an explicit termination such
as a dynamic non-local transfer, such as
.codn return-from ,
or the throwing of an exception.

Upon termination, the end clauses are processed in the order they appear. Each
.code form
is evaluated, left to right.

In the normal termination case, the value of the last
.meta form
of the last end clause appears as the return value of the
.code awk
macro.

Note that only termination of the
.code awk
macro initiated from condition-action clauses,
.code :begin-file
clauses, or
.code :end-file
clauses triggers
.code :end
clause processing.
If termination of the
.code awk
macro is initiated from within a
.codn :let ,
.codn :inputs ,
.code :output
or
.code :begin
clause, then end
clauses are not processed.
If an
.code :end
clause performs a non-local transfer, the remaining
.code :end
forms in that clause and
.code :end
clauses which follow are not evaluated.
.meIP (:begin-file << form *)
All
.code :begin-file
clauses are processed in the order in which they appear, before
.code awk
switches to each new input.

If both
.code :begin
and
.code :begin-file
forms are specified, then before the first input is processed,
.code :begin
clauses are processed first, then the
.code :begin-file
clauses.
.meIP (:set-file >> { place << new-value }*)
The
.code :set-file
clause is a shorthand which translates
.code "(:set-file ...)"
to
.codn "(:begin-file (set ...))" .
.meIP (:end-file << form *)
All
.code :end-file
clauses are processed after the processing of an input
source finishes.

If both
.code :end
and
.code :end-file
forms are specified, then before after the last input is processed,
.code :end-file
clauses are processed first, then the
.code :end
clauses.

The
:end-file
clauses are processed unconditionally, no matter how
the processing of an input source terminates, whether terminated
naturally by running out of records, prematurely by invocation of the
.code next-file
macro, or via a dynamic non-local control transfer such as a block
return or exception throw.

If a
.code :begin-file
clause performs a non-local transfer,
.code :end-file
processing is not triggered, because the processing of the input
source is deemed not to have taken place.
.meIP >> ( condition << action *)
Clauses which do not have one of the specially recognized keywords
in the first position are ordinary condition-action clauses. After
processing the
.code :begin
clauses, the awk enters a loop in which it extracts successive records
from the input sources according to the
.code rs
(record separator) variable. Each record is divided into fields according
to the
.code fs
(field separator)
variable, and various
.code awk
variables are updated. Then, the condition-action clauses are processed, in the order
in which they appear. Each
.meta condition
is evaluated. If the resulting value is a regular expression
or a function, then this regular expression or function is invoked on the value
stored in the record variable
.codn rec ,
and the result is taken to be the truth value of
.metn condition .
Otherwise, if the resulting value of
.meta condition
is other than a function or regular expression, it is taken directly
to be the truth value.
If the condition is true, then its associated
.meta action
forms are evaluated. Either way, processing passes to the next condition
clause (unless an explicit step is taken in one of the
.metn action -s
to prevent this, for instance by invoking the
.code next
and
.code next-file
macros).
When an input source runs out of records,
.code awk
switches to the next input source. When there are no more input sources,
the macro terminates.
.RE

.coNP Variables @ rec and @ orec
.desc
The awk variable
.code rec
holds the current record. It is automatically updated prior to the
processing of the condition-pattern clauses. Prior to the extraction
of the first record, its value is
.codn nil .

It is possible to assign to
.codn rec .
The value assigned to
.code rec
must be a character string. Immediately upon the assignment, the character
string is delimited into fields according to the field separator
awk variable
.codn fs ,
and these fields are assigned to the field list
.codn f .
At the same time, the
.code nf
variable is updated to reflect the new number of fields.
Likewise, modification of these variables causes
.code rec
to be reconstructed by a catenation of the textual representation
of the fields in
.code f
separated by copies of the output field separator
.codn ofs .

The
.code orec
variable ("original record") also holds the current record. It is automatically
updated prior to the processing of the condition-clauses at the same time as
.code rec
with the same contents. Like
.codn rec ,
it is initially
.code nil
before the first record is read. The
.code orec
variable is unaffected by modification of
the variables
.codn rec ,
.code f
and
.codn nf .
It may be assigned. Doing so has no effect on any other
variable.

.coNP Variable @ f
.desc
The awk variable
.code f
holds the list of fields. Prior to the first record being read,
its value is
.codn nil .
Whenever a new record is read, it is divided into fields according
to the field separator variable
.codn fs ,
and these fields are stored in
.code f
as a list of character strings.

If the variable
.code f
is assigned, the new value must be a sequence. The variable
.code nf
is automatically updated to reflect the length of this sequence.
Furthermore, the
.code rec
variable is updated by catenating a string representation of the
elements of this sequence, separated by the contents of the
.code ofs
(output field separator)
awk variable.

Note that assigning to a DWIM bracket form which indexes
.codn f ,
such as for instance
.code "[f 0]"
constitutes an implicit modification of
.codn f ,
and triggers the recalculation of
.codn rec .
Modifications of the
.code f
list which do not involve an implicit or explicit assignment to the variable
.code f
itself do not have this recalculating effect.

Unlike in Awk, assigning to the nonexistent field
.mono
.meti [f << m ]
.onom
where
.meta m
>=
.code nf
is erroneous.

.coNP Variable @ nf
.desc
The awk variable
.code nf
holds the current number of fields in the sequence
.codn f .
Prior to the first record being read, it is initially zero.

If
.code nf
is assigned, then
.code f
is modified to reflect the new number of fields. Fields are deleted from
.code f
if the new value of
.code nf
is smaller. If the new value of
.code nf
is larger, then fields are added. The added fields are empty strings,
which means that
.code f
must be a sequence of a type capable of holding elements which are
strings.

If
.code nf
is assigned, then
.code rec
is also recalculated, in the same way as described in the documentation for the
.code f
variable.

.coNP Variable @ nr
.desc
The awk variable
.code nr
holds the current absolute record number. Record numbers start at 1.
Absolute means that this value does not reset to 1 when
.code awk
switches to a new input source; it keeps incrementing for each record.
See the
.code fnr
variable.

Prior to the first record being read, the value of
.code nr
is zero.

.coNP Variable @ fnr
.desc
The awk variable
.code fnr
holds the current record number within the file. The first record is 1.

Prior to the first record being read from the first input source,
the value of
.code fnr
is zero. Thereafter, it resets to 1 for the first record of each input
source and increments for the remaining records of the same input
source.

.coNP Variable @ arg
.desc
The awk variable
.code arg
is an integer which indicates what input source is being processed.
Prior to input processing, it holds the value zero. When the first
record is extracted from the first input source, it is set to 1.
Thereafter, it is incremented whenever
.code awk
switches to a new input source.

.coNP Variable @ fname
.desc
The awk variable
.code fname
provides access to a character string which, if the current input is
a file stream, is the name of the underlying file. Assigning to this
variable changes its value, but has no effect on the input stream.
Whenever a new input source is used by
.code awk
it sets this variable either from the file name on which it is opening
a stream.. When using an existing stream rather than opening a file,
.code awk
sets this variable from the
.code :name
property of the stream.

Note that the redirection macros
.code <-
and
.code <!
have no effect on this variable. Within their scope,
.code fname
retains its value.

.coNP Variable @ rs
.desc
The awk variable
.code rs
specifies a string or regular expression which is used for
delimiting characters read from the inputs into pieces called records.

Note: the record extraction is internally implemented using record streams
instantiated by the
.code record-adapter
function.

The regular expression pattern stored in
.code rs
is used to matches substrings in the input which separate or terminate records.
Unless the
.code krs
variable is set true, the substrings which match
.code rs
are discarded and the records consist of the non-matching extents between
them.

The initial value of
.code rs
is
.strn "\en" :
the newline character. This means that, by default, records are lines.

If
.code rs
is changed to the value
.codn nil ,
then record separation operates in
.IR "paragraph mode" ,
which is described below.

If a match for the record separator occurs at the end of the stream,
it is not considered to delimit an empty record, but acts as the
terminator for the previous record.

When a new value is assigned to
.codn rs ,
it has no effect on the most recently scanned and delimited record which is
still current, or previous records. The new value applies to the next, not yet
read record.

In paragraph mode, records are separated by a newline character followed by one
or more blank lines (empty lines or lines containing only a mixture of
tabs and spaces). This means that, effectively, the record-separating
sequences match the regular expression
.codn "/\en[ \en\et]*\en/" .

There are two differences between paragraph mode and simply using the above
regular expression as
.codn rs .
The first difference is that if the first record which is read upon entering
paragraph mode is empty (because the input begins with a match for the
separator regex), then that record is thrown away, and the next record is read.
The second difference is that, if field separation based on the
.code fs
variable is in effect, then regardless of the value of
.codn fs ,
newline characters separate fields. Therefore, the programmer-defined
.code fs
doesn't have to include a match for newline. Moreover, if it is a simple
fixed string, it need not be converted to a regular expression which also
matches a newline.

.coNP Variable @ krs
.desc
The awk variable
.code krs
stands for "keep record separator". It is a Boolean variable, initialized to
.codn nil .

If it is set to a true value, then the separating text matched
by the pattern in the
.code rs
variable is retained as part of the preceding record rather than removed.

When a new value is assigned to
.codn krs ,
it has no effect on the most recently scanned and delimited record which is
still current, or previous records. The new value applies to the next, not yet
read record.

.coNP Variables @ fs and @ ft
.desc
The awk variable
.code fs
and
.code ft
each specify a string or regular expression which is used for each
record that is stored in the
.code rec
variable into fields.

Both variables are initialized to
.codn nil ,
in which case a default behavior is in effect, described below.

Use of these variable is mutually exclusive; it is an error for both of these
variables to simultaneously have a value other than
.codn nil .
The value stored in either variable must be
.codn nil ,
a character string or a regular expression. If it contains a string or
regex, it is said to contain a pattern. A string value effectively behaves
as a fixed regular expression which matches the sequence of characters
in the string verbatim, without treating any of them as regex operators.

The splitting of
.code rec
into fields is influenced by the Boolean
.code kfs
("keep field separators")
variable, whose effect is discussed in its description.
If
.code kfs
is false, the splitting is carried out as follows.

If
.code fs
contains a pattern, then
.code rec
is treated specially when it is the empty string: in that case,
the pattern in
.code fs
is ignored, and no fields are produced: the field list
.code f
is the empty list, and
.code nf
is zero.  A non-empty record is split by searching it for matches for the
.code fs
pattern. If a match does not occur, then the entire record is a field.
If one match occurs, then the record is split into two fields, either of which,
or both, might be empty. If two matches occur, the record is split into
three fields, and so on. If
.code fs
finds only an empty string match in the record, then it is considered
to match each of the empty strings between two consecutive characters of the
record. Consequently, the record is split into its individual characters, each
one becoming a field. Note: all of these behaviors, except for the special
treatment of the empty record, are accomplished by a call to the
.code split-str
function.

If the variable
.code ft
("field tokenize") contains a pattern, that pattern is used to positively
recognize tokens within the input record, rather than to match separating
material between them. Those matching tokens then constitute the fields.
The tokenizing is performed using the
.code tok-str
function.

If
.code fs
and
.code ft
are both
.codn nil ,
as is initially the case, then the splitting into fields is performed
as if the
.code ft
variable held the regular expression
.codn "/[^\en\et ]+/" .
This means that, by default, fields are sequences of consecutive characters
which are not spaces, tabs or newlines.
Newlines are excluded from fields (and thus separate them) because they can
occur in a record when the value of the record separator
.code rs
is customized.

.coNP Variable @ kfs
.desc
The awk variable
.code kfs
is a Boolean flag which is initialized to
.codn nil .

If it is set to any other value, it indicates a request to retain
the pieces of the record which separate the fields (even when they are
empty strings).  The retained pieces appear as fields, interspersed
among the regular fields so that all of the fields appear in the order
in which they were extracted from the record.

When
.code kfs
is set, and tokenization-style delimiting is in effect due to
.code ft
being set, there is always at least one field, even if the record is empty.
If the record doesn't match the tokenizing regular expression in
.code ft
then a single field is generated, then the entire record is
taken as one field, denoting the non-matching space, even
if the record is the empty string.

If the record matches one or more tokens, then the first and
last field will always contain the non-matching material before
the first and last token, respectively. This is true even if
the material is empty. Thus
.code "[f 0]"
always has the material before the first token, whether or not
the first token is matched immediately at the first character
position in the record. This behavior follows from the semantics
of the
.code keep-sep
parameter of the
.code tok-str
function.

Similarly, when splitting based on
.code fs
is in effect and
.code kfs
is set, there is always at least one field, even if the record
is empty. If
.code fs
finds no match in the record, then the entire record,
even if empty, is taken as one field. In that case, there
are no separator to retain. When
.code fs
finds one or more
matches, then these are included as fields. Separators are
always between the fields. If a separator finds a nonempty
match at the beginning of a record, that causes an empty field
to be split off: the separator is understood as intervening
between an empty string before the first character of the
record, and subsequent material which follows the text
matched by the separator. Thus the first field is an empty
field, and the second is the matched text which is
included due to
.code kfs
being set.  An analogous situation occurs at the end of the record: if
.code fs
matches a nonempty string at the tail of the record, it splits off an empty
last field, preceded by a field holding the matched separator portion.
Empty matches are only permitted to occur between the characters
of the record, not before the first character of after the last.
If
.code fs
matches the entire record, then there will be three fields:
the first and last of these three will be empty strings,
and the middle field, the separator, will be a copy of the record.
Under
.codn kfs ,
empty matches cause empty string to be included among the
fields. All of this follows from the semantics of the
.code keep-sep
parameter of the
.code split-str
function.

.coNP Variable @ fw
.desc
The awk variable
.code fw
controls the fixed-width-based delimiting of records into fields.

The variable is initialized to
.codn nil .
In that state, it has no effect.
When this variable holds a
.cod2 non- nil
value, it is expected to be a list of integers.
The use of the
.code fs
or
.code ft
variables is suppressed, and fields are extracted according
to the widths indicated by the list. The fields are consecutive,
such that if the list is
.code "(5 3)"
then the first five characters of the record are identified
as field
.code "[f 0]"
and the next three characters after that as
.codn "[f 1]" .

Only complete fields are extracted from the record. If, after
the extraction of the maximum possible complete fields, more characters
remain, those characters are assigned to an extra field.

An empty record produces an empty list of fields regardless
of the integers stored in fw.

A zero width extracts a zero length field, except when
no more characters remain in the record.

If
.code nil
is stored into
.code fw
then control over field separation is relinquished to the
.code fs
or
.code ft
variables, according to their current values.

If
.code fw
holds a value other than
.code nil
or else a list of non-negative integers, the behavior is unspecified.

.TP* Examples

The following table shows how various combinations of the
value the input record
.code rec
and field widths in the variable
.code fw
give rise to field values
.codn f :

.verb
  rec    fw      f
  ---------------------------------
  "abc"  (0)     ("" "abc")
  "abc"  (2)     ("ab" "c")
  "abc"  (1 2)   ("a" "bc")
  "abc"  (1 3)   ("a" "bc")
  "abc"  (1 1)   ("a" "b" "c")
  "abc"  (3)     ("abc")
  "abc"  (4)     ("abc")
  ""     (4)     nil
  ""     (0)     nil
.brev

.coNP Variable @ ofs
.desc
The awk variable
.code ofs
hold the output field separator. Its initial value is a string
consisting of a single space character.

When the
.code prn
function prints two or more arguments, or fields,
the value of
.code ofs
is used to separate them.

Whenever
.code rec
is implicitly updated due to a change in the variable
.code f
or
.codn nf ,
.code ofs
is used to separate the fields, as they appear in
.codn rec .

.coNP Variable @ ors
.desc
The awk variable
.codn ors ,
though it stands for "output record separator" holds what
is in fact the output record terminator. It is named after the
.code ORS
variable in Awk.

Each call to the
.code prn
function terminates its output by emitting the value of
.codn ors .

The initial value of
.code ors
is a character string consisting of a single newline,
and so the
.code prn
function prints lines.

.coNP Function @ prn
.synb
.mets (prn << form *)
.syne
.desc
The awk function
.code prn
performs output into the
.code *stdout*
stream. The
.code :output
clause affects the destination by rebinding
.codn *stdout* .

If called with no arguments,
.code prn
prints
.code rec
followed by
.codn ors .

Otherwise, it prints the values of the arguments, separated by
.codn ofs ,
followed by
.codn ors .

When a condition-action clause specifies no action forms,
then a call to
.code prn
with no arguments is the default action.

Each argument
.meta form
is printed by conversion to a string, as if by the expression
.code `@val`
where
.code val
is some variable which holds the value produced by the
evaluation of
.metn form .
Thus if the value is
.codn nil ,
the output for that argument is an empty string, rather than the text
.strn nil .

.coNP Macro @ next
.synb
.mets (next)
.syne
.desc
The awk macro
.code next
may be invoked in a condition-pattern clause. It terminates
the processing of that clause, and all subsequent clauses,
causing
.code awk
to process the next record, if there is one. If there is no next
record,
.code awk
terminates.

.coNP Macro @ again
.synb
.mets (again)
.syne
.desc
The awk macro
.code again
may be invoked in a condition-pattern clause. It terminates the
processing of that clause, and all subsequent clauses.
Then, the current value of the record, namely the datum stored
in the Awk variable
.codn rec ,
is delimited into fields, and all of the condition-pattern clauses
are processed again.

No other state is modified. In particular, the record number
.code nr
and the
.code orec
variable holding the original record both retain their current values.

Note: this is an original feature in the \*(TL
.code awk
macro, which has no counterpart in POSIX or GNU Awk.

.coNP Macro @ next-file
.synb
.mets (next-file)
.syne
.desc
The awk macro
.code next-file
may be invoked in a condition-pattern clause. It terminates
the processing of that clause, and all subsequent clauses.
Awk then abandons the current input source, and moves to the
next one.  If there is no next input source,
.code awk
terminates.

.coNP Macros @, rng @, -rng @ rng- @, -rng- @, --rng @, --rng- @, rng+ @ -rng+ and @ --rng+
.synb
.mets (rng < from-condition << to-condition )
.mets (-rng < from-condition << to-condition )
.mets (rng- < from-condition << to-condition )
.mets (-rng- < from-condition << to-condition )
.mets (--rng < from-condition << to-condition )
.mets (--rng- < from-condition << to-condition )
.mets (rng+ < from-condition << to-condition )
.mets (-rng+ < from-condition << to-condition )
.mets (--rng+ < from-condition << to-condition )
.syne
.desc
The nine awk macros in the
.code rng
family may be used anywhere within an ordinary condition-pattern
.code awk
clause.

Each provides a Boolean test which is true if the current record lands within
a range of records delimited by conditions.  Each provides its own
distinct, useful nuance, which is identified by the mnemonic characters
prefixed or suffixed to the name.

The basic
.code rng
macro inclusively matches ranges of records. Each such range begins with a record
for which
.meta from-condition
yields true, and ends on the record for which
.meta to-condition
is true. What it means to match is that the
.code rng
expression yields a Boolean true value when it is evaluated in the context
of processing any of the records which are included in the range.

The table below summarizes the semantic variations of these nine
range macro operators. The leftmost column represents the file of records
being processed. The remaining columns indicate, using the character
.code X
those rows for each of the nine range operators yield true. Each operator
is assumed to be invoked with the arguments
.code #/H/
and
.code #/T/
as its
.meta from-condition
and
.metn to-condition ,
respectively: for example,
.code "(rng #/H/ #/T/)"
in the case of
.codn rng :

.verb
  DATA    rng -rng rng- -rng- --rng --rng- rng+ -rng+ --rng+
  ----------------------------------------------------------
  PROLOG
  H1      X        X                       X
  H2      X    X   X     X                 X     X
  H3      X    X   X     X                 X     X
  B1      X    X   X     X      X     X    X     X      X
  B2      X    X   X            X     X    X     X      X
  T1      X    X                X          X     X      X
  T2                                       X     X      X
  T3                                       X     X      X
  EPILOG
.brev

The prefix or suffix characters are mnemonic. A single
.code -
(dash) indicates the exclusion of one record. A double
.code --
(dash dash)
indicates the exclusion of all leading records which match
.metn from-condition ;
this appears on the left side only.
The
.code +
character, appearing on the right only, indicates that
all consecutive records which match
.meta to-condition
are included in the range, not only the first one.

Ranges are oblivious to the division between successive sources of input; a
range can start in one file of records and terminate in another.
To prevent a range from spanning input transitions, additional complexity
is required in the expression.

Ranges expressed using the
.code rng
family macros may combine with other expressions, including
other ranges, and allow arbitrary nesting: the
.meta from-condition
or
.meta to-condition
can be a range, or an expression containing ranges.

The expressions
.meta from-condition
and
.meta to-condition
are ordinary expressions which are evaluated. However, their
evaluation is unusual in two ways.

Firstly, if either expression
produces, as its result, a function or regular expression object,
then that function or regular expression object is applied to
the current record (value of the
.code rec
variable), and the result of that application is then taken
as the result of the condition. This allows for expressions like
.code "(rng (f^ #/start/) #/end/)"
which denotes a range which begins with a record which
begins with the prefix
.str start
and ends with a record which contains
.str end
as a substring.

Secondly, the conditions are evaluated
out of order with respect to the surrounding expression
in which they occur.  Ranges and their constituent
.meta from-condition
and
.meta to-condition
are evaluated just prior to the processing of the condition-action clauses.
Each
.code rng
expression is reduced to a Boolean value.
Then, when the condition-action clauses are processed and their
.meta condition
and
.meta action
forms are evaluated, each occurrence of a
.code rng
expression simply denotes its previously evaluated Boolean value.

Therefore, it is not possible for expressions to short circuit
the evaluation of ranges. Ranges cannot "miss" their starting or
terminating conditions; every range occurring anywhere in the condition-action
clauses is tested against every record that is processed.

Because of this perturbed evaluation order, code which happens to place side
effects into ranges may produce surprising results.

For instance, the expression
.code "(if nil (rng (prinl 'hello) (prinl 'world)))"
will produce output even though the
.code if
condition is
.codn nil ,
and, moreover, this output will happen before the clauses are processed in
which this
.code if
expression appears. At the time when the
.code if
itself is evaluated, the
.code rng
expression merely fetches a previously computed Boolean value which indicates
whether the range is active for this record.

Also, the behavior is unspecified if range expressions attempt to modify
the awk-special variables.
.codn rec ,
.codn f ,
.codn fs ,
.code ft
or
.codn kfs .
It is not recommended to place any side effects into range expressions.

A more detailed description of the range operators follows.
.RS
.meIP (rng < from << to )
This type of range becomes active when a record is encountered for which the
.meta from
expression yields true. While the range is active, the expression evaluates
true. If, when the range is active, a record is encountered for which the
.meta to
expression yields true, the range remains active for that record and is
deactivated after the completion of processing for that record. If
the range is inactive and a record is encountered or which both
.meta from
and
.meta to
are true, then the range is activated for that record and then deactivated
when that record is processed.
Records for which
.meta from
and
.meta to
are not true do not affect the range's activation state.
.meIP (-rng < from << to )
This type of range is active under the same conditions as the
.code rng
type. However, the expression yields a Boolean false value for the
first record which begins a range. That is to say, when the range is
inactive, and a record is scanned for which
.meta from
is true, the range activates, but the range expression yields
.codn nil .
This is true regardless of whether the
.meta to
expression yields true for that record. If there are additional records
in the range, the expression yields a true value for those records.
.meIP (rng- < from << to )
This type of range is active under the same conditions as the
.code rng
type. However, the range expression yields
.code nil
for the record for which
.code to
yields true which terminates the range. This occurs even if that is
the same record which activated the range by triggering the
.meta from
condition.  Note that if a range terminates abruptly due to no more records
being available, the range expression still yields true for the last record.
.meIP (-rng- < from << to )
This type of range is active under the same conditions as the
.code rng
type. However, the range expression yields
.code nil
for the first record which activates the range, and for the last
record which deactivates the range by activating the
.code to
condition. If the range is active over fewer than three records, then
the expression never yields true for that range. If the range terminates
abruptly due to no more records being available, and if the last record
processed isn't the one which activated the range due to triggering the
.code from
condition, the expression yields true for that record.
.meIP (--rng < from << to )
This type of range is active under the same conditions as
.codn rng .
However, the range expression yields
.code nil
for the entire leading sequence of consecutive records for which
.meta from
is true. If
.meta from
is true of the
.meta to
record which terminates the range,
.code nil
is returned for that record also.
.meIP (--rng- < from << to )
This type of range is active under the same conditions as
.codn rng .
However, the range expression yields
.code nil
for the entire leading sequence of consecutive records for which
.meta from
is true, and also yields nil for the last record which triggers the
.meta to
condition.
.meIP (rng+ < from << to )
This range is active under different conditions compared to
.codn rng .
Though it becomes active in the same way, when the
.meta from
expression yields true, the deactivation logic is different.
The range is deactivated when a record for which
.meta to
is true is followed by a record for which
.meta to
is not true. That record is excluded from the range; if the
.meta from
expression happens to be true for that record, a new range begins
at that record. Thus, effectively, the range is terminated not
by single record which triggers
.meta to
but by a sequence of one or more such consecutive records.
.meIP (-rng+ < from << to )
This range is active under the same conditions as 
.codn rng+ .
However, the range expression yields
.code nil
for the first record in the range. If the range contains only one record, then
it returns
.code nil
for that record.
.meIP (--rng+ < from << to )
This range is active under the same conditions as 
.codn rng+ .
However, the range expression yields
.code nil
for the entire leading sequence of consecutive records for which
.meta from
is true. This is the case even for those for which the
.meta to
expression is true.
.RE

.coNP Macro @ ff
.synb
.mets (ff < opip-arg *)
.syne
.desc
The awk macro
.code ff
(filter fields)
provides a shorthand for filtering the field list
.code f
trough a pipeline of chained functions expressed using
.code opip
argument syntax.

The following equivalence holds, except that
.code f
refers to the awk variable even if the
.code mf
invocation occurs in code which establishes
a binding which shadows
.codn f .

.verb
  (ff a b c ...)  <-->  (set f [(opip a b c ...) f])
.brev

.TP* Example:
.verb
  ;; convert all fields from string to floating-point
  (ff (mapcar flo-str))
.brev

.coNP Macro @ mf
.synb
.mets (mf < opip-arg *)
.syne
.desc
The awk macro
.code mf
(map fields)
provides a shorthand for mapping each field
individually trough a pipeline of chained functions expressed using
.code opip
argument syntax.

The following equivalence holds, except that
.code f
refers to the awk variable even if the
.code mf
invocation occurs in code which establishes
a binding which shadows
.codn f .

.verb
  (mf a b c ...)  <-->  (set f (mapcar (opip a b c ...) f))
.brev

.TP* Example:
.verb
  ;; convert all fields from string to floating-point
  (mf flo-str)
.brev

.coNP Macro @ fconv
.synb
.mets (fconv >> { clause | : | - }*)
.syne
.desc
The awk macro
.code fconv
provides a succinct way to request conversions of the textual fields.
Conversions are expressed by clauses which correspond with fields.

Each
.meta clause
is an expression which must evaluate to a function. The clause is evaluated
in the same manner as the argument a
.code dwim
operator, using Lisp-1-style name lookup. Thus, functions may be
specified simply by using their name as a
.metn clause .

Furthermore, several local functions exist in the scope of each
.metn clause ,
providing a short-hand notation. These are described below.

Conversion proceeds by applying the function produced by
a clause to the field to which that clause corresponds, positionally.
The return value of the function applied to the field replaces
the field.

When a clause is specified as the symbol
.code -
(minus)
it has a special meaning: this minus clause occupies a field
position and corresponds to a field, but performs no conversion
on its field.

The
.code :
(colon)
symbol isn't a clause and does not correspond to a field position.
Rather, it acts as a separator among clauses. It need not appear at
all. If it appears, it may appear at most twice. Thus, the
clauses may be separated into up to three sequences.

If the colon does not appear, then all the clauses are
.IR "prefix clauses" .
Prefix clauses line up with fields from left to right.  If there are fewer
fields than prefix clauses, the values of the excess clauses are evaluated, but
ignored.
.IR "Vice versa" ,
if there are fewer prefix clauses than fields, then the excess
fields are not subject to conversions.

If the colon appears once, then the clauses before the colon, if any, are
prefix clauses, as described in the previous paragraph.  Clauses after the
colon, if any, are
.IR "interior clauses" .
Interior clauses apply to any fields which are left unconverted by the prefix
clauses. All interior clauses are evaluated.  If there are fewer fields than
interior clauses, then the values of the excess interior clauses are ignored.
If there are more fields than clauses, then the clause values are cycled:
re-used from the beginning against the excess fields, enough times to convert
all the fields.

If the colon appears twice, then the clauses before the first colon, if any,
are prefix clauses, the clauses between the two clause are interior clauses,
and those after the second colon are
.IR "suffix clauses" .
The presence of suffix clauses change the behavior relative to the one-colon
case as follows. After the conversions are performed according to the prefix
clauses, the remaining fields are counted.  If there are are only as many
fields as there are suffix clauses, or fewer, then the interior clauses are
evaluated, but ignored.  The remaining fields are processed against the suffix
clauses.  If after processing the prefix clauses there are more fields
remaining than suffix clauses, then a number of rightmost fields equal to the
number of suffix clauses is reserved for those clauses.  The interior fields
are applied only to the unreserved middle fields which precede these reserved
rightmost fields, using the same repeating behavior as in the one-colon case.
Finally, the previously reserved rightmost fields are processed using
the suffix clauses.

The following special convenience functions are in scope of the clauses,
effectively providing a short-hand for commonly-needed conversions:
.RS
.coIP i
Provides conversion to integer. It is identical to the
.code toint
function.
.coIP o
Converts a string value holding an octal representation
to the integer which it denotes. The expression
.code "(o str)"
is equivalent to
.codn "(toint str 8)" .
.coIP x
Converts a string value holding a hexadecimal representation
to the integer which it denotes. The expression
.code "(x str)"
is equivalent to
.codn "(toint str 16)" .
.coIP b
Converts a string value holding a binary (base two) representation
to the integer which it denotes. The expression
.code "(b str)"
is equivalent to
.codn "(toint str 2)" .
.coIP c
Converts a string value holding a C-language-style representation
to the integer which it denotes, meaning that the
.code 0x
prefix denotes a hexadecimal value, a leading zero octal, otherwise
decimal. These prefixes follow the
.code +
or
.code -
sign, if present.
The expression
.code "(c str)"
is equivalent to
.codn "(toint str #\ec)" .
.coIP r
Converts a string holding a floating-point representation to
the floating-point value which it denotes. The expression
.code "(r str)"
is equivalent to
.codn "(tofloat str)" .
.ccIP @, iz @, oz @, xz @, bz @ cz and @ rz
Conversion similar to
.codn i ,
.codn o ,
.codn x ,
.codn b ,
.code c
and
.codn r ,
but using
.code tointz
and
.codn tofloatz .
Thus fields which are non-numeric strings or the object
.code nil
get converted to 0, or 0.0 in the case of
.codn rz .
.coIP -
Performs no conversion: the corresponding field is taken as-is.
.RE
.IP
Because
.code fconv
macro destructively operates on the elements of the field list
.codn f ,
it has the same effect as an assignment to the fields:
the value of
.code rec
is updated.

The return value of
.code fconv
is
.codn f .

Note: because
.code f
is
.code nil
when no fields have been extracted, a
.code fconv
expression can be used as the condition in an
.code awk
clause which triggers the action if one or more fields have been
extracted, and performs conversions on them.


Note: although
.code fconv
is intended for converting textual fields, and the semantic descriptions below
consequently make references to string inputs, the behavior of
.code fconv
with respect to non-string fields can be inferred. For instance if a field
actually holds the floating-point value 3.14, and the
.code i
conversion is applied to it, it will produce 3, because it works by
means of the
.code toint
function which.

.TP* Examples:

.verb
  ;; convert up to first three fields to integer:
  (awk ((fconv i i i)))

  ;; convert all fields to floating-point
  (awk ((fconv : r :)))

  ;; convert first and second fields to integer
  ;; from hexadecimal;
  ;; convert last field to integer from octal;
  ;; process pairs of fields in between
  ;; these by leaving the first element of
  ;; each pair unconverted and converting second
  ;; to floating-point;
  (awk ((fconv x x : - r : o)))

  ;; convert all fields, except the first,
  ;; from integer, turning empty strings
  ;; and non-integer junk as zero;
  ;; leave first field unconverted:
  (awk ((fconv - : iz)))
.brev

.coNP Macros @, -> @, ->> @, <- @ !> and @ <!
.synb
.mets (-> < path << form *)
.mets (->> < path << form *)
.mets (<- < path << form *)
.mets (!> < command << form *)
.mets (<! < command << form *)
.syne
.desc
These awk macros provide convenient redirection of output and input to and from
files and commands.

When at least one
.meta form
argument is present, the functions
.codn -> ,
.code ->>
and
.code !>
evaluate each
.meta form
in a dynamic environment in which the
.code *stdout*
variable is bound to a file output stream, for the first two
functions, or output command pipe in the case of the last one.

Similarly, when at least
.meta form
argument is present, the remaining functions
.code <-
and
.code <!
evaluate each
.meta form
in a dynamic environment in which
.code *stdin*
is bound to to a file input stream or input command pipe, respectively.

The
.meta path
and
.meta command
arguments are treated as forms, and evaluated.
They should evaluate to strings.

The first evaluation of one of these macros for a given
.meta path
or
.meta command
being used in a particular direction (input or output) and type (file or
command) creates a stream.  That stream is then associated with the given
.meta path
or
.meta command
string, together with the direction and type. Upon a subsequent evaluation
of one of these macros for the same
.meta path
or
.meta command
string, direction and type, a new stream is not opened; rather, the
previously associated stream is used.

The
.code ->
macro indicates that the file named
.meta path
is to be opened for writing and overwritten, or created if it doesn't exist.
The
.code ->>
macro indicates that the file named by
.meta path
is to be opened in append mode, created if necessary.
The
.code <-
macro indicates that the file given by
.meta path
is to be opened for reading.

The
.code !>
macro indicates that
.meta command
is to be opened as an output command pipe. The
.code <!
macro indicates that
.meta command
is to be opened as an input command pipe.

If any of these macros is invoked without any
.meta form
arguments, then it yields the stream object associated with
.meta path
or
.meta command
argument, direction and type. If the association doesn't exist,
the stream is first created.

If
.meta form
arguments are present, then the value of the last one is yielded
as a value, except in the case when the last form yields the
.code :close
keyword symbol.

If the last
.meta form
yields the
.code :close
keyword symbol, the the association between the
.meta path
or
.metn command ,
direction and type and the stream is removed, and the stream
is closed. In this case, the result value of the macro isn't the
.code :close
symbol, but rather the return value of the
.meta close-stream
call that is implicitly applied to the stream.

Even if there is only one
.meta form
which yields
.codn :close ,
the stream is created, if it doesn't exist prior to the macro
invocation.

In each invocation of these macros, after every
.meta form
is evaluated, the stream is implicitly flushed, if it is an output stream.

The association between the
.meta pipe
or
.meta command
strings, direction and type is scoped to the inner-most enclosing
.code awk
macro. An inner
.code awk
macro cannot refer to the associations established in an outer
.code awk
macro. An outer
.code awk
macro can obtain an association's stream object and communicate
that stream to the nested macro where it can be used.

When the
.meta awk
surrounding macro terminates, all of the streams opened by these
redirection macros are closed, without breaking those associations.
If lexical closures are captured inside the macro, and then invoked after the
macro has terminated, and inside those closures the redirection macros are
used, those macro instances will with closed stream objects, and so
attempts to perform I/O will fail.

.coNP Examples of @ awk Macro Usage
The following examples are
.code awk
macro equivalents of the examples of the POSIX
.code awk
utility given in IEEE Std 1003.1, 2013 Edition.

.RS
.IP 1.
Print lines for which field 3 is greater than 5:

.verb
  ;; print lines with fields separated by ofs,
  ;; and [f 2] converted to integer:
  (awk ((and [f 2] (fconv - - iz) (> [f 2] 5))))

  ;; print strictly original lines from orec
  (awk ((and [f 2] (fconv - - iz) (> [f 2] 5))
        (prn orec)))

.brev
.IP 2.
Print every tenth line:

.verb
  (awk ((zerop (mod nr 10))))
.brev
.IP 3.
Print any line with a substring matching a regex:

.verb
  (awk (#/(G|D)(2\ed[\ew]*)/))
.brev
Note the subtle flaw here: the
.code [\ew]*
portion of the regular expression contributes nothing
to what lines are matched. The following example
has a similar flaw.
.IP 4.
Print any line with a substring beginning with a
.code G
or
.code D
followed by a sequence of digits and characters:

.verb
  (awk (#/(G|D)([\ed\ew]*)/))
.brev
.IP 5.
Print lines where the second field matches a regex,
while the fourth one doesn't:

.verb
  (awk (:let (r #/xyz/))
       ((and [f 3] [r [f 1]] (not [r [f 3]]))))
.brev
.IP 6.
Print lines containing a backslash in the second field:

.verb
  (awk ((find #\e\e [f 1])))
.brev
.IP 7.
Print lines containing a backslash using a regex constructed
from a string. Note that backslash escapes are interpreted
twice: once in the string literal, and once in the parsing
of the regex, requiring four backslashes to encode one:

.verb
  (awk (:let (r (regex-compile "\e\e\e\e")))
       ((and [f 1] [r [f 1]])))
.brev
.IP 8.
Print penultimate and ultimate field in each record,
separating then by a colon:

.verb
  ;; original: {OFS=":";print $(NF-1), $NF}
  ;;
  (awk (t (set ofs ":") (prn [f -2] [f -1])))
.brev
.IP
Note that the above behaves
more correctly than the original Awk example because in the
when there is only one field,
.code $(NF-1)
reduces to
.code $0
which refers to the entire record, not to the field.
This sort of bug is why the \*(TL
.code awk
does not imitate the design decision to make the record
the first numbered field.
.IP 9.
Output the line number and number of fields separated by colon,
by producing a single string first:

.verb
  (awk (t (prn `@nr:@nf`)))
.brev
.IP 10.
Print lines longer than 72 characters:

.verb
  (awk ((> (len rec) 72)))
.brev
.IP 11.
Print first two fields in reverse order, separated by
.codn ofs :

.verb
  (awk (t (prn [f 1] [f 0])))
.brev
.IP 12.
Same as 11, but with field separation consisting of a
comma, or spaces and tabs, or both in sequence:

.verb
  (awk (:set fs #/,[ \et]*|[ \et]+/)
       (t (prn [f 1] [f 0])))
.brev
.IP 13.
Add the values in the first column, then print sum and
average:

.verb
  ;; original:
  ;; {s += $1}
  ;; END {print "sum is ", s, " average is", s/NR}
  ;;
  (awk (:let (s 0) (n 0))
       ([f 0] (fconv r) (inc s [f 0]) (inc n))
       (:end (prn `sum is @s average is @(/ s n)`)))
.brev

Note that the original is not robust against blank lines
in the input. Blank lines are treated as if they had a
first column field of zero, and are counted toward the
denominator in the calculation of the average.
.IP 14.
Print fields in reverse order, one per line:

.verb
  (awk (t (tprint (reverse f))))
.brev
.IP 15.
Print all lines between occurrences of
.code start
and
.codn stop :

.verb
  (awk ((rng #/start/ #/stop/)))
.brev
.IP 16.
Print lines whose first field is different from
the corresponding field in the previous line:

.verb
  (awk (:let prev)
       ((nequal [f 0] prev) (prn) (set prev [f 0])))
.brev
.IP 17.
Simulate the
.code echo
utility:

.verb
  (awk (:begin (prn `@{*args* " "}`)))
.brev

Note: if this is evaluated in the command line, for instance with the
.code -e
option, an explicit exit is required to prevent the arguments from being
processed by
\*(TX after
.code awk
completes:

.verb
  (awk (:begin (prn `@{*args* " "}`) (exit 0)))
.brev
.IP 18.
Pint the components of the
.code PATH
environment variable, one per line:

.verb
  ;; Process variable as if it were a file:
  (awk (:inputs (make-string-input-stream
                  (getenv "PATH")))
       (:set fs ":")
       (t (tprint f)))

  ;; Just get, split and print; awk macro is irrelevant
  (awk (:begin (tprint (split-str (getenv "PATH") ":"))))
.brev
.IP 19.
Given a file called
.code input
which contains page headers of the format
.str "Page #"
and a \*(TL file called
.code prog.tl
which contains:

.verb
  (awk (:let (n (toint n)))
       (#/Page/ (set [f 1] (pinc n)))
       (t))
.brev

the command line:

.verb
  txr -Dn=5 prog.tl input
.brev

prints the file, filling in page numbers starting at 5.
.RE

.SS* Environment Variables and Command Line

Note that environment variable names, their values, and command line
arguments are all regarded as being externally encoded in UTF-8. \*(TX performs
the encoding and decoding automatically.

.coNP Special variables @, *args-full* @ *args-eff* and @ *args*
.desc
The
.code *args-full*
variable holds the original, complete list of arguments passed
from the operating system, including the program executable
name.

During command line option processing, \*(TX may transform the
argument list. The hash bang mechanism, and the
.code --args
and
.code --eargs
options can inject new command line arguments, as can code
which is executed during argument processing via the
.code -e
options and others.

The
.code *args-eff*
variable holds the list of
.I "effective arguments" ,
which is the argument list after these transformations are applied.
This variable is established and set to the same value as
.code *args-full*
prior to command line processing, but is not updated with its final
value until after command line processing.

The
.code *args*
variable holds a list of strings representing the remaining
arguments which follow any options processed by the \*(TX executable,
and the script name. This list is a suffix of
.codn *args-eff* .
Thus, the arguments before
.code *args*
can be calculated using the expression
.codn "(ldiff *args-eff* *args*)" .

The
.code *args*
variable is available to to \*(TL expressions invoked from the
command line via the
.codn -p ,
.code -e
and other such options. During these evaluations,
.code *args*
holds all the remaining options, after the invoking option and its
argument expression. In other words, code executed from the command line
has access to the remaining arguments which follow it.
Furthermore, this code may modify the value of
.codn *args* .
Such a modification is visible to the option processing code.
That is to say code executed from the command line can rewrite the remaining
list of arguments, and that list takes effect.

.coNP Function @ env
.synb
.mets (env)
.syne
.desc
The
.code env
function retrieves the list of environment variables. Each
variable is represented by a single entry in the list: a string which
contains an
.code =
(equal) character somewhere, separating the variable name
from its value.

Multiple calls to
.code env
may return the same list, or lists which share structure.

If a list returned by
.code env
is modified, the behavior is unspecified.

See also: the
.code env-hash
function.

.coNP Function @ env-hash
.synb
.mets (env-hash)
.syne
.desc
The
.code env-hash
function returns an
.code :equal-based
hash whose keys and values are strings. The hash table is populated
with the environment variables, represented as key-value character string
pairs.

The
.code env-hash
function allocates the hash table when it is first invoked; thereafter,
it returns the same hash table.

The hash table is updated by the functions
.codn setenv ,
.code unsetenv
and
.codn getenv .

Note: calls to the underlying C library functions
.code setenv
and
.codn getenv ,
and other direct manipulations of the environment, will not update the hash table.

.coNP Functions @, getenv @ setenv and @ unsetenv
.synb
.mets (getenv << name )
.mets (setenv < name < value <> [ overwrite-p ])
.mets (unsetenv << name )
.syne
.desc
These functions provide access to, as well as manipulation of, environment
variables. Of these three,
.code setenv
and
.code unsetenv
might not be available on some platforms, or
.code unsetenv
might be be present in a simulated form which sets the variable
.meta name
to the empty string rather than deleting it.

The
.code getenv
function searches the environment for the environment variable whose name
is
.metn name .
If the variable is found, its value is returned. Otherwise
.code nil
is returned.

The
.code setenv
function creates or modifies the environment variable indicated by
.metn name .
The
.meta value
string argument specifies the new value for the variable.
If
.meta value
is
.codn nil ,
then
.code setenv
behaves like
.codn unsetenv ,
except that it observes the
.meta overwrite-p
argument. That is to say, the meaning of a null
.meta value
is that the variable is to be removed.

If the
.meta overwrite-p
argument is specified, and is true,
then the variable is overwritten if it already exists.
If the argument is false, then the variable is not modified if it
already exists.  If the argument is not specified, it defaults
to the value
.metn t ,
effectively giving rise to a two-argument form of
.code setenv
which creates or overwrites environment variables.

A variable removal is deemed to be an overwrite.
Thus if both
.meta value
and
.meta overwrite-p
are
.codn nil ,
then
.code setenv
does nothing.

The
.code setenv
function unconditionally returns
.meta value
regardless of whether or not it overwrites or removes an existing variable.

The
.code unsetenv
function removes the environment variable
specified by
.metn name ,
if it exists. On some platforms, it instead sets the environment variable
to the empty string.

Note: supporting removal semantics in
.code setenv
allows for the following simple save/modify/restore pattern:

.verb
  (let* ((old-val (getenv "SOME-VAR")))
    (unwind-protect
      (progn (setenv "SOME-VAR" new-val)
             ...)
      (setenv "SOME-VAR" old-val)))
.brev

This works in the case when
.code SOME-VAR
exists, as well as in the case that it doesn't exist.
In both cases, its previous value or, respectively, non-existence,
is restored by the
.code unwind-protect
cleanup form.

These functions interact with the list returned by the
.code env
function and with the hash table returned by the
.code env-hash
function as follows.

A previously returned list returned by
.code env
is not modified. The
.code setenv
and
.code unsetenv
functions may cause a subsequent call to
.code env
to return a different list. The
.code getenv
function has no effect on the list.

The hash table previously returned by
.code env-hash
is modified by
.code setenv
in the manner consistent with its semantics. A new entry is created in the table,
if required, and an existing entry is overwritten only if the
.code overwrite-p
flag is specified. Likewise, if
.code setenv
is invoked in a way that causes the environment variable to be deleted, it
is removed from the hash also.
The
.code unsetenv
function causes the variable to be removed from the hash table also.
The
.code getenv
function accesses the underlying environment, and updates the hash
table with the name-value pair which is retrieved.

.SS* Command Line Option Processing

\*(TL provides a support for recognizing, extracting and validating
the POSIX-style options from a list of command-line arguments.

The supported options can be defined as a list of option descriptor
objects each of which is constructed by a call to the
.code opt
function. Each option can have a long name, a short name,
a type, and a description.

The
.code getopts
function takes a list of option descriptors, and a list of arguments,
producing a parse, or else throwing an exception of type
.code opt-error
if an error is detected. The returned object, an instance of struct type
.codn opts ,
can then be queried for specific option values, or for the remaining non-option
arguments.

The
.code opthelp
function takes a list of option descriptors and an output stream,
and generates help text on that stream. A program supporting a
.code --help
option can use this to generate that portion of its help text which
describes the available options, as well as the conventions that they use.

The
.code define-option-struct
macro provides a more streamlined, declarative mechanism built on the
same facility. The options are declared in a more condensed way, and
using symbols instead of strings. Furthermore, the parsed option values
become slot values of an object, named by the same symbols.

.NP* Command Line Option Conventions

A command line option can have a short or long name. A short name is always
one-character long, and treated specially in the command line syntax.  Long
options have names two or more characters long.  An option can have both a long
and short name. Options may not begin with the
.code -
(ASCII dash) character. A long option may not contain the
.code =
character.

Short options are invoked by specifying an argument with a single leading
.code -
followed by the option character.  Multiple short options which take
no argument can be "clumped": combined into a single argument consisting of
a single
.code -
followed by multiple short option characters.

An option can take an argument, in which case the argument is required.
An option which takes no argument is Boolean, and a Boolean option
never takes an argument: "takes no argument" and "Boolean" effectively
mean the same thing.

Long options are invoked as an argument which begins with a
.code --
(double dash)
immediately followed by the name. When a long option takes an argument,
it is mandatory. It must be specified in the same argument, separated
from the name by the
.code =
character. If that is omitted, then the next command line argument
is taken as the argument. That argument is removed, and not recognized as
an option, even if it looks like one.

A Boolean long option can be explicitly specified as false using the
.code --no-
prefix rather than the
.code --
prefix.

Short options may be invoked using long name syntax; if
.code a
is a short option, then it may be referenced on the command line as
.code --a
and treated as a long option in all other ways, including the use
of
.code --no-
to explicitly specify false for a Boolean option.

If a short option takes an argument, it may not clump with other
short option. The following command line argument is taken as the
options argument. That argument is removed and is not recognized as
an option even if it looks like one.

If the command line argument
.code --
occurs in the command line where an option would otherwise be recognized,
it signifies the end of the options. The subsequent arguments are the
non-option arguments, even if they resemble options.

.NP* Command Line Processing Examples

The following example illustrates a complete \*(TL program which
parses command line options:

.verb
  (defvarl options
    (list (opt "v" "verbose" :dec
               "Verbosity level. Higher values produce more chatter.")
          (opt nil "help" :bool
               "List this help text.")
          (opt "x" nil :hex
               "The X factor: a number with a mysterious\e \e
                interpretation, affecting the program\e \e
                behavior in strange ways.")
          (opt "z" nil) ;; undocumented option
          (opt nil "cee" :cint
               "C style integer.")
          (opt "g" "gravity" :float
               "Gravitational constant. This gives\e \e
                the gravitational field\e \e
                strength at the Earth's surface.")
          (opt "l" "lit" :str
               "A character string given in TXR Lisp notation.")
          (opt "c" nil 'upcase-str
               "Custom treatment: ARG is converted to upper case.")
          (opt "b" "bool" :bool
               "A flag you can flip true.")))

  (defvarl prog-name *load-path*)

  (let ((o (getopts options *args*)))
    (when [o "help"]
      (put-line "Usage:\en")
      (put-line `  @{prog-name} [options] arg*`)
      (opthelp options)
      (exit 0))
    (put-line `args after opts are: @{o.out-args ", "}`))
.brev

The next example is equivalent to the previous, but using the
.code define-option-struct
macro:

.verb
  (define-option-struct prog-opts nil
    (v   verbose :dec
                 "Verbosity level. Higher values produce more chatter.")
    (nil help    :bool
                 "List this help text.")
    (x   nil     :hex
                 "The X factor: a number with a mysterious\e \e
                  interpretation, affecting the program\e \e
                  behavior in strange ways.")
    ;; undocumented Boolean:
    (z   nil)
    (nil cee     :cint
                 "C style integer.")
    (g   gravity :float
                 "Gravitational constant. This gives\e \e
                  the gravitational field\e \e
                  strength at the Earth's surface.")
    (l   lit     :str
                 "A character string given in TXR Lisp notation.")
    (c   nil     upcase-str
                 "Custom treatment: ARG is converted to upper case.")
    (b   bool    :bool
         "A flag you can flip true."))

  (defvarl prog-name *load-path*)

  (let ((o (new prog-opts)))
    o.(getopts *args*)
    (when o.help
      (put-line "Usage:\en")
      (put-line `  @{prog-name} [options] arg*`)
      o.(opthelp)
      (exit -1))
    (put-line `args after opts are: @{o.out-args ", "}`))
.brev

.coNP Structure @ opt-desc
.synb
.mets (defstruct opt-desc
.mets \ \  short long helptext type
.mets \ \  ... < unspecified << slots )
.syne
.desc
The
.code opt-desc
structure describes a single command line option.

The
.code short
and
.code long
slots are either
.code nil
or else hold strings.
The
.code short
slot gives the option's short name: a one-character-long
string which may not be the ASCII dash character
.codn - .
The
.code long
slot gives the option's long name: a string two or more
characters long which doesn't begin with a dash.
An option must have at least one of these names.

The
.code helptext
slot provides a descriptive string. This string may be long. The
.code opthelp
function displays this text, formatting into multiple lines as necessary.
If
.code helptext
is
.codn nil ,
the option is considered undocumented.

The
.code type
slot may be a symbol naming a global function which takes one argument,
or it may be such a function object. Otherwise it must be one of the
following keyword symbols:
.RS
.coIP :bool
This indicates that the type of the option is Boolean. Such
an option doesn't take any argument. Its value is
.code t
or
.codn nil .
.coIP :dec
This indicates that the option requires an argument, which is a
decimal integer with an optional positive or negative sign.
This argument is converted to an integer object.
.coIP :hex
This type indicates that the option requires an argument consisting
of a hexadecimal integer with an optional positive or negative sign.
This is converted to an integer object.
.coIP :oct
This type indicates that the option requires an argument consisting
of a octal integer with an optional positive or negative sign.
This is converted to an integer object.
.coIP :cint
This type indicates that the option requires an integer argument
whose format conforms to one of three C language conventions in most respects,
other than that this integer may have an arbitrary range.
All forms may carry an optional positive or negative leading sign
at the very beginning.
The first convention consists of decimal digits, which must not have
a superfluous leading zero. The second convention consists of octal
digits which are introduced by an extra leading zero.
The third convention consists of hexadecimal digits introduced by the
.code 0x
prefix.
.coIP :float
This type indicates a decimal floating-point argument, which is converted to
a floating-point number. Its basic form is: an optional leading plus or
minus sign, followed by a sequence of one or more digits which may contain
a single decimal point anywhere, including the very beginning of the
sequence or at the end, optionally followed by the letter
.code e
or
.code E
followed by a decimal integer which may have a leading positive or negative
sign, and include leading zeros.
.coIP :text
This type indicates a simple textual argument. The argument is taken as
verbatim UTF-8 text, converted to a string without interpreting
the characters in any special way.
.coIP :str
This type indicates that the argument consists of the interior notation of
a TXR Lisp character string. It is processed by adding a double quote
at the beginning or end, and parsed as a string literal. This parsing must
successfully yield a string object, otherwise the argument is ill-formed.
.meIP (list << type )
If the type is specified as a compound form headed by the
.code list
symbol, it indicates that the command line option's argument is a list
of elements.  The argument appears on the command line as a single string
contained within one argument.  It may contain commas, and is split into pieces
using the comma character as a separator. The pieces are then individually
treated as of type
.meta type
and converted accordingly. The option's argument is then a list object
whose elements are the converted pieces. For instance
.code "(list :dec)"
will convert a list of comma-separated decimal integer tokens into
a list of integer objects. The
.code list
option type does not nest.
.meIP (cumul << type )
If the type is specified as a compound form headed by the
.code cumul
symbol, it indicates that if the option is specified multiple times,
the values coming from the multiple occurrences are accumulated into a list.
The
.meta type
argument may be a
.code list
type, exemplified by
.code "(cumul (list :dec))"
or a basic type, such as
.codn "(cumul :str)" .
However, this type specifier does not nest. Combinations such as
.code "(cumul (cumul ...)"
and
.code "(list (cumul ...))"
are invalid.
The option values are accumulated in reverse order, so that the rightmost
repetition becomes the first item in the list. For instance, if the
.code -x
option has type
.codn "(cumul :dec)" ,
and the arguments presented for parsing are
.codn "(\(dq-x\(dq \(dq1\(dq \(dq-x\(dq \(dq2\(dq)" ,
then the option's value will be
.codn "(2 1)" .
If a
.codn list -typed
option is cumulative, then the option value will be a list of lists.
Each repetition of the option produces a list, and the lists are accumulated.

.RE

.IP
If
.code type
is a function, then the option requires an argument. The argument string
is passed to the function, and the value is whatever the function returns.

The
.code opt-desc
structure may have additional slots which are not specified.

The
.code opt
convenience function is provided for constructing
.code opt-desc
objects.

.coNP Function @ opt
.synb
.mets (opt < short < long >> [ type <> [ helptext ]])
.syne
.desc
The
.code opt
function provides a slightly condensed syntax for constructing
an object of type
.codn opt-desc .

The required arguments
.meta short
and
.meta long
are strings, corresponding to
.code opt-desc
slots of the same name.

The optional parameter
.meta type
corresponds to the same-named slot and defaults to
.codn :bool .

The optional parameter
.meta helptext
corresponds to the same-named slot, and defaults to
.code nil
(no help text provided for the option).

The
.code opt
function follows this equivalence:

.verb
  (opt a b c d)  <-->  (new opt-desc short a long b
                                     type c helptext d)
.brev

.coNP Structure @ opts
.synb
.mets (defstruct opts nil
.mets \ \  in-args out-args
.mets \ \  ... < unspecified << slots )
.syne
.desc
The
.code opts
structure represents a parsed command line, containing decoded
information obtained from the options, and an indication where
the non-option arguments start.

The
.code opts
structure supports direct indexing for option retrieval.
That is the only documented interface for accessing the parsed
options; the implementation of the information set describing
the parsed options is unspecified.

The
.code in-args
slot holds the original argument list.

The
.code out-args
slot holds the tail of the argument list consisting of the non-option
arguments.

The mechanism by means of which
.code out-args
is calculated, and by means of which the information about the
options is populated, is unspecified. The only interface to that
mechanism is the
.code getopts
function.

The
.code opts
object supports indexing, including indexed assignment.

If
.code o
is an instance of
.code opts
returned by
.codn getopts ,
then the expression
.code "[o \(dqv\(dq]"
tests whether the option
.str v
is available in
.codn o ;
that is, whether it has been specified in the command line.
If so, then its associated value is returned, otherwise
.code nil
is returned. This
.code nil
is ambiguous: for a Boolean option it indicates that either
the option was not specified, or that it was explicitly
specified as false. For a Boolean option that was specified
(positively), the value
.code t
is returned.

The expression
.code "[o \(dqv\(dq dfl]"
yields the value of option
.str v
if that option has been specified. If the option hasn't
been specified, then the expression yields the value
.codn dfl .

Assigning to
.code "[o \(dqv\(dq]"
is possible. This replaces the value associated with option
.strn v .
The assignment is erroneous if no such option was parsed
from the command line, even if it is a valid option.

If an option is defined with both a long form and a short form,
and either form of that option occurs in the command line being
processed, then the option appears under both names in the index.

For instance if option
.str --verbose
has the short form
.strn -v ,
and either option occurs, then both the keys
.str "v"
and
.str "verbose"
will exist in the
.code opts
structure returned by
.codn getopts .
Note that this behavior is different from that of the structure produced
.code define-option-struct
macro. Under that approach, if an option is defined with a long and short name,
the structure will have only a single slot for that option, named after the
long name.

.coNP Function @ getopts
.synb
.mets (getopts < option-desc-list << arg-list )
.syne
.desc
The
.code getopts
function takes a list of
.code opt-desc
structures and a list of strings
.meta arg-list
representing command line arguments.

The
.meta arg-list
is parsed. If the parse is unsuccessful, an exception of type
.code opt-error
is thrown, derived from
.codn error .

If there are problems in
.code option-desc-list
itself, then an exception of type
.code error
is thrown.

If the parse is successful,
.code getopts
returns an instance of the
.code opts
structure describing the parsed opts, and listing the non-option
arguments.

.coNP Function @ opthelp
.synb
.mets (opthelp < opt-desc-list <> [ stream ])
.syne
.desc
The
.code opthelp
function processes the list of
.code opt-desc
structures
.meta opt-desc-list
and compiles a customized body of help text describing all of the
options, as well as general description of the command line option
conventions to guide the user in in the correct use of command
line options.

The text is formatted to fit within 79 columns, and begins and ends with a
blank line. Its format consists of headings which begin in the first column,
and paragraphs and tables which feature a two space left margin.
A blank line follows each section heading. The heading begins with a capital
letter. Its remaining words are uncapitalized, and it ends with a colon.

The text is sent to
.metn stream ,
if specified. This argument defaults to
.codn *stdout* .

If there are problems in
.code option-desc-list
itself, then an exception of type
.code error
is thrown.

.coNP Macro @ define-option-struct
.synb
.mets (define-option-struct < name < super << opt-specifier *)
.syne
.desc
The
.code define-option-struct
macro defines a struct type, instances of which provide command line option
parsing.

The
.meta name
and
.meta super
parameters are subject to the same requirements and have the same
semantics as the same-named parameters of
.codn defstruct .

The
.meta opt-specifier
arguments are lists of between two and four elements:
.meti >> ( short-symbol < long-symbol >> [ type <> [ help-text ]]).
The
.meta short-symbol
and
.meta long-symbol
must be symbols suitable for use as slot names. One of them may be
specified as
.code nil
indicating that the option has no long form, or no short form.

If a
.meta opt-specifier
specifies both a
.meta short-symbol
and a
.meta long-symbol
then only a slot named by
.meta long-symbol
shall exist in the structure.

The struct type defined by
.code define-option-struct
has two methods:
.code getopts
and
.codn opthelp .
It also has two slots:
.code in-args
and
.codn out-args ,
which function in a manner identical to their same-named
counterparts in the
.code opts
class.

The
.code getopts
method takes a single argument: the argument list to be processed.
When the argument list is successfully processed.

The
.code opthelp
method takes an optional stream argument.

Note: to encode the option names
.str "t"
or
.strn "nil" ,
or option names which clash with the slot names
.code in-args
and
.code out-args
or the methods
.code getopts
or
.codn opthelp ,
symbols with these names from a package other than
.code usr
must be used.

.SS* System Programming
.coNP Accessor @ errno
.synb
.mets (errno <> [ new-errno ])
.mets (set (errno) << new-value )
.syne
.desc
The
.code errno
function retrieves the current value of the C library error variable
.codn errno .
If the argument
.meta new-errno
is present and is not
.codn nil ,
then it
specifies a value which is stored into
.codn errno .
The value returned is the prior value.

The place form of
.code errno
does not take an argument.

.coNP Function @ strerror
.synb
.mets (strerror << errno-value )
.syne
.desc
The
.code strerror
returns a character string which provides the host platform's description
of the integer
.meta errno-value
obtained from the
.code errno
function.

If the host platform fails to provide a description, the function returns
.codn nil .

.coNP Function @ exit
.synb
.mets (exit <> [ status ])
.syne
.desc
The
.code exit
function terminates the entire process (running \*(TX image), specifying
the termination status to the operating system. Values of the optional
.meta status
parameter may be
.codn nil ,
.codn t ,
or an integer value.  The value
.code nil
indicates an unsuccessful termination status, whereas
.code t
indicates a successful termination status.
An absence of the
.meta status
argument also specifies a successful termination status.
If
.meta status
is an integer value, it specifies a successful termination if it is
.code 0
otherwise the interpretation of the value is platform specific.

.coNP Variables @, e2big @, eacces @, eaddrinuse @, eaddrnotavail @, eafnosupport @, eagain @, ealready @, ebadf @, ebadmsg @, ebusy @, ecanceled @, echild @, econnaborted @, econnrefused @, econnreset @, edeadlk @, edestaddrreq @, edom @, edquot @, eexist @, efault @, efbig @, ehostunreach @, eidrm @, eilseq @, einprogress @, eintr @, einval @, eio @, eisconn @, eisdir @, eloop @, emfile @, emlink @, emsgsize @, emultihop @, enametoolong @, enetdown @, enetreset @, enetunreach @, enfile @, enobufs @, enodata @, enodev @, enoent @, enoexec @, enolck @, enolink @, enomem @, enomsg @, enoprotoopt @, enospc @, enosr @, enostr @, enosys @, enotconn @, enotdir @, enotempty @, enotrecoverable @, enotsock @, enotsup @, enotty @, enxio @, eopnotsupp @, eoverflow @, eownerdead @, eperm @, epipe @, eproto @, eprotonosupport @, eprototype @, erange @, erofs @, espipe @, esrch @, estale @, etime @, etimedout @, etxtbsy @ ewouldblock and @ exdev
.desc
These variables correspond to the POSIX
.cod2 \(dq errno
constants\(dq, namely
.codn E2BIG ,
.codn EACCES ,
.code EADDRINUSE
and so forth.
Variables corresponding to all of the
.code "<errno.h>"
constants from the Issue 6 2004 edition of POSIX are included.
The variables
.code eownerdead
and
.code enotrecoverable
from Issue 7 2018 are subject to the availability of the corresponding constants
in the host platform.

.coNP Function @ abort
.synb
.mets (abort)
.syne
.desc
The
.code abort
function terminates the entire process (running \*(TX image), specifying
an abnormal termination status to the process.

Note:
.code abort
calls the C library function
.code abort
which works by raising the
.code SIG_ABRT
signal, known in \*(TX as the
.code sig-abrt
variable. Abnormal termination of the process is this signal's
default action.

.coNP Functions @ at-exit-call and @ at-exit-do-not-call
.synb
.mets (at-exit-call << function )
.mets (at-exit-do-not-call << function )
.syne
.desc
The
.code at-exit-call
function registers
.meta function
to be called when the process terminates normally.
Multiple functions can be registered, and the same function
can be registered more than once. The registered
functions are called in reverse order of their
registrations.

The
.code at-exit-do-not-call
function removes all previous
.code at-exit-call
registrations of
.metn function .

The
.code at-exit-call
function returns
.metn function .

The
.code at-exit-do-not-call
function returns
.code t
if it removed anything,
.code nil
if no registrations of
.meta function
were found.

.coNP Function @ usleep
.synb
.mets (usleep << usec )
.syne
.desc
The
.code usleep
function suspends the execution of the program for at least
.meta usec
microseconds.

The return value is
.code t
if the sleep was successfully executed. A
.code nil
value indicates premature wakeup or complete failure.

Note: the actual sleep resolution is not guaranteed, and depends on granularity
of the system timer.  Actual sleep times may be rounded up to the nearest 10
millisecond multiple on a system where timed suspensions are triggered by a 100
Hz tick.

.coNP Functions @ mkdir and @ ensure-dir
.synb
.mets (mkdir < path <> [ mode ])
.mets (ensure-dir < path <> [ mode ])
.syne
.desc
.code mkdir
tries to create the directory named
.meta path
using the POSIX
.code mkdir
function.
An exception of type
.code file-error
is thrown if the function fails. Returns
.code t
on success.

The
.meta mode
argument specifies the request numeric permissions
for the newly created directory. If omitted, the requested permissions are
.code #o777
(511): readable and writable to everyone. The requested permissions
are subject to the system
.codn umask .

The function
.code ensure-dir
also creates a directory named
.metn path .
Unlike
.codn mkdir ,
it also attempt to create all the necessary parent directories,
and does not throw an error if
.meta path
refers to an existing object, if that object is a directory or a symbolic
link to a directory. Rather, in that case it returns
.code nil
instead of
.codn t .

.coNP Function @ chdir
.synb
.mets (chdir << path )
.syne
.desc
.code chdir
changes the current working directory to
.metn path ,
and returns
.metn t ,
or else throws an exception of type
.codn file-error .

.coNP Function @ pwd
.synb
.mets (pwd)
.syne
.desc
The
.code pwd
function retrieves the current working directory.
If the underlying
.code getcwd
C library function fails with an
.code errno
other than
.codn ERANGE ,
an exception will be thrown.

.coNP Function @ rmdir
.synb
.mets (rmdir << path )
.syne
.desc
The
.code rmdir
function removes the directory named by
.codn path .
If successful, it returns
.metn t ,
otherwise it throws an exception of type
.codn file-error .

Note:
.code rmdir
calls the same-named POSIX function, which requires
.code path
to be the name of an empty directory.

.coNP Function @ remove-path
.synb
.mets (remove-path < path <> [ throw-on-error-p ])
.syne
.desc
The
.code remove-path
function tries to remove the filesystem object named
by
.metn path ,
which may be a file, directory or something else.

If successful, it returns
.codn t .

The optional Boolean parameter
.metn throw-on-error-p ,
which defaults to
.codn nil .

A failure to remove the object results in an exception of type
.code file-error
being thrown, unless the failure reason is that the object indicated by
.meta path
doesn't exist. In this non-existence case, the behavior is controlled by the
.meta throw-on-error
argument. If that argument is true, the exception is thrown. Otherwise,
the function returns normally, producing the value
.code nil
to indicate that it didn't perform a removal.

.coNP Function @ rename-path
.synb
.mets (rename-path < from-path << to-path )
.syne
.desc
The
.code rename-path
function tries to rename filesystem path
.metn from-path ,
which may refer to a file, directory or something else, to the path
.metn to-path .

If successful, it returns
.codn t .

A failure results in an exception of type
.codn file-error .

.coNP Functions @ sh and @ run
.synb
.mets (sh << system-command )
.mets (run < program <> [ argument-list ])
.syne
.desc
The
.code sh
function executes
.meta system-command
using the system command interpreter.
The run function spawns a
.metn program ,
searching for it using the
system PATH.  Using either method, the executed process receives environment
variables from the parent.

\*(TX blocks until the process finishes executing. If the program terminates
normally, then its integer exit status is returned. The value zero indicates
successful termination.

The return value
.code nil
indicates an abnormal termination, or the inability
to run the process at all.

In the case of the
.code run
function, if the child process is created successfully
but the program cannot be executed, then the exit status will be an
.code errno
value from the failed
.code exec
attempt.

The standard input, output and error file descriptors of an executed
command are obtained from the streams stored in the
.codn *stdin* ,
.code *stdout*
and
.code *stderr*
special variables, respectively. For a detailed description of the
behavior and restrictions, see the
.code open-command
function, whose description of this mechanism applies to the
.code run
and
.code sh
function also.

Note: as of \*(TX 120, the
.code sh
function is implemented using
.code run
and not by means of the
.code system
C library function, as previously. The
.code run
function is used to invoke the system interpreter by name. On Unix-like
systems, the string
.code /bin/sh
is assumed to denote the system interpreter, which is expected to
support a pair of arguments
.mono
.meti -c < command
.onom
to specify the command to be executed. On MS Windows, the interpreter
is assumed to be the relative path name
.code cmd.exe
and expected to support
.mono
.meti /C < command
.onom
as a way of specifying a command to execute.

.SS* Unix Filesystem Manipulation

.coNP Structure @ stat
.synb
.mets (defstruct stat nil
.mets \ \  dev ino mod nlink uid gid
.mets \ \  rdev size blksize blocks
.mets \ \  atime atime-nsec mtime mtime-nsec
.mets \ \  ctime ctime-nsec path)
.syne
.desc
The
.code stat
structure defines the type of object which is returned
by the
.code stat
and
.code lstat
functions.  Except for
.codn path ,
.codn atime-nsec ,
.code ctime-nsec
and
.codn mtime-nsec ,
the slots are the direct counterparts of the
members of POSIX C structure
.codn "struct stat" .
For instance the slot
.code dev
corresponds to
.codn st_dev .

The
.code path
slot is set by the functions
.code stat
and
.codn lstat .
Its value is
.code nil
when the path is not available.

The
.codn atime-nsec ,
.code ctime-nsec
and
.code mtime-nsec
fields give the fractional parts of
.codn atime ,
.code ctime
and
.codn mtime ,
respectively. They are derived from the newer style information
in which the POSIX function provides the timestamps in
.code "struct timespec"
format. If that is not available from the platform, these
fields take on values of zero.

.coNP Functions @, stat @ lstat and @ fstat
.synb
.mets (stat >> { path | < stream | << fd } <> [ struct ])
.mets (lstat << path )
.mets (fstat >> { path | stream | << fd } <> [ struct ])
.syne
.desc
The
.code stat
function retrieves information about a filesystem object whose pathname
is given by the string argument
.metn path ,
or else about a system object associated with the open stream
.metn stream ,
or one associated with the integer file descriptor
.metn fd .

If a
.meta stream
is specified, that stream must be of a kind from which the
.code fileno
function can retrieve a file descriptor, otherwise an exception of type
.code file-error
is thrown.

If the object is not found or cannot be
accessed, an exception is thrown.

Otherwise, if the
.meta struct
argument is missing, information is retrieved and returned, in the form of a
new structure of type
.codn stat .
If the
.meta struct
argument is present, it must be either: an instance of the
.code struct
structure type, or of a type derived from that type by inheritance, or
else structure type which has all the same slots as the
.code struct
type. The retrieved information is stored into
.meta struct
and that object is returned rather than a new object.

If
.meta path
refers to a symbolic link, the
.code stat
function retrieves information about the target of the link, if it exists,
or else throws an exception of type
.codn file-error .

The
.code lstat
function behaves the same as
.code stat
on objects which are not symbolic links. For a symbolic link, it retrieves
information about the link itself, rather than its target.

The
.code path
slot of the returned structure
holds a copy of their
.meta path
argument value.
When information is retrieved using a
.meta stream
or
.meta fd
argument, this slot is
.codn nil .

The
.code fstat
function is an alias for
.codn stat .

Note: until \*(TX 231,
.code stat
and
.code fstat
were distinct functions:
.code stat
accepted only
.meta path
arguments, whereas
.code fstat
function accepted only
.meta stream
or
.meta fd
arguments.

.coNP Variables @, s-ifmt @, s-iflnk @, s-ifreg @, s-ifblk ... , @ s-ixoth
.desc
The following variables exist, having integer values. These are bitmasks
which can be applied against the value given by the
.code mode
slot of the
.code stat
structure returned by the function
.codn stat :
.codn s-ifmt ,
.codn s-ifsock ,
.codn s-iflnk ,
.codn s-ifreg ,
.codn s-ifblk ,
.codn s-ifdir ,
.codn s-ifchr ,
.codn s-ififo ,
.codn s-isuid ,
.codn s-isgid ,
.codn s-isvtx ,
.codn s-irwxu ,
.codn s-irusr ,
.codn s-iwusr ,
.codn s-ixusr ,
.codn s-irwxg ,
.codn s-irgrp ,
.codn s-iwgrp ,
.codn s-ixgrp ,
.codn s-irwxo ,
.codn s-iroth ,
.code s-iwoth
and
.codn s-ixoth .

These variables correspond to the C language constants from POSIX:
.codn S_IFMT ,
.codn S_IFLNK ,
.code S_IFREG
and so forth.

The
.code logtest
function can be used to test these against values of mode.
For example
.code "(logtest mode s-irgrp)"
tests for the group read permission.

.coNP Function @ umask
.synb
.mets (umask <> [ mask ])
.syne
.desc
The
.code umask
function provides access to the Unix C library function of the same name,
which controls which permissions are denied
when files are newly created.

If
.code umask
is called with no argument, it returns the current value of the mask.

If the
.meta mask
argument is present, it must be an integer specifying the new mask to be
installed.  The previous mask is returned.

If
.meta mask
is absent, then
.code umask
returns the previous mask.

Note: the value of the
.meta mask
argument may be calculated as a bitwise or of the following constants:
.codn s-irwxu ,
.codn s-irusr ,
.codn s-iwusr ,
.codn s-ixusr ,
.codn s-irwxg ,
.codn s-irgrp ,
.codn s-iwgrp ,
.codn s-ixgrp ,
.codn s-irwxo ,
.codn s-iroth ,
.code s-iwoth
and
.codn s-ixoth ,
which correspond to the POSIX C constants
.codn S_IRWXU ,
.codn S_IRUSR ,
.codn S_IWUSR ,
.codn S_IXUSR ,
.codn S_IRWXG ,
.codn S_IRGRP ,
.codn S_IWGRP ,
.codn S_IXGRP ,
.codn S_IRWXO ,
.codn S_IROTH ,
.code S_IWOTH
and
.codn S_IXOTH .

Implementation note: since the
.code umask
C library function provides no way to retrieve the current mask without
overwriting with a new one, the \*(TX
.code umask
function, when given no argument, simulates the pure retrieval of the mask
by calling the C function with an argument of
.code #o777
to temporarily install the maximally safe mask. The value returned is then
reinstated as the mask by another call to
.codn umask ,
and that value is also returned.

.coNP Functions @, makedev @ minor and @ major
.synb
.mets (makedev < minor << major )
.mets (minor << dev )
.mets (major << dev )
.syne
.desc
The parameters
.metn minor ,
.meta major
and
.meta dev
are all integers.  The
.code makedev
function constructs a combined device number from a minor and major pair (by
calling the Unix
.code makedev
function).  This device number is suitable as an
argument to the
.code mknod
function (see below). Device numbers also appear as values of the
.code dev
slot of the
.code stat
structure.

The
.code minor
and
.code major
functions extract the minor and major device number
from a combined device number.

.coNP Function @ chmod
.synb
.mets (chmod < target << mode )
.syne
.desc
The
.code chmod
function changes the permissions of the filesystem object
specified by
.metn target .
It is implemented in terms of the POSIX functions
.code chmod
and
.codn fchmod .
If
.meta mode
is a character string representing a symbolic mode, then the function
also makes use of
.code stat
or
.code fstat
and
.codn umask .


The permissions are specified by
.metn mode ,
which must be an integer or a string.

An integer
.meta mode
is a bitwise combination of permission mode bits. The value is passed
directly to the POSIX
.code chmod
or
.code fchmod
function.
Note: to construct a mode value, applications may use
.code logior
to combine the values
of the variables like
.code s-irusr
or
.code s-ixoth
or take advantage of the well-known numeric structure of POSIX
permissions to express them octal in octal notation.  For instance the mode
.code #o750
denotes that the owner has read, write and execute permissions,
the group owner has read and execute, others have no permission.
This value may also be calculated using
.codn "(logior s-irwxu s-irgrp s-ixgrp)" .

If the argument to
.meta mode
is a string, it is interpreted according to the symbolic syntax
of the POSIX
.code chmod
utility. For instance, a
.meta mode
value of
.str a+w,-s
means to give all users (owner, group and others) write permission,
and remove the setuid and setgid bits.

The full syntax and semantics of symbolic
.meta mode
strings is given in the POSIX standard IEEE 1003.1.

The function throws a
.code file-error
exception if an error occurs, otherwise it returns
.codn t .

The
.meta target
argument may be a character string, in which case it specifies a pathname in
the filesystem. In this case, the POSIX function
.code chmod
is invoked.

The
.meta target
argument may also be an integer file descriptor, or a stream. In these two
cases, the POSIX
.code fchmod
function is invoked. For a stream
.metn target ,
the integer file descriptor is retrieved from the stream using
.code fileno
function.

.TP* Example:
.verb
  ;; Set permissions of foo.txt to "rw-r--r--"
  ;; (owner can read and write; group owner
  ;; and other users can only read).

  ;; numerically:
  (chmod "foo.txt" #o644)

  ;; symbolically:
  (chmod "foo.txt" (logior s-irusr s-iwusr
                           s-irgrp
                           s-iroth))
.brev

Implementation note: The implementation of the symbolic
.meta mode
processing is based on the descriptions given in IEEE 1003.1-2018,
Issue 7 and also on the
.code chmod
program from from GNU Coreutils 8.28: and experiments with its behavior,
and its documentation.

.coNP Functions @ chown and @ lchown
.synb
.mets (chown < target < id << gid )
.mets (lchown < target < id << gid )
.syne
.desc
The
.code chown
and
.code lchown
functions change the user and group ownership of the filesystem object
specified by
.metn target .

They implemented in terms of the POSIX functions
.codn chown ,
.code fchown
and
.codn lchown .

The ownership attributes are specified by
.meta uid
and
.metn gid ,
both integer arguments.

The existing ownership attributes may be obtained using the
.code stat
function.

These functions throw a
.code file-error
exception if an error occurs, otherwise they returns
.codn t .

The
.meta target
argument may be a character string, in which case it specifies a pathname in
the filesystem. In this case, the same-named POSIX function
.code chown
is invoked by
.codn chown ,
whereas
.code lchown
likewise invokes its respective same-named POSIX counterpart.
The difference is that if
.meta target
is a pathname denoting a symbolic link, then
.code lchown
operates on the symbolic link, whereas
.code chown
dereferences the symbolic link.

The
.meta target
argument may also be an integer file descriptor, or a stream. In these two
cases, the POSIX
.code fchown
function is invoked by either function. For a stream
.metn target ,
the integer file descriptor is retrieved from the stream using
.code fileno
function.

Note: in most POSIX systems, unprivileged processes may not change the user
ownership denoted by
.metn uid .
They may change the group ownership indicated in
.metn gid ,
if that value corresponds to the effective group ID of the calling
process or one of its ancillary group IDs.

To avoid trying to change the user ownership (and therefore failing),
the caller should specify a
.meta uid
value which matches the object's existing owner.

.coNP Functions @ utimes and @ lutimes
.synb
.mets (utimes < target < atime-s < atime-ns < mtime-s << mtime-ns )
.mets (lutimes < target < atime-s < atime-ns < mtime-s << mtime-ns )
.syne
.desc
The functions
.code utimes
and
.code lutimes
change the access and modification timestamps of a file indicated by the
.meta target
argument.

The difference between the two functions is that if
.meta target
is the path name of a symbolic link, then
.code lutimes
operates on the symbolic link itself, whereas
.code utimes
resolves the symbolic link.

Note: the full, complete functionality of these functions requires the
platform to provide the POSIX functions
.code futimens
and
.code utimensat
functions.  If these functions are not available, then other functions are
relied on, with some reductions in functionality, that are documented below.

The
.meta target
argument specifies the file to operate on. It may be an integer file descriptor,
an open stream, or a character string representing a path name.

The
.meta atime-s
and
.meta mtime-s
parameters specify the whole seconds part of the new access and modification
times, expressed as seconds since the epoch.

The
.meta atime-ns
and
.meta mtime-ns
parameters specify the fractional part of the access and modification
times, expressed in nanoseconds. If an integer argument is given to these
parameters, it must lie in the range 0 to 999999999, or else the symbols
.code nil
or
.code t
may be passed as arguments.

If the symbol
.code nil
is passed as the nanoseconds part of the access or modification time,
then the access or modification time, respectively, shall not be modified
by the operation. The corresponding seconds argument is ignored.

If the symbol
.code t
is passed as the nanoseconds part of the access or modification time,
then the access or modification time, respectively, shall be obtained
from the current system time. The corresponding seconds argument is ignored.

If the
.code utimensat
and
.code futimens
functions are not available from the host system, then the above
.code nil
and
.code t
convention in the nanoseconds arguments is not supported; the function
will fail by throwing an exception if an attempt is made to pass these
arguments.

If the
.code utimensat
and
.code futimens
functions are not available from the host system, then operating on
a symbolic link with
.code lutimes
is only possible if the system provides the
.code lutimes
C library function, otherwise the operation fails by throwing an exception
(if given a path argument for
.metn target ,
even if that path isn't a symbolic link).

If the implementation falls back on the
.codn utimes ,
.codn futimes ,
and
.code lutimes
functions, then the nanoseconds arguments are truncated to microsecond
precision.

If the implementation falls back on
.codn utime ,
then the nanoseconds arguments are ignored; the times are effectively
truncated to whole seconds.

.coNP Function @ mknod
.synb
.mets (mknod < path < mode <> [ dev ])
.syne
.desc
The
.code mknod
function tries to create an entry in the filesystem: a file,
FIFO, or a device special file, under the name
.metn path .
If it is successful,
it returns
.codn t ,
otherwise it throws an exception of type
.codn file-error .

The
.meta mode
argument is a bitwise or combination of the requested permissions,
and the type of object to create: one of the constants
.codn s-ifreg ,
.codn s-ififo ,
.codn s-ifchr ,
.code s-ifblk
or
.codn s-ifsock .
The permissions are subject to the system
.codn umask .

If a block or character special device
.cod2 ( s-ifchr
or
.codn s-ifblk )
is being
created, then the
.meta dev
argument specifies the major and minor numbers
of the device. A suitable value can be constructed from a major and minor
pair using the
.code makedev
function.

.TP* Example:

.verb
   ;; make a character device (8, 3) called /dev/foo
   ;; requesting rwx------ permissions

   (mknod "dev/foo" (logior #o700 s-ifchr) (makedev 8 3))
.brev

.coNP Function @ mkfifo
.synb
.mets (mkfifo < path << mode )
.syne
.desc
The
.code mkfifo
function creates a POSIX FIFO object.
If it is successful,
it returns
.codn t ,
otherwise it throws an exception of type
.codn file-error .

The
.meta mode
argument is a bitwise or combination of the requested permissions,
and is subject to the system
.codn umask .

Note: the
.code mknod
function can also create FIFOs, specified via the bitwise combination
of the
.code s-ififo
type and the permission mode bits.

.coNP Functions @ symlink and @ link
.synb
.mets (symlink < target << path )
.mets (link < target << path )
.syne
.desc
The
.code symlink
function creates a symbolic link called
.meta path
whose contents
are the absolute or relative path
.metn target .
.meta target
does not actually have to exist.

The link function creates a hard link. The object at
.meta target
is installed
into the filesystem at
.meta path
also.

If these functions succeed, they return
.codn t .
Otherwise they throw an exception
of type
.codn file-error .

.coNP Function @ readlink
.synb
.mets (readlink << path )
.syne
.desc
If
.meta path
names a filesystem object which is a symbolic link, the
.code readlink
function reads the contents of that symbolic link and returns it
as a string.  Otherwise, it fails by throwing an exception of type
.codn file-error .

.coNP Function @ realpath
.synb
.mets (realpath << path )
.syne
.desc
The
.code realpath
function provides access to the same-named POSIX function.
It processes the input string
.meta path
by expanding all symbolic links, removes all superfluous
.str ".."
and
.str "."
path components, and extra path-separating slash characters,
to produce a canonical absolute path name.

If the underlying POSIX function indicates failure, then
.code nil
is returned. In that situation the
.code errno
value is available using the
.code errno
function.

.SS* Unix Filesystem Complex Operations

Functions in this category are complex functionality implemented using
a combination of multiple calls into the host system's POSIX API.

.coNP Functions @ copy-file and @ copy-files
.synb
.mets (copy-file < from-path < to-path >> [ perms-p <> [ times-p ]])
.mets (copy-file < from-list < to-dir >> [ perms-p <> [ times-p ]])
.syne
.desc
The
.code copy-file
function creates a replica of the file
.code from-path
at the destination path
.metn to-path .

Both paths are opened using
.code open-file
in binary mode, as if using
.mono
.meti (open-file < from-path "b")
.onom
and
.mono
.meti (open-file < to-path "wb")
.onom
respectively. Then bytes are read from one stream and written to the other,
in blocks which whose size is a power of two at least as large as 16834.

If the optional Boolean parameter
.meta perms-p
is specified, and is true, then the permissions of
.meta from-path
are propagated to
.metn to-path .

If the optional Boolean parameter
.meta times-p
is specified, and is true, then the access and modification timestamps of
.meta from-path
are propagated to
.metn to-path .

The
.code copy-file
function returns
.code nil
if it is successful, and throws an exception derived from
.code file-error
on failure.

The
.code copy-files
function copies multiple files, whose pathnames are given by the list argument
.meta from-list
into the target directory whose path is given by
.metn to-dir .

The target directory must exist.

For source each path in
.metn from-list ,
the
.code copy-files
function forms a target path by combining the base name of the
source path with
.metn target-dir .
(See the
.code base-name
and
.code path-cat
functions).
Then, the source path is copied to the resulting target path, as if by the
.code copy-file
function.

The
.code copy-files
function returns
.code nil
if it is successful, and throws an exception derived from
.code file-error
on failure.

Additionally,
.code copy-files
provides an internal catch for the
.code retry
and
.code skip
restart exceptions. If the caller, using a handler frame established by
.codn handle ,
catches an error emanating from the
.code copy-files
function, it can retry the failed operation by throwing the
.code retry
exception, or continue copying with the next file by throwing the
.code skip
exception.

.TP* Example:

.verb
  ;; Copy all "/mnt/cdrom/*.jpg" files into "images" directory,
  ;; preserving their time stamps,
  ;; continuing the operation in the face of
  ;; file-error exceptions.
  (handle
    (copy-files (glob "/mnt/cdrom/*.jpg") "images" nil t)
    (file-error (throw 'skip)))
.brev

.coNP Function @ copy-path-rec
.synb
.mets (copy-path-rec < from-path < to-path << option *)
.syne
.desc
The
.code copy-path-rec
function replicates a file system object identified by the path name
.metn from-path ,
creating a similar object named
.metn to-path .

If
.code from-path
is a directory, it is recursively traversed and its structure and content
is replicated under
.codn to-path .

The
.meta option
arguments are keywords, which may be the following:
.RS
.IP :perms
Propagate the permissions of all objects under
.meta from-path
onto their
.meta to-path
counterparts. In the absence of this option, the copied objects
receive permissions with are calculated by applying the
.code umask
of the calling process to the maximally liberal.
.IP :times
Propagate the modification and access time stamps of all objects under
.meta from-path
onto their
.meta to-path
counterparts.
.IP :symlinks
Copy symbolic links literally rather than dereferencing them.
Symbolic links are not altered in any way; their exact content
is preserved. Thus, relative symlinks which point outside of the
.meta from-path
tree may turn into dangling symlinks in the
.meta to-path
tree.
.IP :owner
Propagate the ownership of all objects under
.meta from-path
to their
.meta to-path
counterparts. Ownership refers to the owner user ID and group ID.
Without this option, the ownership of the copied objects is derived
from the effective user ID and group ID of the calling process.
Note that it is assumed that the host system may requires superuser
privileges to set both ownerships IDs of an object, and to set them to an
arbitrary value. An unprivileged process may not change the user ID of a file,
and may only change the group ID of a file which they own, to one of the groups
of which that process is a member, either via the effective GID, or the
ancillary list. The
.code copy-path-rec
function tests whether the application is running under superuser privileges;
if not, then it only honors the
.code :owner
option for those objects under
.meta from-path
which are owned by the caller, and owned by a group to
which the caller belongs.
Other objects are copied as if the
.code :owner
option were not in effect, avoiding an attempt to set their ownership
that is likely to fail.
.IP :all
The
.code :all
keyword is a shorthand representing all of the options being applied:
permissions, times, symlinks and ownership are replicated.
.RE

.IP
The
.code copy-path-rec
function creates all necessary path name components required for
.meta to-path
to come into existence, as if by using the
.code ensure-dir
function.

Whenever an object under
.meta from-path
has a counterpart in
.meta to-path
which already exists, the situation is handled as follows:
.RS
.IP 1.
If a directory object is copied to an existing directory object,
then that existing directory object is accepted as the copy, and
the operation continues recursively within that directory. If any options are
specified, then the requested attributes are propagated to that existing
directory.
.IP 2.
If a non-directory object is copied to a directory object, the
situation throws an exception: the
.code copy-path-rec
function refuses to delete an entire directory or subdirectory in order
to make way for a file, symbolic link, special device or any other kind
of non-directory object.
.IP 3.
If any object is copied to an existing non-directory object,
that target object is removed first, then the copy operation proceeds.
.RE
Copying of files takes place similarly as what is described for the
.code copy-file
function.

Special objects such as FIFOs, character devices, block devices and sockets
are copied by creating a new, similar objects at the destination path.
In the case of devices, the major and minor numbers of the copy are
derived from the original, so that the copy refers to the same device.
However, the copy of a socket or a FIFO is effectively a new, different
endpoint because these objects are identified by their path name.
Processes using the copy of a socket or a FIFO will not connect to
processes which are working with the original.

The
.code copy-path-rec
function returns
.code nil
if it is successful. It throws an exception derived from
.code file-error
when encountering failures.

Additionally
.code copy-path-rec
provides an internal catch for the
.code retry
and
.code skip
restart exceptions. If the caller, using a handler frame established by
.codn handle ,
catches an error emanating from the
.code copy-files
function, it can retry the failed operation by throwing the
.code retry
exception, or continue copying with the next object by throwing the
.code skip
exception.

.coNP Function @ remove-path-rec
.synb
.mets (remove-path-rec << path )
.syne
.desc
The
.code remove-path-rec
function attempts to remove the filesystem object named by
.metn path .
If
.meta path
refers to a directory, that directory is recursively traversed
to remove all of its contents, and is then removed.

The
.code remove-path-rec
function returns
.code nil
if it is successful. It throws an exception derived from
.code file-error
when encountering failures.

Additionally
.code remove-path-rec
provides an internal catch for the
.code retry
and
.code skip
restart exceptions. If the caller, using a handler frame established by
.codn handle ,
catches an error emanating from the
.code copy-files
function, it can retry the failed operation by throwing the
.code retry
exception, or continue removing other objects by throwing the
.code skip
exception. Skipping a failed remove operation may cause subsequent
operations to fail. Notably, the failure to remove an item inside
a directory means that removal of that directory itself will fail,
and ultimately,
.meta path
will still exist when
.code remove-path-rec
completes and returns.

.coNP Functions @ chmod-rec and @ chown-rec
.synb
.mets (chmod-rec < path << mode )
.mets (chown-rec < path < uid << gid )
.syne
.desc
The
.code chmod-rec
and
.code chown-rec
functions are recursive counterparts of
.code chmod
and
.codn lchown .

The filesystem object given by
.meta path
is recursively traversed, and each of its constituent objects
is subject to a permission change in the case of
.codn chown-rec ,
or an ownership change in the case of
.codn chown-rec .

The
.code chmod-rec
function alters the permission of each object that is not a symbolic link
using the
.code chmod
function, and
.meta mode
is interpreted accordingly: it may be an integer or string.
Each object which is a symbolic link is ignored.

The
.code chown-rec
function alters the permission of each object encountered, including
symbolic links, using the
.code lchown
function.

These functions establish restart catches, similarly to
.code remove-path-rec
and
.codn copy-path-rec ,
allowing the caller to retry individual failed operations or skip the objects
on which operations have failed.

.coNP Function @ touch
.synb
.mets (touch < path <> [ ref-path ])
.syne
.desc
The
.code touch
function updates the modification timestamp of the filesystem object
named by
.metn path .
If the object doesn't exist, it is created as a regular file.

If
.meta ref-path
is specified, then the modification timestamp of the object denoted by
.meta path
is updated to be equivalent to the modification timestamp of
the object denoted by
.metn ref-path .
Otherwise
.meta ref-path
being absent, the modification timestamp of
.meta path
is set to the current time.

If
.meta path
is a symbolic link, it is dereferenced;
.code touch
operates on the target of the link.

.SS* Unix Filesystem Object Existence, Type and Access Tests

Functions in this category perform various tests on the attributes of
filesystem objects.

The functions all have a
.meta path
parameter, which accepts three types of arguments. If a character
string is specified, it denotes a filesystem path to
be probed for properties such as ownership and permissions.
The object is probed using the
.code stat
function except in the case of
.code path-symlink-p
which uses
.codn lstat .
If instead a stream is specified as
.metn path ,
then the associated filesystem descriptor is probed for these properties.
If an integer value is specified, it is treated as a POSIX
open file descriptor that is to be probed.
Otherwise, a
.code stat
structure, for example one returned by the
.code stat
or
.code lstat
function may be specified, in which case no system object
is probed. The properties to be tested are those given in the
.code stat
object.

Note: in a situation when it is necessary to use any of these functions to
probe the properties of a symbolic link itself (other than the function
.code path-symlink-p
which does so implicitly) it is necessary to first invoke
.code lstat
on the symlink's path, and then pass the resulting
.code stat
structure to that function instead of the path.

Some of the accessibility tests (functions which determine whether the
calling process has certain access rights) may not be perfectly accurate, since
they are based strictly on portable information available via
.codn stat ,
together with the basic, portable POSIX APIs for inquiring about
security credentials, such as
.codn geteuid .
They ignoring any special permissions which may exist such as operating system
and file system specific extended attributes (for example, file immutability
connected to a "secure level" and such) and special process capabilities
not reflected in the basic credentials.

.coNP Function @ path-exists-p
.synb
.mets (path-exists-p << path )
.syne
.desc
The
.code path-exists-p
function returns
.code t
if
.meta path
is a string which resolves to a filesystem object.
Otherwise it returns
.codn nil .
If the
.meta path
names a dangling symbolic link, it is considered nonexistent.

If
.meta path
is an object returned by
.code stat
or
.codn lstat ,
.code path-exists-p
unconditionally returns
.codn t .

.coNP Functions @, path-file-p @, path-dir-p @, path-symlink-p @, path-blkdev-p @, path-chrdev-p @ path-sock-p and @ path-pipe-p
.synb
.mets (path-file-p << path )
.mets (path-dir-p << path )
.mets (path-symlink-p << path )
.mets (path-blkdev-p << path )
.mets (path-chrdev-p << path )
.mets (path-sock-p << path )
.mets (path-pipe-p << path )
.syne
.desc
.code path-file-p
tests whether
.meta path
exists and is a regular file.

.code path-dir-p
tests whether
.meta path
exists and is a directory.

.code path-symlink-p
tests whether
.meta path
exists and is a symbolic link.

Similarly,
.code path-blkdev-p
tests for a block device,
.code path-chrdev-p
for a character device,
.code path-sock-p
for a socket and
.code path-pipe-p
for a named pipe.

.coNP Function @ path-dir-empty
.synb
.mets (path-dir-empty << path )
.syne
.desc
The
.code path-dir-empty
function returns
.code t
if
.meta path
is an empty directory.

Implementation note: this function performs a test similar to
.codn path-dir-p ;
then, if it is confirmed that
.meta path
is a directory, a directory stream is opened and entries are read.
If an entry is seen which has a name other than
.str .
or
.str ..
then it is concluded that the directory is not empty and
.code nil
is returned. If no such entry is seen, then the directory is deemed empty and
.code t
is returned.

.coNP Functions @, path-setgid-p @ path-setuid-p and @ path-sticky-p
.synb
.mets (path-setgid-p << path )
.mets (path-setuid-p << path )
.mets (path-sticky-p << path )
.syne
.desc
.code path-setgid-p
tests whether
.meta path
exists and has the set-group-ID permission set.

.code path-setuid-p
tests whether
.meta path
exists and has the set-user-ID permission set.

.code path-sticky-p
tests whether
.meta path
exists and has the "sticky" permission bit set.

.coNP Functions @ path-mine-p and @ path-my-group-p
.synb
.mets (path-mine-p << path )
.mets (path-my-group-p << path )
.syne
.desc
.code path-mine-p
tests whether
.meta path
exists, and is effectively owned by the calling process; that is,
it has a user ID equal to the effective user ID of the process.

.code path-my-group-p
tests whether
.meta path
exists, and is effectively owned by a group to which the calling process
belongs. This means that the group owner is either the same as the
effective group ID of the calling process, or else is among the
supplementary group IDs of the calling process.

.coNP Function @ path-readable-to-me-p
.synb
.mets (path-readable-to-me-p << path )
.syne
.desc
.code path-readable-to-me-p
tests whether the calling process can read the
object named by
.metn path .
If necessary, this test examines the effective user ID of the
calling process, the effective group ID, and the list of supplementary groups.

.coNP Function @ path-writable-to-me-p
.synb
.mets (path-writable-to-me-p << path )
.syne
.desc
.code path-writable-to-me-p
tests whether the calling process can write the
object named by
.metn path .
If necessary, this test examines the effective user ID of the
calling process, the effective group ID, and the list of supplementary groups.

.coNP Function @ path-read-writable-to-me-p
.synb
.mets (path-read-writable-to-me-p << path )
.syne
.desc
.code path-readable-to-me-p
tests whether the calling process can both read and write the
object named by
.metn path .
If necessary, this test examines the effective user ID of the
calling process, the effective group ID, and the list of supplementary groups.

.coNP Function @ path-executable-to-me-p
.synb
.mets (path-executable-to-me-p << path )
.syne
.desc
.code path-executable-to-me-p
tests whether the calling process can execute the
object named by
.metn path ,
or perform a search (name lookup, not implying sequential readability) on it,
if it is a directory.
If necessary, this test examines the effective user ID of the
calling process, the effective group ID, and the list of supplementary groups.

.coNP Functions @ path-private-to-me-p and @ path-strictly-private-to-me-p
.synb
.mets (path-private-to-me-p << path )
.mets (path-strictly-private-to-me-p << path )
.syne
.desc
The
.code path-private-to-me-p
and
.code path-strictly-private-to-me-p
functions report whether the calling process can rely on the
object indicated by
.code path
to be, respectively, private or strictly private to the security context
implied by its effective user ID.

"Private" means that beside the effective user ID of the calling process and
the superuser, no other user ID has write access to the object, and thus its
contents may be trusted to be be free from tampering by any other user.

"Strictly private" means that not only is the object private, as above,
but users other than the effective user ID of the calling process
and superuser also not not have read access.

The rules which the function applies are as follows:

A file to be examined is initially assumed to be strictly private.

If the file is not owned by the effective user ID of the caller, or
else by the superuser, then it is not private.

If the file grants write permission to "others", then it is not private.

If the file grants read permission to "others", then it is not strictly
private.

If the file grants write permission to the group owner, then it is not
private if the group contains names other than that of the file owner or the
superuser.

If the file grants read permission to the group owner, then it is not
strictly private if the group contains names other than that of the file owner
or the superuser.

Note that this interpretation of "private" and "strictly private" is vulnerable
to the following time-of-check to time-of-use race condition with regard to the
group check.  At the time of the check, the group might be empty or contain
only the caller as a member. But by the time the file is subsequently accessed,
the group might have been innocently extended by the system administrator to
include additional users, who can maliciously modify the file.

Also note that the function is vulnerable to a time-of-check to time-of-use
race if
.meta path
is a string rather than a
.code stat
structure. If any components of the
.meta path
are symbolic links or directories that can be manipulated by other
users, then the object named by
.meta path
file can pass the check, but can later
.meta path
can be subverted to refer to a different object.

One way to guard against this race is to open the file, then use
.code fstat
on the stream to obtain a
.code stat
structure which is then used as an argument to
.code path-private-to-me-p
or
.codn path-strictly-private-to-me-p .

.coNP Functions @ path-newer and @ path-older
.synb
.mets (path-newer < left-path << right-path )
.mets (path-older < left-path << right-path )
.syne
.desc
The
.code path-newer
function compares two paths or stat results by modification time.
It returns
.code t
if
.meta left-path
exists, and either
.meta right-path
does not exist, or has a modification time stamp in the past
relative to
.metn left-path .

The
.code path-older
function is equivalent to
.code path-newer
with the arguments reversed.

Note:
.code path-newer
takes advantage of sub-second timestamp resolution information,
if available. The implementation is based on using the
.code mtime-nsec
field of the
.code stat
structure, if it isn't
.codn nil .

.coNP Function @ path-same-object
.synb
.mets (path-same-object < left-path << right-path )
.syne
.desc
The
.code path-same-object
function returns
.code t
if
.meta left-path
and
.meta right-path
resolve to the same filesystem object: the same inode number on the same
device.

.SS* Unix Credentials

.coNP Functions @, getuid @, geteuid @ getgid and @ getegid
.synb
.mets (getuid)
.mets (geteuid)
.mets (getgid)
.mets (getegid)
.syne
.desc
These functions directly correspond to the POSIX C library functions
of the same name. They retrieve the real user ID, effective user ID,
real group ID and effective group ID, respectively, of the calling
process.

.coNP Functions @, setuid @, seteuid @ setgid and @ setegid
.synb
.mets (setuid << uid )
.mets (seteuid << uid )
.mets (setgid << gid )
.mets (setegid << gid )
.syne
.desc
These functions directly correspond to the POSIX C library functions
of the same name. They set the real user ID, effective user ID,
real group ID and effective group ID, respectively, of the calling
process.
On success, they return
.codn t .
On failure, they throw an exception of type
.codn system-error .

.coNP Function @ getgroups
.synb
.mets (getgroups)
.syne
.desc
The
.code getgroups
function retrieves the list of supplementary group IDs of the calling
process by calling the same-named POSIX C library function.

Whether or not the effective group ID retrieved by
.code getegid
is included in this list is system-dependent. Programs should not
depend on its presence or absence.

.coNP Function @ setgroups
.synb
.mets (setgroups << gid-list )
.syne
.desc
The
.code setgroups
function corresponds to a C library function found in some Unix
operating systems, complementary to the
.code getgroups
function. The argument to
.meta gid-list
must be a list of numeric group IDs.
If the function is successful, this list is installed as the list of
supplementary group IDs of the calling process, and the value
.code t
is returned.
On failure, it throws an exception of type
.codn system-error .

.coNP Functions @ getresuid and @ getresgid
.synb
.mets (getresuid)
.mets (getresgid)
.syne
.desc
These functions directly correspond to the POSIX C library functions
of the same names available in some Unix operating systems.
Each function retrieves a three element list of numeric IDs.
The
.code getresuid
function retrieves the real, effective and saved user ID of
the calling process.
The
.code getresgid
function retrieves the real, effective and saved group ID of
the calling process.

.coNP Functions @ setresuid and @ setresgid
.synb
.mets (setresuid < real-uid < effective-uid << saved-uid )
.mets (setresgid < real-gid < effective-gid << saved-gid )
.syne
.desc
These functions directly correspond to the POSIX C library functions of the
same names available in some Unix operating systems.  They change the real,
effective and saved user ID or group ID, respectively, of the calling process.

A value of -1 for any of the IDs specifies that the ID is not to be changed.

Only privileged processes may arbitrarily change IDs to different values.

Unprivileged processes are restricted in the following way:
each of the new IDs that is replaced must have a new value which is equal to
one of the existing three IDs.

.SS* Unix Password Database

.coNP Structure @ passwd
.synb
.mets (defstruct passwd nil
.mets \ \  name passwd uid gid
.mets \ \  gecos dir shell)
.syne
.desc
The
.code passwd
structure corresponds to the C type
.codn "struct passwd" .
Objects of this struct are produced by the password database
query functions
.codn getpwent ,
.codn getpwuid ,
and
.codn getpwnam .

.coNP Functions @, getpwent @ setpwent and @ endpwent
.synb
.mets (getpwent)
.mets (setpwent)
.mets (endpwent)
.syne
.desc
The first time
.code getpwent
function is called, it returns the first password database entry.
On subsequent calls it returns successive entries.
Entries are returned as instances of the
.code passwd
structure.  If the function cannot retrieve an entry for any reason,
it returns
.codn nil .

The
.code setpwent
function rewinds the database scan.

The
.code endpwent
function releases the resources associated with the scan.

.coNP Function @ getpwuid
.synb
.mets (getpwuid << uid )
.syne
.desc
The
.code getpwuid
searches the password database for an entry whose user ID field
is equal to the numeric
.metn uid .
If the search is successful, then a
.code passwd
structure representing the database entry is returned.
If the search fails,
.code nil
is returned.

.coNP Function @ getpwnam
.synb
.mets (getpwnam << name )
.syne
.desc
The
.code getpwnam
searches the password database for an entry whose user name
is equal to
.metn name .
If the search is successful, then a
.code passwd
structure representing the database entry is returned.
If the search fails,
.code nil
is returned.

.SS* Unix Group Database

.coNP Structure @ group
.synb
.mets (defstruct group nil
.mets \ \  name passwd gid mem)
.syne
.desc
The
.code group
structure corresponds to the C type
.codn "struct group" .
Objects of this struct are produced by the password database
query functions
.codn getgrent ,
.codn getgrgid ,
and
.codn getgrnam .

.coNP Functions @, getgrent @ setgrent and @ endgrent
.synb
.mets (getgrent)
.mets (setgrent)
.mets (endgrent)
.syne
.desc
The first time
.code getgrent
function is called, it returns the first group database entry.
On subsequent calls it returns successive entries.
Entries are returned as instances of the
.code passwd
structure.  If the function cannot retrieve an entry for any reason,
it returns
.codn nil .

The
.code setgrent
function rewinds the database scan.

The
.code endgrent
function releases the resources associated with the scan.

.coNP Function @ getgrgid
.synb
.mets (getgrgid << gid )
.syne
.desc
The
.code getgrgid
searches the group database for an entry whose group ID field
is equal to the numeric
.metn gid .
If the search is successful, then a
.code group
structure representing the database entry is returned.
If the search fails,
.code nil
is returned.

.coNP Function @ getgrnam
.synb
.mets (getgrnam << name )
.syne
.desc
The
.code getgrnam
searches the group database for an entry whose group name
is equal to
.metn name .
If the search is successful, then a
.code group
structure representing the database entry is returned.
If the search fails,
.code nil
is returned.

.SS* Unix Password Hashing
.coNP Function @ crypt
.synb
.mets (crypt < key << salt )
.syne
.desc
The
.code crypt
function is a wrapper for the Unix C library function of the same name.
It calculates a hash over the
.meta key
and
.meta salt
arguments, which are strings. The hash is returned as a string.

The
.meta key
and
.meta salt
arguments are converted into UTF-8 prior to being passed into the underlying
platform function. The hash value is assumed to be UTF-8 and converted to
Unicode characters, though it is not expected to contain anything but 7
bit ASCII characters.

Note: the underlying C library function uses a static buffer for its return
value. The return value of the \*(TL function is a copy of that buffer.

.SS* Unix Signal Handling

On platforms where certain advanced features of POSIX signal handling are
available at the C API level, \*(TX exposes signal-handling functionality.

A \*(TX program can install a \*(TL function (such as an anonymous.
.codn lambda ,
or the function object associated with a named function) as the handler for
a signal.

When that signal is delivered, \*(TX will intercept it with its own safe,
internal handler, mark the signal as deferred (in a \*(TX sense) and then
dispatch the registered function at a convenient time.

Handlers currently are not permitted to interrupt the execution of most
\*(TX internal code.  Immediate, asynchronous execution of handlers is
currently enabled only while \*(TX is blocked on I/O operations or sleeping.
Additionally, the
.code sig-check
function can be used to dispatch and clear deferred
signals. These handlers are then safely called if they were subroutines of
.codn sig-check ,
and not asynchronous interrupts.

.coNP Variables @, sig-hup @, sig-int @, sig-quit @, sig-ill @, sig-trap @, sig-abrt @, sig-bus @, sig-fpe @, sig-kill @, sig-usr1 @, sig-segv @, sig-usr2 @, sig-pipe @, sig-alrm @, sig-term @, sig-chld @, sig-cont @, sig-stop @, sig-tstp @, sig-ttin @, sig-ttou @, sig-urg @, sig-xcpu @, sig-xfsz @, sig-vtalrm @, sig-prof @, sig-poll @, sig-sys @, sig-winch @, sig-iot @, sig-stkflt @, sig-io @ sig-lost and @ sig-pwr
.desc
These variables correspond to the C signal constants
.codn SIGHUP ,
.code SIGINT
and so forth.
The variables
.codn sig-winch ,
.codn sig-iot ,
.codn sig-stkflt ,
.codn sig-io ,
.code sig-lost
and
.code sig-pwr
may not be available since a system may lack the corresponding signal
constants. See notes for the function
.codn log-authpriv .

The highest signal number is 31.

.coNP Functions @ set-sig-handler and @ get-sig-handler
.synb
.mets (set-sig-handler < signal-number << handling-spec )
.mets (get-sig-handler << signal-number )
.syne
.desc
The
.code set-sig-handler
function is used to specify the handling for a signal, such
as the installation of a handler function. It updates the signal handling for
a signal whose number is
.meta signal-number
(usually one of the constants like
.codn sig-hup ,
.code sig-int
and so forth), and returns the previous value.  The
.code get-sig-handler
function returns the current value.

The
.meta signal-number
must be an integer the range 1 to 31.

Initially, all 31 signal handling specifications are set to the value
.codn t .

The
.meta handling-spec
parameter may be a function. If a function is specified,
then the signal is enabled and connected to that function until another
call to
.code set-sig-handler
changes the handling for that signal.

If
.meta handling-spec
is the symbol
.codn nil ,
then the function previously associated
with the signal, if any, is removed, and the signal is disabled. For a signal
to be disabled means that the signal is set to the
.code SIG_IGN
disposition (refer to the C API).

If
.meta handling-spec
is the symbol
.codn t ,
then the function previously associated
with the signal, if any, is removed, and the signal is set to its default
disposition. This means that it is set to
.code SIG_DFL
(refer to the C API).
Some signals terminate the process if they are generated while the
handling is configured to the default disposition.

Note that the certain signals like
.code sig-quit
and
.code sig-kill
cannot be ignored or handled.
Please observe the signal documentation in the IEEE POSIX standard, and your
platform.

A signal handling function must take two arguments. It is of the form:

.mono
.mets (lambda >> ( signal << async-p ) ...)
.onom

The
.meta signal
argument is an integer indicating the signal number for which the
handler is being invoked. The
.meta asyncp-p
argument is a Boolean value.
If it is
.codn t ,
it indicates that the handler is being invoked
asynchronously\(emdirectly in a signal handling context.  If it is
.codn nil ,
then it
is a deferred call.  Handlers may do more things in a deferred call, such
as terminate by throwing exceptions, and perform I/O.

The return value of a handler is normally ignored. However if it invoked
asynchronously (the
.meta async-p
argument is true), then if the handler returns
a
.cod2 non- nil
value, it is understood that the handler
requesting that it be deferred. This means that the signal will be marked
as deferred, and the handler will be called again at some later
time in a deferred context, whereby
.meta async-p
is
.codn nil .
This is not guaranteed, however;
it's possible that another signal will arrive before that happens,
possibly resulting in another async call, so the handler must
be prepared to deal with an async call at any time.

If a handler is invoked synchronously, then its return value is ignored.

In the current implementation, signals do not queue. If a signal is delivered
to the process again, while it is marked as deferred, it simply stays deferred;
there is no counter associated with a signal, only a Boolean flag.

.coNP Function @ sig-check
.synb
.mets (sig-check)
.syne
.desc
The
.code sig-check
function tests whether any signals are deferred, and for each
deferred signal in turn, it executes the corresponding handler.  For a signal to
be deferred means that the signal was caught by an internal handler in
\*(TX and the event was recorded by a flag.  If a handler function is removed
while a signal is deferred, the deferred flag is cleared for that signal.

Calls to the
.code sig-check
function may be inserted into CPU-intensive code that
has no opportunity to be interrupted by signals, because it doesn't invoke any
I/O functions.

.coNP Function @ raise
.synb
.mets (raise << signal )
.syne
.desc
The
.code raise
function sends
.meta signal
to the process.
It is a wrapper for the C function of the same name.

The return value is
.code t
if the function succeeds, otherwise
.codn nil .

.coNP Function @ kill
.synb
.mets (kill < process-id <> [ signal ])
.syne
.desc
The
.code kill
function is used for sending a signal to a process group or process.
It is a wrapper for the POSIX
.code kill
function.

If the
.meta signal
argument is omitted, it defaults to the same value as
.codn sig-term .

The return value is
.code t
if the function succeeds, otherwise
.codn nil .

.coNP Function @ strsignal
.synb
.mets (strsignal << signal )
.syne
.desc
The
.code strsignal
function returns a character string describing the specified signal number.
It is based on the same-named POSIX C library function.

.SS* Unix Processes

.coNP Functions @ fork and @ wait
.synb
.mets (fork)
.mets (wait >> [ pid <> [ flags ]])
.syne
.desc
The
.code fork
and
.code wait
functions are interfaces to the Unix functions
.code fork
and
.codn waitpid .

The
.code fork
function creates a child process which is a replica of the parent. Both
processes return from the function. In the child process, the return value is
zero. In the parent, it is an integer representing the process ID of the child.
If the function fails to create a child, it returns
.code nil
rather than an integer. In this case, the
.code errno
function can be used to inquire about the cause.

The
.code wait
function, if successful, returns a cons cell consisting of a pair of integers.
The
.code car
of the cons is the process ID of the process or group which was successfully
waited on, and the
.code cdr
is the status. If
.code wait
fails, it returns
.codn nil .
The
.code errno
function can be used to inquire about the cause.

The
.meta process-id
argument, if not supplied, defaults to -1, which means that
.code wait
waits for any process, rather than a specific process. Certain other
values have special meaning, as documented in the POSIX standard
for the
.code waitpid
function.

The
.meta flags
argument defaults to zero. If it is specified as nonzero, it should be
a bitwise combination (via the
.code logior
function) of the variables
.codn w-nohang ,
.code w-untraced
and
.codn w-continued .
If
.code w-nohang
is used, then
.code wait
returns a cons cell whose
.code car
specifies a process ID value of zero in the situation that at least
one of the processes designated by
.code process-id
exist and are children of the calling process, but have not changed state.
In this case, the status value in the
.code cdr
is unspecified.

Status values may be inspected with the functions
.codn w-ifexited ,
.codn w-exitstatus ,
.codn w-ifsignaled ,
.codn w-termsig ,
.codn w-coredump ,
.codn w-ifstopped ,
.code w-stopsig
and
.codn w-ifcontinued .

.coNP Functions @, w-ifexited @, w-exitstatus @, w-ifsignaled @, w-termsig @, w-coredump @ w-ifstopped and @ w-stopsig
.synb
.mets (w-ifexited << status )
.mets (w-exitstatus << status )
.mets (w-ifsignaled << status )
.mets (w-termsig << status )
.mets (w-coredump << status )
.mets (w-ifstopped << status )
.mets (w-stopsig << status )
.mets (w-ifcontinued << status )
.syne
.desc
These functions analyze process exit values produced by the
.code wait
function.

They are closely based on the
POSIX macros
.codn WIFEXITED ,
.codn WEXITSTATUS ,
and so on.

The
.meta status
value is either an integer, or a cons cell. In this case, the cons
cell is expected to have an integer in its
.code cdr
which is used as the status.

The
.codn w-ifexited ,
.codn w-ifsignaled ,
.codn w-coredump ,
.code w-ifstopped
and
.code w-ifcontinued
functions have Lisp Boolean return semantics, unlike their C language
counterparts: they return
.code t
or
.codn nil ,
rather than zero or nonzero. The others return integer values.

.coNP Function @ exec
.synb
.mets (exec < file <> [ args ])
.syne
.desc
The exec function replaces the process image with the executable specified
by string argument
.metn file .
The executable is found by searching the system path.

The
.meta file
argument becomes the first argument of the executable, argument zero.

If
.meta args
is specified, it is a list of strings. These are passed as the additional
arguments of the executable.

If
.code exec
fails, an exception of type
.code file-error
is thrown.

.coNP Function @ exit*
.synb
.mets (exit* << status )
.syne
.desc
The
.code exit*
function terminates the entire process (running \*(TX image), specifying
the termination status to the operating system. The
.meta status
argument is treated exactly like that of the
.code exit
function. Unlike that function, this one exits the process immediately,
cleaning up only low-level operating system resources such as closing file
descriptors and releasing memory mappings, without performing user-space
cleanup.

.code exit*
is implemented using a call to the POSIX function
.codn _exit .

.coNP Functions @ getpid and @ getppid
.synb
.mets (getpid)
.mets (getppid)
.syne
.desc
These functions retrieve the current process ID and the parent process ID
respectively. They are wrappers for the POSIX functions
.code getpid
and
.codn getppid .

.coNP Function @ daemon
.synb
.mets (daemon < nochdir-p << noclose-p )
.syne
.desc
This is a wrapper for the function
.code daemon
which originated in BSD Unix.

It returns
.code t
if successful,
.code nil
otherwise, and the
.code errno
variable is set in that case.

.SS* Unix File Descriptors

.coNP Function @ open-fileno
.synb
.mets (open-fileno < file-descriptor <> [ mode-string ])
.syne
.desc
The
.code open-fileno
function creates a \*(TX stream over a file descriptor. The
.meta file-descriptor
argument must be an integer denoting a valid file descriptor.

For a description of
.metn mode-string ,
see the
.code open-file
function.

.coNP Function @ fileno
.synb
.mets (fileno << stream )
.syne
.desc
The
.code fileno
function returns the underlying file descriptor of
.metn stream ,
if it has one. Otherwise, it returns
.codn nil .

This is equivalent to querying the stream using
.code stream-get-prop
for the
.code :fd
property.

.coNP Function @ dupfd
.synb
.mets (dupfd < old-fileno <> [ new-fileno ])
.syne
.desc
The
.code dupfd
function provides an interface to the POSIX functions
.code dup
or
.codn dup2 ,
when called with one or two arguments, respectively.

.coNP Function @ pipe
.synb
.mets (pipe)
.syne
.desc
The
.code pipe
function, if successful, returns a pair of integer file descriptors
as a cons cell pair. The descriptor in the
.code car
field of the pair is the read end of the pipe.
The
.code cdr
holds the write end.

If the function fails, it throws an exception of type
.codn file-error .

.coNP Function @ close
.synb
.mets (close < fileno <> [  throw-on-error-p ])
.syne
.desc
The
.code close
function passes the integer descriptor
.meta fileno
to the POSIX
.code close
function.  If the operation is successful, then
.code t
is returned. Otherwise an exception of type
.code file-error
is thrown, unless the
.meta throw-on-error-p
argument is present, with a true value. In that case,
.code close
indicates failure by returning
.codn nil .

.coNP Function @ poll
.synb
.mets (poll < poll-list <> [ timeout ])
.syne
.desc
The
.code poll
function suspends execution while monitoring one or more file descriptors
for specified events. It is a wrapper for the same-named POSIX function.

The
.meta poll-list
argument is a list of
.code cons
pairs. The
.code car
of each pair is either an integer file descriptor, or else a stream
object which has a file descriptor (the
.code fileno
function can be applied to that stream to retrieve a descriptor).
The
.code cdr
of each pair is an integer bit mask specifying the events, whose
occurrence the file descriptor is to be monitored for. The variables
.codn poll-in ,
.codn poll-out ,
.code poll-err
and several others are available which hold bitmask values corresponding
to the constants
.codn POLLIN ,
.codn POLLOUT ,
.code POLLERR
used with the C language
.code poll
function.

The
.meta timeout
argument, if absent, defaults to the value -1, which specifies an indefinite
wait. A nonnegative value specifies a wait with a timeout, measured in
milliseconds.

The function returns a list of pairs representing the descriptors or streams
which were successfully polled. If the function times out, it returns an
empty list. If an error occurs, an exception is thrown.

The returned list is similar in structure to the input list. However, it holds
only entries which polled positive. The
.code cdr
of every pair now holds a bitmask of the events which were to have occurred.

.coNP Function @ isatty
.synb
.mets (isatty << stream )
.mets (isatty << fileno )
.syne
.desc
The
.code isatty
function provides access to the underlying POSIX function of the same name.

If the argument is a
.meta stream
object which has a
.code :fd
property, then the file descriptor number is retrieved. The behavior is
then as if that descriptor number were passed as the
.meta fileno
argument.

If the argument is not a
.metn stream ,
it must be a
.metn fileno :
an integer in the representation range of the C type
.codn int .

The POSIX
.code isatty
is invoked on this integer. If it that returns 1, then
.code t
is returned, otherwise
.codn nil .

.SS* Unix File Control

.coNP Variables @, o-accmode @, o-rdonly @, o-wronly @, o-rdwr @, o-creat @, o-noctty @, o-trunc @, o-append @, o-nonblock @, o-sync @, o-async @, o-directory @, o-nofollow @, o-cloexec @, o-direct @ o-noatime and @ o-path
.desc
These variables correspond to the POSIX file mode constants
.codn O_ACCMODE ,
.codn O_RDONLY ,
.codn O_WRONLY ,
.codn O_RDWR ,
.codn O_CREAT ,
.codn O_NOCTTY ,
and so forth.

The availability of the variables
.codn o-async ,
.codn o-directory ,
.codn o-nofollow ,
.codn o-cloexec ,
.codn o-direct ,
.code o-noatime
and
.code o-path
depends on the host platform.

Some of these flags may be set or cleared on an existing file descriptor
using the
.code f-setfl
command of the
.code fcntl
function, in accordance with POSIX and the host platform documentation.

.coNP Variables @, seek-set @ seek-cur and @ seek-end
.desc
These variables correspond to the ISO C constants
.codn SEEK_SET ,
.code SEEK_CUR
and
.codn SEEK_END .
These values, usually associated with the ISO C
.code fseek
function, are also used in the
.code fcntl
file locking interface as values of the
.code whence
member of the
.code flock
structure.

.coNP Variables @, f-dupfd @, f-dupfd-cloexec @, f-getfd @, f-setfd @, f-getfl @, f-setfl @, f-getlk @ f-setlk and @ f-setlkw
.desc
These variables correspond to the POSIX
.code fcntl
command constants
.codn F_DUPFD ,
.codn F_GETFD ,
.codn F_SETFD ,
and so forth. Availability of the
.code f-dupfd-cloexec
depends on the host platform.

.coNP Variable @ fd-cloexec
.desc
The
.code fd-cloexec
variable corresponds to the POSIX
.code FD_CLOEXEC
constant. It denotes the flag which may  be set by the
.code fd-setfd
command of the
.code fcntl
function.

.coNP Variables @, f-rdlck @ f-wrlck and @ f-unlck
.desc
These variables correspond to the POSIX lock type constants
.codn F_RDLCK ,
.code F_WRLCK
and
.codn F_UNLCK .
They specify the possible values of the
.code type
field of the
.code flock
structure.

.coNP Structure @ flock
.synb
.mets (defstruct flock nil
.mets \ \  type whence
.mets \ \  start len
.mets \ \  pid)
.syne
.desc
The
.code flock
structure corresponds to the POSIX structure of the same name.
An instance of this structure must be specified as the third
argument of the
.code fcntl
function when the
.meta command
argument is one of the values
.codn f-getlk ,
.code f-setlk
or
.codn f-setlkw .

All slots must be initialized with appropriate values before
calling
.code fcntl
with the exception that the
.code f-getlk
command does not access the existing value of the
.code pid
slot.

.coNP Function @ fcntl
.synb
.mets (fcntl < fileno < command <> [ arg ])
.syne
.desc
The
.code fcntl
function corresponds to the same-named POSIX function.
The
.meta fileno
and
.meta command
arguments must be integers.
The \*(TL
.code fileno
restricts the
.meta command
argument to the supported values for which symbolic variable names are provided.
Other integer
.meta command
values are rejected by returning -1 and setting the
.code errno
variable to
.codn EINVAL .
Whether the third argument is required, and what type it must be, depends on the
.meta command
value. Commands not requiring the third argument ignore it if it is passed.

.code fcntl
commands for which POSIX requires an argument of type
.code long
require
.meta arg
to be an integer.

The file locking commands
.codn f-getlk ,
.code f-setlk
and
.code f-setlkw
require
.meta arg
to be a
.code flock
structure.

The
.code fcntl
function doesn't throw an error if the underlying POSIX function indicates
failure; the underlying function's return value is converted to a Lisp integer
and returned.

.SS* Unix Itimers
Itimers ("interval timers") can be used in combination with signal handling to
execute asynchronous actions. Itimers deliver delayed, one-time signals,
and also periodically recurring signals. For more information, consult the
POSIX specification.

.coNP Variables @, itimer-real @ itimer-virtual and @ itimer-prof
.desc
These variables correspond to the POSIX constants
.codn ITIMER_REAL ,
.code ITIMER_VIRTUAL
and
.codn ITIMER_PROF .
Their values are suitable as the
.meta timer
argument of the
.code getitimer
and
.code setitimer
functions.

.coNP Functions @ getitimer and @ setitimer
.synb
.mets (getitimer << timer )
.mets (setitimer < timer < interval << value )
.syne
.desc
The
.code getitimer
function returns the current value of the specified timer,
which must be
.codn itimer-real ,
.code itimer-virtual
or
.codn itimer-prof .

The current value consists of a list of two integer values, which
represents microseconds. The first value is the timer interval,
and the second value is the timer's current value.

Like
.codn getitimer ,
the
.code setitimer
function also retrieves the specified timer.
In addition, it stores a new value in the timer,
which is given by the two arguments, expressed in microseconds.

.SS* Unix Syslog

On platforms where a Unix-like syslog API is available, \*(TX exports this
interface. \*(TX programs can configure logging via the
.code openlog
function,
control the logging mask via
.code setlogmask
and generate logs via
.codn syslog ,
or using special syslog streams.

.coNP Variables @, log-pid @, log-cons @, log-ndelay @, log-odelay @ log-nowait and @ log-perror
.desc
These variables take on the values of the corresponding C preprocessor
constants from the
.code <syslog.h>
header:
.codn LOG_PID ,
.codn LOG_CONS ,
etc.
These integer values represent logging options used in the
.meta options
argument to the
.code openlog
function.

Note:
.code LOG_PERROR
is not in POSIX, and so
.code log-perror
might not be available.
See notes about
.code LOG_AUTHPRIV
in the documentation for
.codn log-authpriv .

.coNP Special variables @, log-user @, log-daemon @ log-auth and @ log-authpriv
.desc
These variables take on the values of the corresponding C preprocessor
constants from the
.code <syslog.h>
header:
.codn LOG_USER ,
.codn LOG_DAEMON ,
.code LOG_AUTH
and
.codn LOG_AUTHPRIV .
These are the integer facility codes specified in the
.code openlog
function.

Note:
.code LOG_AUTHPRIV
is not in POSIX, and so
.code log-authpriv
might not be available.
For portability use code like
.code "(or (symbol-value 'log-authpriv) 0)"
to evaluate to 0 if
.code log-authpriv
doesn't exist, or else check for its existence
using
.codn "(boundp 'log-authpriv)" .

.coNP Variables @, log-emerg @, log-alert @, log-crit @, log-err @, log-warning @, log-notice @ log-info and @ log-debug
.desc
These variables take on the values of the corresponding C preprocessor
constants from the
.code <syslog.h>
header:
.codn LOG_EMERG ,
.codn LOG_ALERT ,
etc.
These are the integer priority codes specified in the
.code syslog
function.

.coNP The @ *stdlog* special variable
.desc
The
.code *stdlog*
variable holds a special kind of stream: a syslog stream.  Each
newline-terminated line of text sent to this stream becomes a log message.

The stream internally maintains a priority value that is applied
when it generates messages. By default, this value is that of
.codn log-info .
The stream holds the priority as the value of the
.code :prio
stream property, which may be changed with the
.code stream-set-prop
function.

The latest priority value which has been configured on the stream is used
at the time the newline character is processed and the log message
is generated, not necessarily the value which was in effect at the time the
accumulation of a line began to take place.

Messages sent to
.code *stdlog*
are delimited by newline characters. That is to say, each line of
text written to the stream is a new log.

.coNP Function @ openlog
.synb
.mets (openlog < id-string >> [ options <> [ facility ]])
.syne
.desc
The
.code openlog
function is a wrapper for the
.code openlog
C function, and the
arguments have the same semantics. It is not necessary to use
.code openlog
in order
to call the
.code syslog
function or to write data to
.codn *stdlog* .
The call is necessary in order to override the default identifying string, to
set options, such as having the PID (process ID) recorded in log messages, and
to specify the facility.

The
.meta id-string
argument is mandatory.

The
.meta options
argument is a bitwise mask (see the logior function) of option
values such as
.code log-pid
and
.codn log-cons .
If it is missing, then a value of 0 is
used, specifying the absence of any options.

The
.meta facility
argument is one of the values
.codn log-user ,
.code log-daemon
or
.codn log-auth .
If it is missing, then
.code log-user
is assumed.

.coNP Function @ closelog
.synb
.mets (closelog)
.syne
.desc
The
.code closelog
function is a wrapper for the C function
.codn closelog .

.coNP Function @ setlogmask
.synb
.mets (setlogmask << bitmask-integer )
.syne
.desc
The
.code setlogmask
function interfaces to the corresponding C function, and has the
same argument and return value semantics. The
.meta bitmask-integer
argument is a mask of priority
values to enable. The return value is the prior value. Note that if the
argument is zero, then the function doesn't set the mask to zero; it only
returns the current value of the mask.

Note that the priority values like
.code log-emerg
and
.code log-debug
are integer
enumerations, not bitmasks. These values cannot be combined directly to create
a bitmask. Rather, the
.code mask
function should be used on these values.

.TP* Example:

.verb
  ;; Enable LOG_EMERG and LOG_ALERT messages,
  ;; suppressing all others
  (setlogmask (mask log-emerg log-alert))
.brev

.coNP Function @ syslog
.synb
.mets (syslog < priority < format << format-arg *)
.syne
.desc
The
.code syslog
function is the interface to the
.code syslog
C function. The
.code printf
formatting capabilities of the function are not used;
the
.meta format
argument follows the conventions of the \*(TL 
.code format
function instead. Note in particular that
the
.code %m
convention for interpolating the value of strerror(errno) which is
available in some versions of the
.code syslog
C function is currently not supported.

Note that syslog messages are not newline-terminated.

.SS* Unix Path Globbing

On platforms where the POSIX
.code glob
function is available \*(TX provides this functionality in
the form of a like-named function, and some numeric constants.
\*(TX also provides access the
.code fnmatch
function, where available.

.coNP Variables @, glob-err @, glob-mark @, glob-nosort @, glob-nocheck @, glob-noescape @, glob-period @, glob-altdirfunc @, glob-brace @, glob-nomagic @, glob-tilde @ glob-tilde-check and @ glob-onlydir
.desc
These variables take on the values of the corresponding C preprocessor
constants from the
.code <glob.h>
header:
.codn GLOB_ERR ,
.codn GLOB_MARK ,
.codn GLOB_NOSORT ,
etc.

These values are passed as the optional second argument of the
.code glob
function. They are bitmasks and so multiple values can be combined
using the
.code logior
function.

Note that the
.codn glob-period ,
.codn glob-altdirfunc ,
.codn glob-brace ,
.codn glob-nomagic ,
.codn glob-tilde ,
.code glob-tilde-check
and
.code glob-onlydir
variables may not be available. They are extensions in the GNU C library
implementation of
.codn glob .

.coNP Function @ glob
.synb
.mets (glob < pattern >> [ flags <> [ errfun ]])
.syne
.desc
The
.code glob
function is a interface to the Unix function of the same name.
The
.meta pattern
argument must be a string, which holds a glob pattern: a pattern which
matches zero or more path names, similar to a regular expression.
The function tries to expand the pattern and return a list of strings
representing the matching path names in the file system.

If there are no matches, then an empty list is returned.

The optional
.meta flags
argument defaults to zero. If given, it may be a bitwise combination of the
values of the variables
.codn glob-err ,
.codn glob-mark ,
.code glob-nosort
and others.

If the
.meta errfun
argument is specified, it gives a callback function which is invoked
when
.code glob
encounters errors accessing paths. The function takes two arguments:
the pathname and the
.code errno
value which occurred for that pathname. The function's return value is
Boolean. If the function returns true, then
.code glob
will terminate.

The
.meta errfun
may terminate the traversal by a nonlocal exit, such as by throwing
an exception or performing a block return.

The
.meta errfun
may not re-enter the
.code glob
function. This situation is detected and diagnosed by an exception.

The
.meta errfun
may not capture a continuation across the error boundary. That is to say,
code invoked from the error may not capture a continuation up to a prompt
which surrounds the
.code glob
call. Such an attempt is detected and diagnosed by an exception.

Details of the semantics of the
.code glob
function, and the meaning of all the
.meta flags
arguments are given in the documentation for the C function.

.coNP Variables @, fnm-pathname @, fnm-noescape @, fnm-period @, fnm-leading-dir @ fnm-casefold and @ fnm-extmatch
.desc
These variables take on the values of the corresponding C preprocessor
constants from the
.code <fnmatch.h>
header:
.codn FNM_PATHNAME ,
.codn FNM_NOESCAPE ,
.codn FNM_PERIOD ,
etc.

These values are bit masks which may be combined with the
.code logior
function to form the optional third
.meta flags
argument of the
.code fnmatch
function.

Note that the
.codn fnm-leading-dir ,
.code fnm-case-fold
and
.code fnm-extmatch
may not be available. They are GNU extensions, found in the GNU C library.

.coNP Function @ fnmatch
.synb
.mets (fnmatch < pattern < string <> [ flags ]])
.syne
.desc
The
.code fnmatch
function, if available, provides access
to the like-named POSIX C library function.
The
.meta pattern
argument specifies a POSIX-shell-style file pattern matching expression.
Its exact features and dialect are controlled by
.metn flags .
If
.meta string
matches
.meta pattern
then
.code t
is returned. If there is no match, then
.code nil
is returned. If the C function indicates that an error has occurred,
an exception is thrown.

.SS* Unix Filesystem Traversal

On platforms where the POSIX
.code nftw
function is available \*(TX provides this functionality in
the form of the analogous Lisp function
.codn ftw ,
accompanied by some numeric constants.

Likewise, on platforms where the POSIX functions
.code opendir
and
.code readdir
are available, \*(TX provides the functionality in the form of same-named
Lisp functions, a structure type named
.code dirent
and some accompanying numeric constants.

.coNP Variables @, ftw-phys @, ftw-mount @, ftw-chdir @ ftw-depth and @ ftw-actionretval
.desc
These variables hold numeric values that may be combined into a single
bitmask bitmask value using the
.code logior
function. This value is suitable as the
.meta flags
argument of the
.code ftw
function.

These variables corresponds to the C constants
.codn FTW_PHYS ,
.codn FTW_MOUNT ,
.IR "et cetera" .

Note that
.code ftw-actionretval
is a GNU extension that is not available on all platforms. If the platform's
.code nftw
function doesn't have this feature, then this variable is not defined.

.coNP Variables @, ftw-f @, ftw-d @, ftw-dnr @, ftw-ns @, ftw-sl @ ftw-dp and @ ftw-sln
.desc
These variables provide symbolic names for the integer values that are
passed as the
.code type
argument of the callback function called by
.codn ftw .
This argument classifies the kind of file system node visited, or
error condition encountered.

These variables correspond to the C constants
.codn FTW_F ,
.codn FTW_D ,
.IR "et cetera" .

Not all of them are present. If the underlying platform doesn't have
a given constant, then the corresponding variable doesn't exist in \*(TX.

.coNP Variables @, ftw-continue @, ftw-stop @ ftw-skip-subtree and @ ftw-skip-siblings
.desc
These variables are defined if the variable
.code ftw-actionretval
is defined.

If the value of
.code ftw-actionretval
is included in the
.meta flags
argument of
.codn ftw ,
then the callback function can use the values of these variables
as return codes. Ordinarily, the callback returns zero to continue
the search and nonzero to stop.

These variables correspond to the C constants
.codn FTW_CONTINUE ,
.codn FTW_STOP ,
.IR "et cetera" .

.coNP Function @ ftw
.synb
.mets (ftw < path-or-list < callbackfun >> [ flags <> [ nopenfd ]])
.mets >> [ callbackfun < path < type < stat-struct < level << base ]
.syne
.desc
The
.code ftw
function provides access to the
.code nftw
POSIX C library function.

Note that the
.meta flags
and
.meta nopenfd
arguments are reversed with respect to the C language interface.
They are both optional;
.meta flags
defaults to zero, and
.meta nopenfd
defaults to 20.

The
.meta path-or-list
argument may be a string specifying the top-level path name that
.code ftw
shall visit. Or else,
.meta path-or-list
may be a list. If it is a list, then
.code ftw
recursively invokes itself over each of the elements, taking
that element as the
.meta path-or-name
argument of the recursive call, passing down all other argument
values as-is.
The traversal stops when any recursive invocation of
.code ftw
returns a value other than
.code t
or
.codn nil ,
and that value is returned. If
.code t
or
.code nil
is returned, the traversal continues with the
application of
.code ftw
to the next list element, if any.
If the list is completely traversed, and some recursive
invocations of
.code ftw
return
.codn t ,
then the return value is
.codn t .
If all recursive invocations return
.code nil
then
.code nil
is returned.
If the list is empty,
.code t
is returned.

The
.code ftw
function walks the filesystem, as directed by the
.meta path-or-list
argument and
.meta flags
bitmask arguments.

For each visited entry, it calls the supplied
.meta callbackfun
function, which receives five arguments. If this function returns
normally, it must return either
.codn nil ,
.codn t ,
or an integer value in the range of the C type
.codn int .

The
.code ftw
function can continue the traversal by returning any non-integer value,
or the integer value zero.
If
.code ftw-actionretval
is included in the
.meta flags
bitmask, then the only integer code which continues the traversal without
any special semantics is
.code ftw-continue
and only
.code ftw-stop
stops the traversal.  (Non-integer return values behave like
.codn ftw-continue ).

The
.meta path
argument of
.meta callbackfun
gives the path of the
visited filesystem object.

The
.meta type
argument is an integer code which indicates the kind of
object that is visited, or an error situation in visiting
that filesystem entry.  See the documentation for
.code ftw-f
and
.code ftw-d
for possible values.

The
.meta stat-struct
argument provides information about the filesystem object
as a
.code stat
structure, the same kind of object as what is returned by the
.code stat
function.

The
.meta level
argument is an integer value representing the directory level
depth. This value is obtained from the C structure
.code FTW
in the
.code nftw
C API.

The
.meta base
argument indicates the length of the directory part of the
.code path
argument. Characters in excess of this length are thus the base name of the
visited object, and the expression
.mono
.meti >> [ path << base ..:]
.onom
calculates the base name.

The
.code ftw
function returns either
.code t
upon successful completion, or an integer value returned by
.metn callbackfun ,
as described below.
On failure it throws an exception derived from
.codn file-error ,
whose specific type is based on analyzing the POSIX
.code errno
value.

The
.meta callbackfun
may return a value of any type. If it returns a value that is not of integer
type, then zero is returned to the
.code nftw
function and traversal continues. Similarly, traversal continues
if the function returns an integer zero.

If
.meta callbackfun
returns an integer value, that value must be in the range of the C type
.codn int .
That
.code int
value is returned to
.codn nftw .
If the value is not zero, and is not -1, then
.code nftw
will terminate, and return that value, which
.code ftw
then returns. If the value is -1, then
.code nftw
is deemed to have failed, and
.code ftw
will thrown an exception of type
.codn file-error ,
whose specific type is based on analyzing the POSIX
.code errno
value. If the value is zero, then the traversal continues.

The
.meta callbackfun
may also terminate the traversal by a nonlocal exit, such as by throwing
an exception or performing a block return.

The
.meta callbackfun
may not re-enter the
.code ftw
function. This situation is detected and diagnosed by an exception.

The
.meta callbackfun
may not capture a continuation across the callback boundary. That is to say,
code invoked from the callback may not capture a continuation up to a prompt
which surrounds the
.code ftw
call. Such an attempt is detected and diagnosed by an exception.

.coNP Structure @ dirent
.synb
.mets (defstruct dirent nil
.mets \ \  name ino type)
.syne
.desc
Objects of the
.code dirent
structure type are returned by the
.code readdir
function.

The
.code name
slot is a character string giving the name of the directory entry.
If the
.code opendir
function's
.meta prefix-p
argument is specified as true,
then
.code readdir
operations produce
.code dirent
structures whose
.code name
slot is a path formed by combining the directory path with the directory
entry name.

The
.code ino
slot is an integer giving the inode number of the object named by the
directory entry.

The
.code type
slot indicates the type of the object, which is an integer code. Support for
this member is platform-dependent. If the directory traversal doesn't provide
the information, then this slot takes on the
.code nil
value. In this situation, the
.code dirstat
function may be used to back-fill the missing information.

.coNP Variables @, dt-blk @, dt-chr @, dt-dir @, dt-fifo @, dt-lnk @, dt-reg @ dt-sock and @ dt-unknown
.desc
These variables give the possible type code values exhibited by the
.code type
slot of the
.code dirent
structure.

If the underlying host platform does not feature a
.code d_type
field in the
.code dirent
C structure, then almost all these variables are defined anyway using the values that they
have on GNU/Linux.
These definitions are useful in conjunction with the
.code dirstat
function below.

If the host platform does does not feature a
.code d_type
field in the
.code dirent
structure, then the variable
.code dt-unknown
is not defined. Note: the application can take advantage of this this to detect
the situation, in order to conditionally define code in such a way that some
run-time checking is avoided.

.coNP Function @ opendir
.synb
.mets (opendir < dir-path <> [ prefix-p ])
.syne
.desc
The
.code opendir
function initiates a traversal of the directory object named by the
string argument
.metn dir-path ,
which must be the name of a directory. If
.code opendir
is not able to open the directory traversal, it throws an exception of type
.codn system-error .
Otherwise an object of type
.code dir
is returned, which is a directory traversal handle suitable as an argument
for the
.code readdir
function.

If the
.meta prefix-p
argument is specified and has a true value, then it indicates that
the subsequent
.code readdir
operations should produce the value of the
.code name
slot of the
.code dirent
structure by combining
.meta dir-path
with the directory entry name using the
.code path-cat
function.

.coNP Function @ readdir
.synb
.mets (readdir < dir-handle <> [ dirent-struct ])
.syne
.desc
The
.code readdir
function returns the next available directory entry from the directory
traversal controlled by
.metn dir-handle ,
which must be a
.code dir
object returned by
.codn opendir .

If no more directory entries remain, then
.code readdir
returns
.codn nil .
In this situation, the
.meta dir-handle
is also closed, as if by a call to
.codn closedir .

Otherwise, the next available directory entry is returned as a
structure object of type
.codn dirent .

The
.code readdir
function internally skips and does not report the
.str .
(dot)
and
.str ..
(dotdot) directory entries.

If the
.meta dirent-struct
argument is specified, then it must be a
.code dirent
structure, or one which has all of the required slots.
In this case,
.code readdir
stores values in that structure and returns it. If
.meta dirent-struct
is absent, then
.code readdir
allocates a fresh
.code dirent
structure.

.coNP Function @ closedir
.synb
.mets (opendir << dir-handle )
.syne
.desc
The
.code closedir
function terminates the directory traversal managed by
.metn dir-handle ,
releasing its resources.

If this has already been done before,
.code closedir
returns
.codn nil ,
otherwise it returns
.codn t .

Further
.code readdir
calls on the same
.meta dir-handle
return
.codn nil .

Note: the
.code readdir
function implicitly closes
.meta dir-handle
when the handle indicates that no more directory entries remain to be traversed.

.coNP Function @ dirstat
.synb
.mets (dirstat < dirent-struct >> [ dir-path <> [ struct ]])
.syne
.desc
The
.code dirstat
function invokes
.code lstat
on the object represented by the
.code dirent
structure
.metn dirent-struct ,
sets the
.code type
slot of the
.meta dirent-struct
accordingly, and then returns the value that
.code lstat
returned.

If the
.meta struct
argument is specified, it is passed to
.codn lstat .

The
.meta dir-path
parameter must be specified, if the
.code name
slot of
.meta dirent-struct
is a simple directory entry name, rather than the full path to the object.
In that case, the slot's value gives the effective path.
If the
.code name
slot is already a path (due to, for instance, a true value of
.meta prefix-p
having been passed to
.codn opendir )
then
.meta dir-path
must not be specified.
If
.meta dir-path
is specified, then its value is combined with the
.meta name
slot of
.meta dirent-struct
using
.code path-cat
to form the effective path.

The
.code lstat
function is invoked on the effective path, and if it succeeds,
then type information is obtained from the resulting
structure to set the value of the
.code type
slot of
.metn dirent-struct .
The same structure that was returned by
.code lstat
is then returned.

.SS* Unix Sockets

On platforms where the underlying system interface is available, \*(TX provides
a sockets library for communicating over Internet networks, or over Unix
sockets.

Stream as well as datagram sockets are supported.

The classic Version 4 of the Internet protocol is supported, as well
as IP Version 6.

Sockets are mapped to \*(TX streams. The
.code open-socket
function creates a socket of a specified type, in a particular address family.
This socket is actually a stream (always, even if it isn't used for
data transfer, but only as a passive contact point).

The functions
.codn sock-connect ,
.codn sock-bind ,
.codn sock-listen ,
.code sock-accept
and
.code sock-shutdown
are used for enacting socket communication scenarios.

Stream sockets use ordinary streams, re-using the same underlying framework
that is used for file I/O and process types.

Datagram socket streams are implemented using special datagram socket streams.
Datagram socket streams eliminate the need for operations analogous to the
.code sendto
and
.code recvfrom
socket API functions, even in server programs which handle multiple
clients. An overview of datagrams is treated in the following section,
Datagram Socket Streams.

The
.code getaddrinfo
function is provided for resolving host names and services to IPv4 and IPv6
addresses.

Several structure types are provided for representing socket addresses,
and options for
.codn getaddrinfo .

Various numeric constants are also provided:
.codn af-unix ,
.codn af-inet ,
.codn af-inet6 ,
.codn sock-stream ,
.code sock-dgram
and others.

.NP* Datagram Socket Streams

Datagram socket streams are a new paradigm unique to \*(TX which
attempts to unify the programming model of stream and datagram
sockets.

A datagram socket stream is created by the
.code open-socket
function, when the
.code sock-dgram
socket type is specified. Another way in which a datagram socket
is created is when
.code sock-accept
is invoked on a datagram socket, and returns a new socket.

I/O is performed on datagram sockets using the regular I/O functions.
None of the functions take or return peer addresses. There are no I/O
functions which are analogous to the C library
.code recvfrom
and
.code sendto
functions which are usually used for datagram programming.
Datagram I/O assumes that the datagram datagram socket is connected to a
specific remote peer, and that peer is implicitly used for all I/O.

Datagram streams solve the message framing problem by
considering a single datagram to be an entire stream.  On input, a datagram
stream holds an entire datagram in a buffer. The stream ends
(experiences the EOF condition) after the last byte of this buffer
is removed by an input operation. Another datagram will be received and
buffered if the EOF condition is first explicitly cleared with the
.code clear-error
function, and then another input operation is attempted.
On output, a datagram stream gathers data into an ever-growing output buffer
which isn't subject to any automatic flushing. An explicit
.code flush-stream
operation sends the buffer contents to the connected peer as a new
datagram, and empties the buffer. Subsequent output operations prepare
data for a new datagram. The
.code close-stream
function implicitly flushes the stream in the same way, and thus also
potentially generates a datagram.

A client-style datagram stream can be explicitly connected to a peer with the
.code sock-connect
function. This is equivalent to connecting a
datagram socket using the C library
.code connect
function. Writes on the stream will be transmitted using the C library function
.codn send .
A client-style datagram stream can also be "soft-connected" to a
peer using the
.code sock-set-peer
function. Writes on the stream will transmit data using the C library function
.code sendto
to the peer address.

A datagram server program which needs
to communicate using multiple peers is implemented by means of the
.code sock-accept
function which, unlike the C library
.code accept
function, works with datagram sockets as well as stream sockets.
The server creates a datagram socket, and uses
.code sock-bind
to bind it to a local address. Optionally, it may also call
.code sock-listen
which is a no-op on datagram sockets. Supporting this function on datagram
sockets allows program code to be more easily changed between datagram and
stream operation.
The server then uses
.code sock-accept
to accept new clients. Note that this is not possible with the C
library function
.codn accept ,
which only works with stream sockets.

The
.code sock-accept
function receives a datagram from a client, and creates a new datagram
socket stream which is connected to that client, and whose input buffer
contains the received datagram. Input operations on this stream consume
the datagram. Note that clearing the EOF condition and trying to receive
another datagram is not recommended on datagram streams returned
by
.codn sock-accept ,
since they share the same underlying operating system socket, which is
not actually connected to a specific peer. The receive operation could
receive a datagram from any peer, without any indication which peer that is.
Datagram servers should issue a new
.code sock-accept
call should be issued for each client datagram, treating it as a new
stream.

Datagram sockets ignore almost all aspects of the
.meta mode-string
passed in
.code open-socket
and
.codn sock-accept .
The only attribute not ignored is the buffer size specified
with a decimal digit character; however, it cannot be the
only item in the mode string. The string must be syntactically
valid, as described under the
.code open-file
function. The buffer size attribute controls the size used by
the datagram socket for receiving a datagram: the capture size.
A datagram socket has obtains a default capture size if one isn't
specified by the
.metn mode-string .
The default capture size is 65536 bytes for a datagram socket created by
.codn open-socket .
If a size is not passed to
.code sock-accept
via its
.meta mode-string
argument when it is invoked on a datagram socket,
that socket's size is used as the capture size of the
newly created datagram socket which is returned.

.coNP Structure @ sockaddr
.synb
.mets (defstruct sockaddr nil
.mets \ \  (:static family nil))
.syne
.desc
The
.code sockaddr
structure represents the abstract base class for socket addresses, from which
several other types are derived:
.codn sockaddr-in ,
.code sockaddr-in6
and
.codn sockaddr-un .

It has a single slot called
.code family
which is static, and initialized to
.codn nil .

.coNP Structure @ sockaddr-in
.synb
.mets (defstruct sockaddr-in sockaddr
.mets \ \  (addr 0) (port 0) (prefix 32)
.mets \ \  (:static family af-inet))
.syne
.desc
The
.code sockaddr-in
address represents a socket address used in the context of networking over
IP Version 4. It may be used with sockets in the
.code af-inet
address family.

The
.code addr
slot holds an integer denoting an abstract IPv4 address. For instance the hexadecimal
integer literal constant
.code #x7F000001
or its decimal equivalent
.code 2130706433
represents the loopback address, whose familiar "dot notation" is
.codn 127.0.0.1 .
Conversion of the abstract IP address to four bytes in network order, as
required, is handled internally.

The
.code port
slot holds the TCP or UDP port number, whose value ranges from 0 to 65535.
Zero isn't a valid port; the value is used for requesting an ephemeral port number
in active connections. Zero also appears in situations when the port number isn't required:
for instance, when the
.code getaddrinfo
function is used with the aim of looking up the address of a host, without
caring about the port number.

The
.code prefix
field is set by the function
.codn inaddr-str ,
when it recognizes and parses a prefix field in the textual representation.

The
.code family
static slot holds the value
.codn af-inet .

.coNP Structure @ sockaddr-in6
.synb
.mets (defstruct sockaddr-in6 sockaddr
.mets \ \  (addr 0) (port 0) (flow-info 0) (scope-id 0)
.mets \ \  (prefix 128)
.mets \ \  (:static family af-inet6))
.syne
.desc
The
.code sockaddr-in6
address represents a socket address used in the context of networking over
IP Version 6. It may be used with sockets in the
.code af-inet6
address family.

The
.code addr
slot holds an integer denoting an abstract IPv6 address. IPv6 addresses are
pure binary integers up to 128 bits wide.

The
.code port
slot holds the TCP or UDP port number, whose value ranges from 0 to 65535.
In IPv6, the port number functions similarly to IPv6; see
.codn sockaddr-in .

The
.code flow-info
and
.code scope-id
are special IPv6 parameters corresponding to the
.code sin6_flowinfo
and
.code sin6_scope_id
slots of the
.code sockaddr_in6
C language structure. Their meaning and use are beyond the scope of this document.

The
.code prefix
field is set by the function
.codn in6addr-str ,
when it recognizes and parses a prefix field in the textual representation.

The
.code family
static slot holds the value
.codn af-inet6 .

.coNP Structure @ sockaddr-un
.synb
.mets (defstruct sockaddr-un sockaddr
.mets \ \  path
.mets \ \  (:static family af-unix))
.syne
.desc
The
.code sockaddr-un
address represents a socket address used for inter-process communication
within a single operating system node, using the "Unix domain" sockets
of the
.code af-unix
address family.

This structure has only one slot,
.code path
which holds the rendezvous name for connecting pairs of socket endpoints.
This name appears in the filesystem.

When the
.code sockaddr-un
structure is converted to the C structure
.codn "struct sockaddr_un" ,
the
.code path
slot undergoes conversion to UTF-8. The resulting bytes are stored in the
.code sun_path
member of the C structure. If the resulting UTF-8 byte string
is larger than the
.code sun_path
array, it is silently truncated.

Note: Linux systems have support for "abstract" names which do not appear in
the filesystem. These abstract names are distinguished by starting with a null
byte. For more information, consult Linux documentation.
This convention is supported in the
.code path
slot of the
.code sockaddr-un
structure. If
.code path
contains occurrences of the pseudo-null character U+DC00, these translate
to null bytes in the
.code sun_path
member of the corresponding C structure
.codn "struct sockaddr_un" .
For example, the path
.str "\exDC00;foo"
is valid and represents an abstract address consisting of the three bytes
.str "foo"
followed by null padding bytes.

The
.code family
static slot holds the value
.codn af-unix .

.coNP Structure @ addrinfo
.synb
.mets (defstruct addrinfo nil
.mets \ \ (flags 0) (family 0) (socktype 0))
.syne
.desc
The
.code addrinfo
structure is used in conjunction with the
.code getaddrinfo
function. If that function's
.meta hints
argument is specified, it is of this type.
The purpose of the argument is to narrow down
or possibly alter the selection of addresses which
are returned.

The
.code flags
slot holds a bitwise or combination (see the
.code logior
function) of
.code getaddrinfo
flags: values given by the variables.
.codn ai-passive ,
.codn ai-numerichost ,
.codn ai-v4mapped ,
.codn ai-all ,
.code ai-addrconfig
and
.codn ai-numericserv .
These correspond to the C constants
.codn AI_PASSIVE ,
.code AI_NUMERICHOST
and so forth.

The
.code family
slot holds an address family, which may be the value of
.codn af-unspec ,
.codn af-unix ,
.code af-inet
or
.codn af-inet6 .

The
.code socktype
slot holds, a socket type. Socket types are given
by the variables
.code sock-dgram
and
.codn sock-stream .

.coNP Function @ getaddrinfo
.synb
.mets (getaddrinfo >> [ node >> [ service <> [ hints ]]])
.syne
.desc
The
.code getaddrinfo
returns a list of socket addresses based on search criteria expressed
in its arguments.
That is to say, the returned list, unless empty, contains objects of type
.code sockaddr-in
and
.codn sockaddr-in6 .

The function is implemented directly in terms of the like-named C library
function. All parameters are optional.  Omitting any argument causes a null
pointer to be passed for the corresponding parameter of the C library function.

The
.meta node
and
.meta service
parameters may be character strings which specify a host name, and service.
The contents of these strings may be symbolic, like
.str www.example.com
and
.str ssh
or numeric, like
.str 10.13.1.5
and
.strn 80 .

If an argument is given for the
.code hints
parameter, it must be of type
.codn addrinfo .

The
.meta node
and
.meta service
parameters may also be given integer arguments.
An integer argument value in either of these parameters is converted to a null
pointer when calling the C
.code getaddrinfo
function. The integer values are then simply installed into every returned
address as the IP address or port number, respectively.  However, if both
arguments are numeric, then no addresses are returned, since the C library
function is then called with a null node and service.

.coNP Variables @, af-unix @ af-inet and @ af-inet6
.desc
These variables hold integers which give the values of address
families. They correspond to the C constants
.codn AF_UNIX ,
.code AF_INET
and
.codn AF_INET6 .
Address family values are used in the
.meta hints
argument of the
.code getaddrinfo
function, and in the
.code socket-open
function.
Note that unlike the C language socket addressing structures,
the \*(TX socket addresses do not contain an address family slot.
That is because they indicate their family via their type.
That is to say, an object of type
.code sockaddr-in
is an address which is implicitly associated with the
.code af-inet
family via its type.

.coNP Variables @ sock-stream and @ sock-dgram
.desc
These variables hold integers which give the values of address
families. They correspond to the C constants
.code SOCK_STREAM
and
.codn SOCK_DGRAM .

.coNP Variables @, ai-passive @, ai-numerichost @, ai-v4mapped @, ai-all @ ai-addrconfig and @ ai-numericserv
.desc
These variables hold integers which are bitmasks that combine
together via bitwise or, to express the
.code flags
slot of the
.code addrinfo
structure. They correspond to the C constants
.codn AI_PASSIVE ,
.codn AI_NUMERICHOST ,
.code AI_V4MAPPED
and so forth. They influence the behavior of the
.code getaddrinfo
function.

.coNP Variables @, inaddr-any @, inaddr-loopback @ in6addr-any and @ in6addr-loopback
.desc
These integer-valued variables provide constants for commonly used IPv4
and IPv6 address values.

The value of
.code inaddr-any
and
.code in6addr-any
is zero. This address is used in binding a passive socket to all of the
external interfaces of a host, so that it can accept connections or datagrams
from all attached networks.

The
.code inaddr-loopback
variable is IPv4 loopback address, the same integer as the hexadecimal
constant
.code #x7F000001.

The
.code in6addr-loopback
is the IPv6 loopback address. Its value is 1.

.TP* Example:

.verb
  ;; Construct an IPv6 socket address suitable for binding
  ;; a socket to the loopback network, port 1234:
  (new sockaddr-in6 addr in6addr-loopback port 1234)

  ;; Mistake: IPv4 address used with IPv6 sockaddr.
  (new sockaddr-in6 addr inaddr-loopback)
.brev

.coNP Function @ open-socket
.synb
.mets (open-socket < family < type <> [ mode-string ])
.syne
.desc
The
.code open-socket
function creates a socket, which is a kind of stream.

The
.meta family
parameter specifies the address family of the socket. One of the
values
.codn af-inet ,
.code af-inet
or
.code af-inet6
should be used to create a Unix domain, Internet IPv4 or Internet IPv6
socket, respectively.

The
.meta type
parameter specifies the socket type, either
.code sock-stream
(stream socket) or
.code sock-dgram
(datagram socket).

The
.meta mode-string
specifies several properties of the stream; for a description of
.meta mode-string
parameters, refer to the
.code open-file
function. Note that the defaulting behavior for an omitted
.meta mode-string
argument is different under
.code open-socket
from other functions. Because sockets are almost always used for bidirectional
data flow, the default mode string is
.str r+b
rather than the usual
.strn r .

Rationale for including the
.str b
flag in the default mode string is that network protocols are usually defined
in a way that is independent of machine and operating system, down to the byte
level, even when they are textual. It doesn't make sense for the same \*(TX
program to see a network stream differently based on what platform it is
running on. Line ending conversion has to do with how a platform locally stores
text files, whereas network streams are almost always external formats.

Like other stream types, stream sockets are buffered and marked as no
non-real-time streams. Specifying the
.str i
mode in
.meta mode-string
marks a socket as a real-time-stream, and, if it is opened for writing
or reading and writing, changes it to use line buffering.

.coNP Function @ open-socket-pair
.synb
.mets (open-socket-pair < family < type <> [ mode-string ])
.syne
.desc
The
.code open-socket-pair
function provides an interface to the functionality of the
.code socketpair
C library function.

If successful, it creates and returns a list of two stream objects,
which are sockets that are connected together.

Note: the Internet address families
.code af-inet
and
.code af-inet6
are not supported.

The
.code mode-string
is applied to each stream. For a description, see
.code open-socket
and
.codn open-file .

.coNP Functions @ sock-family and @ sock-type
.synb
.mets (sock-family << socket )
.mets (sock-type << socket )
.syne
.desc
These functions retrieve the integer values representing the address family
and type of a socket. The argument to the
.meta socket
parameter must be a socket stream or a file or process stream. For a file stream,
both functions return
.codn nil .
An exception of type
.code type-error
is thrown for other stream types.

.coNP Accessor @ sock-peer
.synb
.mets (sock-peer << socket )
.mets (set (sock-peer << socket ) << address )
.syne
.desc
The
.code sock-peer
function retrieves the peer address
has most recently been assigned to
.metn socket .

Sockets which are not connected initially
have a peer address value of
.codn nil .
A socket which is connected to a remote peer
receives that peer's address as its
.codn sock-peer .

If a socket is connected to a remote peer via
a successful use of the
.code sock-connect
function, then its
.code sock-peer
address is set to match that of the peer.

Sockets returned by the
.code sock-accept
function are connected, and have the remote endpoint address as their
.code sock-peer
address.

Assigning an address to a
.code sock-peer
form is equivalent to using
.code sock-set-peer
to set the address.

Implementation note: the
.code sock-peer
function does not use the
.code getpeername
C library function; the association between a stream and
.code sockaddr
struct is maintained by \*(TX.

.coNP Function @ sock-set-peer
.synb
.mets (sock-set-peer < socket << address )
.syne
.desc
The
.code sock-set-peer
function stores
.meta address
into
.meta socket
as that socket's peer.

Subsequently, the
.code sock-peer
function will retrieve that address.

If
.meta address
is not an appropriate address object in the address family of
.metn socket ,
the behavior is unspecified.

.coNP Function @ sock-connect
.synb
.mets (sock-connect < socket < address <> [ timeout-usec ])
.syne
.desc
The
.code sock-connect
function connects a socket stream to a peer address.

The
.meta address
argument must be a
.code sockaddr
object of type matching the address family of the socket.

If the operation fails, an exception of type
.code socket-error
is thrown. Otherwise, the function returns
.metn socket .

If the
.meta timeout-usec
argument is specified, it must be a fixnum integer.
It denotes a connection timeout period in microseconds.
If the connection doesn't succeed within the specified timeout,
an exception of type
.code timeout-error
is thrown.

.coNP Function @ sock-bind
.synb
.mets (sock-bind < socket << address )
.syne
.desc
The
.code sock-bind
function binds a socket stream to a local address.

The
.meta address
argument must be a
.code sockaddr
object of type matching the address family of the socket.

If the operation fails, an exception of type
.code socket-error
is thrown. Otherwise, the function returns
.codn t .

Returns
.code t
if successful.

.coNP Function @ sock-listen
.synb
.mets (sock-listen < socket <> [ backlog ])
.syne
.desc
The
.code sock-listen
function prepares
.meta socket
for listening for connections. The
.meta backlog
parameter, if specified, requires an integer
argument. The default value is 16.

.coNP Function @ sock-accept
.synb
.mets (sock-accept < socket >> [ mode-string <> [ timeout-usec ]])
.syne
.desc
The
.code sock-accept
function waits for a client connection on
.metn socket ,
which must have been prepared for listening for
connections using
.code sock-bind
and
.codn sock-listen .

If the operation fails, an exception of type
.code socket-error
is thrown. Otherwise, the function returns a new socket
which is connected to the remote peer.

The peer's address may be retrieved from this socket using
.codn sock-peer .

The
.code mode-string
parameter is applied to the new socket just like the
similar argument in
.codn socket-open .
It defaults to
.strn r+ .

If the
.meta timeout-usec
argument is specified, it must be a fixnum integer.
It denotes a timeout period in microseconds.
If no peer connects for the specified timeout,
.code sock-accept
throws an exception of type
.codn timeout-error .

.coNP Variables @, shut-rd @ shut-wr and @ shut-rdwr
.desc
The values of these variables are useful as the second argument to the
.code sock-shutdown
function.

.coNP Function @ sock-shutdown
.synb
.mets (sock-shutdown < sock <> [ direction ])
.syne
.desc
The
.code sock-shutdown
function indicates that no further communication is to take place on
.meta socket
in the specified direction(s).

If the operation fails, an exception of type
.code socket-error
is thrown. Otherwise, the function returns
.codn t .

The
.code direction
parameter is one of the values given by the variables
.codn shut-rd ,
.code shut-wr
or
.codn shut-rdwr .
These values shut down communication in the read direction, write direction,
or both directions, respectively.

If the argument is omitted,
.code sock-shutdown
defaults to closing the write direction.

Notes: shutting down is most commonly requested in the write direction, to perform
a "half close". The communicating process thereby indicates that it has written
all the data which it intends to write.  When the shutdown action is processed on the
remote end, that end is unblocked from waiting on any further data, and
effectively experiences an "end of stream" condition on its own socket or
socket-like endpoint, while continuing to be able to transmit data.
Shutting down in the reading direction is potentially abrupt. If it is executed
before an "end of stream" indication is received from a peer, it results in an
abortive close.

.coNP Functions @ sock-recv-timeout and @ sock-send-timeout
.synb
.mets (sock-recv-timeout < sock << usec )
.mets (sock-send-timeout < sock << usec )
.syne
.desc
The
.code sock-recv-timeout
and
.code sock-send-timeout
functions configure, respectively, receive and send timeouts on socket
.metn sock .

The
.meta usec
parameter specifies the value, in microseconds. It must be a
.code fixnum
integer.

When a receive timeout is configured on a socket, then an
exception of type
.code timeout-error
is thrown when an input operation waits for at least
.code usec
microseconds without receiving input.

Similarly, when a send timeout is configured, then an
exception of type
.code timeout-error
is thrown when an output operation waits for at least
.code usec
microseconds for the availability of buffer space in the socket.

.coNP Functions @ str-inaddr and @ str-in6addr
.synb
.mets (str-inaddr address <> [ port ])
.mets (str-in6addr address <> [ port ])
.syne
.desc
The
.code str-inaddr
and
.code str-in6addr
functions convert an IPv4 and IPv6 address, respectively, to textual
notation which is returned as a character string.
The conversion is done in conformance with RFC 5952, section 4.

IPv6 addresses representing IPv6-mapped IPv4 addresses are printed
in the hybrid notation exemplified by
.codn ::ffff:192.168.1.1 .

The
.meta address
parameter must be a non-negative integer in the appropriate range
for the address type.

If the
.meta port
number argument is supplied, it is included in the returned character string,
according to the requirements in section 6 of RFC 5952 pertaining to IPv6
addresses (including IPv6-mapped IPv6 addresses) and section 3.2.3 of RFC 3986
for IPv4 addresses. In brief, IPv6 addresses with ports are expressed as
.code [address]:port
and IPv6 addresses follow the traditional
.code address:port
pattern.

.coNP Functions @ str-inaddr-net and @ str-in6addr-net
.synb
.mets (str-inaddr-net < address <> [ width ])
.mets (str-in6addr-net < address <> [ width ])
.syne
.desc
The functions
.code str-inaddr-net
and
.code str-in6addr-net
convert, respectively, IPv4 and IPv6 network prefix addresses to
the "slash notation". For IPv6 addresses, the requirements of section
2.3 of RFC 4291 are implemented. For IPv4, section 3.1 of RFC 4632 is followed.

The condensed portion of the IP address is always determined by measuring
the contiguous extent of all-zero bits in the least significant position
of the address. For instance an IPv4 address which has at least 24 zero bits
in the least significant position, so that the only nonzero bits are in the
highest octet, is always condensed to a single decimal number: the value of
the first octet.

If the
.meta width
parameter is specified, then its value is incorporated into the returned
textual notation as the width. No check is made whether this width
large enough to span all of the nonzero bits in the address.

If
.meta width
is omitted, then it is calculated as the number of bits in the address,
excluding the contiguous all-zero bits in the least significant position:
how many times the address can be shifted to the right before a 1 appears
in the least significant bit.

.coNP Functions @ inaddr-str and @ in6addr-str
.synb
.mets (inaddr-str << string )
.mets (in6addr-str << string )
.syne
.desc
The
.code inaddr-str
and
.code in6addr-str
functions recover an IPv4 or IPv6 address from a textual representation.
If the parse is successful, the address is returned as, respectively, a
.code sockaddr-in
or
.code sockaddr-in6
structure.

If
.meta string
is a malformed address, due to any issue such as invalid syntax or
a numeric value being out of range, an exception is thrown.

The
.code inaddr-str
function recognizes the dot notation consisting of four decimal numbers
separated by period characters. The numbers must be in the range 0 to 255.
Note: superfluous leading zeros are permitted, though this is a nonstandard
extension; not all implementations of this notations support this.

A prefix may be specified in the notation as a slash followed by a decimal
number, in the range 0 to 32. In this case, the integer value of the
prefix appears as the
.code prefix
member of the returned
.code sockaddr-in
structure. Furthermore, the address is masked, so that any bits not
included in the prefix are zero. For instance, the address
.str 255.255.255.255/1
is equivalent to
.strn 128.0.0.0 ,
except that the
.code prefix
if the returned structure is 1 rather than 32.
When a prefix is not specified, the
.code prefix
member of the structure retains its default value of 32.
When the prefix is specified, the address part need not contain all four
octets; it may contain between one and four octets. Thus,
.str 192.168/16
is a valid address, equivalent to
.strn 192.168.0.0/16 .

A port number may be specified in the notation as a colon, followed by a
decimal number in the range 0 to 65535. The integer value of this port
number appears as the
.code port
member of the returned structure. An example of this notation is
.strn 127.0.0.1:23 .

A prefix and port number may both be specified; in this case the prefix must
appear first, followed by the port number. For example,
.strn "127/8:23" .

The
.code in6addr-str
function recognizes the IPv6 notation consisting of 16-bit hexadecimal pieces
separated by colons. If the operation is successful, it returns a
.code sockaddr-in6
structure.  Each piece must be a value in the range 0 to FFFF.
The hexadecimal digits may be any mixture of upper and lower case. Leading
zeros are permitted.
Up to eight such pieces must be specified. If fewer pieces are specified,
then the token
.code ::
(double colon)
must appear in the address exactly once. That token denotes the condensation of
a sufficient number of zero-valued pieces to make eight pieces.
The token must be in one of three positions: it may be the leftmost element of
the address, immediately followed by a hexadecimal piece; it may be the rightmost element
of the address, preceded by a hexadecimal piece; or else, it may be in the
middle of the address, flanked on both sides by hexadecimal pieces.

The
.code in6addr-str
also recognizes the special notation for IPv6-mapped IPv4 addresses. This
notation consists of the address string
.str ::FFFF
which may appear in any upper/lower case mixture, possibly with leading
zeros, followed by an IPv4 address given in the four-octet dot notation.
For example,
.strn ::FFFF:127.0.0.1 .

A prefix may be specified using a slash, followed by a decimal number in the
range 0 to 128. The handling of the prefix is similar to that of
.code inaddr-str
except that pieces of the address may not be omitted. Condensing the
pieces of the IPv6 address is always done by means of the
.code ::
token, whether or not a prefix is present. Furthermore, the octets specified in
the IPv6-mapped IPv4 notation must all be present, regardless of the prefix.

A port number may be specified in the notation as follows: the entire address,
including any slash-separated prefix, must appear surrounded in square
brackets. The closing square bracket must be followed by a colon and one or
more digits denoting a decimal number in the range 0 to 65535. For instance
.strn "[1:2:3::4/64]:1234".

.SS* Unix Terminal Control

\*(TX provides access to the terminal control "termios" interfaces defined by
POSIX, and some of the extensions to it in Linux. By using termios, programs
can control serial devices, consoles and virtual terminals. Terminal control
in POSIX revolves around a C language structure called
.codn "struct termios" .
This is mirrored in a \*(TL structure also called
.codn termios .

Like-named \*(TL functions are provided which correspond to the C functions
.codn tcgetattr ,
.codn tcsetattr ,
.codn tcsendbreak ,
.codn tcdrain ,
.code tcflush
and
.codn tcflow .

These have somewhat different argument conventions. The TTY device is specified last,
so that it can conveniently default to the
.code *stdin*
stream. A TTY device can be specified as either a stream object or a numeric
file descriptor.

The functions
.codn cfgetispeed ,
.codn cfgetospeed ,
.code cfsetispeed
and
.code cfsetospeed
are not provided, because they are unnecessary. Device speed (informally, "baud rate")
is specified directly as a integer value in the
.code termios
structure. The \*(TL termios functions automatically convert between integer
values and the speed constants (like
.codn B38400 )
used by the C API.

All of the various termios-related constants are provided, including some non-standard
ones. They appear in lower case. For instance
.code IGNBRK
and
.code PARENB
are simply known as the predefined \*(TL variables
.code ignbrk
and
.codn parenb .

.coNP Structure @ termios
.synb
.mets (defstruct termios nil
.mets \ \ iflag oflag cflag lflag
.mets \ \ cc ispeed ospeed)
.syne
.desc
The
.code termios
structure represents the kernel level terminal device configuration.
It holds hardware related setting such as serial line speed, parity
and handshaking. It also holds software settings like translations,
and settings affecting input behaviors. The structure closely corresponds
to the C language
.code termios
structure which exists in the POSIX API.

The
.codn iflag ,
.codn oflag ,
.code cflag
and
.code lflag
slots correspond to the
.codn c_iflag ,
.codn c_oflag ,
.code c_cflag
and
.code c_lflag
members of the C structure. They hold integer values representing
bit fields.

The
.code cc
slot corresponds to the
.code c_cc
member of the C structure. Whereas the
C structure's
.code c_cc
member is an array of the C type
.codn cc_t ,
the
.code cc
slot is a vector of integers, whose values must have the same range as the
.code cc_t
type.

.coNP Variables @, ignbrk @, brkint @, ignpar @, parmrk @, inpck @, istrip @, inlcr @, igncr @, icrnl @, iuclc @, ixon @, ixany @, ixoff @ imaxbel and @ iutf8
.desc
These variables specify bitmask values for the
.code iflag
slot of the
.code termios
structure. They correspond to the C language preprocessor symbols
.codn IGNBRK ,
.codn BRKINT ,
.code IGNPAR
and so forth.

The
.code imaxbel
and
.code iutf8
variables are specific to Linux and may not be present.
Portable code should test for their presence with
.codn boundp .

The
.code iuclc
variable is a legacy feature not found on all systems.

Note: the
.code termios
methods
.code set-iflags
and
.code clear-iflags
provide a convenient means for setting and clearing combinations of
these flags.

.coNP Variables @, opost @, olcuc @, onlcr @, ocrnl @, onocr @, onlret @, ofill @, ofdel @, vtdly @, vt0 @, vt1 @, nldly @, nl0 @, nl1 @, crdly @, cr0 @, cr1 @, cr2 @, cr3 @, tabdly @, tab0 @, tab1 @, tab2 @, tab3 @, bsdly @, bs0 @, bs1 @, ffdly @ ff0 and @ ff1
.desc
These variables specify bitmask values for the
.code oflag
slot of the
.code termios
structure. They correspond to the C language preprocessor symbols
.codn OPOST ,
.codn OLCUC ,
.code ONLCR
and so forth.

The variable
.code ofdel
is Linux-specific. Portable programs should test for its presence using
.codn boundp .

The
.code olcuc
variable is a legacy feature not found on all systems.

Likewise, whether the following groups of symbols are present is
platform-specific:
.codn nldly ,
.code nl0
and
.codn nl1 ;
.codn crdly ,
.codn cr0 ,
.codn cr1 ,
.code cr2
and
.codn cr3 ;
.codn tabdly ,
.codn tab0 ,
.codn tab1 ,
.code tab2
and
.codn tab3 ;
.codn bsdly ,
.code bs0
and
.codn bs1 ;
and
.codn ffdly ,
.code ff0
and
.codn ff1 .

Note: the
.code termios
methods
.code set-oflags
and
.code clear-oflags
provide a convenient means for setting and clearing combinations of
these flags.

.coNP Variables @, csize @, cs5 @, cs6 @, cs7 @, cs8 @, cstopb @, cread @, parenb @, parodd @, hupcl @, clocal @, cbaud @, cbaudex @ cmspar and @ crtscts
.desc
These variables specify bitmask values for the
.code cflag
slot of the
.code termios
structure. They correspond to the C language preprocessor symbols
.codn CSIZE ,
.codn CS5 ,
.code CS6
and so forth.

The following are present on Linux, and may not be available
on other platforms. Portable code should test for them using
.codn boundp :
.codn cbaud ,
.codn cbaudex ,
.code cmspar
and
.codn crtscts .

Note: the
.code termios
methods
.code set-cflags
and
.code clear-cflags
provide a convenient means for setting and clearing combinations of
these flags.

.coNP Variables @, isig @, icanon @, echo @, echoe @, echok @, echonl @, noflsh @, tostop @, iexten @, xcase @, echoctl @, echoprt @, echoke @, flusho @ pendin and @ extproc
.desc
These variables specify bitmask values for the
.code lflag
slot of the
.code termios
structure. They correspond to the C language preprocessor symbols
.codn ISIG ,
.codn ICANON ,
.code ECHO
and so forth.

The following are present on Linux, and may not be available
on other platforms. Portable code should test for them using
.codn boundp :
.codn iexten ,
.codn xcase ,
.codn echoctl ,
.codn echoprt ,
.codn echoke ,
.codn flusho ,
.code pendin
and
.codn extproc .

Note: the
.code termios
methods
.code set-lflags
and
.code clear-lflags
provide a convenient means for setting and clearing combinations of
these flags.

.coNP Variables @, vintr @, vquit @, verase @, vkill @, veof @, vtime @, vmin @, vswtc @, vstart @, vstop @, vsusp @, veol @, vreprint @, vdiscard @, vwerase @ vlnext and @ veol2
.desc
These variables specify integer offsets into the vector stored in the
.code cc
slot of the
.code termios
structure. They correspond to the C language preprocessor symbols
.codn VINTR ,
.codn VQUIT ,
.code VERASE
and so forth.

The following are present on Linux, and may not be available
on other platforms. Portable code should test for them using
.codn boundp :
.codn vswtc ,
.codn vreprint ,
.codn vdiscard ,
.code vlnext
and
.codn veol2 .

.coNP Variables @, tcooff @, tcoon @ tcioff and @ tcion
.desc
These variables hold integer values suitable as the
.meta action
argument of the
.code tcflow
function. They correspond to the C language preprocessor symbols
.codn TCOOFF ,
.codn TCOON ,
.code TCIOFF
and
.codn TCION .

.coNP Variables @, tciflush @ tcoflush and @ tcioflush
.desc
These variables hold integer values suitable as the
.meta queue
argument of the
.code tcflush
function. They correspond to the C language preprocessor symbols
.codn TCIFLUSH ,
.code TCOFLUSH
and
.codn TCIOFLUSH .

.coNP Variables @, tcsanow @ tcsadrain and @ tcsaflush
.desc
These variables hold integer values suitable as the
.meta actions
argument of the
.code tcsetattr
function. They correspond to the C language preprocessor symbols
.codn TCSANOW ,
.code TCSADRAIN
and
.codn TCSAFLUSH .

.coNP Functions @ tcgetattr and @ tcsetattr
.synb
.mets (tcgetattr <> [ device ])
.mets (tcsetattr < termios >> [ actions <> [ device ]])
.syne
.desc
The
.code tcgetattr
and
.code tcsetattr
functions, respectively, retrieve and install the configuration
of the terminal driver associated with the specified device.

These functions are wrappers for the like-named POSIX C library functions,
but with different argument conventions, and operating using
a \*(TL structure.

The
.code tcgetattr
function, if successful, returns a new instance of the
.code termios
structure.

The
.code tcsetattr
function requires an instance of a
.code termios
structure as an argument to its
.meta termios
parameter.

A program may alter the settings of a terminal device by
retrieving them using
.codn tcgetattr ,
manipulating the structure returned by this function, and
then using
.code tcsetattr
to install the modified structure into the device.

The
.meta actions
argument of
.code tcsetattr
may be given as the value of one of the variables
.codn tcsanow ,
.code tcsadrain
or
.codn tcsaflush .
If it is omitted, the default is
.codn tcsadrain .

If an argument is given for
.meta device
it must be either a stream, or an integer file descriptor.
In either case, it is expected to be associated with a
terminal (TTY) device.

If the argument is omitted, it defaults to the stream currently
stored in the
.code *stdin*
stream special variable, expected to be associated with
a terminal device.

.TP* Notes:

The C
.code termios
structure usually does not have members for representing the input
and output speed. \*(TL does not use such members, in any case, even
if they are present. The speeds are encoded in the
.code cc_iflag
and
.code cc_lflag
bitmasks. When retrieving the settings, the
.code tcgetattr
function uses the POSIX functions
.code cfgetispeed
and
.code cfgetospeed
to retrieve the speed values from the C structure. These values
are installed as the
.code ispeed
and
.code ospeed
slots of the Lisp structure.   A reverse conversion takes place
when setting are installed using
.codn tcsetattr :
the speed values are taken from the slots, and installed into
the C structure using
.code cfsetispeed
and
.code cfsetospeed
before the structure is passed to the C
.code tcsetattr
function.

On Linux, TTY devices do not have a separate input and output speed.
The C
.code termios
structure stores only one speed which is taken as both the input
and output speed, with a special exception. The input speed may be
programmed as zero. In that case, it is independently represented.
speed may be programmed as zero.

.coNP Function @ tcsendbreak
.synb
.mets (tcsendbreak >> [ duration <> [ device ]])
.syne
.desc
The
.code tcsendbreak
function generates a break signal on serial devices. The
.meta duration
parameter specifies the length of the break signal in milliseconds.
If the argument is omitted, the value 500 is used.

The
.meta device
parameter is exactly the same as that of the
.code tcsetattr
function.

.coNP Function @ tcdrain
.synb
.mets (tcdrain <> [ device ])
.syne
.desc
The
.code tcdrain
function waits until all queued output on a terminal
device has been transmitted. It is a direct wrapper
for the like-named POSIX C function.

The
.meta device
parameter is exactly the same as that of the
.code tcsetattr
function.

.coNP Function @ tcflush
.synb
.mets (tcflush < queue <> [ device ])
.syne
.desc
The
.code tcflush
function discards either untransmitted output data,
or received and yet unread input data, depending on the
value of the
.meta queue
argument. It is a direct wrapper for the like-named
POSIX C function.

The
.meta queue
argument should be the value of one of the variables
.codn tciflush ,
.code tcoflush
and
.codn tcioflush ,
which specify the flushing of input data, output
data or both.

The
.meta device
parameter is exactly the same as that of the
.code tcsetattr
function.

.coNP Function @ tcflow
.synb
.mets (tcflow < action <> [ device ])
.syne
.desc
The
.code tcflow
function provides bi-directional flow control on the
specified terminal device. It is a direct wrapper
for the like-named POSIX C function.

The
.meta action
argument should be the value of one of the
variables
.codn tcooff ,
.codn tcoon ,
.code tcioff
and
.codn tcion .

The
.meta device
parameter is exactly the same as that of the
.code tcsetattr
function.

.coNP Methods @, set-iflags @, set-oflags @, set-cflags @, set-lflags @, clear-iflags @, clear-oflags @ clear-cflags and @ clear-lflags
.synb
.mets << termios .(set-iflags << flags *)
.mets << termios .(set-oflags << flags *)
.mets << termios .(set-cflags << flags *)
.mets << termios .(set-lflags << flags *)
.mets << termios .(clear-iflags << flags *)
.mets << termios .(clear-oflags << flags *)
.mets << termios .(clear-cflags << flags *)
.mets << termios .(clear-lflags << flags *)
.syne
.desc
These methods of the
.code termios
structure set or clear multiple flags of the four bitmask flag fields.

The
.meta flags
arguments specify zero or more integer values. These values
are combined together bitwise, as if by the
.code logior
function to form a single effective mask.
If there are no
.meta flags
arguments, then the effective mask is zero.

The
.code set-iflags
method sets, in the
.code iflag
slot of the
.meta termios
structure, all of the bits which
are set in the effective mask. That is to say,
the effective mask is combined with the value in
.code iflag
by a
.code logior
operation, and the result is stored back into
.codn iflag .
Similarly, the
.codn set-oflags ,
.code set-cflags
and
.code set-lflags
methods operate on the
.codn oflag ,
.code cflag
and
.code lflag
slots of the structure.

The
.code clear-iflags
method clears, in the
.code iflag
slot of the
.meta termios
structure, all of the bits which are
set in the effective mask. That is to say,
the effective mask is bitwise inverted as if
by the
.code lognot
function, and then combined with the
existing value of the
.code iflag
slot using
.codn logand .
The resulting value is stored back into the
.code iflag
slot.
Similarly, the
.codn clear-oflags ,
.code clear-cflags
and
.code clear-lflags
methods operate on the
.codn oflag ,
.code cflag
and
.code lflag
slots of the structure.

Note: the methods
.codn go-raw ,
.code go-cbreak
and
.code go-canon
are provided for changing the settings to raw, "cbreak" and canonical mode.
These methods should be preferred to directly manipulating the flag and
.code cc
slots.

.TP* Example

In this example,
.code tio
is assumed to be a variable holding an instance of a
.code termios
struct:

.verb
  ;; clear the ignbrk, brkint, and various other flags:
  tio.(clear-iflags ignbrk brkint parmrk istrip
                    inlcr igncr icrnl ixon)

  ;; set the csize and parenb flags:
  tio.(set-cflags csize parenb)
.brev

.coNP Methods @ go-raw and @ go-cbreak
.synb
.mets << termios .(go-raw)
.mets << termios .(go-cbreak)
.syne
.desc
The
.code go-raw
and
.code go-cbreak
methods of the
.code termios
structure manipulate the flag slots, as well as certain elements
of the
.code cc
slot, in order to prepare the terminal settings for, respectively,
"raw" and "cbreak" mode, described below.

Note that manipulating the
.code termios
structure doesn't actually put these settings into effect in
the terminal device; the settings represented by the structure must
be installed into the device using
.codn tcsetattr .
There is no way to reverse the effect of these methods.
To precisely restore the previous terminal settings, the program
should retain a copy of the original
.code termios
structure.

"Raw" mode refers to a configuration of the terminal device driver in which input
and output is passed transparently and without accumulation, conversion or
interpretation. Input isn't buffered into lines; as soon as a single byte is
received, it is available to the program. No special input characters such as
commands for generating an interrupt or process suspend request are processed
by the terminal driver; all characters are treated as input data.  Input isn't
echoed; the only output which takes place is that generated by program
output requests to the device.

"Cbreak" mode is named after a concept and function in the "curses" terminal
control library. It refers to a configuration of the terminal device driver
which is less transparent than "raw" mode. Input isn't buffered into lines,
and line editing commands are ordinary input characters, allowing
character-at-a-time input. However, most input translations are preserved,
except that the conversion of CR characters to NL is disabled.  The
signal-generating characters are processed in this mode. This latter feature of
the configuration is the likely inspiration for the word "cbreak". Unless
otherwise configured, the interrupt character corresponds to the Ctrl-C key,
and "break" is another term for an interactive interruption.

.coNP Methods @ string-encode and @ string-decode
.synb
.mets << termios .(string-encode)
.mets << termios .(string-decode << string )
.syne
.desc
The
.code string-encode
method converts the terminal state stored in a
.code termios
structure into a textual format, returning that representation
as a character string.

The
.code string-decode
method parses the character representation produced by
.code string-encode
and populates the
.meta termios
structure with the settings are encoded in that string.

If a string is passed to
.code string-decode
which wasn't produced by
.codn string-encode ,
the behavior is unspecified. An exception may or may not be
thrown, and the contents of
.meta termios
may or may not be affected.

Note: the textual representation produced by
.code string-encode
is intended to be identical to that produced by the
.code -g
option of the GNU Coreutils version of the
.code stty
utility, on the same platform. That is to say, the output of
.code "stty -g"
may be used as input into
.codn string-decode ,
and the output of
.code string-encode
may be used as an argument to
.codn stty .

.SS* Unix System Identification

.coNP Structure @ utsname
.synb
.mets (defstruct utsname nil
.mets \ \ sysname nodename release
.mets \ \ version machine domainname)
.syne
.desc
The
.code utsname
structure corresponds to the POSIX structure of the same name.
An instance of this structure is returned by the
.code uname
function.

.coNP Function @ uname
.synb
.mets (uname)
.syne
.desc
The
.code uname
function corresponds to the POSIX
function of the same name. It returns an instance of the
.code utsname
structure.  Each slot of the returned structure is
initialized with a character string that identifies the corresponding attribute
of the host system.

The host system might not support the reporting of the
NIS domain name. In this case, the
.code domainname
slot of the returned
.code utsname
structure will have the value
.codn nil .

.SS* Web Programming Support

.coNP Functions @ url-encode and @ url-decode
.synb
.mets (url-encode < string <> [ space-plus-p ])
.mets (url-decode < string <> [ space-plus-p ])
.syne
.desc
These functions convert character strings to and from a form which is suitable 
for embedding into the request portions of URL syntax.

Encoding a string for URL use means identifying in it certain characters that
might have a special meaning in the URL syntax and representing it using
"percent encoding": the percent character, followed by the ASCII value of the
character.  Spaces and control characters are also encoded, as are all byte
values greater than or equal to 127 (7F hex).  The printable ASCII characters
which are percent-encoded consist of this set:

.verb
  :/?#[]@!$&'()*+,;=%
.brev

More generally, strings can consists of Unicode characters, but the URL
encoding consists only of printable ASCII characters. Unicode characters in the
original string are encoded by expanding into UTF-8, and applying
percent-encoding the UTF-8 bytes, which are all in the range
.codn \exx80-\exxFF .

Decoding is the reverse process: reconstituting the UTF-8 byte sequence
specified by the URL-encoding, and then decoding the UTF-8 sequence into the
string of Unicode characters.

There is an additional complication: whether or not to encode spaces as plus,
and to decode plus characters to spaces. In encoding, if spaces are not encoded
to the plus character, then they are encoded as
.codn %20 ,
since spaces are reserved
characters that must be encoded. In decoding, if plus characters are not
decoded to spaces, then they are left alone: they become plus characters in the
decoded string.

The
.code url-encode
function performs the encoding process. If the
.code space-plus-p
argument is omitted or specified as
.codn nil ,
then spaces are encoded as
.codn %20 .
If the argument is a value other than
.codn nil ,
then spaces are encoded as the
character
.code +
.codn (plus) .

The
.code url-decode
function performs the decoding process. If the
.code space-plus-p
argument is omitted or specified as
.codn nil ,
then
.code +
.code (plus)
characters in the
encoded data are retained as
.code +
characters in the decoded strings. Otherwise,
plus characters are converted to spaces.

.coNP Functions @, html-encode @ html-encode* and @ html-decode
.synb
.mets (html-encode << text-string )
.mets (html-decode << html-string )
.syne
.desc
The
.code html-encode
and
.code html-decode
functions convert between an HTML and raw
representation of text.

The
.code html-encode
function returns a string which is based on the content of
.metn text-string ,
but in which all characters which have special meaning in HTML
have been replaced by HTML codes for representing those characters literally.
The returned string is the HTML-encoded verbatim representation of
.metn text-string .

The
.code html-decode
function converts
.metn html-string ,
which may contain HTML
character encodings, into a string which contains the actual characters
represented by those encodings.

The function composition
.code "(html-decode (html-encode text))"
returns a string which is equal to
.codn text .

The reverse composition
.code "(html-encode (html-decode html))"
does not necessarily return a string equal to
.codn html .

For instance if html is the string
.strn "<p>Hello, world&#33;</p>" ,
then
.code html-decode
produces
.strn "<p>Hello, world!</p>" .
From this,
.code html-encode
produces
.strn "&lt;p&gt;Hello, world!&lt;/p&gt;" .

The
.code html-encode*
function is similar to
.code html-encode
except that it does not encode the single and double quote characters
(ASCII 39 and 34, respectively). Text prepared by this function may not
be suitable for insertion into a HTML template, depending on the
context of its insertion. It is suitable as text placed between
tags but not necessarily as tag attribute material.

.coNP Functions @, base64-encode @ base64-decode and @ base64-decode-buf
.synb
.mets (base64-encode >> [ string | << buf ] <> [ column-width ])
.mets (base64-decode < string)
.mets (base64-decode-buf < string)
.syne
.desc
The
.code base64-encode
function converts the UTF-8 representation of
.metn string ,
or the contents of
.metn buf ,
to Base64 and returns that representation as a string.
The Base64 encoding is described in RFC 4648, section 5.

The second argument must either be a character string, or
a buffer object.

The
.code base64-decode
functions performs the opposite conversion; it extracts the
bytes encoded in a Base64 string, and decodes them as UTF-8
to return a character string.

The
.code base64-decode-buf
extracts the bytes encoded in a Base64 string, and returns
a new buffer object containing these bytes.

The Base64 encoding divides the UTF-8 representation of
.meta string
or the bytes contained in
.meta buf
into groups of six bits, each representing the values 0 to 63. Each value is
then mapped to the characters
.code A
to
.codn Z ,
.code a
to
.codn z ,
the digits
.code 0
to
.code 9
and the characters
.code +
and
.codn / .
One or two consecutive occurrences of the character
.code =
are added as padding so that the number of
non-whitespace characters is divisible by four. These characters map to
the code 0, but are understood not to contribute to the length of the
encoded message. The
.code base64-encode
function enforces this convention, but
.code base64-decode
doesn't require these padding characters.

Base64-encoding an empty string or zero-length buffer results in an empty
string.

If the
.meta column-width
argument is passed to
.codn base64-encode ,
then the Base64 encoded string, unless empty, contains newline
characters, which divide it into lines which are
.meta column-width
long, except possibly for the last line.

.coNP Functions @ base64-stream-enc and @ base64-stream-dec
.synb
.mets (base64-stream-enc < out < in >> [ nbytes <> [ column-width ]])
.mets (base64-stream-dec < out << in )
.syne
.desc
The
.code base64-stream-enc
and
.code base64-stream-dec
perform, respectively, bulk Base64 encoding and decoding between streams.
This format is described in RFC 4648, section 5.

The
.meta in
and
.meta out
arguments must be stream objects.
The
.meta out
stream must support output. In the decode operation, it must support
byte output.
The
.meta in
stream must support input. In in the encode operation it must support
byte input.

The
.code base64-stream-enc
function reads a sequence of bytes from the
.meta in
stream and writes characters to the
.meta out
stream comprising the Base64 encoding of that sequence. If the
.meta nbytes
argument is specified, it must be a non-negative integer. At most
.meta nbytes
bytes will be read from the
.meta in
stream. If
.meta nbytes
is omitted, then the operation will read from the
.meta in
stream without limit, until that stream indicates that no more bytes
are available.

The optional
.meta column-with
argument influences the formatting of Base64 output, in the same manner
as documented for the
.code base64-encode
function.

The
.code base64-stream-dec
function reads the characters of a Base64 encoding from the
.meta in
stream and writes the corresponding byte sequence to the
.meta out
stream. It keeps reading and decoding until it encounters the end of the
stream, or a character not used in Base64: a character that is not whitespace
according to
.codn chr-isspace ,
isn't any of the Base64 coding characters (not an alphanumeric character,
and not one of the characters
.codn + ,
.code /
or
.codn = .
If the function stops due to a non-Base64 character, that character is
pushed back into the
.meta in
stream.

The
.code base64-stream-enc
function returns the number of bytes encoded;
the
.code base64-stream-dec
function returns the number of bytes decoded.

.coNP Functions @, base64url-encode @ base64url-decode and @ base64url-decode-buf
.synb
.mets (base64url-encode >> [ string | << buf ] <> [ column-width ])
.mets (base64url-decode < string)
.mets (base64url-decode-buf < string)
.syne
.desc
The
.codn base64url-encode ,
.code base64url-decode
and
.code base64url-decode-buf
functions conform, in nearly every respect, to the descriptions of,
respectively,
.codn base64-encode ,
.code base64-decode
and
.codn base64-decode-buf .
The difference is that these functions use the encoding described in
section 6 of RFC 4648, rather than section 5. This means that, in the
encoding alphabet, instead of the symbols
.code +
(plus)
and
.code /
(slash)
the symbols
.code -
(minus)
and
.code _
(underline) are used.

.coNP Functions @ base64url-stream-enc and @ base64url-stream-dec
.synb
.mets (base64url-stream-enc < out < in >> [ nbytes <> [ column-width ]])
.mets (base64url-stream-dec < out << in )
.syne
.desc
The
.code base64url-stream-enc
and
.code base64url-stream-dec
functions conform, in nearly every respect, to the descriptions of,
respectively,
.code base64-stream-enc
and
.codn base64-stream-dec .
The difference is that these functions use the encoding described in
section 6 of RFC 4648, rather than section 5. This means that, in the
encoding alphabet, instead of the symbols
.code +
(plus)
and
.code /
(slash)
the symbols
.code -
(minus)
and
.code _
(underline) are used.

.SS* Filter Module
The filter module provides a trie (pronounced "try") data structure,
which is suitable for representing dictionaries for efficient filtering.
Dictionaries are unordered collections of keys, which are strings, which
have associated values, which are also strings.  A trie can be used to filter
text, such that keys appearing in the text are replaced by the corresponding
values. A trie supports this filtering operation by providing an efficient
prefix-based lookup method which only looks at each input character ones, and
which does not require knowledge of the length of the key in advance.

.coNP Function @ make-trie
.synb
.mets (make-trie)
.syne
.desc
The
.code make-trie
function creates an empty trie. There is no special data type for
a trie; a trie is some existing type such as a hash table.

.coNP Function @ trie-add
.synb
.mets (trie-add < trie < key << value )
.syne
.desc
The
.code trie-add
function adds the string
.meta key
to the trie, associating
it with
.metn value .
If
.meta key
already exists in
.metn trie ,
then the value is updated with
.metn value .

The
.meta trie
must not have been compressed with
.metn trie-compress .

A trie can contain keys which are prefixes of other keys. For instance
it can contain
.str dog
and
.strn dogma .
When a trie is used for matching
and substitution, the longest match is used. If the input presents
the text
.strn doggy ,
then the match is
.strn dog .
If the input is
.strn dogmatic ,
then
.str dogma
matches.

.coNP Function @ trie-compress
.synb
.mets (trie-compress << trie )
.syne
.desc
The
.code trie-compress
function changes the representation of
.meta trie
to a representation which occupies less space and supports faster lookups.
The new representation is returned.

The compressed representation of a trie does not support the
.code trie-add
function.

The
.code trie-compress
function destructively manipulates
.metn trie ,
and may return an object
that is the same object as
.codn trie ,
or it may return a different object,
while at the same time still modifying the internals of
.metn trie .
Consequently, the program should not retain the input object
.codn trie ,
but use the returned object in its place.

.coNP Function @ trie-lookup-begin
.synb
.mets (trie-lookup-begin << trie )
.syne
.desc
The
.code trie-lookup-begin
function returns a context object for performing
an open-coded lookup traversal of a trie. The
.meta tri
argument
is expected to be a trie that was created by the
.code make-trie
function.

.coNP Function @ trie-lookup-feed-char
.synb
.mets (trie-lookup-feed-char < trie-context << char )
.syne
.desc
The
.code trie-lookup-feed-char
function performs a one character step in a trie
lookup. The
.meta trie-context
argument must be a trie context returned
by
.metn trie-lookup-begin ,
or by some previous call to
.codn trie-lookup-feed-char .
The
.meta char
argument is the next character to match.

If the lookup is successful (the match through the trie can continue
with the given character) then a new trie context object is returned.
The old trie context remains valid.

If the lookup is unsuccessful,
.code nil
is returned.

Note: determining whether a given string is stored in a trie can be
performed looking up every character of the string successively
with
.codn trie-lookup-feed-char ,
using the newly returned context
for each successive operation. If every character is found, it means
that either that exact string is found in the trie, or a prefix.
The ambiguity can be resolved by testing whether the trie has a value
at the last node using
.codn tree-value-at .
For instance, if
.str catalog
is inserted into an empty trie with value
.strn foo ,
then
.str cat
will look up successfully, being a prefix of
.strn catalog ;
however, the value at
.str cat
is
.codn nil ,
indicating that
.str cat
is only a prefix of one or more entries in the trie.

.coNP Function @ tree-value-at
.synb
.mets (trie-value-at << trie-context )
.syne
.desc
The
.code trie-value-at
function returns the value stored at the node in
in the trie given by
.metn trie-context .
Nodes which have not been given
a value hold the value
.codn nil .

.coNP Function @ filter-string-tree
.synb
.mets (filter-string-tree < filter << obj )
.syne
.desc
The
.code filter-string-tree
a tree structure similar to
.metn obj ,
in which all of the
string atoms have been filtered through
.metn filter .

The
.meta obj
argument is a string tree structure: either the symbol
.codn nil ,
denoting an empty structure; a string; or a list of tree structures. If
.meta obj
is
.codn nil ,
then
.code filter-string-tree
returns
.codn nil .

The
.meta filter
argument is a filter: it is either a trie, a function, or nil.
If
.meta filter
is
.codn nil ,
then
.code filter-string-trie
just returns
.metn obj .

If
.meta filter
is a function, it must be a function that can be called
with one argument. The strings of the string tree are filtered by passing
each one into the function and substituting the return value into the
corresponding place in the returned structure.

Otherwise if
.meta filter
is a trie, then this trie is used for filtering,
the string elements similarly to a function. For each string, a new
string is returned in which occurrences of the keys in the trie are
replaced by the values in the trie.

.coNP Function @ filter-equal
.synb
.mets (filter-equal < filter-1 < filter-2 < obj-1 << obj-2 )
.syne
.desc
The
.code filter-equal
function tests whether two string trees are equal
under the given filters.

The precise semantics can be given by this expression:

.mono
.mets (equal (filter-string-tree < filter-1 << obj-1 )
.mets \ \ \ \ \ \  (filter-string-tree < filter-2 << obj-2 ))
.onom

The string tree
.meta obj-1
is filtered through
.metn filter-1 ,
as if by the
.code filter-string-tree
function, and similarly,
.meta obj-2
is
filtered through
.metn filter-2 .
The resulting structures are compared
using
.codn equal ,
and the result of that is returned.

.coNP Function @ regex-from-trie
.synb
.mets (regex-from-trie << trie )
.syne
.desc
The
.code regex-from-trie
function returns a representation of
.meta trie
as regular expression abstract syntax, suitable for
processing by the
.code regex-compile
function.

The values stored in the trie nodes are not represented in
the regular expression.

The
.meta trie
may be one that has been compressed via
.codn trie-compress ;
in fact, a compressed
.meta trie
results in more compact syntax.

Note: this function is useful for creating a compact, prefix-compressed
regular expression which matches a list of strings.

.coNP Special variable @ *filters*
.desc
The
.code *filters*
special variable holds a hash table which associates symbols with
filters. This hash table defines the named filters used in the
\*(TX pattern language. The names are the hash table keys, and filter
objects are the values. Filter objects are one of three representations.
The value
.code nil
represents a null filter, which performs no filtering, passing the input
string through. A filter object may be a raw or compressed trie.
It may also be a Lisp function, which must be callable with one argument
of string type, and must return a string.

The application may define new filters by associating symbolic keys in
.code *filters*
with values which conform to the above representation of filters.

The behavior is unspecified if any of the predefined filters
are removed or redefined, and are subsequently used, or if the
.code *filters*
variable is replaced or rebound with a hash table value which omits
those keys, or associates them with different values.

Note that functions
.codn html-encode ,
.code html-encode*
and
.code html-decode
use, respectively, the HTML-related
.codn :tohtml ,
.code :tohtml*
and
.codn :fromhtml .

.SS* Access To TXR Pattern Language From Lisp

It is useful to be able to invoke the abilities of the \*(TX pattern Language
from \*(TL. An interface for doing this provided in the form of the
.code match-fun
function, which is used for invoking a \*(TX pattern function.

The
.code match-fun
function has a cumbersome interface which requires the \*(TL program to
explicitly deal with the variable bindings emerging from the pattern match
in the form of an association list.

To make it the interface easier to use, \*(TX provides
the macros
.codn txr-if ,
.code txr-when
and
.codn txr-case .

.coNP Function @ match-fun
.synb
.mets (match-fun < name < args >> [ input <> [ files ]])
.syne
.desc
The
.code match-fun
function invokes a \*(TX pattern function whose name is
given by
.metn name ,
which must be a symbol.

The
.meta args
argument is a list of expressions. The expressions may be symbols
which will be interpreted as pattern variables, and may be bound or unbound.
If they are not symbols, then they are treated as expressions (of the
pattern language, not \*(TL) and evaluated accordingly.

The
.meta input
argument is a list of strings, which may be lazy. It represents the
lines of the text stream to be processed. If omitted, it defaults to
.codn nil .

The
.meta files
argument is a list of filename specifications, which follow
the same conventions as files given on the \*(TX command line. If the pattern
function uses the
.code @(next)
directive, it can process these additional files. If this argument is
omitted, it defaults to
.codn nil .

The
.code match-fun
function's return value falls into three cases. If there is a
match failure, it returns
.codn nil .
Otherwise it returns a cons cell. The
.code car
field
of the cons cell holds the list of captured bindings. The
.code cdr
of the cons cell is one of two values. If the entire input was processed, the
cdr field holds the symbol
.codn t .
Otherwise it holds another cons cell whose
.code car
is the remainder of the list of lines which were not matched, and whose
.code cdr
is the line number.

.TP* Example:

.verb
  @(define foo (x y))
  @x:@y
  @line
  @(end)
  @(do
     (format t "~s\en"
               (match-fun 'foo '(a b)
                          '("alpha:beta" "gamma" "omega") nil)))

  Output:
  (((a . "alpha") (b . "beta")) ("omega") . 3)
.brev

In the above example, the pattern function
.code foo
is called with arguments
.codn "(a b)" .
These are unbound variables, so they correspond to parameters
.code x
and
.code y
of the function. If
.code x
and
.code y
get bound, those values propagate to
.code a
and
.codn b .
The data being matched consists of the lines
.strn alpha:beta ,
.str gamma
and
.strn omega .
Inside
.codn foo ,
.code x
and
.code y
bind to
.str alpha
and
.strn beta ,
and then the line variable binds to
.strn gamma .
The input stream is left with
.strn omega .

Hence, the return value consists of the bindings of
.code x
and
.code y
transferred to
.code a
and
.codn b ,
and the second cons cell which gives information about the rest of the
stream: it is the part starting at
.strn omega ,
which is line 3. Note that the binding for the
.code line
variable does not propagate
out of the pattern function
.codn foo ;
it is local inside it.

.coNP Macro @ txr-if
.synb
.mets (txr-if < name <> ( argument *) < input
.mets \ \ \ \ \ \ \  < then-expr <> [ else-expr ])
.syne
.desc
The
.code txr-if
macro invokes the \*(TX pattern matching function
.meta name
on some input given by the
.meta input
parameter, which is a list of strings, or a single string.

If
.meta name
succeeds, then
.meta then-expr
is evaluated, and if it fails,
.meta else-expr
is evaluated instead.

In the successful case,
.meta then-expr
is evaluated in a scope in which the bindings emerging from the
.meta name
function are turned into \*(TL variables.
The result of
.code txr-if
is that of
.metn then-expr .

In the failed case,
.meta else-expr
is evaluated in a scope which does not have any new bindings.
The result of
.code txr-if
is that of
.metn else-expr .
If
.meta else-expr
is missing, the result is
.codn nil .

The
.meta argument
forms supply arguments to the pattern function
.metn name .
There must be as many of these arguments as the function
has parameters.

Any argument which is a symbol is treated, for the purposes
of calling the pattern function, as an unbound pattern variable.
The function may or may not produce a binding for that variable.
Also, every argument which is a symbol also denotes a local variable
that is established around
.meta then-expr
if the function succeeds. For any such pattern variable for which the function
produces a binding, the corresponding local variable will be initialized
with the value of that pattern variable. For any such pattern variable
which is left unbound by the function, the corresponding local variable
will be set to
.codn nil .

Any
.meta argument
can be a form other than a symbol. In this situation, the argument is
evaluated, and will be passed to the pattern function as the value of
the binding for the corresponding argument.

.TP* Example:

.verb
  @(define date (year month day))
  @{year /\ed\ed\ed\ed/}-@{month /\ed\ed/}-@{day /\ed\ed/}
  @(end)
  @(do
     (each ((date '("09-10-20" "2009-10-20"
                    "July-15-2014" "foo")))
       (txr-if date (y m d) date
         (put-line `match: year @y, month @m, day @d`)
         (put-line `no match for @date`))))

  Output:

  no match for 09-10-20
  match: year 2009, month 10, day 20
  no match for July-15-2014
  no match for foo
.brev

.coNP Macro @ txr-when
.synb
.mets (txr-when < name <> ( argument *) < input << form *)
.syne
.desc
The
.code txr-when
macro is based on
.codn txr-if .
It is equivalent to

.mono
.meti \ \ (txr-if < name <> ( argument *) < input (progn << form *))
.onom

If the pattern function
.meta name
produces a match, then each
.meta form
is evaluated in the scope of the variables established by the
.meta argument
expressions. The result of the
.code txr-when
form is that of the last
.metn form .

If the pattern function fails then the forms are not evaluated,
and the result value is
.codn nil .

.coNP Macro @ txr-case
.synb
.mets (txr-case < input-form
.mets \ \  >> {( name <> ( argument *) << form *)}*
.mets \ \  >> [( t << form *)])
.syne
.desc
The
.code txr-case
macro evaluates
.meta input-form
and then uses the value as an input to zero or more test clauses.
Each test clause invokes the pattern function named by that clause's
.meta name
argument.

If the function succeeds, then each
.meta form
is evaluated, and the value of the last
.meta form
is taken to be the result value of
.codn txr-case ,
which terminates. If there are no forms, then
.code txr-case
terminates with a
.code nil
result.

The forms are evaluated in an environment in which variables are bound
based on the
.meta argument
forms, with values depending on the result of the
invocation of the
.meta name
pattern function, in the same manner as documented in detail for the
.code txr-if
macro.

If the function fails, then the forms are not evaluated, and control passes to
the next clause.

A clause which begins with the symbol
.code t
executes unconditionally and causes
.code txr-case
to terminate. If it has no forms, then
.code txr-case
yields
.codn nil ,
otherwise the forms are evaluated in order and the value of the last
one specifies the result of
.codn txr-case .

.coNP Function @ txr-parse
.synb
.mets (txr-parse >> [ source >> [ error-stream
.mets \ \ \ \ \ \ \ \ \ \ \  >> [ error-retval <> [ name ]]]])
.syne
.desc
The
.code txr-parse
function converts textual \*(TX query syntax into a Lisp data
structure representation.

The
.meta source
argument may be either a character
string, or a stream.  If it is omitted, then
.code *stdin*
is used as the stream.

The
.meta source
must provide the text representation of one complete \*(TX query.

The optional
.meta error-stream
argument can be used to specify a stream to which
parse errors diagnostics are sent. If absent, the diagnostics are suppressed.

The optional
.meta name
argument can be used to specify the file name which is used for reporting
errors. If this argument is missing, the name is taken from the name
property of the
.meta source
argument if it is a stream, or else the word
.code string
is used as the name if
.meta source
is a string.

If there are no parse errors, the function returns the parsed data
structure. If there are parse errors, and the
.meta error-retval
parameter is
present, its value is returned. If the
.meta error-retval
parameter
is not present, then an exception of type
.code syntax-error
is thrown.

.SS* Debugging Functions
.coNP Functions @ source-loc and @ source-loc-str
.synb
.mets (source-loc << form )
.mets (source-loc-str < form <> [ alternative ])
.syne
.desc
These functions map an expression in a \*(TX program to the file name and
line number of the source code where that form came from.

The
.code source-loc
function returns the raw information as a cons cell
whose
.cod3 car / cdr
consist of the line number, and file name.

The
.code source-loc-str
function formats the information as a string.

Forms which were parsed from a file have source location info
tracking to their origin in that file. Forms which are the result
of macro-expansion are traced to the form whose evaluation produced
them. That is to say, they inherit that form's source location info.

More precisely, when a form is produced by macro-expansion,
it usually consists of material which was passed to the macro as arguments,
plus some original material allocated by the macro, and possibly
literal structure material which is part of the macro code.
After the expansion is produced, any of its constituent material
which already has source location info keeps that info. Those nodes
which are newly allocated by the macro-expansion process inherit
their source location info from the form which yields the expansion.

If
.meta form
is not a piece of the program source code that was constructed by the
\*(TX parser or by a macro, and thus it was neither attributed with
source location info, nor has it inherited such info, then
.code source-loc
returns
.codn nil .

In the same situation, and if its
.meta alternative
argument is missing, the
.code source-loc-str
returns a string whose text conveys that the source location is not
available. If the
.meta alternative
argument is present, it is returned.

.coNP Functions @ rlcp and @ rlcp-tree
.synb
.mets (rlcp < dest-form << source-form )
.mets (rlcp < dest-tree << source-form )
.syne
.desc
The
.code rlcp
function copies the source code location info ("rl" means "read location")
from the
.meta source-form
object to the
.meta dest-form
object. These objects
are pieces of list-based syntax.
If
.meta dest-form
already has source code location info, then no copying
takes place.

The
.code rlcp-tree
function copies the source code location info from
.code rlcp
into every cons cell in the
.meta dest-tree
tree structure which doesn't already have location info.
It may be regarded as a recursive application of
.code rlcp
via
.cod3 car / cdr
recursion on the tree structure. However, the traversal performed by
.code rlcp-tree
gracefully handles circular structures.

Note: these functions are intended to be used in certain kinds of macros. If a
macro transforms
.meta source-form
to
.metn dest-form ,
this function can be used to propagate the
source code location info also, so that when the \*(TL evaluator
encounters errors in transformed code, it can give diagnostics which refer
to the original untransformed source code.

The macro expander already performs this transfer. If a macro call form
has location info, the expander propagates that info to that form's
expansion. In some situations, it is useful for a macro or other code
transformer to perform this action explicitly.

.coNP Special variable @ *rec-source-loc*
.desc
The Boolean special variable
.code *rec-source-loc*
controls whether the
.code read
and
.code iread
functions record source location info. The variable is
.code nil
by default, so that these functions do not record source location info.
If it is true, then these functions record source location info.

Regardless of the value of this variable, source location info is
recorded for Lisp forms which are read from files or streams under the
.code load
function or specified on the \*(TX command line. Source location
info is also always recorded when reading the \*(TX pattern language syntax.

Note: recording and propagating location info incurs a memory and performance
penalty.  The individual cons cells and certain other literal objects in the
structure which emerges from the parser are associated with source location
info via a global weak hash table.


.coNP Function @ macro-ancestor
.synb
.mets (macro-ancestor << form )
.syne
.desc
The
.code macro-ancestor
function returns information about the macro-expansion ancestor of
.metn form .
The ancestor is the original form whose expansion produced
.metn form .

If
.meta form
is not the result of macro-expansion, or the ancestor information
is unavailable, the function returns
.codn nil .

.SS* Profiling
.coNP Operator @ prof
.synb
.mets (prof << form *)
.syne
.desc
The
.code prof
operator evaluates the enclosed forms from left to right similarly
to
.codn progn ,
while determining the memory allocation requests and time
consumed by the evaluation of the forms.

If there are no forms, the prof operator measures the smallest measurable
operation of evaluating nothing and producing
.codn nil .

If the evaluation terminates normally (not abruptly by a non-local
control transfer), then
.code prof
yields a list consisting of:

.mono
.mets >> ( value < malloc-bytes < gc-bytes << milliseconds )
.onom

where
.meta value
is the value returned by the rightmost
.metn form ,
or
.code nil
if there are no forms,
.meta malloc-bytes
is the total number of bytes of all memory allocation
requests (or at least those known to the \*(TX runtime, such as those of all
internal objects),
.meta gc-bytes
is the total number of bytes drawn from the
garbage-collected heaps, and
.meta milliseconds
is the total processor time
consumed over the execution of those forms.

Notes:

The bytes allocated by the garbage collector from the C function
.code malloc
to create
heap areas are not counted as
.metn malloc-bytes .
.meta malloc-bytes
includes storage
such as the space used for dynamic strings, vectors and bignums (in addition to
their gc-heap-allocated nodes), and the various structures used by the
.code cobj
type objects such as streams and hashes. Objects in external libraries that use
uninstrumented allocators are not counted: for instance the C
.code "FILE *"
streams.

.coNP Macro @ pprof
.synb
.mets (pprof << form *)
.syne
.desc
The
.code pprof
(pretty-printing
.codn prof )
macro is similar to
.codn progn .
It evaluates
.metn form -s,
and returns the rightmost one, or
.code nil
if there are no forms.

Over the evaluation of
.metn form -s,
it counts memory allocations, and measures
CPU time. If
.metn form -s
terminate normally, then just prior to returning,
.code pprof
prints these statistics in a concise report on the
.codn *stdout* .

The
.code pprof
macro relies on the
.code prof
operator.

.SS* Garbage Collection
.coNP Function @ sys:gc
.synb
.mets (sys:gc <> [ full ])
.syne
.desc
The
.code gc
function triggers garbage collection.  Garbage collection means
that unreachable objects are identified and reclaimed, so that their
storage can be re-used.

The function returns
.code nil
if garbage collection is disabled (and consequently nothing is done), otherwise
.codn t .

The Boolean
.meta full
argument, defaulting to
.codn nil ,
indicates whether a full garbage collection should be requested.

Even if this argument is
.codn nil ,
a full garbage collection may occur due to having been scheduled.

.coNP Function @ sys:gc-set-delta
.synb
.mets (sys:gc-set-delta << bytes )
.syne
.desc
The
.code gc-set-delta
function sets the GC delta parameter.

Note: This function may disappear in a future release of \*(TX or suffer
a backward-incompatible change in its syntax or behavior.

When the amount of new dynamic memory allocated since the last garbage
collection equals or exceeds the GC delta, a garbage collection pass is
triggered. From that point, a new delta begins to be accumulated.

Dynamic memory is used for allocating heaps of small garbage-collected objects
such as cons cells, as well as the satellite data attached to some objects:
like the storage arrays of vectors, strings or bignum integers. Most garbage
collector behaviors are based on counting objects in the heaps.

Sometimes a program works with a small number of objects which are very large,
frequently allocating new, large objects and turning old ones into garbage.
For instance a single large integer could be many megabytes long.  In such a
situation, a small number of heap objects therefore control a large amount of
memory.  This requires garbage collection to be triggered much more often than
when working with small objects, such as conses, to prevent runaway allocation
of memory. It is for this reason that the garbage collector uses the GC delta.

There is a default GC delta of 64 megabytes. This may be overridden in
special builds of \*(TX for small systems.

.coNP Function @ finalize
.synb
.mets (finalize < object < function <> [ reverse-order-p ])
.syne
.desc
The
.code finalize
function registers
.meta function
to be invoked in the situation when
.meta object
is identified by the garbage collector as unreachable.
A function registered in this way is called a finalizer.

If and when this situation occurs, the finalizer
.meta function
will be called with
.meta object
as its only argument.

Multiple finalizer functions can be registered for the same object,
up to an internal limit which is not required to be greater than 255.
If the limit is exceeded,
.code finalize
throws an error exception.

All registered finalizers are called when the object becomes unreachable.
Finalizers registered against an object may also be invoked
and removed using the
.code call-finalizers
function.

If the
.meta reverse-order-p
argument isn't specified, or is
.codn nil ,
then finalizer is registered at the end of the list.

If
.meta reverse-order-p
is true, then the finalizer is registered at the front of
the list.

Finalizers which are activated in the same finalization processing phase
are called in the order in which they appear in the
registration list.

After a finalization call takes place, its registration is removed.  However,
neither
.meta object
nor
.meta function
are reclaimed immediately; they are treated as if they were reachable objects
until at least the next garbage collection pass.
It is therefore safe for
.meta function
to store somewhere a persistent reference to
.meta object
or to itself, thereby reinstating these objects as reachable.

A finalizer is itself permitted to call
.code finalize
to register the original
.code object
or any other object for finalization. Finalization processing can be
understood as taking place in one or more rounds.  At the start of each round,
finalizers are identified that are to be called, arranged in order, and removed
from the registration list. If this identification stage produces no
finalizers, then finalization ends. Otherwise, those finalizers are processed,
and then another round is initiated, to look for finalizers that may have been
registered during the previous round.

Note: it is possible for the application to create an infinite finalization
loop, if one or more objects have finalizers that register new finalizers,
which register new finalizers and so on.

.coNP Function @ call-finalizers
.synb
.mets (call-finalizers << object )
.syne
.desc
The
.code call-finalizers
function invokes and removes the finalizers, if any, registered against
.metn object .
If any finalizers are called, it returns
.codn t ,
otherwise
.codn nil .

Finalization performed by
.code call-finalizers
works in the manner described under the specification of he
.code finalize
function.

It is permissible for a finalizer function itself to call
.codn call-finalizers .
Such a call can happen in two possible contexts: finalization
initiated by by garbage collection, or under the scope of a
.code call-finalizers
invocation from application code. Doing so is safe, since the finalization
logic may be re-entered recursively.  When finalizers are being called during a
round of processing, those finalizers have already been removed from the
registration list, and will not be redundantly invoked by a recursive
invocation of finalization.

Under the scope of garbage-collection-driven reclamation, the
order of finalizer calls may not be what the application logic
expects. For instance even though a finalizer registered for some object
.code A
itself invokes
.codn "(call-finalizers B)" ,
it may be the case during GC reclamation that both
.code A
and
.code B
are identified as unreachable objects at the same time, and some or all
finalizers registered against
.code B
have already been called before the given
.code A
finalizer performs the explicit
.code call-finalizers
invocation against
.codn B .
Thus the the call either has no effect at all, or only calls some remaining
.code B
finalizers that have not yet been processed, rather than all of them,
as the application expects.

The application must avoid creating a dependency on the order of
finalization calls, to prevent the situation that the finalization actions are
only correct under an explicit
.code call-finalizers
but incorrect under spontaneous reclamation driven by garbage collection.

.SS* Modularization
.coNP Variable @ self-path
.desc
This variable holds the invocation path name of the \*(TX program.
The value of
.code self-path
when \*(TL expressions are being evaluated in command line arguments
is the string
.strn cmdline-expr .
The value of
.code self-path
when a \*(TX query is supplied on the command line via the
.code -c
command line option is the string
.strn cmdline .

Note that for programs read from a file,
.code self-path
holds the resolved name, and not the invocation name. For instance if
.code foo.tl
is invoked using the name
.codn foo ,
whereby \*(TX infers the suffix, then
.code self-path
holds the suffixed name.

.coNP Variable @ stdlib
.desc
The
.code stdlib
variable expands to the directory where the \*(TX standard library
is installed. It includes the trailing slash.

Note: there is no need to use the value of this variable to load library
modules. Library modules are keyed to specific symbols, and lazily loaded. When
a \*(TL library function, macro or variable is referenced for the first time,
the library module which defines it is loaded.  This includes references
which occur during the code expansion phase, at "macro time", so it works for
macros. In the middle of processing a syntax tree, the expander may encounter a
symbol that is registered for auto-loading, and trigger the load. When the load
completes, the symbol might now be defined as a macro, which the expander
can immediately use to expand the given form that is being traversed.

.coNP Function @ load
.synb
.mets (load << target )
.syne
.desc
The
.code load
function causes a file containing \*(TL or \*(TX code to be read and processed.
The
.meta target
argument is a string. The function can load \*(TL source files as well
as compiled files.

Firstly, the value in
.meta target
is converted to a
.I "tentative pathname"
as follows.

If
.meta target
specifies a pure relative pathname, as defined by the
.code pure-rel-path-p
function, then a special behavior applies.
If an existing load operation is in progress, then the special variable
.code *load-path*
has a binding. In this case,
.code load
will assume that the relative pathname is a reference relative to the
directory portion of that path name.
If
.code *load-path*
has the value
.codn nil ,
then a pure relative
.meta target
pathname is used as-is, and thus resolved relative to the current working
directory.

Once the tentative path name is determined,
.code load
determines whether the name is suffixed. The name is suffixed if it
ends in any of these four suffixes:
.codn .tlo ,
.codn .tl ,
.code .txr
or
.codn .txr_profile .

Depending on whether the tentative path name is suffixed,
.code load
tries to make one or more attempts to open several variations of that name.
These variations are called
.I "actual paths" .
If any attempt fails due to an error other than non-existence,
such as a permission error, then no further attempts are made; the
error exception propagates to
.codn load 's
caller.

If the tentative path name is suffixed, then
.code load
tries to open a file by that actual path name. If that attempt
fails, no other names are tried.

If the tentative path name is unsuffixed, then first the suffix
.code .tlo
is appended to the name, and an attempt is made to open a file
with this actual path. If that file is not found, then the suffix
.code .tl
is similarly tried. If that file is not found, then the unsuffixed
name is tried.

If an unsuffixed file is opened, its contents are treated as interpreted Lisp.
Files ending in
.code .txr_profile
are also treated as interpreted Lisp. Files ending in
.code .tlo
are treated as compiled Lisp, and those ending in
.code .txr
are treated as the \*(TX Pattern Language.

If the file is treated as \*(TL, then Lisp forms are read from it in
succession. Each form is evaluated as if by the
.code eval
function, before the next form is read.
If a syntax error is encountered, an exception of type
.code eval-error
is thrown.

If a file is treated as a compiled \*(TL object file, then the compiled images
of top-level forms are read from it, converted into compiled objects, and
executed.

If the file treated as \*(TX Pattern Language code,
then its contents are parsed in their entirety.
If the parse is successful, the query is executed.
Previous \*(TX pattern variable and function bindings are in
effect. If the query binds new variables and functions,
these emerge from the
.code load
and take effect. If the parse is unsuccessful, an exception of type
.code query-error
is thrown.

Parser error messages are directed to the
.code *stderr*
stream.

Over the evaluation of either a \*(TL, compiled file, or \*(TX file,
.code load
establishes a new dynamic binding for several special
variables. The variable
.code *load-path*
is given a new binding containing the actual path name.
The
.code *package*
variable is also given a new dynamic binding, whose value is the
same as the existing binding. Thus if the processing of the
loaded file has the effect of altering the value of
.codn *package* ,
that effect will be undone when the binding is removed
after the load completes.

When the
.code load
function terminates normally after processing a file,
it returns
.codn nil .
If the file contains a \*(TX pattern query which is
processed to completion, the matching success or failure
of that query has no bearing on the return value of
.codn load .
Note that this behavior is different from the
.code @(load)
directive which itself fails if the loaded query
fails, causing subsequent directives not to be processed.

A \*(TX pattern language file loaded with the Lisp
.code load
function does not have the usual implicit access to the
command line arguments, unlike a top-level \*(TX query.
If the directives in the file try to match input, they
work against the
.code *stdin*
stream.  The
.code @(next)
directive behaves as it does when no more arguments
are available.

If the source or compiled file begins with the characters
.codn #! ,
usually indicating "hash bang" script,
.code load
reads reads the first line of the file and discards it.
Processing of the file then begins with the first byte
following that line.

.coNP Special variable @ *load-path*
.desc
The
.code *load-path*
special variable has a top-level value which is
.codn nil .

When a file is being loaded, it is dynamically bound to the
path name of that file. This value is visible to the forms
are evaluated in that file during the loading process.

The
.code *load-path*
variable is is bound when a file is loaded from the command
line.

If the
.code -i
command line option is used to enter the interactive listener,
and a file to be loaded is also specified, then the
.code *load-path*
variable remains bound to the name of that file inside the
listener.

The
.code load
function establishes a binding for
.code *load-path*
prior to processing and evaluating all the top-level forms
in the target file. When the forms are evaluated, the binding
is discarded and
.code load
returns.

The
.code compile-file
function also establishes a binding for
.codn *load-path* .

The
.code @(load)
directive, also similarly establishes a binding around the
parsing and processing of a loaded \*(TX source file.

Also, during the processing of the profile file (see Interactive Profile File),
the variable is bound to the name of that file.

.coNP Macro @ load-for
.synb
.mets (load-for >> {( kind < sym << target )}*)
.syne
.desc
The
.code load-for
macro takes multiple arguments, each of which is a three-element
clause. Each clause specifies that a given
.meta target
file is to be conditionally loaded based on whether a symbol
.meta sym
has a certain kind of binding.

Each argument clause has the syntax
.mono
.meti >> ( kind < sym << target )
.onom
where
.meta kind
is one of the five symbols
.codn var ,
.codn fun ,
.codn macro ,
.code struct
or
.codn pkg .
The
.meta sym
element is a symbol suitable for use as a variable, function
or structure name, and
.meta target
is an expression which is evaluated to produce a value that is suitable
as an argument to the
.code load
function.

First, all
.code target
expressions in all clauses are unconditionally evaluated in left to right
order. Then the clauses are processed in that order. If the
.meta kind
symbol of a clause is
.codn var ,
then
.code load-for
tests whether
.meta sym
has a binding in the variable namespace using the
.code boundp
function. If a binding does not exist, then the value of the
.meta target
expression is passed to the
.code load
function. Otherwise,
.code load
is not called.
Similarly, if
.meta kind
is the symbol
.codn fun ,
then
.meta sym
is instead tested using
.codn fboundp ,
if
.meta kind
is
.codn macro ,
then
.meta sym
is tested using
.codn mboundp ,
if
.meta kind
is
.codn struct ,
then
.meta sym
is tested using
.codn find-struct-type ,
and if
.meta kind
is
.codn pkg ,
then
.meta sym
is tested using
.codn find-package .

When
.code load-for
invokes the
.code load
function, it confirms whether loading file has had the expected effect of
providing a definition of
.meta sym
of the right
.metn kind .
If this isn't the case, an error is thrown.

The
.code load-for
function returns
.codn nil .

.coNP Variable @ txr-exe-path
.desc
This variable holds the absolute path name of the executable file
of the running \*(TX instance.

.SS* Function Tracing

.coNP Special variable @ *trace-output*
.desc
The
.code *trace-output*
special variable holds a stream to which all trace output
is sent. Trace output consists of diagnostics enabled by the
.code trace
macro.

.coNP Macros @ trace and @ untrace
.synb
.mets (trace << function-name *)
.mets (untrace << function-name *)
.syne
.desc
The
.code trace
and
.code untrace
macros control function tracing.

When
.code trace
is called with one or more arguments, it considers each
argument to be the name of a global function. For each
function, it turns on tracing, if it is not already turned on.
If an argument denotes a nonexistent function, or is invalid
function name syntax,
.code trace
terminates by throwing an exception, without processing the
subsequent arguments, or undoing the effects already applied
due to processing the previous arguments.

When
.code trace
is called with no arguments, it lists the names of functions
for which tracing is currently enabled. In other cases it
returns
.codn nil .

When
.code untrace
is called with one or more arguments, it considers each
argument to be the name of a global function. For each
function, it turns off tracing, if tracing is enabled.

When
.code untrace
is called with no arguments, it disables tracing for all
functions.

The
.code untrace
macro always returns
.code nil
and silently tolerates arguments which are not names of functions
currently being traced.

Tracing a function consists of printing a message prior to entry into the
function indicating its name and arguments, and another message upon leaving
the function indicating its return value, which is syntactically correlated
with the entry message, using a combination of matching and indentation.
These messages are posted to the
.code *trace-output*
stream.

When traced functions call each other or recurse, these trace messages
nest. The nesting is detected and translated into indentation levels.

Tracing works by replacing a function definition with a trace hook function, and
retaining the previous definition. The trace hook calls the previous definition
and produces the diagnostics around it. When
.code untrace
is used to disable tracing, the previous definition is restored.

Methods can be traced; their names are given using
.mono
.meti (meth < struct << slot )
.onom
syntax: see the
.code func-get-name
function.

Macros can be traced; their names are given using
.mono
.meti (macro << name )
.onom
syntax. Note that
.code trace
will not show the destructured internal macro arguments, but only the
two arguments passed to the expander function: the whole form, and the
environment.

The
.code trace
and
.code untrace
functions return
.codn nil .

.SS* Dynamic Library Access

.coNP Function @ dlopen
.synb
.mets (dlopen >> [{ lib-name | nil} <> [ flags ])
.syne
.desc
The
.code dlopen
function provides access to the POSIX C library function of the
same name.

The argument to the optional
.meta lib-name
parameter may be a character string, or
.codn nil .

If it is
.codn nil ,
then the POSIX function is called with a null pointer for
its name argument, returning the handle for the main program,
if possible.

The
.meta flags
argument should be expressed as some bitwise combination of the values
of the variables
.codn rtld-lazy ,
.codn rtld-now ,
or other
.code rtld-
variables which give names to the
.codn dlopen -related
flags.  If the
.meta flags
argument is omitted, the default value used is
.codn rtld-lazy .

If the function succeeds, it returns an object of type
.code cptr
which represents the open library handle ("dlhandle").

Otherwise it throws an exception, whose message incorporates, if possible,
error text retrieved from the
.code dlerror
POSIX function.

The
.code cptr
handle returned by
.code dlopen
will automatically be subject to
.code dlclose
when reclaimed by the garbage collector.

.coNP Function @ dlclose
.synb
.mets (dlclose << dlhandle )
.syne
.desc
The
.code dlclose
closes the library indicated by
.metn dlhandle ,
which must be a
.code cptr
object previously returned by
.codn dlopen .

The handle is closed by passing the stored pointer to the POSIX
.code dlclose
function. The internal pointer contained in the
.code cptr
object is then reset to null.

It is permissible to invoke
.code dlclose
more than once on a
.code cptr
object which was created by
.codn dlopen .
The first invocation resets the
.code cptr
object's pointer to null; the subsequent invocations
do nothing.

The
.code dlclose
function returns
.code t
if the POSIX function reports a successful result (zero), otherwise
it returns
.codn nil .
It also returns
.code nil
if invoked on a previously closed, and hence nulled-out
.code cptr
handle.

.coNP Functions @ dlsym and @ dlvsym
.synb
.mets (dlsym < dlhandle << sym-name )
.mets (dlvsym < dlhandle < sym-name << ver-name )
.syne
.desc
The
.code dlsym
function provides access to the same-named POSIX function. The
.code dlvsym
function provides access to the same-named GNU C Library function,
if available.

The
.meta dlhandle
argument must be a
.code cptr
handle previously returned by
.code dlopen
and not subsequently closed by
.code dlclose
or altered in any way.

The
.meta sym-name
and
.meta ver-name
arguments are character strings.

If these functions succeed, they return a
.code cptr
value which holds the address of the symbol which was found
in the library.

If they fail, they return a
.code cptr
object containing a null pointer.

.coNP Functions @ dlsym-checked and @ dlvsym-checked
.synb
.mets (dlsym-checked < dlhandle << sym-name )
.mets (dlvsym-checked < dlhandle < sym-name << ver-name )
.syne
.desc
The
.code dlsym-checked
and
.code dlvsym-checked
functions are alternatives to
.code dlsym
and
.codn dlvsym ,
respectively. Instead of returning a null
.code cptr
on failure, these functions throw an exception.

.coNP Variables @, rtld-lazy @, rtld-now @, rtld-global @, rtld-local @, rtld-nodelete @ rtld-noload and @ rtld-deepbind
.desc
These variables provide the same values as constants in the POSIX C library
header
.code "<dlfcn.h>"
named
.codn RTLD_LAZY ,
.codn RTLD_NOW ,
.codn RTLD_LOCAL ,
.IR "et cetera" .

.SH* FOREIGN FUNCTION INTERFACE

On platforms where it is supported, \*(TX provides a feature called the
.IR "foreign function interface" ,
or FFI. This refers to the ability to interoperate with programming
interfaces which are defined by the binary data type representations
and calling conventions of the platform's principal C language compiler.

\*(TX's FFI module provides a succinct Lisp-based type notation for expressing C
data types, together with memory-management semantics pertinent to the transfer
of data between software components. The notation is used to describe the
arguments and return values of functions in external libraries, and of Lisp
callback functions that can be called from those libraries.  Driven by the
compiled representation of the type notation, the FFI module performs
transparent conversions between Lisp data types and C data types, and
automatically manages memory around foreign calls and incoming callbacks,
for many common interfacing conventions.

The FFI module consists of a library of functions which provide all of its
semantics.  On top of these functions, the FFI module provides a number of
macros which comprise an expressive, convenient language for defining
foreign interfaces.

The FFI module supports passing and returning both structures and arrays
by value. Passing arrays by value isn't a feature of the C language syntax;
from the C point of view, these by-value array objects in the \*(TX FFI
type system are equivalent to C arrays encapsulated in
.codn struct -s.

A
.code carray
type is provided for situations when foreign code generates arrays of
undeclared, dynamic length, other than strings, and returns these arrays
by the usual convention of pointer to the first element.  The handling of
.code carray
requires more responsibility from the application.

.SS* Cautionary Notes

The FFI feature is inherently unsafe. If the FFI type language is used to write
incorrect type definitions which do not match the actual binary interface of a
foreign function, undefined behavior results. Incorrect use of FFI can corrupt
memory, creating instability and security problems. Also, incorrect use of FFI
can cause memory leaks and/or use-after-free errors due to inappropriate
deallocation of memory.

The implicit memory management behaviors encoded in the FFI type system
are convenient, but risky. A minor declarative detail such as writing
.code str
instead of
.code str-d
in the middle of some nested type can make the difference between correct code
and code which causes a memory leak, or instability by freeing memory which is
in use.

FFI developers are encouraged to unit-test their FFI definitions carefully
and use tools such as Valgrind to detect memory misuses and leaks.

.SS* Key Concepts

.NP* The \fIput\fP operation

When a function call takes place from the \*(TL arena into a foreign
library function, argument values must be prepared in the foreign
representation. This takes place by converting Lisp objects into
stack-allocated temporary buffers representing C objects. For aggregate objects
containing pointers, additional buffers are allocated dynamically. For
instance, suppose a structure contains a string and is passed by value. The
structure will be converted to a stack-allocated equivalent C structure, in
which the string will appear as a pointer.  That pointer may use dynamically
allocated (via
.codn malloc )
string data.  The operation which prepares argument material before a foreign
function call is the
.I put
operation. In FFI callback dispatch, the operation which propagates the
callback return value to the foreign caller is also the put operation.

.NP* The \fIin\fP operation

After a foreign function call returns from a foreign library back to the \*(TL
arena, the arguments have to be examined one more time, because two-way
communication is possible, and because some of the material has temporary
dynamically-allocated buffers associated with it which must be released. For
instance a structure passed by pointer may be updated by the foreign function.
FFI needs to propagate the changes which the foreign function performed to the
C version of the structure, back to the original Lisp structure. Furthermore,
a structure passed by pointer uses a dynamically allocated buffer. This buffer
must be freed.  The operation which handles the responsibility for propagating
argument data back into \*(TL objects, and frees any temporary memory that had
been arranged by the
.I put
operation is the
.I in
operation.

The in operation has two nuances: the by-value nuance and the
by-pointer nuance.
Data passed into a function by value such as function arguments or via
.code ptr-in
are subject to the by-value nuance. Updates to the foreign representation
of these objects does not propagate back to the Lisp representation to the
external representation; however, those objects may contain pointers requiring
the by-pointer nuance of the in operation of those pointers to be invoked.

.NP* The \fIget\fP operation

After a foreign call completes, it is also necessary to retrieve the call's
return value, convert it to a Lisp object, and free any dynamic memory.
This is preformed by the
.I get
operation.

The
.I get
operation is also used by a Lisp callback function, called from a foreign
library, to convert the arguments to Lisp objects.

.NP* The \fIout\fP operation

When a Lisp callback invoked by a foreign library completes, it must
provide a return value, and also update any argument objects with new
values. The return value is propagated using the put operation. Updates
to arguments are performed by the
.code out
operation. This operation is like the reverse of the in operation. Like
that operation, it has a by-value and by-pointer nuance.

For instance, if a callback receives a structure by value, upon return, there
is no use in reconstructing a new version of the structure from the updated
Lisp structure; the caller will not receive the change. However, if the
structure contains pointers to data that
was updated, by the callback, those changes must materialize. This is achieved
by triggering the by-value nuance of the structure type's out operation, which
will recursively invoke the out operation of embedded pointers, which will
in turn invoke the by-pointer nuance.

.SS* The FFI Type System

The FFI type system consists of a notation built using Lisp syntax. Basic,
unparametrized types are denoted by symbolic atoms. Similarly to a concept
in the C language,
.code typedef
names can be globally defined, using the
.code ffi-typedef
function, or the
.code typedef
macro.

Like in the C language,
.code typedef
names are aliases for an existing type, and not distinct types. However,
this is of no consequence, since the FFI doesn't perform any type checking
between two foreign types, and thus never takes into consideration whether two
such types are equal. The main concern in FFI is correspondence between Lisp
values and foreign types. For instance, a Lisp string argument will not convert
to a foreign function parameter of type
.codn int .

Compound expressions denote the construction of derived types, or types which
are instantiated with parameters. Each such expression has a type constructor
symbol in the operator position, from a limited, fixed vocabulary, which cannot
be extended.

Some constituents of compound type syntax are expressions which evaluate to
integer values: the dimension value for array types, the size for buffers,
the width for bitfields and the value expressions for enumeration constants are
such expressions. These expressions allow full use of \*(TL. They are
evaluated without visibility into any apparent surrounding lexical scope.

Some predefined types which are provided are in fact typedef names.
For instance, the
.code size-t
type is a typedef name for some other integral type, defined in a
platform-specific way. Which type that is may be determined by passing
the syntax to the type compiler function using the expression
.codn "(ffi-type-compile 'size-t)" .
The type compiler converts the
.code size-t
syntax to the compiled type object, resolving the typedef name to
the type which it denotes. The printed representation of that object
reveals the identity of the type. For instance, it might be
.codn "#<ffi-type uint>" ,
indicating that
.code size-t
is an alias for the
.code uint
basic type, which corresponds to the C type
.codn "unsigned int" .

.SS* Simple FFI Types

.coNP FFI types @, char @, zchar @ uchar and @ bchar
These first two of these types,
.code char
and
.code zchar
correspond to the C character type
.codn char .
The
.code uchar
and
.code bchar
types correspond to
.codn "unsigned char" .
Both Lisp integers and character values
convert to these representation, if they are in their numeric range.
Out-of-range values produce an exception.
A foreign
.codn char ,
.codn zchar ,
and
.code bchar
value converts to a Lisp character, whereas a
.code uchar
value converts to an integer.

If these types are used for representing individual scalar values,
there is no difference among
.codn char ,
.code zchar
and
.codn bchar .

What is different among these three types is that the
.code array
and
.code zarray
type constructors treat them specially. Arrays of these types are
subject to conversion to and from Lisp strings. The variation among
these types expresses different conversion semantics. That is to say,
an array of
.code bchar
converts between the foreign and native Lisp representation differently
from an array of
.codn zchar ,
which in turn converts differently from an array of
.codn char .

Note: it is recommended to avoid using the types
.code bchar
and
.code zchar
other than for expressing the element type of an
.code array
or
.codn zarray .

.coNP FFI types @, short @, ushort @, int @, uint @, long @ and @ ulong
These types correspond to the C integer types
.codn short ,
.codn "unsigned short" ,
.codn int ,
.codn "unsigned int" ,
.code long
and
.codn "unsigned long" .
Lisp characters and integers convert to these foreign representations, if they
are in their numeric range.  Foreign values of these types convert
to Lisp integers.

.coNP FFI types @ longlong and @ ulonglong
These types are
.code typedef
names for integer types whose representation corresponds to the C types
.code "long long"
and
.codn "unsigned long long" .

.coNP FFI types @ int8 and @ uint8
These types correspond to 8 bit signed and unsigned integers.
They convert like integer types: both Lisp integers and characters
convert to these types, if in a suitable range; and under
the reverse conversion, the foreign values become Lisp integers.

.coNP FFI types @, int16 @, uint16 @, int32 @, uint32 @ int64 and @ uint64
These types correspond denote precisely sized C integer types.
They convert like integer types: both Lisp integers and characters
convert to these types, if in a suitable range; and under
the reverse conversion, the foreign values become Lisp integers.

.coNP FFI types @ float and @ double
These types correspond to the same-named C types. They convert
Lisp integers, characters and floating-point numbers to these C types.
Because the \*(TL
.code float
is represented as a C
.code double
it converts directly to
.code double
without the possibility of range error or loss of precision.
A conversion to type
.code float
is subject to a range check; an exception is thrown if the Lisp
floating-point value is out of range of this type. Even when the
conversion is possible, it alters the value, results in a loss of precision.
In the reverse direction, values of both types convert to the one and
only \*(TL
.code float
type.

.coNP FFI type @ bool
The type
.code bool
is a typedef name for the
.code uchar
instance of the parametrized
.code bool
type, which is to say,
.codn "(bool uchar)" .

.coNP FFI type @ val
The FFI
.code val
type denotes the machine representation of a Lisp value cell, which is
corresponds to a C pointer. Not all cell values are actually pointers, but
values that are heap objects, such as vectors and conses, are.
The
.code val
type transparently converts any Lisp object to a foreign pointer value
with no representation change at all; and performs the reverse conversion
from pointer to Lisp value.

Note: this is utterly dangerous. Lisp values that aren't pointers must not
be dereferenced by foreign code. Foreign code must not generate Lisp pointer
values that aren't objects which came from a Lisp heap.
Interpreting a Lisp value in foreign code requires a correct decoding of
its type tag, and, if necessary, stripping the tag bits to recover a heap
pointer and interpreting the type code stored in the heap object.

The conversion from foreign bit pattern to Lisp value is subject to a
validity checks; an exception will be thrown if the bit pattern isn't a valid
Lisp object. Nevertheless, the checks has cases which report as false
positives: admit some invalid objects may be admitted into the Lisp realm,
possibly with catastrophic results.

.coNP FFI type @ cptr
This type corresponds to a foreign pointer of any type, including a pointer to a function.

The
.code cptr
type converts between a foreign pointer and a Lisp object of type
.codn cptr .

Lisp objects of type
.code cptr
are tagged with a symbolic tag, which may be
.codn nil .

The unparametrized
.code cptr
converts foreign pointers to
.code cptr
objects which are tagged with
.codn nil .

In the reverse direction, it converts
.code cptr
Lisp objects of type
.code cptr
to foreign pointer, without regard for their type tag.

There is a parametrized version of the
.code cptr
FFI type, which provides a measure of type safety.

Note: the
.code cptr
type, in the context of FFI, is particularly useful for representing
C pointers that are used in C library interfaces as "opaque" handles.
For instance a FFI binding for the C functions
.code fopen
and
.code fclose
may use the
.code cptr
to represent the
.code "FILE *"
type. That is to say,
.code cptr
can be specified as the return type for
.codn fopen ,
thereby capturing the stream handle in a
.code cptr
object when that function is invoked through FFI. Then, the captured
.code cptr
object can be passed as the argument of
.code fclose
to close the stream.

.coNP FFI types @, str @, bstr @ str-d and @ bstr-d
These FFI types correspond to the C pointer type
.codn "char *" ,
providing automatic conversion between Lisp strings and null-terminated
C strings. The
.code str
and
.code str-d
types use UTF-8 encoding. The
.code bstr
and
.code bstr-d
types do not use UTF-8: only Lisp strings which contain strictly
code points in the range U+0000 to U+00FF may convert to these types;
out-of-range characters trigger an error exception.
The
.code -d
suffixed types differ from the unsuffixed variants
in that they denote the transfer of ownership of dynamically allocated memory,
and thus the responsibility for freeing that memory.

The
.code str
type behaves as follows. The put operation allocates, using
.codn malloc ,
a buffer large enough to hold the UTF-8 encoded version of the Lisp
string, encodes the string into that buffer, and then stores the
.code "char *"
pointer into the argument space. The in operation deallocates the
buffer. If
.code str
is passed by pointer, the in operation also takes the current value of the
.code "char *"
pointer, which may have been replaced by a different pointer, and creates a new
Lisp string by decoding UTF-8 from that buffer. The get operation retrieves the
C pointer and duplicates a new string by decoding the UTF-8 contents. The type
has no out operation: a string is not expected to be modified in-place.

The type
.code str-d
type differs in behavior from
.code str
as follows. Firstly, it has no in operation. Consequently,
.code str-d
doesn't deallocate the buffer that had been allocated by put.
Under the get operation, the
.code str-d
type assumes that ownership over the C pointer has been granted, and
after duplicating a new string from the decoded UTF-8 data in the C string,
it deallocates that C string by invoking the C library function
.code free
on it.

The type
.code bstr-d
behaves like
.code str-d
with regard to memory management; it differs from
.code str-d
in the same way that
.code str
differs from
.codn bstr :
it doesn't perform UTF-8 encoding or decoding.

Like other types, the string types combine with the
.code ptr
type family. Because the
.code ptr
family has memory management semantics, as does the string family,
it is important to understand the memory management implications
of the combination of the two.

The types
.code "(ptr str-d)"
and
.code "(ptr str)"
are effectively equivalent. They denote a string passed by pointer,
with in-out semantics. The effect is that the string is dynamic in both
directions. What that means is that the foreign function either must not
free the pointer it was given, or else it must replace it with one which the
caller can also free (or with a null pointer). The two are equivalent
because
.code str-d
has no in operation, so its get operation is used instead; but that operation
is similar to the in operation of the
.code str
type:
both decode the string currently referenced by the
.code "char *"
pointer, and then pass that pointer to the C
.code free
function.

To receive a string pointer by pointer from a foreign
function, one of the types
.code "(ptr-out str)"
or
.code "(ptr-out str-d)"
should be used, which have different semantics. In either situation, FFI will
prepare a pointer-sized uninitialized buffer, which the called function fills
with a
.code "char *"
pointer. In the
.code str
case, FFI will duplicate that string to a Lisp string. In the
.code str-d
case, FFI will also free the string received from the foreign function.

The type combination
.code "(ptr-in str-d)"
refers to a string pointer passed to a foreign function by pointer,
whereby the foreign function will retain and free the pointer. The type
combination
.code "(ptr-in str)"
passes the string pointer in the same way, but the foreign module mustn't
use the pointer after returning. FFI will free the pointer that had been
passed.

.coNP FFI types @ wstr and @ wstr-d
The FFI type
.code wstr
corresponds to the C type
.code "wchar_t *"
pointing to the first character of a null terminated wide string.
It converts between Lisp strings and symbols, and C strings.
The memory management is similar to the
.code str
and
.code str-d
types, except that no UTF-8 conversion takes place.

.coNP FFI types @ buf and @ buf-d
The
.code buf
type creates a correspondence between the \*(TL
.code buf
type and a C pointer to a block of arbitrary data. Note that there also
exists a parametrized version of the
.code buf
and
.code buf-d
type syntax which specifies a size.

Under the
.code buf
type's put operation, no memory allocation takes place. The pointer to the
buffer object's data is is written into the argument space, so the foreign
function can manipulate the buffer directly. If the object isn't a buffer
but rather the symbol
.codn nil ,
then a null pointer is written.

The
.code buf
in operation has semantics
as follows. In the pass-by-pointer nuance, the buffer pointer currently in the
argument space is compared to the original one which had been written there
from the buffer object.  If they are identical, then the in operation
yields the original buffer object. Otherwise, if the altered
pointer is non-null,
it allocates a new buffer equal in size to the original one and copies in the
new data from the new pointer that was placed into the argument space by the
foreign function.  If the altered pointer is null, then instead of allocating a
new buffer, the object
.code nil
is returned.
The by-value nuance of the in operation does nothing.

The get operation is not meaningful for an unsized
.codn buf :
it yields a zero length
.code buf
object. For this reason, parametrized
.code buf
type should be used for retrieving a buffer with a specific fixed size.

The
.code buf-d
type has different memory management from
.codn buf .
The put operation of
.code buf-d
allocates a copy of the buffer and writes into the argument space
a pointer to the copy. It is assumed that the foreign function takes
ownership of the copy.

The in operation of
.code buf-d
is also different. The by-value nuance of the in operation
is a no-op, like that of
.codn buf .
The by-pointer nuance doesn't attempt to compare the previously written
pointer to the current value. Rather, it assumes that if there is any non-null
pointer value in the argument space, then it should take ownership of
that object and return it as a new buffer. Thus if two-way dynamic buffer
passing is requested using
.code "(buf buf-d)"
it means that the foreign function must replace the pointer with a null
to indicate that it has consumed the buffer. Any non-null value in the
argument space indicates that the foreign function has either rejected
the pointer (not taken ownership), or has replaced it with a new object,
whose ownership is being passed.

Unidirectional by-pointer passing of a
.code buf-d
can be performed using the types
.code "(ptr-out buf-d)"
or
.codn "(ptr-int buf-d)" .
The former type will not invoke
.codn buf-d 's
put operation. It will only allocate a pointer-sized space, without
initializing it. After the foreign call, the by-pointer semantics of the
in operation will be triggered If the foreign function places a non-null
pointer into the space, its ownership will be seized by a newly instantiated
buffer object. Otherwise the function must place a null pointer, which
results in a
.code nil
value emerging from the in operation as documented above. The latter type will
achieve a transfer of ownership in the other direction, by invoking the
.code buf-d
put operation, which places a copy of the buffer into the pointer-sized
location prepared in the argument space. After
the call, it will invoke the by-value in semantics of
.codn buf-d ,
which is a no-op: thus no attempt is made to extract a buffer, even if
the foreign function alters the pointer.

.coNP FFI type @ closure
The
.code closure
type converts two kinds of Lisp objects to a C pointer: the
.code cptr
type, and the special
.code ffi-closure
type, whose instances are produced by the
.code ffi-make-closure
function, or by calls to functions defined by the
.code deffi-cb
macro. The
.code closure
type is useful for passing callbacks to foreign functions: Lisp functions
which appear to be C functions to foreign code.

.coNP FFI type @ void
The
.code void
type is useful for indicating the return type of foreign functions and
callbacks which return no value. It corresponds to a zero-sized object.
It will convert any lisp value into zero bytes, and convert
zero bytes into
.codn nil .

.SS* Parametrized FFI Type Operators

The following following parametrized type operators are available.

.coNP FFI type @ enum
.synb
.mets (enum < name >> {( sym << value ) | << sym }*)
.syne
.desc
The type
.code enum
specifies an enumerated type, which establishes a correspondence between
a set of Lisp symbols and foreign integer values of type
.codn int .

The
.meta name
argument must either be
.code nil
or a symbol for which the
.code bindable
function returns true. It gives the tag name of the enumerated
type. The remaining arguments specify the enumeration constants.

In the enumeration constant syntax, each occurrence of
.meta sym
They must be a bindable symbol according to the
.code bindable
function. The symbols may not repeat within the same enumerated type.
Unlike in the C language, different enumerations may use the same symbols;
they are in separate spaces.

If a
.meta sym
is given, it is associated with an integer value which is one greater
than the integer value associated with the previous symbol.
If there is no previous symbol, then the value is zero. If the previous
symbol has been assigned the highest possible value of the FFI
.code int
type, then an error exception is thrown.

If
.meti >> ( sym << value )
is given, then
.meta sym
is given the specified value. The
.meta value
is an expression which must evaluate to an integer value in range of the FFI
.code int
type. 
It is evaluated in an environment in which the previous
symbols from the same enumeration appear as variables whose binding are the
their enumeration values, making it possible to use earlier enumerations in the
definition of later enumerations.

The FFI
.code enum
type converts two kinds of Lisp values to the foreign type
.codn int :
symbols which are in the set defined by the type, and integer values
which are in the range which that foreign type can represent.
Out-of-range integer values, symbols not defined in the enumeration, and
objects not of symbol or integer type all trigger an exception.

In the reverse direction, the
.code enum
type extracts from the foreign representation values of FFI type
.codn int ,
and converts them, if possible, to symbols. If an integer value occurs
which is not assigned to any enumeration symbol, then the conversion produces
that integer value itself rather than a symbol. If an integer value occurs
which is assigned to multiple enumeration symbols, it is not specified which
of those symbols is produced.

.coNP FFI type @ enumed
.synb
.mets (enumed < type < name >> {( sym << value ) | << sym }*)
.syne
.desc
The
.code enumed
type operator is a generalization of
.code enum
which allows the base integer type of the enumeration to be specified.
The following equivalence holds:

.verb
  (enum n a b c ...)  <-->  (enumed int n a b c ...)
.brev

Any integer type or
.meta typedef
name may be specified for
.metn type ,
including any one of the endian types. The enumeration inherits its
size, alignment and other foreign representation details from
.metn type .

The values associated with the enumeration symbols must be in
the representation range of
.metn type ,
which is not checked until the conversion of a symbol
through the enumeration is is attempted at run time.

.coNP FFI type @ struct
.synb
.mets (struct < name >> {( slot << type <> [ init-form ])}*)
.syne
.desc
The FFI
.code struct
type maps between a Lisp
.code struct
and a C
.codn struct .
The
.meta name
argument of the syntax gives the structure type name, known as the tag.
If this argument is the symbol
.meta nil
then the structure type is named by a newly generated uninterned
symbol (gensym).

The
.meta name
is entered into a global namespace of tags which is shared by structures
and unions.

The
.meta name
also specifies the Lisp
.code struct
name associated with the FFI type.

The
.meta slot
and
.code type
pairs specify the structure members. The
.meta slot
elements must be symbols, and the
.meta type
elements must be FFI type expressions.

A
.meta struct
definition with no member refers to a previously defined
.code struct
or
.code union
type which has the same
.meta name
in the global
.cod3 struct / union
tag space.

If no prior
.code struct
or
.code union
exists, then a definition with no slots specifies a new,
structure type that is incomplete.
A
.meta struct
definition with no members never causes a Lisp structure type to be created.

A
.meta struct
definition that specifies one or more members either defines a new structure
type, or completes an existing one. If an incomplete structure or union
type which has the same
.meta name
exists, then the newly appearing definition is understood to provide
a completion of that type. If the incomplete type is a
.codn union ,
it thereby converted to a
.code struct
type.

If a complete structure type which has the
same
.meta name
already exists, then the newly appearing definition replaces that type
in the tag namespace.

A struct
.code struct
definition with members is entered into the
.cod3 struct / union
tag space immediately as an incomplete type (if it isn't already), before the
members are processed. Therefore, the member definitions can refer to the
.code struct
type. The type becomes complete when the last member is processed,
except in the special situation when that member causes the type to become
a flexible structure, described several paragraphs below.

A
.meta struct
definition that specifies members causes a Lisp
.code struct
having the same
.code name
to exist, if such a type doesn't already exist. If such a type is
created, instance slots are defined for it which correspond to the
member definitions in the FFI
.code struct
definition.

For any
.meta slot
which specifies an
.meta init-form
expression, that expression is evaluated during the processing of the type syntax,
in the global environment. The resulting value then becomes the initial value for
the slot. The semantics of this value is similar to that of a quoted object
appearing as an
.meta init-form
in the
.code defstruct
macro's
.meta slot-specifier
syntax. For example, if the type expression
.codn "(struct s (a int expr))" ,
which specifies a slot
.code a
initialized by
.codn expr ,
generates a Lisp struct type, the manner in which that type is generated
will resemble that of
.code "(defstruct s nil (a (quote [value-of-expr])))"
where
.code [value-of-expr]
denotes the substitution of the value of
.code expr
which had been obtained by evaluation in the global environment.
Note: if more flexible initialization semantics is required, the application must
define the Lisp struct type first with the desired characteristics, before
processing the FFI struct type. The FFI struct type will then related to the
existing Lisp struct type.

Those members whose
.meta slot
name is specified as
.code nil
is ignored; no instance slots are created in the Lisp type.
If a
.meta init-form
is specified for such a slot, there exists is no situation in which that
form will be evaluated.

When a Lisp object is converted to a struct, it must, firstly, be of the struct
type specified by
.metn name .
Secondly, that type must have all of the slots defined in the FFI type.
The slots are pulled from the Lisp structure in the order that they appear
in the FFI
.code struct
definition. They are placed into the target memory area in that order,
with all required padding between the members, and possibly after
the last member, for alignment.

Whenever a member is defined using
.code nil
as the
.meta slot
name, that member represents anonymous padding. The corresponding
.meta type
expression is used only to determine the size of the padding only. Its data
transfer semantics is completely suppressed. When converting from Lisp, the
anonymous padding member simply generates a skip of the number of byte
corresponding to the size of its type, plus any necessary additional padding
for the alignment of the subsequent member.

Structure members may be bitfields, which are described using the
.codn ubit ,
.code sbit
and
.code bit
compound type operators.

A structure member must not be an incomplete or zero sized array,
unless it is the last member. If the last member of FFI structure is
an incomplete array, then it is a flexible structure.

A structure member must not be a flexible structure, unless it is the
last member; the containing structure is then itself a flexible structure.

Flexible structures correspond to the C concept of a "flexible array member":
the idea that the last member of a structure may be an array of unknown size,
which allows for variable-length data at the end of a structure, provided
that the memory is suitably allocated.

Flexible structures are subject to special restrictions and requirements.  See
the section Flexible Structures below. In particular, flexible structures
may not be passed or returned by value.

See also: the
.code make-zstruct
function and the
.code znew
macro.

.coNP FFI type @ union
.synb
.mets (union < name >> {( slot << type )}*)
.syne
.desc
The FFI
.code union
type resembles the
.code struct
type syntactically. It provides handling for foreign objects of C
.code union
type.

The
.meta name
argument specifies the name for the union type, known as a tag.
If this argument is the symbol
.meta nil
then the union type is named by a newly generated uninterned
symbol (gensym).

The
.meta name
is entered into a global namespace of tags which is shared by structures
and unions.

The
.meta slot
and
.code type
pairs specify the union members. The
.meta slot
elements must be symbols, and the
.meta type
elements must be FFI type expressions.

A
.meta union
definition with no member refers to a previously defined
.code struct
or
.code union
type which has the same
.meta name
in the global
.cod3 struct / union
tag space.

If no prior
.code struct
or
.code union
exists, then a definition with no slots specifies a new,
.code union
type that is incomplete.

A
.meta union
definition that specifies one or more members either defines a new structure
type, or completes an existing one. If an incomplete structure type which has
the same
.meta name
exists, then the newly appearing definition is understood to provide
a completion of that type. If the prior incomplete type is a
.codn struct ,
it is converted to
.code union
type.  If a complete structure or union type which has the
same
.meta name
already exists, then the newly appearing definition replaces that type
in the tag namespace.

A struct
.code union
definition with members is entered into the
.cod3 struct / union
tag space immediately as an incomplete type (if it isn't already), before the
members are processed. Therefore, the member definitions can refer to the
.code union
type. The type becomes complete when the last member is processed.

Unlike the FFI
.code struct
type, the
.code union
type doesn't provide automatic conversion between C and Lisp data.
This is because the
.code union
is inherently unsafe, due to its placement of multiple types into the
same storage, and lack of any information to discriminate which type
is currently stored. Instead, the FFI
.code union
creates a correspondence between a C union that is regarded as just
a region of memory, and a \*(TL data type called
.codn union .

An instance of the Lisp
.code union
type holds a copy of the C union memory, and also contains type information
about the unions members. Functions are provided to store and retrieve the
members; it is these functions which provide the conversion between the
Lisp types and the foreign representations stored in the C union.
This is done under control of the application, because due to the inherent
lack of safety of the C
.codn union ,
only the application program knows which member of the union may be accessed.

Conversion between the C
.code union
and the Lisp
.code union
consists of just a memory copying operation.

The following functions are provided for manipulating unions:
.code make-union
instantiates a new union object;
.code union-members
retrieves a list of the symbols serving as the union's member names;
.code union-get
retrieves a specified member from the union's storage, converting it
to a Lisp object;
.code union-put
places a Lisp object into a union, using the specified member's type
to convert it to a foreign representation;
.code union-in
performs the "in semantics" on the specified member of a union,
propagating modifications in that member back to a Lisp object; and
.code union-out
performs "out semantics" on the specified member of a union,
propagating modifications done on a previously retrieved Lisp object
back into the union.

.coNP FFI type @ array
.synb
.mets (array < dim << type )
.mets (array << type )
.syne
.desc
The FFI
.code array
type creates a correspondence between Lisp sequences and
"by value" fixed size arrays in C. It converts Lisp sequences to C arrays, and
C arrays to Lisp vectors.

Arrays passed by values do not exist
in the C language syntax. Rather, the C type which corresponds to the
FFI array is a C array that is encapsulated in a
.codn struct .
For instance the type
.code "(array 3 char)"
can be visualized as corresponding to the C type
.codn "struct { char anonymous[3]; }" .

Thus, in the FFI syntax, we can specify arrays as function parameters
passed by value and as return values.

On conversion from Lisp to the foreign type, the FFI
.code array
simply iterates over the Lisp sequence, and performs an element for
element conversion to
.metn type .

If the sequence is shorter than the array, then the remaining elements
are filled with zero bits. If the sequence is longer than the array, then the
excess elements in the sequence are ignored.

Since Lisp arrays and C arrays do not share the same representation,
temporary buffers are automatically created and destroyed by FFI
to manage the conversion.

The
.meta dim
argument is an ordinary Lisp expression expanded and evaluated in the
top-level environment. It must produce a non-negative integer value.

In addition, several types are treated specially: when
.meta type
is one of
.codn char ,
.codn zchar ,
.code bchar
or
.codn wchar ,
the array type establishes a special correspondence with Lisp strings.
When the C array is decoded, a Lisp string is created or updated in place
to reflect the new contents. This is described in detail below.

The second form, whose syntax omits the
.meta dim
element, it denotes a variable length
array. It corresponds to the concept of an incomplete array
in the C language, except that no implicit array-to-pointer conversion
concept is implemented in the FFI type system. This type may not
be used as an array element or structure member. It also may not
be passed or returned by value, only by pointer.

Since the type has unknown length, it has a trivial get operation which returns
.codn nil .
It is useful for passing a variable amount of data into a foreign
function by pointer.

An array of
.code char
represents non-null-terminated UTF-8 character data, which converts to
and from a Lisp string. Any null bytes in the data correspond to
the pseudo-null character
.code #\exDC00
also notated as
.codn #\epnul .

An array of
.code zchar
represents a field of optionally null-terminated UTF-8 character data.
If a null byte occurs in the data then the text terminates before that
null byte, otherwise the data comprises the entire foreign array.
Thus, null bytes do not occur in the data. A null byte in the array will
not generate a pseudo-null character in the Lisp string.

An array of
.code bchar
values represents 8-bit character data that isn't UTF-8 encoded,
and is not null terminated. Each byte holds a character whose code is
in the range 0 to 255. If a null byte occurs in the data, is interpreted
as a string terminator.

.coNP FFI type @ zarray
.synb
.mets (zarray < dim << type )
.mets (zarray << type )
.syne
.desc
The
.code zarray
type is a variant of
.codn array .
When converting from Lisp to C, it ensures that the array is null-terminated.
This means that if the
.meta zarray
is dimensioned, then the
.mono
.meti >> [ dim - 1]
.onom
element of the C array is written out as all zero bytes,
ignoring the corresponding Lisp value in the Lisp array.
If the
.meta zarray
is undimensioned, then the size of the C array is deemed to be one greater
than the actual length of the Lisp array.  The elements in the Lisp array are
converted to the corresponding elements of the C array, and then the
last element of the C array is filled with null bytes.
The
.code zarray
type is useful for handling null terminated character arrays representing
strings, and for null terminated vectors.
Unlike
.codn array ,
.code zarray
allows the Lisp object to be one element short. For instance,
when a
.code "(zarray 5 int)"
passed by pointer a foreign function is converted back to Lisp,
the Lisp object is required to have only four elements. If the Lisp object
has five elements, then the fifth one will be decoded from the C array
in earnest; it is not expected to be null. However, when that Lisp
representation is converted back to C, that extra element will be ignored and
output as a zero bytes.

Lastly, the
.code zarray
further extends the special treatment which the
.code array
type applies to the types
.codn zchar ,
.codn char ,
.code wchar
and
.codn bchar .
The
.code zarray
type assumes, and depends on the incoming data being null-terminated, and
converts it to a Lisp string accordingly. The regular
.code array
type doesn't assume null termination. In particular, this means that whereas
.code "(array 42 char)"
will decode 42 bytes of UTF-8, even if some of them are null, converting
those null bytes the U+DC00 pseudo-null, in contrast, a
.code zarray
will treat the 42 bytes as a null-terminated string, and decode UTF-8 only
up to the first null.
In the other direction, when converting from Lisp string to the foreign array,
.code zarray
ensures null termination.

Note that the type combination
.code zarray
of
.code zchar
behaves in a manner indistinguishable from a
.code zarray
of
.codn char .

The one-argument variant of the
.code zarray
syntax which omits the
.meta dim
argument specifies a null-terminated variant of the variable-length array.
Like that type, it corresponds to the concept of an incomplete
array in the C language. It may not be used as an array element
or structure member, and cannot be passed as an argument or returned
as a value.

Unlike the ordinary variable-length
.codn array ,
the
.code zarray
type supports the get operation, which extracts elements, accumulating them
into a resulting vector, until it encounters an element consisting of all zero
bytes. That element terminates the decoding, and isn't included in the
resulting array.

The variable-length
.code zarray
also has a special in operation. Like the get operation, the in operation
extracts all elements until a terminating null, decoding them to a vector.
Then, the entire original vector is replaced with the new vector,
even if the original vector is longer.

.coNP FFI type @ ptr
.synb
.mets (ptr << type )
.syne
.desc
The
.meta ptr
denotes the passage of a value by pointer. The
.meta type
argument gives the pointer's target type. The
.code ptr
type converts a single Lisp value, to and from the target type,
using a C pointer as the external representation.

When used for passing a value to a foreign function, the
.code ptr
type has in-out semantics: it supports the interfacing concept that
the called function can update datum which has been passed to it "by pointer",
thereby altering the caller's object. Since a Lisp value requires a conversion
to the FFI external representation, it cannot be directly passed by pointer.
Instead, this semantics is simulated. The put semantics of
.code ptr
allocates a temporary buffer, large enough to hold the representation of
.metn type .
The Lisp value is then encoded into this buffer, recursively relying on
the type's put semantics. After the foreign call,
.code ptr
triggers the in semantics of
.meta type
to update the Lisp object from the temporary buffer, and releases the
buffer.

The get semantics of
.code ptr
is used in retrieving a
.code ptr
return value, or, in a FFI callback, for retrieving the values of
incoming arguments that are of
.code ptr
type. The get semantics assumes that the memory referenced by the C
pointer is owned by foreign code. The Lisp object is merely decoded from the
data area, which is then not touched.

The
.code out
semantics of
.codn ptr ,
used by callbacks for updating the values of arguments
passed by pointer, assumes that the argument space already contains a
valid pointer. The pointer is retrieved from the argument space, and the
Lisp value is encoded into the memory referenced by that pointer.

Note that only Lisp objects with mutable slots can be meaningfully passed by
pointer with in-out semantics. If a Lisp objects without immutable slots, such
as an integer, is passed using
.code ptr
the incoming updated value of the external representation will be ignored.
Concretely, if a C function has the argument signature
.code "(int *)"
with in-out semantics such that it updates the
.code int
object which is passed in, this function can be called as a foreign function
using a
.code "(ptr int)"
FFI type for the argument. However, the argument of the foreign call on the
\*(TL side is just an integer value, and that cannot be updated.

On the other hand, if a FFI
.code struct
member is declared as of type
.code "(ptr int)"
then the Lisp
.code struct
is expected to have an integer-valued slot corresponding to that member.
The slot is then subject to a bi-directional transfer. FFI will create an
.codn int -sized
temporary data area, encode the slot into that area and place that area's
pointer into the encoded structure.  After the call, the new value of the
.code int
will be extracted from the temporary buffer, which will then be released.
The Lisp structure's slot will be updated with the new integer.
This will happen even if the Lisp structure is being passed as a by-value
argument.

.coNP FFI type @ ptr-in
.synb
.mets (ptr-in << type )
.syne
.desc
.code ptr-in
type is a variation of
.code ptr
which denotes the passing of a value by pointer into a function, but
not out. The put semantics of
.code ptr-in
is the same as that of
.codn ptr ,
but after the completion of the foreign function call, the in semantics
differs. The
.code ptr-in
type only frees the temporary buffer, without decoding from it.

The out semantics of
.code ptr-in
differs also. It effectively treats the object as if it were "by value",
since the reverse data transfer is ruled out. In other words,
.code ptr-in
simply triggers the by-value nuance of
.metn type 's
out semantics.

The get semantics of
.code ptr-in
is the same as that of
.codn ptr .

.coNP FFI type @ ptr-out
.synb
.mets (ptr-out << type )
.syne
.desc
The
.code ptr-out
type is a variant of
.code ptr
which denotes a by pointer data transfer out of a function only, not into.
The put semantics of
.code ptr-out
prepares a data area large enough to hold
.meta type
and stores a pointer to that area into the argument space.
The Lisp value isn't encoded into the data area.

The in semantics is the same as that of
.codn ptr :
the by-pointer nuance of
.metn type 's
in semantics is invoked to decode the external representation to
Lisp data.

.coNP FFI type @ ptr-in-d
.synb
.mets (ptr-in-d << type )
.syne
.desc
The
.code ptr-in-d
type is a variant of
.code ptr-in
which transfers ownership of the allocated buffer to the invoked
function. That is to say, the in semantics of
.code ptr-in-d
doesn't involve the freeing of memory that was allocated by put
semantics.

The
.code ptr-in-d
type is useful when a function expects a pointer to an object that
was allocated by
.code malloc
and expects to take responsibility for freeing that object.

Since the function may free the object even before returning,
the pointer must not be used once the function is called. This is
ensured by the in semantics of
.code ptr-in-d
which is the same as that of
.codn ptr-in .

The
.code ptr-in-d
type also has get semantics which assumes that ownership of the
C object is to be seized. FFI will automatically free the C object
when get semantics is invoked to retrieve a value through a
.codn ptr-in-d .

.coNP FFI type @ ptr-out-d
.synb
.mets (ptr-out-d << type )
.syne
.desc
The
.code ptr-out-d
type is a variant of
.code ptr-out
which is useful for capturing return values or, in a callback
producing return values.

The
.code ptr-out-d
type has empty put semantics. If it put semantics is invoked, it does
nothing: no area is allocated for
.meta type
and no pointer is stored into the argument space.

The in semantics is the same as that of
.codn ptr :
a pointer is retrieved from the argument space, the object is subject to
.metn type 's
in semantics to recover the updated Lisp value, and then the object
is freed.

The get semantics of
.code ptr-out-d
is identical to that of
.codn ptr-in-d .

The out semantics is identical to that of
.codn ptr .

.coNP FFI type @ ptr-out-s
.synb
.mets (ptr-out-s << type )
.syne
.desc
The
.code ptr-out-d
type is a variant of
.code ptr-out
similar to
.codn ptr-out-d ,
which assumes that the C object being received has an indefinite
lifetime, and doesn't need to be freed. The suffix stands for "static".

Like
.codn ptr-out-d ,
the
.code ptr-out-s
has no put semantics.

Its in semantics recovers a Lisp value from the external object whose pointer
has been stored by the foreign function, but doesn't free the external
object.

The get semantics retrieves a Lisp value without freeing.

.coNP FFI type @ bool
.synb
.mets (bool << type )
.syne
.desc
The parametrized type
.code bool
can be derived from any integer or floating-point type. There is also an
unparametrized
.code bool
which is a
.code typedef
for the type
.codn "(bool uchar)" .

The
.code bool
type family represents Boolean values, converting between a Lisp Boolean
and foreign Boolean. A given instance of the
.code bool
type inherits all of its characteristics from
.metn type ,
such as its size, alignment and foreign representation. It alters the
get and put semantics, however. The get semantics converts a foreign zero
value of
.meta type
to the Lisp symbol
.codn nil ,
and all other values to the symbol
.codn t .
The put semantics converts the Lisp symbol
.code nil
to a foreign value of zero. Any other Lisp object converts to the foreign
value one.

The
.code bool
types are not integers, and cannot be used as the basis of bitfields:
syntax like
.code "(bit 3 (bool uint))"
is not permitted. However, Boolean bitfields are possible when this
syntax is turned inside out: the
.code bool
type can be derived from a bitfield type, as exemplified by
.codn "(bool (bit 3 uint))" .
This simply applies the above described Boolean conversion semantics to a
three-bit field.  A zero/nonzero value of the field converts to
.cod3 nil / t
and a
.code nil
or
.cod2 non- nil
Lisp value converts to a 0 or 1 field value.

.coNP FFI types @ ubit and @ sbit
.synb
.mets ({ubit | sbit} << width )
.syne
.desc
The
.code ubit
and
.code sbit
types denote C language style bitfields. These types can only appear
as members of structures. A bitfield type cannot be the argument or return
value of a foreign function or closure, and cannot be a foreign variable.
Arrays of bitfields and pointers, of any kind, to bitfields are a forbidden
type combination that is rejected by the type system.

The
.code ubit
type denotes a bitfield of type
.codn uint ,
corresponding to an
.code unsigned
bitfield in the C language.

The
.code sbit
type denotes a bitfield of type
.codn int .
Unlike in the C language, it is not implementation-defined whether such
a bitfield represents signed values; it converts between Lisp integers
that may be positive or negative, and a foreign representation which is
two's complement.

Bitfields based on some other types are supported using the more general
.code bit
operator, which is described below.

The
.meta width
parameter of is an expression evaluated in the top-level environment,
indicates the number of bits. It may range from
zero to the number of bits in the
.code uint
type.

In a structure, bitfields produced by
.code sbit
and
.code ubit
are allocated out in storage units which have the
same width and alignment requirements as a
.codn uint .
These storage units themselves can be regarded as anonymous members of the
structure.  When a new unit needs to be allocated in a structure to hold
bitfields, it is allocated in the same manner as a named member of type
.code uint
would be at the same position.

A zero-length bitfield is permitted. It may be given a name, but the field
will not perform any conversions to and from the corresponding slot in the
Lisp structure.  Note that in situations when the FFI struct definition 
causes the corresponding Lisp structure type to come into existence, the
Lisp structure type will have slots for all the zero width named bitfields,
even though those slots don't participate in any conversions in conjunction
with the FFI type.

The presence of a zero-length bitfield ensures that a subsequent
structure member, whether bitfield or not, is placed in a new storage
unit of the size of the bitfield's base type.

Details about the algorithm by which bitfields are allocated within a structure
are given in the paragraph below entitled
.BR "Bitfield Allocation Rules" .

A
.code ubit
field stores values which follow a pure binary enumeration. For instance,
a bit field of width 4 stores values from 0 to 15. On conversion from
the Lisp structure to the foreign structure, the corresponding member
must be a integer value in this range, or an error exception is thrown.

On conversion from the foreign representation to Lisp, the integer
corresponding to the bit pattern is recovered. Bitfields follow the
bit order of the underlying storage word. That is to say, the most
significant binary digit of the bitfield is the one which is closest
to the the most significant bit of the underlying storage unit.
If a four-bit field is placed into an empty storage unit and the value
8 its stored, then on a big-endian machine, this has the effect of
setting to 1 the most significant bit of the underlying storage word.
On a little-endian machine, it has the effect of setting bit 3 of
the word (where bit 0 is the least significant bit).

The
.code sbit
field creates a correspondence between a range of Lisp integers,
and a foreign representation based on the two's complement system.
The most significant bit of the bit field functions as a sign bit.
Values whose most significant bit is clear are positive, and use
a pure binary representation just like their
.code ubit
counterparts. The representation of negative values is defined
by the "two's complement" operation, which maps each value to
its additive inverse. The operation consists of temporarily treating the
entire bitfield as unsigned, and inverting the logical value of all the
bits, and then adding 1 with "wrap-around" to zero if 1 is added to a field
consisting of all 1 bits. (Thus zero maps to zero, as expected).
An anomaly in the two's complement system is that the most negative
value has no positive counterpart. The two's complement operation
on the most negative value produces that same value itself.

A
.code sbit
field of width 1
can only store two values: -1 and 0, represented by the bit patterns
1 and 0. An attempt to convert any other integer value to a
.code sbit
field of width 1 results in an error.

A
.code sbit
field of width 2 can represent the values -2, -1, 0 and 1, which are
stored as the bit patterns 10, 11, 00 and 01, respectively.

.coNP FFI type @ bit
.synb
.mets (bit < width << type )
.syne
.desc
The
.code bit
operator is more general than
.code ubit
and
.codn sbit .
It allows for bitfields based on integer units smaller than or equal to 
.codn uint .

The
.meta type
argument may be any of the types
.codn char ,
.codn short ,
.codn int ,
.codn uchar ,
.codn ushort ,
.codn uint ,
.codn int8 ,
.codn int16 ,
.codn int32 ,
.codn uint8 ,
.code uint16
and 
.codn uint32 .

When the character types
.code char
and
.code uchar
are used as the basis of bitfields, they convert integer values, not
characters.
In the case of
.codn char ,
the bitfield is signed. 

All remarks about
.code ubit
and
.code sbit
apply to
.code bit
also.

Details about the algorithm by which bitfields are allocated within a structure
are given in the paragraph below entitled
.BR "Bitfield Allocation Rules" .

.coNP FFI types @ buf and @ buf-d
.synb
.mets ({buf | buf-d} << size )
.syne
.desc
The parametrized
.code buf
and
.code buf-d
types are variants of the unparametrized
.code buf
and
.codn buf-d ,
respectively. The
.meta size
argument is an expression which is evaluated in the top-level
environment, and must produce a non-negative integer.

Because they have a size, these types have useful get
semantics.

The get semantics of
.code buf-d
is that a Lisp object of type
.code buf
is created which takes direct ownership of the memory.

The get semantics of
.code buf
is that a Lisp object is created using a dynamically allocated copy
of the memory.

.coNP FFI type @ carray
.synb
.mets (carray << type )
.syne
.desc
The
.code carray
type corresponds to a C pointer, in connection with the concept
of representing a variable length array that is passed and returned
as a pointer to the base element. On the Lisp side, the
.code carray
FFI type corresponds to the
.code carray
Lisp type. The
.code carray
Lisp type is similar to
.codn cptr ,
but supports array indexing operations, and some other features.
It can be regarded as a semantic cross between
.code cptr
and
.codn buf .

The get semantics of
.code carray
is simply that a pointer is retrieved from memory and converted to
a freshly allocated
.code carray
object which holds that pointer, and is marked as having an unknown
size. No copy is made of the underlying array.  When the application
determines the size of the array, it can inform that object by means
of calling the
.code carray-set-length
function.

The put semantics of the
.code carray
FFI type is simply to write, into the argument space, the pointer which the
object holds.  The object must be a
.code carray
whose element type matches that of the FFI type.

The
.code carray
type lacks in or out semantics, since FFI doesn't manage any foreign
memory for the passage of a
.code carray
and any two-directional communication of data through the array
handled by performing direct operations on the
.code carray
Lisp object in application code.

The
.code carray
type is particularly useful in situations when
foreign code generates such an array, and the size of that array
isn't known from the object itself.

It is also useful, instead of a variable-length
.code zarray
for passing a dynamic array to foreign code in situations when the application benefits
from managing the memory for the array. The variable-length
.code zarray
FFI type's disadvantage relative to
.code carray
is that the
.code zarray
converts an entire Lisp sequence to a temporarily allocated
array, which is used only for one call. By contrast, the
.code carray
object holds the C representation which Lisp code can manipulate;
and that representation is passed directly, just like in the case of
.codn buf .

Unlike
.codn buf ,
there is no dynamic variant of
.codn carray .
The transfer of ownership of a
.code carray
requires the use of explicit operations like
.code carray-free
and
.codn carray-own .

It is possible to create a
.code carray
view over a buffer, using
.codn carray-buf .

.coNP FFI type @ cptr
.synb
.mets (cptr << type-sym )
.syne
.desc
The parametrized
.code cptr
type is similar to the unparametrized
.codn cptr .
It also converts between Lisp objects of type
.code cptr
and foreign pointers. However, it provides a measure of type safety.

When a foreign pointer is converted to a Lisp object under control of the
parametrized
.codn cptr ,
the resulting Lisp
.code cptr
object is tagged with the
.meta type-sym
symbol.

In the reverse direction, when a Lisp
.code cptr
object is converted to the parametrized type, its type tag must match
.metn type-sym ,
or else the conversion fails with an error exception.
This rule contains a slight relaxation: a
.code cptr
object with a
.code nil
tag can be converted to a foreign representation using any parametrized type,
if its value is null. In other situations, the
.code cptr-cast
function must be used to coerce the pointer object to the matching type.

Note that if
.meta type-sym
is specified as
.codn nil ,
then this is precisely equivalent to the unparametrized
.code cptr
which doesn't provides the above safety measure.

Pointer type safety is useful, because FFI can be used to create bindings
to large application programming interfaces (APIs) in which objects of
many different kinds are referenced using pointer handles. The erroneous
situation can occur that a FFI call passes a handle of one kind to a function
expecting a different kind of handle. If all pointer handles are represented
by a single
.code cptr
type, then such a situation proceeds without diagnosis.
If handles of different types are all mapped to
.code cptr
types with different tags, the situation is intercepted and diagnosed
with an error exception.

.coNP FFI type @ align
.synb
.mets (align < width << type )
.syne
.desc
The FFI type operator
.code align
defines a type which is a copy of
.metn type ,
but with the alignment requirement replaced by the
.metn width .

The
.meta width
argument is an expression which is evaluated in the top-level
environment. It must produce a positive integer which is a power of two.

The
.code align
operator can be used to create a version of
.meta type
with stricter or weaker alignment. Alignment affects the placement of
the type as a structure member, and as an array element.

A type with alignment 1 can be placed at any byte offset. A type with
alignment 2 can be placed only at even addresses and offsets.

Alignment can be applied to all types, including arrays and structs.
It may also be applied to bitfields, but special considerations have
to be observed to obtain the intended effect, described below.
However,
out of the elementary types, only the integer and floating point types are
required to support a weakening of alignment. Whether a type which corresponds
to a pointer, such as a
.code str
or
.codn buf ,
can be written at an offset which doesn't meet that type's default alignment
is machine-dependent.

If a FFI struct type is declared with a weakened alignment, whether or not such
a structure can be read or written at the misaligned offsets depends on whether
the individual members support it. If they are integer or floating-point types,
or aggregates thereof, the usage is supported in a machine-independent manner.

A struct type declared to have a weaker alignment, such as 1, does not
lose any of the padding at its end. That is to say, alignment has no effect
on structure size. It affects the offset at which a structure is placed as
a member of an array or another structure, with its padding intact. To
eliminate the padding at the end of a structure, it is necessary to use
.code align
to manipulate the alignment of individual members.

When
.code align
is applied to the type of a bitfield member of a structure, it has no effect on
placement. The alignment of a non-zero bitfield which begins a new
storage unit is taken into consideration for the purpose of determining
the most strictly alignment member of the structure.  The alignment of all
other bitfields is ignored.
.PP

.SS* Additional Types
.coNP FFI types @, size-t @, ptrdiff-t @, int-ptr-t @, uint-ptr-t @, wint-t @, sig-atomic-t @ time-t and @ clock-t .
These additional FFI types for common C language types are provided as
.code typedef
aliases.

.coNP FFI type @ qref
.synb
.mets (qref < struct-type < member1 >> [ member2 ...])
.syne
.desc
The FFI type operator
.code qref
provides a way to reference the type of a member of a struct or union.
The
.meta struct-type
argument must be a type expression denoting a struct or union.
The
.meta member1
argument and any additional arguments must be symbols.

If
.code S
is a struct or union type, and
.code M
is a member, then
.code "(qref S M)"
is a type expression denoting the type of
.codn M .
Moreover, if
.code M
itself is a struct or union, which has a member named
.code N
then the type of
.code N
can be denoted by the expression
.codn "(qref S M N)" .
Similarly, additional symbols reference through additional struct/union
nestings.

Note: the referencing dot syntax can be used to write
.code qref
expressions.
For instance,
.code "(qref S M N)"
can be written as
.code S.M.N
instead.

.coNP FFI type @ elemtype
.synb
.mets (elemtype << type )
.syne
.desc
The FFI type operator
.code elemtype
denotes the element type of
.metn type ,
which must be a pointer, array or enum.

Note: there is also a macro
.codn elemtype .
The macro expression
.code "(elemtype X)"
is equivalent to the expression
.codn "(ffi (elemtype X))" .

.coNP FFI types @, blkcnt-t @, blksize-t @, clockid-t @, dev-t @, fsblkcnt-t @, fsfilcnt-t @, gid-t @, id-t @, ino-t @, key-t @, loff-t @, mode-t @, nlink-t @, off-t @, pid-t @ ssize-t and @ uid-t
The additional names of various common POSIX types may also be available,
depending on platform. They are provided as
.code typedef
aliases.

.SS* Endian Types
In addition to the type system described in the previous section.
the FFI type system supports
.IR "endian types" ,
which are useful for dealing with
data formats defined by networking protocols and other kinds of standards,
or data structure definitions from other machines. 

There are two kinds of
.IR endianness :
.I "Little endian"
refers to the least-significant byte of a data type being
stored at the lowest address in memory, lowest offset in a buffer, lowest
offset in a file, or earlier byte in a communication stream.
.I "Big endian"
is the opposite: it refers to the most significant byte occurring
at the lowest address, offset or stream position.
For each of the signed integral types

.code int16
through
.codn int64 ,
the corresponding unsigned types
.code uint16
through
.codn uint64 ,
and the two floating-point types
.code float
and
.codn double ,
the FFI type system provides a big-endian and little endian version,
whose names are derived by prefixing the
.code be-
or
.code le-
prefix to its related type.

Thus, the exhaustive list of the endian types is:
.codn be-int16 ,
.codn be-uint16 ,
.codn be-int32 ,
.codn be-uint32 ,
.codn be-int64 ,
.codn be-uint64 ,
.codn be-float ,
.codn be-double ,
.codn le-int16 ,
.codn le-uint16 ,
.codn le-int32 ,
.codn le-uint32 ,
.codn le-int64 ,
.codn le-uint64 ,
.code le-float
and
.codn le-double .

These types have the same size and alignment as their plain, unprefixed
counterparts. Alignment can be overridden with the
.code align
type construction operator to create versions of these types with alternative
alignment.

Endian types are supported as arguments to functions, return values,
members of structs and elements of arrays.

\*(TL's FFI performs the automatic conversion from the abstract Lisp integer
representation to the foreign representations exhibiting the specified
endianness.

.SS* Incomplete Types

In the \*(TL FFI type system, the following types are
.IR incomplete :
the type
.codn void ,
arrays of unspecified size, and any
.code struct
whose last element is of incomplete type.

An incomplete type cannot used as a function parameter type, or a return
value type. It may not be used as an array element or union member type.
A struct member type may be incomplete only if it is the last member.

An incomplete structure whose last member is an array is a
.IR "flexible structure" .

.SS* Flexible Structures

If a FFI
.code struct
type is defined with an incomplete array (an array of unspecified size) as its
last member, then it specifies an incomplete type known as a
.IR "flexible structure" .
That array is the
.IR "terminating array" .
The terminating array corresponds to a slot in the Lisp structure; that
slot is the
.IR "last slot" .

A structure which has a flexible structure as its last member is also,
effectively, a flexible structure.

When a Lisp structure is being converted to the foreign representation
under the control of a flexible structure FFI type, the number of elements
in the terminating array is determined from the length of the object
stored in the last slot of the Lisp structure. The length includes the
terminating null element for
.code zarray
types. The conversion is consistent with the semantics of an incomplete
arrays that is not a structure member.

In the reverse direction, when a foreign representation is being converted
to a Lisp structure under the control of a flexible structure FFI type,
the size of the array that is accessed and extracted is determined from
the length of the object stored in the last slot, or, if the array type
is a
.code zarray
from detecting null-termination of the foreign array. The conversion of
the array itself is consistent with the semantics of an incomplete
arrays that is not a structure member.
Before the conversion takes place, all of the members of the
structure prior to the the terminating array, are extracted and converted to
Lisp representations.  The corresponding slots of the Lisp structure are
updated. Then if the Lisp structure type has a
.code length
method, that method is invoked. The return value of the method is used
to perform an adjustment on the object in the last slot.
If the existing object in the last slot is a vector, its length is adjusted to
the value returned by the method. If the existing
object isn't a vector, then it is replaced by a new
.codn nil -filled
vector, whose length is given by the return value of
.codn length .
The conversion of the terminating array to Lisp representation the proceeds
after this adjustment, using the adjusted last slot object.

.SS* Bitfield Allocation Rules
The \*(TL FFI type system follows rules for bitfield allocation which were
experimentally derived from the behavior of the GNU C compiler on several
mainstream architectures.

The allocation algorithm can be imagined to walk through the structure
from the first member to the last, maintaining a byte offset
.I O
which indicates how many whole bytes have been allocated to members so far,
and a bit offset
.I B
which indicates, additionally, how many bits have been allocated in the
byte which follows these
.I O
bytes, between 0 and 7.

When a non-bitfield member is placed, then there are two cases: either
.I B
is zero (only
.I O
bytes have been allocated, with no fractional byte) or else
.I B
is nonzero. In this latter case,
.I B
is reset to zero and
.I O
is incremented by one. In either case,
.I O
is adjusted up to the required alignment boundary for the new member.
The member is placed, and
.I O
is incremented again by the size of that member.

When a bitfield member is placed, the algorithm considers the structure
to be allocated in units of the base type of that bitfield member.
For instance if the bitfield is derived from type
.code uint16
then the structure's layout is considered to have been allocated in
.code uint16
units. The algorithm examines the value of
.I O
and
.I B
to determine the first available unit in which at least
one bit of unallocated space remains.
Then, if the unit at that offset has enough space to hold the new
bitfield, according to the bitfield's width, then the bitfield is
placed into that unit. Otherwise, the bitfield is placed into the
next available unit.

After a bitfield is placed, the values of
.I O
and
.I B
are adjusted so that
.I O
reflects the whole number of bytes which have been allocated to the
structure so far, and
.I B
indicates the 0 to 7 additional bits of any bitfield material protruding
past those whole bytes.

A zero-width bitfield is also considered with regard to the storage
unit size indicated by its type. As in the case of the nonzero-width
bitfield, the offset of the first available unit is found which
has at least one bit of unallocated space. Then, if that unit is
entirely empty, the zero-width bitfield has no effect. If that unit is
partially filled, then
.I O
is adjusted to point to the next unit after that, and
.I B
is reset to zero. Note that according to this semantics, a zero-width bitfield
can have an effect even if placed between non-bitfield members, or appears
as the last member of a structure.  Also, a structure containing only a
zero-width bitfield has size zero.

If, after the placement of all structure members,
.I B
has a nonzero value, then the offset
.I O
is incremented by one to cover that byte.

As the last allocation step, the size of the structure is then padded up to a
size which is a multiple of the alignment of the most strictly aligned member.

A named bitfield contributes to the alignment of the structure, according to
its type, the same way as a non-bitfield member of the same type.
An unnamed bitfield doesn't contribute alignment, or else may be regarded as
having the weakest possible alignment, which is byte alignment.
If all of the members of a structure are unnamed bitfield members of any type,
it exhibits byte alignment.

The description isn't complete without a treatment of byte and bit order.
Bitfield allocation follows an imaginary "bit endianness" whose direction
follows the machine's byte order: most significant bits are allocated first on
big endian, least significant bits first on little-endian.

If a one-bit-wide bitfield is allocated into a hitherto empty structure, it
will be placed into the first byte of that structure, regardless of the
machine's endianness, and regardless of the underlying storage unit size for
that bitfield. Within that first byte, it will be placed into the most
significant bit position on a big-endian machine (bit 7); and on a
little-endian machine, it will be placed into the least significant bit
position (bit 0). If another one-bit-wide is allocated, it is placed into
bit 6 on big-endian, and bit 1 on little-endian.

More generally, whenever a bitfield is allocated for a big-endian machine, and
the storage unit is determined into which that bitfield shall be placed, the
most significant bits of that storage unit are filled first on a big-endian
machine, whereas the least significant bits are filled first on a little-endian
machine.  From this it follows that on either type of machine, that field shall
be placed at the lowest-addressed byte or bytes in which unallocated bits
remain.

.SS* FFI Call Descriptors

The FFI mechanism makes use of a type-like representation called the "call
descriptor". A call descriptor is an object which uses FFI types to describe
function arguments and return values. A FFI descriptor is required to call
a foreign function, and to create a FFI closure to use as a callback
function from a foreign function back into \*(TL.

A FFI descriptor object can be constructed from a return value type, and a list
of argument types, and several other pieces of information using the
function
.codn ffi-make-call-desc .

This object can then be passed to
.code ffi-call
to specify the C type signature of a foreign function, or to
.code ffi-make-closure
to specify the C type signature of a FFI closure to bind to a Lisp function.

The FFI macros
.code deffi
and
.code deffi-cb
provide a simplified syntax for expressing FFI call descriptors,
which includes a notation for expressing variadic calls.

A note about variadic foreign functions: although there is support
in the call descriptor mechanism for expressing a variadic function,
it expresses a particular
.B instance
of a variadic function, rather than the variadic function's type
.IR "per se" .
To call the same variadic function using different variadic arguments,
different call descriptors are required. For instance to perform
the equivalent of the C function call
.mono
printf("hello\en")
.onom
requires a certain descriptor. To perform the equivalent of
.mono
printf("hello, %s\en", name)
.onom
requires a different descriptor.

.SS* Foreign Function Type API

This group of functions comprises the basic interface to the \*(TL's FFI
type system module.

.coNP Function @ ffi-type-compile
.synb
.mets (ffi-type-compile << syntax )
.syne
.desc
The
.code ffi-type-compile
function produces and returns a compiled type object from a
.meta syntax
argument which specifies valid FFI syntax.
If the type syntax is invalid, or specifies a nonexistent
type specifier or operator, an exception is thrown.

Note: whenever a function argument is required to be of FFI type,
what it means is that it must be a compiled object, and not
a Lisp expression denoting FFI syntax.

.TP* Examples:

.verb
  (ffi-type-compile 'int) -> #<ffi-type int>
  (ffi-type-compile
    '(array 3 double)) -> #<ffi-type (array 3 double)>
  (ffi-type-compile 'blarg) -> ;; error
.brev

.coNP Function @ ffi-make-call-desc
.synb
.mets (ffi-make-call-desc < ntotal < nfixed < rettype << argtypes )
.syne
.desc
The
.code ffi-make-call-desc
function constructs a FFI call descriptor.

The
.meta ntotal
argument must be a non-negative integer; it indicates the number
of arguments in the call.

If the call denotes a variadic function, the
.meta nfixed
argument must be an integer between 1 and
.metn ntotal ,
denoting the number of fixed arguments.
If the call denotes an ordinary, non-variadic function, then
.meta nfixed
must be specified as
.codn nil .

The
.meta rettype
parameter must be an FFI type. It specifies the function
return type. Functions which don't return a value are specified
by the (compiled version of) the return type
.codn void .

The
.meta argtypes
argument must be a list of types, containing at least
.meta ntotal
elements. If the function takes no arguments, this list is empty.
If the function is variadic, then the first
.meta nfixed
elements of this list specify the types of the fixed arguments;
the remaining elements specify the variadic arguments.

Note: variadic functions must not be called using a non-variadic
descriptor, and
.IR "vice versa" ,
even if the return types and
argument types match.

.TP* Example:

.verb
  ;;
  ;; describe a call to the variadic function
  ;;
  ;;   type void (*)(char *, ...)
  ;;
  ;; with these actual arguments
  ;;
  ;;   (char *, int)
  ;;
  (ffi-make-call-desc
    2 ;; two arguments
    1 ;; one fixed
   (ffi-type-compile 'void)        ;; returns nothing
   (list (ffi-type-compile 'str)   ;; str -> char *
         (ffi-type-compile 'int))) ;; int
  -->
  #<ffi-call-desc #<ffi-type void>
    (#<ffi-type str> #<ffi-type int>)>
.brev

.coNP Function @ ffi-type-operator-p
.synb
.mets (ffi-type-operator-p << symbol )
.syne
.desc
The
.code ffi-type-operator-p
function return
.code t
if
.meta symbol
is a type operator symbol: a symbol used in the first position of
a recognized compound type form in the FFI type system.

Otherwise, it returns
.codn nil .

.coNP Function @ ffi-type-p
.synb
.mets (ffi-type-p << symbol )
.syne
.desc
The
.code ffi-type-p
function returns
.code t
if
.meta symbol
denotes a type in the FFI type system: either a built-in type or
an alias type name established by
.codn typedef .

Otherwise, it returns
.codn nil .

.coNP Function @ ffi-make-closure
.synb
.mets (ffi-make-closure < lisp-fun < call-desc
.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \  >> [ safe-p <> [ abort-val ]])
.syne
.desc
The
.code ffi-make-closure
function binds a Lisp function
.metn lisp-fun ,
which may be a lexical closure, or any callable object, with a FFI call
descriptor
.meta call-desc
to produce a FFI closure.

A FFI closure is an object of type
.code ffi-closure
which is suitable as an argument for the type denoted by the
.code closure
type specifier keyword in the FFI type language.

This type appears a C function pointer in the foreign code,
and may be called as such. When it is called by foreign
code, it triggers a call to
.metn lisp-fun .

The optional
.meta safe-p
parameter controls whether the closure dispatch is "safe", the meaning of
which is described shortly. The default value is
.code t
so that unsafe closure dispatch must be explicitly requested with a
.code nil
argument for this parameter.

A callback closure which is safely dispatched, firstly, does not permit
the capture of delimited continuations across foreign code. Delimited
continuations can be captured inside a closure dispatched that way, but the
delimiting prompt must be within the callback's local stack frame, without
traversing across the foreign stack frames.  Secondly, a callback closure which
is safely dispatched doesn't permit direct non-local control transfers across
foreign code, such as exception handling. Such transfers, however, appear to
work anyway (with caveats): this is because they are specially handled. The
closure dispatch mechanism intercepts all dynamic control transfers, converts
them to an ordinary return from the callback to the foreign code, and resumes
the control transfer when the foreign code itself finishes and returns.
If the callback returns a value (its return type is other than
.codn void )
then in this situation, the callback returns an all-zero-bits return
value to the foreign caller. If the
.meta abort-val
parameter is specified and its value is other than
.codn nil ,
then that value will be used as the return value instead of an all-zero
bit pattern.

An unsafely dispatched closure permits the capture of continuations from
the callback across the foreign code and direct dynamic control transfers which
abandon the foreign stack frames.

Unsafe closure dispatch is only compatible with foreign code which is
designed with that usage in mind. For instance foreign code which holds
dynamic resources in stack variables will leak those resources if abandoned
this way. There are also issues with capturing continuations across foreign
code.

Note: the C function pointer is called a "closure" because it carries
environment information. For instance, if
.code lisp-fun
is a lexical closure, invocations of it through the FFI closure
occur in its proper lexical environment, even though its external
representation is a simple C function pointer. This requires a special
trampoline trick: a piece of dynamically constructed machine code with the
closure binding embedded inside it, with the C function pointer pointing
to the machine code.

Note: the same call descriptor can be reused multiple times to create
different closures. The same Lisp function can be involved in multiple
FFI closures.

.TP* Example:

.verb
  ;; Package the TXR cmp-str function as a string
  ;; comparison callback compatible with:
  ;;
  ;;   int (*)(const char *, const char *)
  ;;
  (ffi-make-closure
    (fun cmp-str)
    (ffi-make-call-desc 2 nil ;; two args, non-variadic
      (ffi-type-compile 'int) ;; int return
      [mapcar ffi-type-compile '(str str)])) ;; args
.brev


.coNP Function @ ffi-call
.synb
.mets (ffi-call < fun-cptr < call-desc <> { arg }*)
.syne
.desc
The
.code ffi-call
function invokes a foreign function.

The
.meta fun-cptr
argument which must be a
.code cptr
object. It is assumed to point to a foreign function.

The
.meta call-desc
argument must be a FFI call descriptor, produced by
.codn ffi-call-desc .

The
.meta call-desc
must correctly describe the foreign function.

The zero or more
.meta arg
arguments are values which are converted into foreign
argument values. There must be exactly as many of these arguments
as are required by
.metn call-desc .

The
.code ffi-call
function converts every
.meta arg
to a corresponding foreign object. If these conversions are
successful, the converted foreign arguments are passed by value
to the foreign function indicated by
.metn fun-cptr .
An unsuccessful conversion throws an error.

When the call returns, the foreign function's return value is
converted to a Lisp object and returned, in accordance with the
return type that is declared inside
.metn call-desc .

.coNP Function @ ffi-typedef
.synb
.mets (ffi-typedef < name << type )
.syne
.desc
The
.code ffi-typedef
function installs the compiled FFI type given by
.meta type
as a typedef name under the symbol given by
.metn name .

After this registration, whenever the type compiler encounters that
symbol being used as a type specifier, it will replace it by the
type object it represents.

The
.code ffi-typedef
function returns type.

.TP* Example:

.verb
  ;; define refcount-t as an alias for uint32
  (ffi-typedef 'refcount-t (ffi-type-compile 'uint32))
.brev

.coNP Function @ ffi-size
.synb
.mets (ffi-size << type )
.syne
.desc
The
.code ffi-size
function returns an integer which gives the storage size of
the given FFI type: the amount of storage required for the
external representation of that type.

Bitfield types do not have a size; it is an error to apply
this function to a bitfield.

The size is machine:specific.

.TP* Example:

.verb
  (ffi-size '(ffi-type-compile 'double)) -> 8
  (ffi-size '(ffi-type-compile 'char)) -> 1
  (ffi-size '(ffi-type-compile
               '(array 42 char))) -> 42
.brev

.coNP Function @ ffi-alignof
.synb
.mets (ffi-alignof << type )
.syne
.desc
The
.code ffi-alignof
function returns an integer which gives the alignment
the given FFI type. When an instance of
.meta type
is placed into a structure as a member, it is placed after the previous member
at the smallest available offset which is divisible by the alignment.
The bytes skipped from the smallest available offset to the smallest
available aligned offset are referred to as
.IR padding .

Bitfield types do not have an alignment; it is an error to apply
this function to a bitfield. Bitfields are allocated in
storage cells, and those cells have alignment which is the
same as that of the type
.codn int .

The alignment is machine-specific. It may be more strict than what the
hardware architecture requires, yet at the same time be smaller than the size
of the type. For instance, the size of the type
.code double
is commonly 8, yet the alignment is often 4, and this is so
even on processors like Intel x86 which can load and store
a double at a misaligned address.

The alignment of an array is the same as that of its element type.

The alignment of a structure is that of its member which has the
most strict (largest-valued) alignment.

It is a property of arrays, derived from requirements governing the C
language, that if the first element of an array is at a correctly aligned
address, then all elements are. To ensure that this property holds for
for arrays of structures, structures sometimes must include
padding at the end. This is because the size of a structure without any
padding might not be multiple of its alignment, which is derived from the most
strictly aligned member. For instance, if we assume an architecture on which
the size and alignment of
.code int
is 4, the size of the structure type
.code "(struct ab (a int) (b char))"
would be 5 if no padding were included.  However,
in an array of these structures, the second element's
.code a
member would be placed at offset 5, rendering it misaligned.
To ensure that every
.code a
is placed at an offset which is multiple of 4, the struct type is extended
with anonymous padding so that its size is 8.

.TP* Example:

.verb
  (ffi-alignof (ffi double)) -> 4
.brev

.coNP Function @ ffi-offsetof
.synb
.mets (ffi-offsetof < type << member )
.syne
.desc
The
.code ffi-alignof
function calculates the byte offset of
.meta member
within the FFI type
.metn type .

If
.meta type
isn't a FFI struct type, or if
.meta member
isn't a symbol naming a member of that type,
the function throws an exception.

An exception is also thrown if
.meta member
is a bitfield.

.TP* Example:

.verb
  (ffi-offsetof (ffi (struct ab (a int) (b char))) 'b) -> 4
.brev

.coNP Function @ ffi-arraysize
.synb
.mets (ffi-arraysize << type )
.syne
.desc
The
.code ffi-arraysize
function reports the number of elements in
.metn type ,
which must be an array type: an
.codn array ,
.code zarray
or
.codn carray .

.TP* Example:

.verb
  (ffi-arraysize (ffi (array 5 int))) -> 5
.brev

.coNP Function @ ffi-elemsize
.synb
.mets (ffi-elemsize << type )
.syne
.desc
The
.code ffi-elemsize
function reports the size of the element type of an array,
of the target type of a pointer, or of the base integer type of an enumeration.
The
.meta type
argument must be an array, pointer or enumeration type: a type constructed
by one of the operators
.codn array ,
.codn zarray ,
.codn carray ,
.codn ptr ,
.codn ptr-in ,
.codn ptr-out ,
.code enum
or
.codn enumed .

.TP* Example:

.verb
  (ffi-elemsize (ffi (array 5 int))) -> 4 ;; (sizeof int)
.brev

.coNP Function @ ffi-elemtype
.synb
.mets (ffi-elemtype << type )
.syne
.desc
The
.code ffi-elemtype
function retrieves the element type of an array type,
target type of a pointer type, or base integer type of an enumeration.
The
.meta type
argument must be an array, pointer or enumeration type: a type constructed
by one of the operators
.codn array ,
.codn zarray ,
.codn carray ,
.codn ptr ,
.codn ptr-in ,
.codn ptr-out ,
.code enum
or
.codn enumed .

.TP* Example:

.verb
  (ffi-elemtype (ffi (ptr int))) -> #<ffi-type int>
.brev

.SS* Foreign Function Macro Language

This group of macros provides a higher-level language for working with
FFI types and defining foreign function bindings. The macros are implemented
using the Foreign Function Type API described in the previous section.

.coNP Macro @ with-dyn-lib
.synb
.mets (with-dyn-lib < lib-expr << body-form *)
.syne
.desc
The
.code with-dyn-lib
macro works in conjunction with the
.codn deffi ,
.code deffi-sym
and
.code deffi-var
macros.

When a
.code deffi
form appears as one of the
.metn body-form -s
of the
.code with-dyn-lib
macro, that
.code deffi
form is permitted to use the simplified forms of the
.meta fun-expr
argument, to refer to library functions succinctly, without having
to specify the library. The same remark applies to
.code deffi-sym
and
.codn deffi-var ,
regarding their
.meta var-expr
parameter.

A form invoking the
.code with-dyn-lib
macro should be a top-level form.  The macro creates a global variable named
by a symbol generated by
.code gensym
whose initializing expression binds it to a dynamic library handle.
The macro then creates an environment in which the enclosed
.codn deffi ,
.code deffi-var
and
.code deffi-sym
forms can implicitly refer to that library via the global variable.

The
.meta lib-expr
argument can take on three different forms:
.RS
.meIP nil
If
.meta lib-expr
is
.codn nil ,
then
.code with-dyn-lib
arranges for the library to refer to the \*(TX executable itself.
.meIP < string
If
.meta lib-expr
is a literal string, then
.code with-dyn-lib
will arrange for the hidden variable to be initialized with
an expression which opens a handle to the specified library.

.meIP < form
If
.meta lib-expr
is any other form, then it is assumed to denote syntax for
opening the handle to a library. That syntax is used verbatim
as the initializing expression for the generated global variable
which holds the library handle.
.RE

.IP
The result value of a
.code with-dyn-lib
form is the symbol which names the generated variable which
holds the library handle.

.TP* Examples:

.verb
  ;; refer to malloc and free functions
  ;; in the executable

  (with-dyn-lib nil
    (deffi malloc "malloc" cptr (size-t))
    (deffi free "free" void (cptr)))

  ;; refer to "draw" function in fictitious
  ;; "libgraphics" library:

  (with-dyn-lib "libgraphics.so.5"
    (deffi draw "draw" int (cptr cptr)))

  ;; refer to "init_foo" function via specific
  ;; library handle.

  (defvarl foo-lib (dlopen "libfoo.so.1"))

  (with-dyn-lib foo-lib
    (deffi init-foo "init_foo" void (void)))
.brev

.coNP Macro @ deffi
.synb
.mets (defmacro deffi < name < fun-expr < rettype << argtypes )
.syne
.desc
The
.code deffi
macro arranges for a Lisp function to be defined, via
.codn defun ,
which calls a foreign function.

The
.meta name
argument must be a symbol suitable as a function name in a
.code defun
form. This specifies the function's Lisp name.

The
.meta fun-expr
parameter specifies the foreign function which is to be called.
The syntactic variants permitted for its argument are
described below.

The
.meta rettype
argument must specify the return type, using the FFI type syntax,
as an unquoted literal.  The macro arranges for the compilation of this
syntax via
.codn ffi-type-compile .

The
.meta argtypes
argument must specify a list of the argument types, as an unquoted
literal list, using FFI type syntax. The macro arranges for these types
to be compiled. Furthermore, a special convention may be used for
specifying a variadic function: if the
.code :
(colon keyword)
symbol appears as one of the elements of
.metn argtypes ,
then the
.code deffi
form specifies a fixed call to a foreign function which is variadic. The
argument types before the colon keyword are the fixed arguments. The types
after the colon, if any, are the variadic arguments.

The following syntactic variants are permitted of the
.meta fun-expr
argument:
.RS
.meIP < name-string
If
.meta fun-expr
is a literal string, then the
.code deffi
form must be enclosed in the
.code with-dyn-lib
macro, appearing as one of that macro's
.metn body-form -s.
In this situation the literal character string
.meta name-string
specifies a symbol to be found within the library established by the
.meta with-dyn-lib
macro.
.meIP >> ( name-string << ver-string )
This manner of specifying the
.meta fun-expr
also requires the
.code deffi
form to be enclosed in a
.codn with-dyn-lib .
It selects a particular version of a symbol from the library.
.meIP < form
If
.meta fun-expr
is any other form, then it must specify an expression which evaluates to a
.code cptr
object giving the address of a foreign library symbol. If this form
is used, then the
.code deffi
form need not be surrounded by a call to the
.code with-dyn-lib
macro.
.RE

.IP
The result value of a
.code deffi
form is
.metn name .

.coNP Macros @ deffi-cb and @ deffi-cb-unsafe
.synb
.mets (deffi-cb < name < rettype < argtypes <> [ abort-val ])
.mets (deffi-cb-unsafe < name < rettype << argtypes )
.syne
.desc
The
.code deffi-cb
macro defines, using
.code defun
a Lisp function called
.metn name .

Thus the
.meta name
argument must be a symbol suitable as a function name in a
.code defun
form.

The
.meta rettype
and
.meta argtypes
arguments are processed exactly as in the corresponding arguments in the
.code deffi
macro.

The
.code deffi-cb
macro arranges for
.meta rettype
and
.meta argtypes
to be compiled into a FFI call descriptor.
The generated function called
.meta name
then serves as a combinator which takes a Lisp function as its argument,
and binds it to the FFI call descriptor to produce a FFI closure.
That closure may then be passed to foreign functions as a callback.
The
.code deffi-cb
macro generates a callback which uses safe dispatch, which is explained
in the description of the
.code ffi-make-closure
function. The optional
.meta abort-val
parameter specifies an expression which evaluates to the value
to be returned by the callback in the event that a dynamic control
transfer is intercepted. The purpose of this value is to indicate
to the foreign code that the callback wishes to abort operation;
it is useful in situations when a suitable return value will induce
the foreign code to co-operate and itself return to the Lisp code
which will then continue the dynamic control transfer.

The
.code deffi-cb-unsafe
macro is a variant of
.code deffi-cb
with the same argument conventions. The difference is that it arranges for
.code ffi-make-closure
to be invoked with
.code nil
for the
.meta safe-p
parameter. This macro has no
.meta abort-val
parameter, since unsafe callbacks do not use it.

.TP* Example:

.verb
  ;; create a closure combinator which binds
  ;; Lisp functions to a call descriptor has the C type
  ;; signature void (*)(int).

  (deffi-cb void-int-closure void (int))

  ;; use the combinator
  ;; some-foreign-function's second arg is
  ;; of type closure, specifying a callback:

  (some-foreign-function
    42
    (void-int-closure (lambda (x)
                        (puts `callback! @x`))))

.brev

.coNP Macro @ deffi-var
.synb
.mets (deffi-var < name < var-expr << type )
.syne
.desc
The
.code deffi-var
macro defines a global symbol macro which expands to an expression
accessing a foreign variable, creating the illusion that the
variable is available as a Lisp variable holding a Lisp data type.

The
.meta name
argument gives the name of the symbol macro to be defined.

The
.meta var-expr
argument is one of several permitted syntactic forms
which specify the address of the foreign variable.
They are described below.

The
.meta type
argument expresses the variable type in FFI type syntax.

Once the variable is defined, accessing the macro symbol
.meta name
performs a get operation on the foreign variable, yielding
the conversion of that variable to a Lisp value.
An assignment to the symbol performs a put operation,
converting a Lisp object to a value which overwrites
the object.

Note: FFI memory management is not helpful in the use of
variables. Suppose a string value is
stored in a variable of type
.codn str .
This means that FFI dynamically allocates a buffer which
stores the UTF-8 encoded version of the string, and this
buffer is placed into the foreign variable.
Then suppose another such assignment takes place.
The previous value is simply overwritten without being
freed.

The following syntactic variants are permitted of the
.meta var-expr
argument:
.RS
.meIP < name-string
If
.meta var-expr
is a literal string, then the
.code deffi-var
form must be enclosed in the
.code with-dyn-lib
macro, appearing as one of that macro's
.metn body-form -s.
In this situation the literal character string
.meta name-string
specifies a symbol to be found within the library established by the
.meta with-dyn-lib
macro.
.meIP >> ( name-string << ver-string )
This manner of specifying the
.meta fun-expr
also requires the
.code deffi
form to be enclosed in a
.codn with-dyn-lib .
It selects a particular version of a symbol from the library.
.meIP < form
If
.meta var-expr
is any other form, then it must specify an expression which evaluates to a
.code cptr
object giving the address of a foreign library symbol. If this form
is used, then the
.code deffi
form need not be surrounded by a call to the
.code with-dyn-lib
macro.
.RE

.coNP Macro @ deffi-sym
.synb
.mets (deffi-sym < name < var-expr <> [ type-sym ])
.syne
.desc
The
.code deffi-sym
macro defines a global lexical variable called
.code name
whose value is a
.code cptr
object that refers to a symbol in a foreign library.

The
.meta name
argument gives the name for the variable to be defined.
This definition takes place place as if by the
.code defparml
macro.

The
.meta var-expr
is syntax which specifies the foreign pointer, using exactly the same
conventions as described for the
.code deffi-var
macro, allowing for a short-hand notation if this form is
enclosed in a
.code with-dyn-lib
macro invocation.

The optional
.meta type-sym
argument must be a symbol. If it is absent, it defaults to nil.
This argument specifies the type label for the
.code cptr
object which holds the pointer to the foreign symbol.

The result value of
.meta deffi-sym
is the symbol
.metn name .

.coNP Macro @ typedef
.synb
.mets (typedef < name << type-syntax )
.syne
.desc
The
.code typedef
macro provides a convenient way to define type aliases.

The
.meta type-syntax
expression is compiled as FFI syntax, and the
.meta name
symbol is installed as an alias denoting that type.

The
.code typedef
macro yields the compiled version of
.meta type-syntax
as its value.

.coNP Macro @ sizeof
.synb
.mets (sizeof < type-syntax <> [ object-expr ])
.syne
.desc
The macro
.code sizeof
calculates the size of the FFI type denoted by
.codn type-syntax .

The
.meta type-syntax
expression is compiled to a type using
.codn ffi-type-compile .
The
.meta object-expr
expression is evaluated to an object value.

If
.code type-syntax
denotes an incomplete array or structure type, and the
.meta object-expr
argument is present, then a
.I "dynamic size" is computed: the actual number of bytes required to store
that object value as a foreign representation.

The
.code sizeof
macro arranges for the size calculation to be carried out at macro-expansion
time, if possible, so that the
.code sizeof
form is replaced by an integer constant. This is possible when the
.meta object-expr
is omitted, or if it is a constant expression according to the
.code constantp
function.

For the type
.codn void ,
incomplete array types, and bitfield types, the one-argument form of
.code sizeof
reports zero.

For incomplete structure types, the one-argument
.code sizeof
reports a size which is equivalent to the offset of the last member.
The size of an incomplete structure does not include padding
for the most strictly aligned member.

.coNP Macro @ alignof
.synb
.mets (alignof << type-syntax )
.syne
.desc
The macro
.code alignof
calculates the alignment of the FFI type denoted by
.code type-syntax
at macro-expansion time, and produces that
integer value as its expansion, such that there is no
run-time computation. It uses the
.code ffi-alignof
function.

.coNP Macro @ offsetof
.synb
.mets (offsetof < type-syntax << member-name )
.syne
.desc
The macro
.code sizeof
calculates the offset of the structure member indicated by
.metn member-name ,
a symbol, inside the FFI struct type indicated by
.metn type-syntax .
This calculation is performed by a macro-expansion-time call to the
.code ffi-offsetof
function, and produces that
integer value as its expansion, such that there is no
run-time computation.

.coNP Macro @ arraysize
.synb
.mets (arraysize << type-syntax )
.syne
.desc
The macro
.code arraysize
calculates the number of elements of the array type indicated by
.metn type-syntax .
This calculation is performed by a macro-expansion-time call to the
.code ffi-arraysize
function, and produces that
integer value as its expansion, such that there is no
run-time computation.

.coNP Macro @ elemsize
.synb
.mets (elemsize << type-syntax )
.syne
.desc
The macro
.code elemsize
calculates the size of the element type of an array type, or
the size of target type of a pointer type indicated by
.metn type-syntax .
This calculation is performed by a macro-expansion-time call to the
.code ffi-elemsize
function, and produces that
integer value as its expansion, such that there is no
run-time computation.

.coNP Macro @ elemtype
.synb
.mets (elemtype << type-syntax )
.syne
.desc
The macro
.code elemtype
produce the element type of an array type, or
the target type of a pointer type indicated by
.metn type-syntax .
Note: the
.code elemtype
macro may be understood in terms of several possible implementations.
The form
.code "(elemtype X)"
is equivalent to
.codn "(ffi-elemtype (ffi-type-compile X))" .
Since there exists an
.code elemtype
type operator, the expression is also equivalent to
.codn "(ffi-type-compile '(elemtype X))" .

.coNP Macro @ ffi
.synb
.mets (ffi << type-syntax )
.syne
.desc
The
.code ffi
macro provides a shorthand notation for compiling a literal
FFI type expression to the corresponding type object. The
following equivalence holds:

.verb
  (ffi expr)  <-->  (ffi-type-compile 'expr)
.brev

.SS* Zero-filled Object Support

Communicating with foreign interfaces sometimes requires representations
to be initialized consisting of all zero bits, or mostly zero bits.

\*(TX provides convenient ways to prepare Lisp objects such that when those
objects are converted to a foreign representation, they generate zero-filled
representations.

.coNP Function @ make-zstruct
.synb
.mets (make-zstruct < type >> { slot-sym << init-value }*)
.syne
.desc
The
.code make-zstruct
function provides a convenient means of instantiating a structure
for use in foreign function calls, imitating a pattern of initialization
often seen in the C language. It instantiates a Lisp
.code struct
by conversion of zero-filled memory through FFI, thus creating a Lisp
structure which appears zero-filled when converted to the foreign representation.

This simplifies application code, which is spared from providing individual
slot initializations which have this effect.

The
.meta type
argument must be a compiled FFI
.code struct
type. The remaining arguments must occur pairwise. Each
.meta slot-sym
argument must be a symbol naming a slot in the FFI
.code struct
type. The
.meta init-value
argument which follows it specifies the value for that
slot.

The
.code make-zstruct
function operates as follows. Firstly, the Lisp
.code struct
type is retrieved which corresponds to the FFI type given by
.metn type .
A new instance of the Lisp type is instantiated, as if by
a one-argument call to
.codn make-struct .
Next, each slot indicated by a
.meta slot-sym
argument is set to the corresponding
.metn init-value .
Finally, each slot of the struct which is not initialized via
.meta slot-sym
and
.meta init-value
pair, and which is known to the FFI type, is re-initialized by a conversion
from a foreign object of all-zero bits to a Lisp value.
argument. The
.code struct
object is then returned.

Note: the
.code znew
macro provides a less verbose notation based on
.codn make-zstruct .

Note: slots which are not known to the FFI
.code struct
type may be initialized by
.codn make-zstruct .
Each
.meta slot-sym
must be a slot of the Lisp
.code struct
type; but need not be declared as a member in the FFI
.code struct
type.

.coNP Macro @ znew
.synb
.mets (znew < type-syntax >> { slot-sym << init-value }*)
.syne
.desc
The
.code znew
macro provides a convenient way of using
.codn make-zstruct ,
using syntax which resembles that of the
.code new
macro.

The
.code znew
macro generates a
.code make-zstruct
call, arranging for the
.meta type-syntax
argument to be compiled to a FFI type object, and
applies quoting to every
.meta slot-sym
argument.


The following equivalence holds:

.verb
  (znew s a i b j ...)  <-->  (make-zstruct (ffi s)
                                            'a i 'b j ...)
.brev

.TP* Example

Given the following FFI type definition

.verb
  (typedef foo (struct foo (a (cptr bar)) (b uint) (c bool)))
.brev

the following results are observed:

.verb
  ;; ordinary instantiation
  (new foo) -> #S(foo a nil b nil c nil)

  ;; Under znew, a is null cptr of correct type:
  (znew foo) -> #S(foo a #<cptr bar: 0> b 0 c nil)

  ;; value of b is specified; others come from zeros:
  (znew foo b 42) -> #S(foo a #<cptr bar: 0> b 42 c nil)
.brev

.coNP Function @ zero-fill
.synb
.mets (zero-fill < type << obj )
.syne
.desc
The
.code zero-fill
function invokes the by-reference in semantics of FFI type
.meta type
against a zero-filled buffer, and a Lisp object
.metn obj .

This means that if
.meta obj
is an aggregate such as a vector, list or structure,
it is updated as if from an all-zero-bit foreign representation.
In that situation,
.meta obj
is also returned.

An object which has by-value semantics, such as an integer,
is not updated. In this case, nevertheless, the return value
is a Lisp object produced by converting an all-zero-bit buffer to
.metn type .

.SS* Foreign Unions

The following group of functions provides the means for working
with foreign unions, in conjunction with the
.code union
FFI type.

.coNP Function @ make-union
.synb
.mets (make-union < type >> [ initval <> [ member ]])
.syne
.desc
The
.code make-union
function instantiates a new object of type
.codn union ,
based on the FFI type specified by the
.meta type
parameter, which must be compiled FFI
.code union
type.

The object provides storage for the foreign representation of
.codn type ,
and that storage is initialized to all zero bytes.

Additionally, if
.meta initval
is specified, but
.meta member
is not, then
.meta initval
is stored into the union's via the first member, as if by
.codn union-put .
If the union type has no members, an error exception is thrown.

If both
.meta initval
and
.meta member
are specified, then
.meta initval
is stored into the union using the specified member, as if by
.codn union-put .

.coNP Function @ union-members
.synb
.mets (union-members << union )
.syne
.desc
The
.code union-members
function retrieves the list of symbols which name the members of
.metn union .
These are derived from the object's FFI type.
It is unspecified whether the list is freshly allocated on each call,
or whether the same list is returned; applications shouldn't
destructively manipulate this list.

.coNP Function @ union-get
.synb
.mets (union-get < union << member )
.syne
.desc
The
.code union-get
function performs the get semantics (conversion from a foreign
representation to Lisp) on the member of
.meta union
which is specified by the
.meta member
argument. That argument must be a symbol corresponding to one of the member
names.

The
.meta union
object's storage buffer is treated as an object of the foreign
type indicated by that member's type information, and converted
accordingly to a Lisp object that is returned.

.coNP Function @ union-put
.synb
.mets (union-put < union < member << new-value )
.syne
.desc
The
.code union-put
function performs the put semantics (conversion from a Lisp object
to foreign representation) on the member of
.meta union
which is specified by the
.meta member
argument. That argument must be a symbol corresponding to one of the member
names.

The object given as
.meta new-value
is converted to the foreign representation according to the type
information of the indicated member, and that representation is
placed into the
.meta union
object's storage buffer.

The return value is
.metn new-value .

.coNP Functions @ union-in and @ union-out
.synb
.mets (union-in < union < memb << memb-obj )
.mets (union-out < union < memb << memb-obj )
.syne
.desc
The
.code union-in
and
.code union-out
functions perform the FFI in semantics and out semantics, respectively.
These semantics are involved in two-way data transfers between foreign
representations and Lisp objects.

The
.meta union
argument must be a
.code union
object and the
.meta memb
argument a symbol which matches one of that object's member names.

In the case of
.codn union-in ,
.meta memb-obj
is a Lisp object that was previously stored into
.meta union
using the
.code union-put
operation, into the same member that is currently indicated by
.metn member .

In the case of
.codn union-out ,
.meta memb-obj
is a Lisp object that was previously retrieved from
.meta union
using the
.code union-get
operation, from the same member that is currently indicated by
.metn member .

The
.code union-in
performs the by-value nuance of the in semantics on the indicated
member: if the member contains pointers to any objects, those
objects are updated from their counterparts in
.meta memb-obj
using their respective by-reference in semantics, recursively.

Similarly
.code union-out
performs the by-value nuance of the out semantics on the indicated
member: if the member contains pointers to any objects, those
objects are updated with their Lisp counterparts in
.meta memb-obj
using their respective by-reference out semantics, recursively.

Note:
.code union-in
is intended to be used after a FFI call, on a union-typed by-value
argument, or a union-typed object contained in an argument,
in situations when the function is expected to have updated
the contents of the union. The
.code union-out
function is intended to be used in a FFI callback, on a union-typed
callback argument or union-typed object contained in such
an argument, in cases when the callback has updated the Lisp
object corresponding to a union member, and that change needs
to be propagated to the foreign caller.

.SS* FFI-type-driven I/O Functions

These functions provide a way to perform I/O on stream using the foreign
representation of Lisp objects, performing conversion between the Lisp
representations in memory and the foreign representations in a stream.

The
.meta stream
argument used with these functions must be a stream object which,
in the case of input functions, supports
.code get-byte
and, in the case of output, supports
.codn put-byte .

.coNP Function @ put-obj
.synb
.mets (put-obj < object < type <> [ stream ])
.syne
.desc
The
.code put-obj
function encodes
.meta object
into a foreign representation, according to the FFI type
.metn type .
The bytes of the foreign representation are then written to
.metn stream .

If
.meta stream
is omitted, it defaults to
.codn *stdout* .

If the operation successfully writes all bytes of the representation to
.metn stream ,
the value
.code t
is returned. A partial write causes the return value to be
.codn nil .

All other stream error situations throw exceptions.

.coNP Function @ get-obj
.synb
.mets (get-obj < type <> [ stream ])
.syne
.desc
The
.code get-obj
function reads from
.meta stream
the bytes corresponding to a foreign representation according to the FFI type
.metn type .

If
.meta stream
is omitted, it defaults to
.codn *stdin* .

If the read is successful, these bytes are decoded, producing a Lisp
object, which is returned.

If the read is incomplete, the value returned is
.metn nil .

All other stream error situations throw exceptions.

.coNP Function @ fill-obj
.synb
.mets (fill-obj < object < type <> [ stream ])
.syne
.desc
The
.code get-obj
function reads from
.meta stream
the bytes corresponding to a foreign representation according to the FFI type
.metn type .

If the read is successful, then
.meta object
is updated, if possible, from that representation, using the by-value in
semantics of the FFI type and returned. If a by-value update of
.meta object
isn't possible, then a new object is decoded from the data and returned.

If the read is incomplete, the value returned is
.metn nil .

All other stream error situations throw exceptions.

.SS* Buffer Functions

Functions in this area provide a way to perform conversion between
Lisp objects and foreign representation to and from objects of the
.code buf
type.

.coNP Functions @ ffi-put and @ ffi-put-into
.synb
.mets (ffi-put < obj << type )
.mets (ffi-put-into < dst-buf < obj < type <> [ offset ])
.syne
.desc
The
.code ffi-put
function encodes the Lisp object
.meta obj
according to the FFI type
.meta type
and returns a new buffer object of type
.code buf
which holds the foreign representation.

The
.code ffi-put-into
function is similar, except that it uses an existing buffer
.meta dst-buf
which must be large enough to hold the foreign representation.

The
.meta type
argument must be a compiled FFI type.

If
.meta type
is has a variable length, then the actual size of the foreign representation is
calculated from
.metn obj .

The
.meta obj
argument must be an object compatible with the conversions
implied by
.metn type .

The optional
.meta offset
argument specifies a byte offset from the beginning of the data area of
.meta dst-buf
where the foreign-representation of
.meta obj
is stored. The default value is zero.

These functions perform the "put semantics" encoding action similar to
what happens to the arguments of an outgoing foreign function call.

Caution: incorrect use of this function, or its use in isolation
without a matching
.code ffi-in
call, can cause memory leaks, because, depending on
.metn type ,
temporary resources may be allocated, and pointers to those resources
will be stored in the buffer.

.coNP Function @ ffi-out
.synb
.mets (ffi-out < dst-buf < obj < type < copy-p <> [ offset ])
.syne
.desc
The
.code ffi-out
function performs the "out semantics" encoding action, similar
to the treatment applied to the arguments of a callback prior to
returning to foreign code.

It is assumed that
.code obj
is an object that was returned by an earlier call to
.codn ffi-get ,
and that the
.meta dst-buf
and
.meta type
arguments are the same objects that were used in that call.

The
.meta copy-p
argument is a Boolean flag which is true if the buffer represents a datum
that is being passed by pointer. If
.meta copy-p
is true, then
.meta obj
is converted to a foreign representation which is stored into
.metn dst-buf .
If it is false, it indicates that the buffer itself is a pass-by-value object.
This means that the object itself will not be copied, but if it is an aggregate
which contains pointers, the operation will recurse on those objects, invoking
their "out semantics" action with pass-by-pointer semantics. The required
pointers to these indirect objects are obtained from
.metn dst-buf .

The optional
.meta offset
argument specifies a byte offset from the beginning of the data area of
.meta dst-buf
where the foreign-representation of
.meta obj
is understood to be stored, and where it is updated if requested by
.metn copy-p .
The default value is zero.

The
.code ffi-out
function returns
.metn dst-buf .

.coNP Function @ ffi-in
.synb
.mets (ffi-in < src-buf < obj < type < copy-p <> [ offset ])
.syne
.desc
The
.code ffi-in
function performs the "in semantics" decoding action, similar to the
treatment applied to the arguments of a foreign function call after
it returns, in order to free temporary resources and recover the new
values of objects that have been modified by the foreign function.

It is assumed that
.meta src-buf
is a buffer that was prepared by a call to
.code ffi-put
or
.codn ffi-put-into ,
and that
.meta type
and
.meta obj
are the same values that were passed as the
corresponding arguments of those functions.

The
.code ffi-in
function releases the temporary memory resources that were allocated by
.code ffi-put
or
.codn ffi-put-into ,
which are obtained from the buffer itself, where they appear as pointers.
The function recursively performs the in semantics across the entire type,
and the entire object graph rooted at the buffer.

The
.meta copy-p
argument is a Boolean flag which is true if the buffer represents a datum
that is being passed by pointer. If it is false, it indicates that the
buffer itself is a pass-by-value object. Under pass-by-pointer semantics,
either a whole new object is extracted from the buffer and returned,
or else the slots of
.meta obj
are updated with new values from the buffer.
Under pass-by-value semantics, no such extraction takes place, and
.meta obj
is returned.
However, regardless of the value of
.codn copy-p ,
if the object is an aggregate which contains pointers, the recursive
treatment through those pointers involves pass-by-pointer semantics.

This is consistent with the idea that we can pass a structure by value,
but that structure can have pointers to objects which are updated by
the called function. Those indirect objects are passed by pointer.
They get updated, but the parent structure cannot.

If
.meta type
is has a variable length, then the actual size of the foreign representation is
calculated from
.metn obj .

The optional
.meta offset
argument specifies a byte offset from the beginning of the data area of
.meta src-buf
from which the foreign-representation of
.meta obj
is taken.

The
.code ffi-in
function returns either
.meta obj
or a new object which is understood to have been produced as its
replacement.

.coNP Function @ ffi-get
.synb
.mets (ffi-get < src-buf < type <> [ offset ])
.syne
.desc
The
.code ffi-get
function extracts a Lisp value from buffer
.meta src-buf
according to the FFI type
.metn type .
The
.meta src-buf
argument is an object of type
.meta buf
large enough to hold a foreign representation of
.metn type ,
at the byte offset indicated by the
.meta offset
argument.
The
.meta type
argument is compiled FFI type.
The optional
.meta offset
argument defaults to zero.

The external representation in
.meta src-buf
at the specified offset is scanned according to
.meta type
and converted to a Lisp value which is returned.

The
.code ffi-get
operation is similar to the "get semantics" performed by FFI
in order to extract the return value of foreign function
calls, and by the FFI callback mechanism to extract the
arguments coming into a callback.

The
.meta type
argument may not be a variable length type, such as an array of
unspecified size.

.SS* Foreign Arrays

Functions in this area provide a means for working with
foreign arrays, in connection with the FFI
.code carray
type.

.coNP Functions @ carray-vec and @ carray-list
.synb
.mets (carray-vec < vec < type <> [ null-term-p ])
.mets (carray-list < list < type <> [ null-term-p ])
.syne
.desc
The
.code carray-vec
and
.code carray-list
functions allocate storage for the representation of a foreign array, and
return a
.code carray
object which holds a pointer to that storage.

The argument
.metn type ,
which must be a compiled FFI type,
is retained as the
.code carray
object's element type.

Prior to returning, the functions
initializes the foreign array by converting the elements of
.meta vec
or, respectively,
.meta list
into elements of the foreign array.
The conversion is performed using the put semantics of
.metn type ,
which is a compiled FFI type.

The length of the returned
.code carray
is determined from the length of
.meta vec
or
.meta list
and from the value of the Boolean argument
.metn null-term-p .

If
.meta null-term-p
is
.codn nil ,
then the length of the
.code carray
is the same as that of the input
.meta vec
or
.metn list .

A true value of
.meta null-term-p
indicates null termination.
This causes the length of the
.code carray
to be one greater than that of
.meta vec
or
.metn list ,
and the extra element allocated to the foreign array is filled with zero bytes.

.coNP Function @ carrayp
.synb
.mets (carrayp << object )
.syne
.desc
The
.code carrayp
function returns
.code t
if
.meta object
is a
.codn carray ,
otherwise it returns
.codn nil .

.coNP Function @ carray-blank
.synb
.mets (carray-blank < length << type )
.syne
.desc
The
.code carray-blank
function allocates storage for the representation of a foreign array,
filling that storage with zero bytes, and returns a
.code carray
object which holds a pointer to that storage.

The argument
.metn type ,
which must be a compiled FFI type,
is retained as the
.code carray
object's element type.

The
.meta length
argument must be a nonnegative integer; it specifies the number
of elements in the foreign array and is retained as the
.code carray
object's length.

The size of the foreign array is the product of the size of
.meta type
as reported by the
.code ffi-size
function, and of
.metn length .

.coNP Function @ carray-buf
.synb
.mets (carray-buf < buf < type <> [ offset ])
.syne
.desc
The
.code carray-buf
function creates a
.code carray
object which refers to the storage provided and managed by the buffer object
.metn buf ,
providing a view of that storage, and manipulation thereof, as an array.

The optional
.meta offset
parameter specifies an offset from the start of the buffer to the
location which is interpreted as the start of the
.codn carray ,
which extends from that offset to the end of the buffer.

The default value is zero: the
.code carray
covers the entire buffer.

If a value is specified, it must be in the range zero to the length of
.metn buf .

The
.meta type
argument must be a compiled FFI type whose size is nonzero.

The
.code carray
is overlaid onto the storage of
.meta buf
as follows:

First,
.meta offs
is subtracted from the bytewise length of
.metn buf ,
as reported by
.code length-buf
function to produce the effective length of the storage to be used for the array.

The effective length is divided by the size of
.metn type ,
as reported by
.codn ffi-size .
The resulting quotient represents the length (number of elements) of the
.code carray
object.

Note: the returned
.code carray
object holds a reference to
.metn buf ,
preventing
.meta buf
from being reclaimed by garbage collection, thereby protecting the
underlying storage from becoming invalid. A subsequent invocation of
.code carray-own
operation releases this reference.

Note: the relationship between the
.code carray
object and
.meta buf
is inherently unsafe: if
.meta buf
is subsequently subject to operations which reallocate the storage,
such as
.code buf-set-length
the pointer stored inside the referencing
.code carray
object becomes invalid, and operations involving that pointer
have undefined behavior.

Note: if the length of the buffer is not evenly divisible by the size of the
type, the calculated number of elements is rounded down. The trailing portion
of the buffer corresponding to the division remainder, being insufficient
to constitute a whole array element, is excluded from the array view.

.coNP Function @ carray-buf-sync
.synb
.mets (carray-buf-sync << carray )
.syne
.desc
The
.code carray-buf-sync
function requires
.meta carray
to be a
.code carray
object which refers to a
.code buf
object for its storage. Such objects are created by the function
.codn carray-buf .

The
.code carray-buf-sync
function retrieves and returns the buffer object associated with
.meta carray
and at the same time also updates the internal properties of
.meta carray
using the current information: the pointer to the data, and the
length of
.meta carray
are altered to reflect the current state of the buffer.

.coNP Function @ buf-carray
.synb
.mets (buf-carray << carray )
.syne
.desc
The
.code buf-carray
function duplicates the underlying storage of
.meta carray
and returns that storage represented as an object of
.code buf
type.

The storage size is calculated by multiplying the
.code carray
object's element size by the number of elements.
Only that extent of the storage is duplicated.

.coNP Function @ carray-cptr
.synb
.mets (carray-cptr < cptr < type <> [ length ])
.syne
.desc
The
.code carray-cptr
function creates a
.code carray
object based on a pointer derived from a
.code cptr
object.

The
.meta cptr
argument must be of type
.codn cptr .
The object's
.code cptr
type tag is ignored.

The
.meta type
argument must specify a compiled FFI type, which will become
the element type of the returned
.codn carray .

If
.meta length
is specified as
.codn nil ,
or not specified,
then the returned
.code carray
object will be of unknown length. Otherwise,
.meta length
must be a non-negative integer which will be taken as the
length of the array.

Note: this conversion is inherently unsafe.

.coNP Function @ length-carray
.synb
.mets (length-carray << carray )
.syne
.desc
The
.code length-carry
function returns the length of the
.meta carray
argument, which must be an object of type
.codn carray .

If
.meta carray
has an unknown length, then
.code nil
is returned.

.coNP Function @ copy-carray
.synb
.mets (copy-carray << carray )
.syne
.desc
The
.code copy-carray
function returns a duplicate of
.metn carray .

The duplicate has the same element type and length, but has its own
copy of the underlying storage. This is true whether or not
.meta carray
owns its storage or not. In either case, the duplicate owns
.I its
copy of the storage.

.coNP Function @ carray-set-length
.synb
.mets (carray-set-length < carray << length )
.syne
.desc
The
.code carry-set-length
attempts to change the length of
.metn carray ,
which must be an object of
.code carray
type.

The
.meta length
argument indicates the new length, which must be
a non-negative integer.

The operation throws an
.code error
exception if
.meta length
is negative.

An
.code error
exception is also thrown if
.meta carray
is an object which owns the underlying storage. There is no provision in the
.code carray
type to change the storage size.

It is permissible to change the length of a
.code carray
object which acts as a view into a buffer (as constructed via the
.code carray-buf
operation).

This creates a potentially unsafe situation in which the length requires
a larger amount of backing storage than is provided by the buffer.

.coNP Accessor @ carray-ref
.synb
.mets (carray-ref < carray << idx )
.mets (set (carray-ref < carray << idx ) << new-val )
.syne
.desc
The
.code carray-ref
function accesses an element of the foreign array
.metn carray ,
converting that element to a Lisp value, which is returned.

The
.meta idx
argument must be a non-negative integer. If
.meta carray
has a known length,
.meta idx
must be less than the length.

If
.meta carray
has an unknown length, then the the access is permitted regardless of how
positive is the value of
.metn idx .
Whether the access has well-defined behavior depends on the actual extent of
the underlying array storage.

The validity of any access to the underlying storage depends on the
validity of the pointer to that storage.

The access to the array storage proceeds as follows. Every
.code carray
object has an element type, which is a compiled FFI type.
A byte offset
address is calculated by multiplying the size of the element type of
.meta carray
by
.metn idx .
Then, the get semantics of the element type is invoked to convert, to
a Lisp object, a region of data starting at calculated byte offset in the array
storage. The resulting object is returned.

Assigning an a value to a
.code caddr-ref
form is equivalent to using
.code caddr-refset
to store the value.

.coNP Function @ carray-refset
.synb
.mets (carray-refset < carray < idx << new-val )
.syne
.desc
The
.code carray-refset
function accesses an element of the foreign array
.metn carray ,
overwriting that element with a new value obtained
from a conversion of the Lisp value
.metn new-val .

The return value is
.metn new-val .

The
.meta idx
argument must be a non-negative integer. If
.meta carray
has a known length,
.meta idx
must be less than the length.

If
.meta carray
has an unknown length, then the the access is permitted regardless of how
positive is the value of
.metn idx .
Whether the access has well-defined behavior depends on the actual extent of
the underlying array storage.

The validity of any access to the underlying storage depends on the
validity of the pointer to that storage.

The access to the array storage proceeds as follows. Every
.code carray
object has an element type, which is a compiled FFI type.
A byte offset
address is calculated by multiplying the size of the element type of
.meta carray
by
.metn idx .
Then, the put semantics of the element type is invoked to convert
.meta new-val
to a foreign representation, which is written into the array storage
started at the calculated byte offset.

If
.meta new-val
has a type which is not compatible with the element type, or a value which
is out of range or otherwise unsuitable, an exception is thrown.

.coNP Functions @ carray-dup and @ carray-own
.synb
.mets (carray-dup << carray )
.mets (carray-own << carray )
.syne
.desc
The
.code carray-dup
function acts upon a
.code carray
object which doesn't own its underlying array storage.
It allocates a duplicate copy of the array storage referenced by
.metn carray ,
and assigns to
.meta carray
the new copy. Then it marks
.meta carray
as owning that storage. Lastly, if
.meta carray
references another object, that reference is removed;
.meta carray
no longer prevents the other object from being reclaimed by
the garbage collector.

If
.meta carray
already owns its storage, then this function has no effect.

If
.meta carray
has an unknown size, then an error exception is thrown.

A
.code carray
produced by the functions
.code carray-vec
or
.code carray-blank
already owns its storage.

A
.code carray
object does not own its storage if it is produced by
.code carray-buf
or by the conversion of a foreign pointer under the control of the
.code carray
FFI type.

Because
.code carray
objects derived from foreign pointers via FFI have an unknown size,
before using
.codn carray-dup ,
the application must determine the length of the array, and call
.code carray-set-length
to establish that length.

After
.codn carray-dup ,
the length may not be altered.

The
.code carray-dup
function returns
.code t
if it has performed the duplication operation. If it has done
nothing, it returns
.codn nil .

The
.code carray-own
function resembles
.codn carray-dup ,
differing from that function only in in two ways.
Instead of allocating a duplicate copy of the underlying array storage,
.code carray-own
causes
.meta carray
to
.B assume
ownership of the existing storage. Secondly, it is an error to use
.code carray-own
on a
.meta carray
which references a buffer object.

The
.meta carray-own
function always returns
.codn nil .

In all other regards, the descriptions of
.code carray-dup
apply to
.codn carray-own .

.coNP Function @ carray-free
.synb
.mets (carray-free << carray )
.syne
.desc
If
.meta carray
is a
.code carray
object which owns the storage to which it refers, then
.code carray-free
function liberates that storage by passing the pointer to the C
library function
.codn free .
It then replaces that pointer with a null pointer, and
changes the size to zero.

If
.meta carray
doesn't own the storage, an exception is thrown.

.coNP Function @ carray-type
.synb
.mets (carray-type << carray )
.syne
.desc
The
.code carray-type
function returns the element type of
.metn carray ,
a compiled FFI type.

.coNP Functions @ vec-carray and @ list-carray
.synb
.mets (vec-carray < carray <> [ null-term-p ])
.mets (list-carray < carray <> [ null-term-p ])
.syne
.desc
The
.code vec-carray
and
.code list-carray
functions convert the array storage of
.meta carray
to a freshly constructed object representation: vector, and list, respectively.
The new vector or list is returned.

The
.meta carray
object must have a known size; an
.code error
exception is thrown if these functions are invoked on a
.code carray
object of unknown size.

The effective length of the new vector or list is derived
from the length of
.metn carray ,
taking into account the value of
.metn null-term-p .

The
.meta null-term-p
Boolean parameter defaults to
.codn nil .
If specified as true, then it has the effect that the
effective length of the returned vector or list is
one less than that of
.metn carray :
in other words, a true value of
.meta null-term-p
indicates that
.meta carray
holds storage which represents a null-terminated array, and the
terminating null element is to be excluded from the conversion.

If
.meta null-term-p
is true, but the length of
.meta carray
is already zero, then it has no effect; the effective length remains zero,
and a zero-length vector or list is returned.

Conversion of the foreign array to the vector or list is performed
by iterating over all of its elements, starting from element zero, up to the
element before the effective length.

.coNP Functions @ carray-get and @ carray-getz
.synb
.mets (carray-get << carray )
.mets (carray-getz << carray )
.syne
.desc
The
.code carray-get
and
.code carray-getz
functions treat the contents of
.meta carray
as a FFI
.code array
and
.code zarray
type, respectively.

They invoke the get semantics to convert the FFI array to a Lisp
object, and return that object.

If the element type is one of
.codn char ,
.code bchar
or
.codn wchar ,
then the expected string conversion semantics applies.

.coNP Functions @ carray-put and @ carray-putz
.synb
.mets (carray-put < carray << new-val )
.mets (carray-putz < carray << new-val )
.syne
.desc
The
.code carray-put
and
.code carray-putz
functions treat the contents of
.meta carray
as a FFI
.code array
and
.code zarray
type, respectively.

They invoke the put semantics to convert the Lisp object
.meta new-val
array to the foreign array representation, which is placed into
the array storage referenced by
.metn carray .

If the element type is one of
.codn char ,
.code bchar
or
.codn wchar ,
then the expected string conversion semantics applies.

Both of these functions return
.metn carray .

.coNP Accessor @ carray-sub
.synb
.mets (carray-sub < carray >> [ from <> [ to ]])
.mets (set (carray-sub < carray >> [ from <> [ to ]]) << new-val )
.syne
.desc
The
.code carray-sub
function extracts a subrange of a
.meta carray
object, returning a new
.code carray
object denoting that subrange.

The semantics of
.meta from
and
.meta to
work exactly like the corresponding arguments of the
.code sub
accessor, following the same conventions.

The returned
.code carray
shares the array has the same element type as the original and
shares the same array storage. If, subsequently, elements of the
original array are modified which lie in the range, then the
modifications will affect the previously returned subrange
.codn carray .
The returned
.code carray
references the original object, to ensure that as long as the returned object
is reachable by the garbage collector, so is the original.  This relationship
can be severed by invoking
.code carray-dup
on the returned object, after which the two no longer share storage,
and modifications in the original are not reflected in the subrange.

If
.code carray-sub
is used as a syntactic place, the argument expressions
.metn carray ,
.metn from ,
.meta to
and
.meta new-val
are evaluated just once. The prior value, if required, is accessed by calling
.code carray-sub
and
.meta new-val
is then stored via
.codn carray-replace .

.coNP Function @ carray-replace
.synb
.mets (carray-replace < carray < item-sequence >> [ from <> [ to ]])
.syne
.desc
The
.code carray-replace
function is a specialized version of
.code replace
which works on
.code carray
objects. It replaces a sub-range of
.meta carray
with elements from
.metn item-sequence .
The replacement sequence need not have the same length
as the range which it replaces.

The semantics of
.meta from
and
.meta to
work exactly like the corresponding arguments of the
.code replace
function, following the same conventions.

The semantics of the
.code carray-replace
operation itself differs from the
.code replace
semantics on sequences in one important regard: the
.code carray
object's length always remains the same.

The range indicated by
.meta from
and
.meta to
is deleted from
.meta carray
and replaced by elements of
.metn item-sequence ,
which undergo conversion to the foreign type that defines the
elements of
.metn carray .

If this operation would make the
.code carray
longer, any elements in excess of the object's length are discarded,
whether they are the original elements, or whether they come from
.metn item-sequence .
Under no circumstances does
.code carray-replace
write an element beyond the length of the underlying storage.

If this operation would make the
.meta carray
shorter (the range being replaced is longer than
.metn item-sequence )
then the downward relocation of items above the replacement range
creates a gap at the end of
.meta carray
which is filled with zero bytes.

The return value is
.meta carray
itself.

.coNP Function @ carray-pun
.synb
.mets (carray-pun < carray << type )
.syne
.desc
The
.code carray-pun
creates a new
.code carray
object which provides an aliased view of the same data that is referenced by
the original
.meta carray
object.

The
.meta type
argument specifies the element type used by the returned aliasing array.

The
.code carray-pun
function considers the byte size of the array, which is a product of
the original length and element size. It then calculates how many elements of
.meta type
fit into this size. This value becomes the length of the aliasing array
which is returned.

Since the returned aliasing array and the original refer to the same
storage, modifications performed in one view are reflected in the other.

The aliasing array holds a reference to the original, so that as long as
it is reachable by the garbage collector, so is the original.
That relationship is severed if
.code carray-dup
is invoked on the aliasing array.

The meaning of the aliasing depends entirely on the bitwise representations of
the types involved.

.coNP Functions @ carray-uint and @ carray-int
.synb
.mets (carray-uint < number <> [ type ])
.mets (carray-int < number <> [ type ])
.syne
.desc
The
.code carray-uint
and
.code carray-int
functions convert
.metn number ,
an integer, to a binary image, which is then used as
the underlying storage for a
.codn carray .

The
.meta type
argument, a compiled FFI type, determines the element type for the returned
.codn carray .
If it is omitted, it defaults to the
.code uint
type, so that the array is effectively of bytes.

Regardless of
.metn type ,
these functions first determine the number of bytes required to represent
.meta number
in a big endian format. Then the number of elements is determined for the
array, so that it provides at least as that many bytes of storage. The
representation of
.meta number
is then placed into this storage, such that its least significant byte
coincides with the last byte of that storage. If the number is smaller
than the storage provided by the array, it extended with padding bytes on the
left, near the beginning of the array.

In the case of
.codn carray-uint ,
.meta number
must be a non-negative integer. An unsigned representation is produced
which carries no sign bit. The representation is as many bytes wide as
are required to cover the number up to its most significant bit whose
value is 1. If any padding bytes are required due to the array being larger,
they are always zero.

The
.code carray-int
function encodes negative integers also, using a variable-length two's
complement representation. The number of bits required to hold the number
is calculated as the smallest width which can represent the value in two's
complement, including a sign bit.  Any unused bits in the most significant
byte are filled with copies of the sign bit: in other words, sign extension
takes place up to the byte size.  The sign extension continues through the
padding bytes if the array is larger than the number of bytes required to represent
.metn number ;
the padding bytes are filled with the value
.code #b11111111
(255) if the number is negative, or else 0 if it is non-negative.

.coNP Functions @ uint-carray and @ int-carray
.synb
.mets (uint-carray << carray )
.mets (int-carray < number <> [ type ])
.syne
.desc
The
.code uint-carray
and
.code int-carray
functions treat the storage bytes
.meta carray
object as the representation of an integer.

The
.code uint-carray
function simply treats all of the bytes as a big-endian unsigned integer in
a pure binary representation, and returns that integer, which is necessarily
always non-negative.

The
.code int-carray
function treats the bytes as a two's complement representation. The returned
number is negative if the first storage byte of
.meta carray
has a 1 in the most significant bit position: in other words, is in the
range
.code #x80
to
.codn #xFF .
In this case, the two's complement of the entire representation is calculated:
all of the bits are inverted, the resulting positive integer is extracted.
Then 1 is added to that integer, and it is negated. Thus, for example, if all
of the bytes are
.codn #xFF ,
the value -1 is returned.

.coNP Functions @ fill-carray and @ put-carray
.synb
.mets (fill-array < carray >> [ pos <> [ stream ]])
.mets (put-array < carray >> [ pos <> [ stream ]])
.syne
.desc
The
.code fill-array
and
.code put-array
functions perform stream output using the
.code carray
object as a buffer.

The semantics of these functions is as follows.
A temporary buffer is created which aliases the storage of
.meta carray
and this buffer is used as an argument in an invocation of, respectively,
the buffer I/O function
.meta fill-buf
or
.metn put-buf .

The value returned by buffer I/O function is returned.

The
.meta pos
and
.meta stream
arguments are defaulted exactly in the same manner as by
.code fill-buf
and
.codn put-buf ,
and have the same meaning. In particular,
.meta pos
indicates a byte offset into the
.meta carray
object's storage, not an array index.

.SH* LISP COMPILATION

.SS* Overview

\*(TX supports two modes of processing of Lisp programs: evaluation and compilation.

Expressions entered into the listener, loaded from source files via
.codn load ,
processed by the
.code eval
function, or embedded into the \*(TX pattern language, are processed by the
.IR evaluator .
The evaluator expands all macros, and then interprets the program
by traversing its raw syntax tree structure. It uses an inefficient
representation of lexical variables consisting of heap-allocated environment
objects which store variable bindings as Lisp association lists. Every time a
variable is accessed, the chain of environments is searched for the binding.

\*(TX also provides a compiler and virtual machine for more efficient execution
of Lisp programs. In this mode of processing, top-level expressions are
translated into the instructions of Lisp-oriented virtual machine. The virtual
machine language is traversed more efficiently compared to the traversal of the
cons cells of the original Lisp syntax tree. Moreover, compiled code uses a
much more efficient representation for lexical variables which doesn't involve
searching through an environment chain. Lexical variables are always allocated
on the stack (the native one established by the operating system). They are
transparently relocated to dynamic storage only when captured by lexical
closures, and without sacrificing access speed.

\*(TX provides the function
.code compile
for compiling individual functions, both anonymous and named. File compilation
is supported via the function
.codn compile-file .
The function
.code compile-toplevel
is provided for compiling expressions in the global environment. This
function is the basis for both
.code compile
and
.codn compile-file .

The
.code disassemble
function is provided to list the compiled code in a more understandable way;
.code disassemble
takes a compiled code object and decodes it into an assembly language
presentation of its virtual machine code, accompanied by a dump of the various
information tables.

File compilation via
.code compile-file
refers to a processing step whereby a source file containing \*(TL forms
(typically named with a
.code .tl
file name suffix) is translated into an object file (named with a
.code .tlo
suffix) containing a compiled version of those forms.

The compiled object file can then be loaded via the
.code load
function instead of the source file. Usually, loading the compiled file
produces the same effect as if the source file were loaded. However, note that
the behavior of compiled code can differ from interpreted code in a number of
ways. Differences in behavior can be deliberately induced.  Certain erroneous
or dubious situations can also cause compiled code to behave differently from
interpreted code.

Compilation not only provides faster execution; compiled files also load much
faster than source files. Moreover, they can be distributed unaccompanied by
the source files, and resist reverse engineering.

.SS* Top-Level Forms

An important concept in file compilation via
.code compile-file
is that of the
.IR "top-level form" ,
and how that term is defined.  The file compiler individually processes
top-level forms; for each such form, it emits a translated image.

In the context of file compilation, a top-level form isn't simply any Lisp form
which is not enclosed by another one.  Rather, in this specific context, it has
this specific definition, which allows some enclosed forms to still be
considered top-level forms:

.RS
.IP 1.
If a form appearing in a \*(TL source file isn't enclosed in another
form, it is a top-level form.
.IP 2.
If a
.code progn
form is top-level form, then each of its constituent forms is also a top-level
form.
.IP 3.
If a
.code compile-only
form is top-level form, then each of its constituent forms is also a top-level
form.
.IP 4.
If an
.code eval-only
form is top-level form, then each of its constituent forms is also a top-level
form.
.IP 5
If a
.code load-time
form is top-level form, then its argument is a top-level form.
.IP 6.
When a form is identified as a top-level form by the above rule 1,
its constituents are considered under rules 2-4 only after the form is
fully macro-expanded.
.IP 7.
No other forms are top-level forms.
.RE

A top-level form is a
.I primary
top-level form if it doesn't contain any other top-level forms.
This means that it is not a form based on any of the operators
.codn progn ,
.code compile-only
or
.codn eval-only .

.SS* File Compilation Model

The file compiler reads each successive forms from a file, performs a partial
expansion on that form, then traverses it to identify all of the
top-level forms which it contains. Each top-level form is subject to
three actions, either of the latter two of which may be omitted: compilation,
execution and emission. Compilation refers to the translation to compiled form.
Execution is the invocation of the compiled form. Emission refers to appending
an externalized representation of the compiled form (its image) to the output
which is written into the compiled file.

By default, all three actions take place for every top-level form. Using the
operators
.code compile-only
or
.codn eval-only ,
execution or emission, or both, may be suppressed. If both are suppressed,
then compilation isn't performed; the forms processed in this mode are
effectively ignored.

When a compiled file is loaded, the images of compiled forms are read from
it and converted back to compiled objects, which are executed in sequence.

Partial expansion means that file compilation doesn't fully expand each
form that is encountered. Rather, an incremental expansion is performed,
similar to the algorithm used by the
.code eval
function:
.RS
.IP 1
First, if
.meta form
is a macro, it is macro-expanded as if by an application of the function
.codn macroexpand .
.IP 2
If the resulting expanded form is a
.codn progn ,
.codn compile-only ,
or
.code eval-only
form, then
.code compile-file
iterates over that form's argument expressions, compiling each expression
recursively as if it were a separate expression.
.IP 3
Otherwise, if the expanded form isn't one of the above three kinds of
expressions, it is subject to a full expansion and compilation.
.RE
.SS* Treatment of Literals

Programs specify not only code, but also data. Data embedded in a program is
called
.IR "literal data" .
There are restrictions on what kinds of object may be used as literal data
in programs subject to file compilation. Programs which stray outside of these
restrictions will produce compiled files which load incorrectly or fail to
load.

Literal objects arise not only from the use of literal such as numbers,
characters and strings, and not only from quoted symbols or lists.
For instance, compiled forms which define or reference free variables or global
functions require the names of these variables or functions to be represented
as literals.

An object used as a literal in file-compiled code must be
.I externalizable
which means that it has a printed representation which can be scanned to
produce a similar object. An object which does not have a readable printed
representation will give rise to a compiled file which triggers an exception.
Literals which are themselves read from program source code naturally meet this
restriction; however, with the use of macros, it is possible to embed arbitrary
objects into program code.

If the same object appears in two or more places in the code specified in a
single file, the file compilation and loading mechanism ensures that the
multiple occurrences of that object in the compiled file become a single object
when the compiled file is loaded. For example, if macros are used in such a way
that the compiled file defines a function which has a name generated by
.codn gensym ,
and there are calls to that function throughout that file, this will work
properly: the multiple occurrences of the gensym will appear as the same symbol.
However: that symbol in the loaded file will not be identical to any other
symbol in the \*(TX image; it will be newly allocated each time the compiled
file is loaded.

Interned symbols are recorded in a compiled file by means of their textual
names and package prefixes. When a compiled file is loaded, the interned
symbols which occur as literals in it are entered into the specified packages
under the specified names. The value of the
.code *package*
special variable has no influence on this.

Circular structures in compiled literals are preserved; on loading, similar
circular structures are reproduced.

.SS* Treatment of The Hash Bang Line

\*(TX supports the hash bang mechanism in compiled
.code .tlo
files, thereby allowing compiled scripts to be executable.

When a source file begins with the
.code #!
("hash-bang") character sequence, the file compiler propagates that
line (all characters up to and including the terminating newline) to the
compiled file, subject to the following transformation: occurrences of
.str --lisp
which are not followed by a dash are replaced with
.strn --compiled .

Furthermore, certain permissions are propagated from a hash bang source
file to the target file. If the source file is executable to its owner,
then the target file is made executable as if by using
.code chmod
with the
.code +x
mode: all the executable permissions that are allowed by the current
.code umask
are are enabled on the target file. If the target file is thus being marked
executable, then additional permissions are also treated as follows.  If the
target file has the same owner as the source file, and the source file's setuid
permission bit is set, then this is propagated to the target file. Similarly,
if the target file has the same group owner as the source file, and the source
file's group execute bit and setgid permission bit are set, then the setgid
bit is set on the target file.

.SS* Compiled File Compatibility

\*(TX's virtual machine architecture for executing compiled code
is evolving, and that evolution has implications for the compatibility between
compiled files the \*(TX executable image.

The basic requirement is that a given version of \*(TX can load and execute
the compiled files which that same version has produced.

Furthermore, these files are architecture-independent, except that their
encoding is in the local byte order ("endianness") of the host machine.
The byte order is explicitly indicated in the files, and the
.code load
function resolves it. Thus a file produced by \*(TX running on a 64 bit big
endian Power PC can be loaded by \*(TX running on 32 bit x86, which is
little endian.

A given \*(TX version may also be capable of loading files produced by
an older version, or even ones produced by a newer version. Whether this
is possible depends on the versions involved.

Compiled files contain a minor and major version number (which is independent
of the \*(TX version). The
.code load
function examines these numbers and decides whether the file is loadable,
or whether it must be rejected.

The first version of \*(TX which featured the compiler and virtual machine was
191. Older versions therefore cannot load compiled files.

Versions 191 and 192 produce version 1 compiled files, and load only that
version.

Versions 193 through 198 produce version 2 compiled files and load only
that version.

Version 199 produces version 3 files and loads version 2 or 3.

Versions 200 through 215 produce version 4 files and load version 2, 3 or 4.

Versions 216 through 243 produce version 5.0 files and load
version 2, 3, 4 or 5, regardless of minor version.

Versions 244 through 246 produce version 5.1 files and load
version 2, 3, 4 or 5, regardless of minor version.

.SS* Semantic Differences between Compilation and Interpretation

The
.code compile-only
and
.code eval-only
operators can be used to deliberately produce code which behaves differently
when compiled and interpreted. In addition, unwanted differences in behavior
can also occur. The situations are summarized below.

.coNP Differences due to @ load-time

Forms evaluated by
.code load-time
are treated differently by the compiler. When a top-level form is compiled,
its embedded
.code load-time
forms are factored out such that the compiled image of the top-level form
will evaluate these forms before other evaluations take place.
The interpreter doesn't perform this factoring; it evaluates a
.code load-time
form when it encounters it for the first time.

.coNP Treatment of literals

The compiler identifies multiple occurrences of equivalent strings and bignum
integers that occur as literals, and condenses each one to a single instance,
within the scope of the compilation. The scope is possibly as wide as a file.

If the literal
.str abc
appears in multiple places in the same file that is processed by
.codn compile-file ,
in the resulting compiled file, there may be just a single
.str abc
object. For instance, if the file contains two functions:

.verb
  (defun f1 () "abc")
  (defun f2 () "abc")
.brev

when compiled, these will return the same object such that

.verb
  (eq (f1) (f2)) -> t
.brev

No such de-duplication is performed for interpreted code.

Consequently, code which depends on multiple occurrences of these objects to be
distinct objects may behave correctly when interpreted, but misbehave when
compiled. Or
.IR "vice versa .
One example is code which modifies a string literal.
Under compilation, the change will affect all occurrences of that literal
that have been merged into one object.  Another example is an
expression like
.codn "(eq \(dqabc\(dq \(dqabc\(dq)" ,
which yields
.code nil
under interpretation because the two strings are distinct object in spite
of appearing side by side in the syntax, but
.code t
when compiled, since they denote the same string object.

In the future, objects other than strings and bignums may be similarly
consolidated, such as lists and vectors, which means that interpreted
code which works today when compiled may misbehave in the future.

Note that objects which are literally notated in source code are not the only
kinds of objects considered to be literals.  Objects which are constructed by
macros and inserted into macro-expansions are also literals.  Literals are
self-evaluating objects that appear as expressions in the syntax which remains
after macro-expansion, as well as arguments of the
.code quote
operator. If a macro calculates a new string each time it is expanded,
and inserts it into the expansion as a literal, the compiler will identify
and consolidate groups of such strings that are identical.

.coNP Treatment of unbound variables

Unbound variables are treated differently by the compiler. A reference
to an unbound variable is treated as a global lexical access. This means that
if a variable access is compiled first and then a
.code defvar
is processed which introduces the variable as a dynamically scoped ("special")
variable, the compiled code will not treat the variable as special; it
will refer to the global binding of the variable, even when a dynamic binding
for that variable exists.  The interpreter treats all variable references
that do not have lexical bindings as referring to dynamic variables.
The compiler treats a variable as dynamic if a
.code defvar
has been processed which marked that variable as special.

.coNP Unbound symbols in @ dwim

Arguments of a
.code dwim
form (or the equivalent bracket notation) which are unbound
symbols are treated differently by the
compiler. The code is compiled under the assumption that all such symbols
refer to global functions. For instance, if neither
.code f
nor
.code x
are defined, then
.code "[f x]"
will be compiled under the assumption that they are functions.  If they are
later defined as variables, the compiled code will fail because no function
named
.code x
exists. The interpreter resolves each symbol in a
.code dwim
form at the time the form is being executed. If a symbol is defined
as a variable at that time, it is accessed as a variable. If it defined as a
function, it is accessed as a function.

.coNP Bound symbols in @ dwim

The symbolic arguments of a
.code dwim
form that refer to global bindings are also treated differently by the compiler.
For each such symbol, the compiler determines whether it refers to a
function or variable and, further, whether the variable is global lexical or
special. This treatment of the symbol is then cemented in the compiled code;
the compiled code will treat that symbol that way regardless of the
run-time situation. By contrast, the interpreter performs this classification
each time the arguments of a
.code dwim
form are evaluated. The rules are otherwise the same: if the symbol is bound as
a variable, it is treated as a variable. If it is bound as a function, it is
treated as a function. If it has both bindings, it is treated as a variable.
The difference is that this is resolved at compile time for compiled code,
and at evaluation time for interpreted code.

.coNP File-wide insertion of gensyms

The following degenerate situation occurs, illustrated by example. Suppose the
following definitions are given:

.verb
  (defvarl %gensym%)

  (defmacro define-secret-fun ((. args) . body)
    (set %gensym% (gensym))
    ^(defun ,%gensym% (,*args) ,*body))

  (defmacro call-secret-fun (. args)
    ^(,%gensym% ,*args))
.brev

The idea is to be able to define a function whose name is an uninterned
symbol and then call it. An example module might use these definitions as
follows:

.verb
  (define-secret-fun (a) (put-line `a is @a`))

  (call-secret-fun 42)
.brev

The effect is that the second top-level form calls the function, which
prints 42 to standard out. This works both interpreted and compiled with
.codn compile-file .
Each of these two macro calls generates a top-level form into which
the same gensym is inserted. This works under file compilation due to a
deliberate strategy in the layout of compiled files, which allows such
uses. Namely, the file compiler combines multiple top-level forms are combined
into a single object, which is read at once, and which uses the circle
notation to unify gensym references.

However, suppose the following change is introduced:

.verb
  (define-secret-fun (a) (put-line `a is @a`))

  (defpackage foo) ;; newly inserted form

  (call-secret-fun 42)
.brev

This still works when interpreted, and compiles successfully. However, when the
compiled file is loaded, the compiled version of the
.code call-secret-fun
form fails with an error complaining that the
.code #:g0039
(or other gensym name) function is not defined.

This is because for this modified source file, the file compiler is not
able to combine the compiled forms into a single object. It would not
be correct to do so in the presence of the
.code defpackage
form, because the evaluation of that form affects the subsequent interpretation
of symbols. After the package definition is executed, it is possible for
a subsequent top-level form to refer to a symbol in the
.code foo
package such as
.code foo:bar
to occur, which would be erroneous if the package didn't exist.

The file compiler therefore arranges for the compiled forms after the
.code defpackage
to be emitted into a separate object. But that division in the output file
consequently prevents the occurrences of the gensym to resolve to the same
symbol object.

In other words, the strategy for allowing global gensym use is in conflict
with support for forms which have a necessary read-time effect such as
.codn defpackage .

The solution is to rearrange the file to unravel the interference, or
to use interned symbols instead of gensyms.

.coNP Delimited Continuations

There are differences in behavior between compiled and interpreted code
with regard to delimited continuations. This is covered in the
Delimited Continuations section of the manual.

.SS* Compilation Library

.coNP Function @ compile-toplevel
.synb
.mets (compile-toplevel < form << expanded-p )
.syne
.desc
The
.code compile-toplevel
function takes the Lisp form
.meta form
and compiles it. The return value is a
.I "virtual machine description"
object representing the compiled form. This object isn't of function type, but may be
invoked as if it were a function with no arguments.

Invoking the compiled object is expected to produce the same effect as
evaluating the original
.meta form
using the
.code eval
function.

The
.meta expanded-p
argument indicates that
.meta form
has already been expanded and is to be compiled without further expansion.

If
.meta expanded-p
is
.codn nil ,
then it is subject to a full expansion.

Note: in spite of the name,
.code compile-toplevel
makes no consideration whether or not
.meta form
is a "top-level form" according to the definition of that term
as it applies to
.code compile-file
processing.

Note: a form like
.code "(progn (defmacro foo ()) (foo))"
will not be processed by
.code compile-toplevel
in a manner similar to the processing by
.code eval
or
.codn compile-file .
In this example,
.code defmacro
form will not be evaluated prior to the expansion of
.code "(foo)"
(and in fact not evaluated at all)
and so the latter expression isn't correctly referring to that macro.
The form
.code "(progn (macro-time (defmacro foo ())) (foo))"
can be processed by
.codn compile-toplevel ;
however, the macro definition now takes place during expansion, and isn't
compiled.
The
.code compile-file
function has no such issue when it encounters such a form at the top-level,
because that function will consider a top-level
.code progn
form to consist of multiple top-level forms that are compiled
individually, and also executed immediately after being compiled.

.TP* Example

.verb
  ;; compile (+ 2 2) form and execute to calculate 4
  ;;
  (defparm comp (compile-toplevel '(+ 2 2)))

  (call comp) -> 4

  [comp] -> 4
.brev

.coNP Function @ compile
.synb
.mets (compile << function-name )
.mets (compile << lambda-expression )
.mets (compile << function-object )
.syne
.desc
The
.code compile
function compiles functions.

It can compile named functions when
the argument is a
.metn function-name .
A function name is a symbol denoting an existing interpreted function,
or compound syntax such as
.mono
.meti (meth < type << name )
.onom
to refer to methods. The code of the interpreted function is retrieved,
compiled in a manner which produces an anonymous compiled function,
and then that function replaces the original function under the same name.

If the argument is a lambda expression, then that function is
compiled.

If the argument is a function object, and that object is an interpreted
function, then its code is retrieved and compiled.

In all cases, the return value of
.code compile
is the compiled function.

.coNP Functions @ compile-file and @ compile-update-file
.synb
.mets (compile-file < input-path <> [ output-path ])
.mets (compile-update-file < input-path <> [ output-path ])
.syne
.desc
The
.code compile-file
function reads forms from an input file, and produces a compiled output file.

First,
.meta input-path
is converted to a
.I "tentative path name"
as follows.

If
.meta input-path
specifies a pure relative pathname, as defined by the
.code pure-rel-path-p
function, then a special behavior applies.
If an existing load operation is in progress, then the special variable
.code *load-path*
has a binding. In this case,
.code load
will assume that the relative pathname is a reference relative to the
directory portion of that path name.

If
.code *load-path*
has the value
.codn nil ,
then a pure relative
.meta input-path
pathname is used as-is, and thus resolved relative to the current working
directory.

The tentative path name is converted to an
.I "actual input path name"
as follows. Firstly, if the tentative path name ends with one of the suffixes
.code .tl
or
.code .txr
then it is considered suffixed, otherwise it is considered unsuffixed.
If it is suffixed, then the actual path name is the same as the tentative path name.
In the unsuffixed case, two possible actual input path names are formed. First,
the suffix
.code .tl
is added to the tentative path name. If that path exists, it is taken
taken as the actual path. Otherwise, the unmodified tentative path
is taken as the actual input path.

If the actual path ends in the suffix
.code .txr
then the behavior is unspecified.

If the
.meta output-path
parameter is given an argument, then that argument specifies the
output path.
Otherwise the output path is derived from the tentative input path
as follows. If the tentative input path is unsuffixed, then
.code .tlo
is added to it to produce the output path.
Otherwise, the suffix is removed from the tentative input path
and replaced with the
.code .tlo
suffix.

The
.code compile-file
function binds the variables
.code *load-path*
and
.code *package*
similarly to the
.code load
function.

Over the compilation of the input file,
.code compile-file
establishes a new dynamic binding for several special
variables. The variable
.code *load-path*
is given a new binding containing the actual input path name.
The
.code *package*
variable is also given a new dynamic binding, whose value is the
same as the existing binding. Thus if the compilation of the
file has side the effect of altering the value of
.codn *package* ,
that effect will be undone when the binding is removed
after the compilation completes.

Compilation proceeds according to the File Compilation Model.

If the compilation process fails to produce a successful translation
for each form in the input file, the output file is removed.

The
.code compile-update-file
function differs from
.code compile-file
in the following regard: compilation is performed only if the input
file is newer than the output file, or else if the output file doesn't
exist.

The
.code compile-file
always returns
.code t
if it terminates normally, which occurs if it successfully translates
every form in the input file, depositing the translation into the output
file. If compilation fails,
.code compile-file
terminates by throwing an exception.

The
.code compile-update-file
function returns
.code t
if it successfully compiles, similarly to
.codn compile-file .
If compilation is skipped, the function returns
.codn nil .

Note: the following idiom may be used to load a file, compiling it if
necessary:

.verb
  (or (compile-update-file "file")
      (load-file "file"))
.brev

However, note that it relies on the effect of compiling a source file being the
same as the effect of loading the compiled file.
This can only be true if the source file contains no
.code compile-only
or
.code eval-only
top-level forms.

.coNP Macro @ with-compilation-unit
.synb
.mets (with-compilation-unit << form *)
.syne
.desc
When a file is processed by
.codn compile-file ,
certain actions, such as the issuance of diagnostics about undefined functions
and variables, are delayed until the file is completely processed.

The
.code with-compilation-unit
macro allows these actions to be collectively deferred until multiple files
are completely processed.

The macro evaluates each enclosed
.meta form
in a single compilation environment. After the last
.meta form
is evaluated, deferred actions of any enclosed
.code compile-file
forms are performed, and then the value of the last
.meta form
is returned.

It is permissible to nest
.code with-compilation-unit
forms, lexically or dynamically. The outer-most invocation of
.code with-compilation-unit
dominates; all deferred
.code compile-file
actions are held until the outer-most enclosing
.code with-compilation-unit
terminates.

.coNP Operators @ compile-only and @ eval-only
.synb
.mets (compile-only << form *)
.mets (eval-only << form *)
.syne
.desc
These operators take on a special behavior only when they appear as top-level forms
in the context of file compilation.
When a
.code compile-only
or
.code eval-only
form is processed by the evaluator rather than compiler, or when it is
processed outside of file compilation, or when it is appears as other than a
top-level form even under file compilation, then these operators behave
in a manner identical to
.codn progn .

When a
.code compile-only
form appears as a top-level form under file compilation, it indicates to the
file compiler that the
.metn form -s
enclosed in it are not to be evaluated. By default, the file compiler executes
each top-level form after compiling it.  The
.code compile-only
operator suppresses this evaluation.

When a
.code eval-only
form appears as a top-level form under file compilation, it indicates to the
file compiler that the
.metn form -s
enclosed in it are not to be emitted into the output file. By default, the file
compiler includes the compiled image in the output written to the output file.
The
.code eval-only
operator suppresses this inclusion.

Forms which are surrounded by both an
.code eval-only
form and a
.code compile-only
form are neither executed nor emitted into the output file. In this situation,
the forms are skipped entirely; no compilation takes place.

.TP* Notes:

The
.code compile-file
function not only compiles, but also executes every form for the following
reason: the correct compilation of forms can depend on the execution of earlier
forms. For instance, code may depend on macros. Macros may in turn depend on
functions and variables. All those definitions are required in order to compile
the dependent code. Those dependencies may be in a separate file which is
loaded by a
.code load
form; that
.code load
form must be executed.

Note that execution of a form implies that the
.code load-time
forms that it contains are evaluated (prior to other evaluations). Suppression
of the execution of a form also suppresses the evaluation of
.code load-time
forms.

Situations in which
.code compile-only
is useful are those in which it is desirable to stage the execution of some
top-level form into the compiled file, and not have it happen during
compilation. For instance:

.verb
   ;; in a main module
   (compile-only (start-application))
.brev

It is not desirable to have the file compiler try to start the application
as a side effect of compiling the main module. The right behavior is to
compile the
.code "(start-application)"
top-level form so that this will happen when that module is loaded.

Situation in which
.code eval-only
is useful is for specifying forms which have a compile-time effect only,
but are not propagated into the compiled file.

For example, since the correct treatment of literal symbols occurring in a
compiled file does not depend on the
.code *package*
variable, in many cases, the
.code in-package
invocation in the file can be wrapped with
.codn eval-only :

.verb
  (eval-only (in-package app))
.brev

The
.code in-package
form must be evaluated during compilation so that the remaining forms are read
in the correct package. However the loading of the compiled versions of those
forms doesn't require that package to be in effect; thus a compiled image
of the
.code in-package
form need not appear in the compiled file.

Macros definitions may be treated with
.code eval-only
if the intent is only to make the expanded code available in the compiled file,
and not to propagate compiled versions of the macros which produced it.

.coNP Macro @ load-time
.synb
.mets (load-time << form )
.syne
.desc
The
.code load-time
macro makes it possible for a program to evaluate a form, such that,
subsequently, the value of that form is then treated as if it were
a literal object.

Literals are pieces of the program syntax which are not evaluated at all.
On the other hand, the values of expressions are not literals.

From time to time, certain situations benefit from the program being
able to perform an evaluation, and then have the result of that evaluation
treated as a literal.

There is already an operator named
.code macro-time
which makes this possible in its particular manner: that operator
allows one or more expressions to be evaluated during macro expansion.
The result of the
.code macro-time
is then quoted and substituted in place of the expression. That result
then appears as a true quoted literal to the executing code.

The
.code load-time
macro similarly arranges for the single form
.meta form
to be evaluated. However, this evaluation doesn't take place at
expansion time. It is delayed until the program executes.

What exactly "delayed until the program executes" means depends on whether
.code load-time
is used in compiled or interpreted code, and in what situation is
it compiled.

If the
.code load-time
form appears in interpreted code, then the exact time when
.meta form
is evaluated is unspecified. The evaluator may identify all
.code load-time
forms which occur anywhere in a top-level expression, and perform
their evaluations immediately, before evaluating the form itself.
Then, when the
.code load-time
forms are encountered again during the evaluation of the form,
they simply retrieve the previously evaluated values as if
they were literal.  Or else, the evaluation may be performed late: when the
.code load-time
form itself is encountered during normal evaluation. In that case,
.meta form
will still be evaluated only once and then its value will be be
inserted as a literal in subsequent re-evaluations of that
.code load-time
form, if any.

If a
.code load-time
form appears in a non-top-level expression which is compiled, the
compiler arranges for the compiled version of
.meta form
to be executed when compiled version of the entire expression is
executed. This execution occurs early, before the execution of
forms that are not wrapped in
.codn load-time .
The value produced by
.code form
is entered into the static data vector associated with the
compiled top-level expression, which also holds ordinary literals.
Whenever the value of that
.code load-time
form is required, the compiled code references it from the data
vector as if it were a true literal.

When a
.code load-time
top-level form is processed by
.codn compile-file ,
it has no unusual semantics; the effect is that it is replaced by
its argument
.metn form ,
which is in that case also considered a top-level form.

The implications of the translation scheme may be understood
separately from the perspective of code processed with
.codn compile-toplevel ,
.code compile
and
.codn compile-file .

A
.code load-time
form appearing in a form passed to
.code compile-toplevel
is translated such that its embedded
.meta form
will be executed each time the virtual machine description returned by
.code compile-toplevel
is executed, and the execution of all such forms is placed ahead
of other code.

A
.code load-time
form appearing in an interpreted function which is processed by
.code compile
is evaluated immediately, and its value becomes a literal
in the compiled version of the function.

A
.code load-time
form appearing as a non-top-level form inside a file that is processed by
.code compile-file
is compiled along with that form and deposited into the object file.
When the object file is loaded, each compiled top-level form is executed.
Each compiled top-level form's
.code load-time
calculations are executed first, and the corresponding
.meta form
values become literals at that point. This execution order is individually
ensured for each top-level form.
Thus, the
.code load-time
forms in a given top-level form may rely on the side-effects of
prior top-level forms having taken place.
Note that, by default,
.code compile-file
also immediately executes each top-level form which it compiles and deposits
into the output file. This execution is equivalent to a load; it causes
.code load-time
forms to be evaluated. The
.code compile-only
operator must be used around
.code load-time
forms which must be evaluated only when the compiled file is loaded,
and not at compile time.

In all situations, the evaluation of
.meta form
takes place in the global environment. Even if the
.code load-time
form is surrounded by constructs which establish lexical bindings,
those lexical bindings aren't visible to
.metn form .
Which dynamic bindings are visible to
.meta form
depends on the exact situation. If a
.code load-time
form occurs in code that had been processed by
.code compile-file
and is now being loaded by
.codn load ,
then the dynamic environment in effect is the one in which the
.code load
occurred, with any modifications to that environment that were performed
by previously executed forms. If a
.code load-time
form occurs in code that had been processed by
.codn compile-toplevel ,
then
.meta form
is evaluated in the dynamic environment of the caller which invokes
the execution of the resulting compiled object.
When a
.code load-time
form occurs in the code of an function being processed by
.codn compile ,
then
.meta form
is evaluated in the dynamic environment of the caller which invokes
.codn compile .
If a
.code load-time
form occurs in a form processed processed by the evaluator, it is unspecified
whether it takes place in the original dynamic environment in which the
evaluator was invoked, or whether it is in the dynamic environment of
the immediately enclosing form which surrounds the
.code load-time
form.

A
.code load-time
form may be nested inside another
.code load-time
form. In this situation, two cases occur.

If the two forms are not embedded in a
.codn lambda ,
or else are embedded in the same
.codn lambda ,
then the inner
.code load-time
form is superfluous due to the presence of the outer
.codn load-time .
That is to say, the inner
.mono
.meti (load-time << form )
.onom
expression is equivalent to
.metn form ,
because the outer form already establishes its evaluation to be in a load-time
context.

If the inner
.code load-time
form occurs in a
.codn lambda ,
but the outer form occurs outside of that
.codn lambda ,
then the semantics of the inner
.code load-time
form is relevant and necessary. This is because expressions occurring in a
.code lambda
are evaluated when the
.code lambda
is called, which may take place from a non-load-time context, even if the
.code lambda
itself was produced in a load-time context.

An expression being embedded in a
.code lambda
means that it appears either in the
.code lambda
body, or else in the parameter list as the initializing
expression for an optional parameter.

.TP* Notes:

When interpreted code containing
.code load-time
is evaluated, a mutating side effect may take place
on the tree structure of that code itself as a result of the
.code load-time
evaluation.
If that previously evaluated code is subsequently compiled, the compiled
translation may be different from compiling the original unevaluated code.
Specifically, the compiler may take advantage of the
.code load-time
evaluation which had already taken place in the interpreter, and simply take
that value, and avoid compiling
.meta form
entirely. This also has implications on the dynamic environment
that is in effect when
.meta form
is evaluated. If
.meta form
is evaluated by the interpreter, then it interacts with the dynamic environment
which as in effect in that situation; then when the compiler later just takes
the result of that evaluation, the compiler's dynamic environment is irrelevant
since
.meta form
isn't being evaluated any more.

If
.metn form ,
when evaluated multiple times, potentially produces a different value on each
evaluation, this has implications for the situation when an object produced by
.code compile-toplevel
is invoked multiple times. Each time such an object is invoked, the