aboutsummaryrefslogtreecommitdiff
path: root/docs/book/print.html
blob: 6361bdd1793170952bf877329ee5b7547965c616 (plain) (blame) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544

<!DOCTYPE HTML>
<html lang="en" class="light" dir="ltr">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>The Puck Programming Language</title>
        <meta name="robots" content="noindex">


        <!-- Custom HTML head -->

        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff">

        <link rel="icon" href="favicon.svg">
        <link rel="shortcut icon" href="favicon.png">
        <link rel="stylesheet" href="css/variables.css">
        <link rel="stylesheet" href="css/general.css">
        <link rel="stylesheet" href="css/chrome.css">
        <link rel="stylesheet" href="css/print.css" media="print">

        <!-- Fonts -->
        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
        <link rel="stylesheet" href="fonts/fonts.css">

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="highlight.css">
        <link rel="stylesheet" href="tomorrow-night.css">
        <link rel="stylesheet" href="ayu-highlight.css">

        <!-- Custom theme stylesheets -->

    </head>
    <body class="sidebar-visible no-js">
    <div id="body-container">
        <!-- Provide site root to javascript -->
        <script>
            var path_to_root = "";
            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
        </script>

        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script>
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script>
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
            if (theme === null || theme === undefined) { theme = default_theme; }
            var html = document.querySelector('html');
            html.classList.remove('light')
            html.classList.add(theme);
            var body = document.querySelector('body');
            body.classList.remove('no-js')
            body.classList.add('js');
        </script>

        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

        <!-- Hide / unhide sidebar before it is displayed -->
        <script>
            var body = document.querySelector('body');
            var sidebar = null;
            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            } else {
                sidebar = 'hidden';
            }
            sidebar_toggle.checked = sidebar === 'visible';
            body.classList.remove('sidebar-visible');
            body.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <div class="sidebar-scrollbox">
                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../index.html">The Puck Programming Language</a></li><li class="chapter-item expanded "><a href="OVERVIEW.html"><strong aria-hidden="true">1.</strong> Basic Usage</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">1.1.</strong> Variables and Comments</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.2.</strong> Functions and Indentation</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.3.</strong> Uniform Function Call Syntax</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.4.</strong> Basic Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.5.</strong> Conditionals and Pattern Matching</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.6.</strong> Error Handling</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.7.</strong> Blocks and Loops</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.8.</strong> Module System</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.9.</strong> Compile-time Programming</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.10.</strong> Async System and Threading</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.11.</strong> Memory Management</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.12.</strong> Types System</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.13.</strong> Structs and Tuples</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.14.</strong> Unions and Enums</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.15.</strong> Classes</div></li></ol></li><li class="chapter-item expanded "><a href="SYNTAX.html"><strong aria-hidden="true">2.</strong> Syntax</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">2.1.</strong> Call Syntax</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">2.2.</strong> Indentation Rules</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">2.3.</strong> Expression Rules</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">2.4.</strong> Reserved Keywords</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">2.5.</strong> A Formal Grammar</div></li></ol></li><li class="chapter-item expanded "><a href="TYPES.html"><strong aria-hidden="true">3.</strong> Type System</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">3.1.</strong> Basic Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.2.</strong> Parameter Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.3.</strong> Reference Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.4.</strong> Abstract Types</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.5.</strong> Advanced Types</div></li></ol></li><li class="chapter-item expanded "><a href="MODULES.html"><strong aria-hidden="true">4.</strong> Module System</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">4.1.</strong> What are modules?</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">4.2.</strong> Using modules</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">4.3.</strong> Implicit modules</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">4.4.</strong> Defining interfaces [todo]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">4.5.</strong> Defining an external API [todo]</div></li></ol></li><li class="chapter-item expanded "><a href="MEMORY_MANAGEMENT.html"><strong aria-hidden="true">5.</strong> Memory Management [todo]</a></li><li class="chapter-item expanded "><a href="METAPROGRAMMING.html"><strong aria-hidden="true">6.</strong> Metaprogramming</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">6.1.</strong> Scope</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">6.2.</strong> Usage</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">6.3.</strong> Quoting [todo]</div></li></ol></li><li class="chapter-item expanded "><a href="ERRORS.html"><strong aria-hidden="true">7.</strong> Error Handling</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">7.1.</strong> Errors as monads</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">7.2.</strong> Errors as checked exceptions</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">7.3.</strong> Errors as effects [todo]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">7.4.</strong> Unrecoverable Exceptions</div></li></ol></li><li class="chapter-item expanded "><a href="ASYNC.html"><strong aria-hidden="true">8.</strong> Async System</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">8.1.</strong> Effects System [todo]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">8.2.</strong> Threading [todo]</div></li></ol></li><li class="chapter-item expanded "><a href="INTEROP.html"><strong aria-hidden="true">9.</strong> Language Interop [draft]</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">9.1.</strong> Rust</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">9.2.</strong> Swift, Nim</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">9.3.</strong> Java, Kotlin</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">9.4.</strong> Python, Racket, C</div></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">10.</strong> Effects System [draft]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">11.</strong> Refinement Types [draft]</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">12.</strong> Dependent Types [draft]</div></li><li class="chapter-item expanded "><a href="EXAMPLES.html"><strong aria-hidden="true">13.</strong> Examples</a></li></ol>
            </div>
            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                <div class="sidebar-resize-indicator"></div>
            </div>
        </nav>

        <!-- Track and set sidebar scroll position -->
        <script>
            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
            sidebarScrollbox.addEventListener('click', function(e) {
                if (e.target.tagName === 'A') {
                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
                }
            }, { passive: true });
            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
            sessionStorage.removeItem('sidebar-scroll');
            if (sidebarScrollTop) {
                // preserve sidebar scroll position when navigating via links within sidebar
                sidebarScrollbox.scrollTop = sidebarScrollTop;
            } else {
                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
                var activeSection = document.querySelector('#sidebar .active');
                if (activeSection) {
                    activeSection.scrollIntoView({ block: 'center' });
                }
            }
        </script>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                                <div id="menu-bar-hover-placeholder"></div>
                <div id="menu-bar" class="menu-bar sticky">
                    <div class="left-buttons">
                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                            <i class="fa fa-bars"></i>
                        </label>
                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                            <i class="fa fa-paint-brush"></i>
                        </button>
                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                        </ul>
                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                            <i class="fa fa-search"></i>
                        </button>
                    </div>

                    <h1 class="menu-title">The Puck Programming Language</h1>

                    <div class="right-buttons">
                        <a href="print.html" title="Print this book" aria-label="Print this book">
                            <i id="print-button" class="fa fa-print"></i>
                        </a>

                    </div>
                </div>

                <div id="search-wrapper" class="hidden">
                    <form id="searchbar-outer" class="searchbar-outer">
                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                    </form>
                    <div id="searchresults-outer" class="searchresults-outer hidden">
                        <div id="searchresults-header" class="searchresults-header"></div>
                        <ul id="searchresults">
                        </ul>
                    </div>
                </div>

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script>
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <h1 id="-puck---an-experimental-programming-language"><a class="header" href="#-puck---an-experimental-programming-language">🧚 puck - an experimental programming language</a></h1>
<p>A place where I can make some bad decisions.</p>
<p>Puck is an experimental, memory safe, structurally typed, interface-first, imperative programming language.
It aims to be consistent and succinct while performant: inspired by the syntax and metaprogramming of <a href="https://nim-lang.org/">Nim</a>, the error handling of <a href="https://www.swift.org/">Swift</a>, the memory management of <a href="https://www.rust-lang.org/">Rust</a> and <a href="https://koka-lang.github.io/">Koka</a>, the async/await and comptime of <a href="https://ziglang.org/">Zig</a>, and the module system of <a href="https://ocaml.org/">OCaml</a>.</p>
<details>
<summary><b>Example: Type Classes</b></summary>
<pre><code class="language-puck"># Note: These declarations are adapted from the standard prelude.

## The Result type. Represents either success or failure.
pub type Result[T, E] = union
  Okay(T)
  Error(E)

## The Err class. Useful for dynamically dispatching errors.
pub type Err = class
  str(Self): str
  dbg(Self): str

## A Result type that uses dynamically dispatched errors.
## The Error may be any type implementing the Err class.
pub type Result[T] = Result[T, ref Err]

## Implements the `dbg` function for strings.
## As the `str` function is already defined for strings,
## this in turn means strings now implicitly implement Err.
pub func dbg(self: str) = "\"" &amp; self &amp; "\""
</code></pre>
</details>
<details>
<summary><b>Example: Metaprogramming</b></summary>
<pre><code class="language-puck"># Note: These declarations are adapted from the standard prelude.

## Syntactic sugar for dynamic result type declarations.
pub macro !(T: type) =
  quote Result[`T`]

## Indirect access. Propagates `Error`.
pub macro ?[T, E](self: Result[T, E]) =
  quote
    match `self`
    of Okay(x) then x
    of Error(e) then return Error(e)
</code></pre>
</details>
<details open>
<summary><b>Example: Pattern Matching</b></summary>
<pre><code class="language-puck">## Opens the std.tables module for unqualified use.
use std.tables

pub type Value = str
pub type Ident = str
pub type Expr = ref union # tagged, algebraic unions
  Literal(Value)
  Variable(Ident)
  Abstraction(param: Ident, body: Expr)
  Application(body: Expr, arg: Expr)
  Conditional(condition: Expr,
    then_branch: Expr, else_branch: Expr)

## Evaluate an Expr down to a Value, or return an Error.
pub func eval(context: mut Table[Ident, Value], expr: lent Expr): Value! =
  match expr # structural pattern matching and guards are supported but not shown
  of Literal(value) then
    Okay(value.clone) # ownership necessitates we explicitly clone
  of Variable(ident) then
    context.get(ident) # whitespace is significant but flexible
      .err("Could not find variable {} in context!"
      .fmt(ident)) # uniform function call syntax allows arbitrary piping/chaining
  of Application(body, arg) then
    if body of Abstraction(param, body as inner_body) then # compact matching with if
      context.set(param, context.clone.eval(arg)?)
      context.eval(inner_body) # all values must be handled: returns are implicit
    else
      Error("Expected Abstraction, found body {} and arg {}".fmt(body.clone, arg.clone))
  of Conditional(condition, then_branch, else_branch) then
    if context.clone.eval(condition)? == "true" then
      context.eval(then_case)
    else
      context.eval(else_case)
  of _ then Error("Invalid expression {}".fmt(expr))
</code></pre>
</details>
<details>
<summary><b>Example: Modules</b></summary>
<pre><code class="language-puck"># The top-level module declaration can be elided if the file shares the same name.
pub mod tables =
  ## The Table class. Any sort of table - no matter the underlying
  ## representation - must implement these methods.
  pub type Table[K, V] = class
    get(lent Self, lent K): lent V?
    get(mut Self, lent K): mut V?
    set(mut Self, lent K, V): V?
    pop(mut Self, lent K): V?
    clear(mut Self)
    size(lent Self): uint
    init(varargs (K, V)): Self

  ...

  pub mod hashtable =
    use std.hashes

    pub type HashTable[K, V] = struct
      ...
</code></pre>
</details>
<h2 id="why-puck"><a class="header" href="#why-puck">Why Puck?</a></h2>
<p>Puck is primarily a testing ground and should not be used in any important capacity.
Don't use it. Everything is unimplemented and it will break underneath your feet.</p>
<p>That said: in the future, once somewhat stabilized, reasons why you <em>would</em> use it would be for:</p>
<ul>
<li>The <strong>syntax</strong>, aiming to be flexible, predictable, and succinct, through the use of <em>uniform function call syntax</em>, significant whitespace, and consistent scoping rules</li>
<li>The <strong>type system</strong>, being modern and powerful with a strong emphasis on safety, algebraic data types, optional and result types, first-class functions, generics, interfaces, and modules</li>
<li>The <strong>memory management system</strong>, implementing a model of strict ownership with an optimized reference counting escape hatch</li>
<li>The <strong>metaprogramming</strong>, providing integrated macros capable of rewriting the abstract syntax tree before or after typechecking</li>
<li>The <strong>interop system</strong>, allowing foreign functions to be usable with native syntax/semantics from a bevy of other languages</li>
</ul>
<p>This is the language I keep in my head. It sprung from a series of unstructured notes I kept on language design, that finally became something more comprehensive in early 2023. The overarching goal is to provide a language capable of elegantly expressing any problem, and explore ownership and interop along the way.</p>
<h2 id="how-do-i-learn-more"><a class="header" href="#how-do-i-learn-more">How do I learn more?</a></h2>
<ul>
<li>The <a href="../docs/BASIC.html">basic usage</a> document lays out the fundamental semantics of Puck.</li>
<li>The <a href="../docs/SYNTAX.html">syntax</a> document provides a deeper and formal look into the grammar of Puck.</li>
<li>The <a href="../docs/TYPES.html">type system</a> document gives an in-depth analysis of Puck's extensive type system.</li>
<li>The <a href="../docs/MODULES.html">modules</a> document provides a more detailed look at the first-class module system.</li>
<li>The <a href="../docs/ERRORS.html">error handling</a> document gives a look at the various kinds of error handling available.</li>
<li>The <a href="../docs/MEMORY_MANAGEMENT.html">memory management</a> document gives an overview of Puck's memory model.</li>
<li>The <a href="../docs/METAPROGRAMMING.html">metaprogramming</a> document explains how using metaprogramming to extend the language works.</li>
<li>The <a href="../docs/ASYNC.html">asynchronous</a> document gives an overview of Puck's colourless asynchronous support.</li>
<li>The <a href="../docs/INTEROP.html">interop</a> document gives an overview of how the first-class language interop system works.</li>
<li>The <a href="../docs/STDLIB.html">standard library</a> document provides an overview and examples of usage of the standard library.</li>
<li>The <a href="../docs/ROADMAP.html">roadmap</a> provides a clear view of the current state and future plans of the language's development.</li>
</ul>
<p>These are best read in order.</p>
<p>Note that all of these documents (and parts of this README) are written as if everything already exists. Nothing already exists! You can see the <a href="../docs/ROADMAP.html">roadmap</a> for an actual sense as to the state of the language. I simply found writing in the present tense to be an easier way to collect my thoughts.</p>
<p>This language does not currently integrate ideas from the following areas of active research: effects systems, refinement types, and dependent types. It plans to base (un)safety tracking, exception handling, and async/await on a future effects system. It plans to integrate refinement types in the future as a basis for <code>range[]</code> types, and to explore safety and optimizations surrounding integer overflow.</p>
<h2 id="primary-references"><a class="header" href="#primary-references">Primary References</a></h2>
<ul>
<li><a href="https://graydon2.dreamwidth.org/307291.html">The Rust I wanted had no future</a></li>
<li><a href="https://boats.gitlab.io/blog/post/notes-on-a-smaller-rust/">Notes on a smaller Rust</a></li>
<li><a href="https://matklad.github.io/2023/01/25/next-rust-compiler.html">Notes on the next Rust compiler</a></li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="an-overview-of-puck"><a class="header" href="#an-overview-of-puck">An Overview of Puck</a></h1>
<p>Puck is an experimental, high-level, memory-safe, statically-typed, whitespace-sensitive, interface-oriented, imperative programming language with functional underpinnings.</p>
<p>It attempts to explore designs in making functional programming paradigms comfortable to those familiar with imperative and object-oriented languages, as well as deal with some more technical problems along the way, such as integrated refinement types and typesafe interop.</p>
<p>This is the language I keep in my head. It reflects the way I think and reason about code.</p>
<p>I do hope others enjoy it.</p>
<h2 id="variables-and-comments"><a class="header" href="#variables-and-comments">Variables and Comments</a></h2>
<pre><code class="language-puck">let ident: int = 413
# type annotations are optional
var phrase = "Hello, world!"
const compile_time = std.os.file_name
</code></pre>
<p>Variables may be mutable (<code>var</code>), immutable (<code>let</code>), or compile-time evaluated and immutable (<code>const</code>).
Type annotations on variables and other bindings follow the name of the binding (with <code>: Type</code>), and are typically optional.
Variables are conventionally written in <code>snake_case</code>. Types are conventionally written in <code>PascalCase</code>.
The type system is comprehensive, and complex enough to warrant delaying full coverage of until the end. Some basic types are of note, however:</p>
<ul>
<li><code>int</code>, <code>uint</code>: signed and unsigned integers
<ul>
<li><code>i[\d]+</code>, <code>u[\d]+</code>: arbitrary fixed-size counterparts</li>
</ul>
</li>
<li><code>float</code>, <code>decimal</code>: floating-point numbers
<ul>
<li><code>f32</code>/<code>f64</code>/<code>f128</code>: their fixed-size counterparts</li>
<li><code>dec64</code>/<code>dec128</code>: their fixed-size counterparts</li>
</ul>
</li>
<li><code>byte</code>: an alias to <code>u8</code>, representing one byte</li>
<li><code>char</code>: an alias to <code>u32</code>, representing one Unicode character</li>
<li><code>bool</code>: defined as <code>union[false, true]</code></li>
<li><code>array[T, size]</code>: primitive fixed-size arrays</li>
<li><code>list[T]</code>: dynamic lists</li>
<li><code>str</code>: mutable strings. internally a <code>list[byte]</code>, externally a <code>list[char]</code></li>
<li><code>slice[T]</code>: borrowed "views" into the three types above</li>
</ul>
<p>Comments are declared with <code>#</code> and run until the end of the line.
Documentation comments are declared with <code>##</code> and may be parsed by language servers and other tooling.
Multi-line comments are declared with <code>#[ ]#</code> and may be nested.
Taking cues from the Lisp family of languages, any expression may be commented out with a preceding <code>#;</code>.</p>
<h2 id="functions-and-indentation"><a class="header" href="#functions-and-indentation">Functions and Indentation</a></h2>
<pre><code class="language-puck"></code></pre>
<p>Functions are declared with the <code>func</code> keyword. They take an (optional) list of generic parameters (in brackets), an (optional) list of parameters (in parentheses), and <strong>must</strong> be annotated with a return type if they return a type. Every function parameter must be annotated with a type. Their type may optionally be prefixed with either <code>lent</code>, <code>mut</code> or <code>const</code>: denoting an immutable or mutable borrow (more on these later), or a <em>constant</em> type (known to the compiler at compile time, and usable in <code>const</code> exprs). Generic parameters may each be optionally annotated with a type functioning as a <em>constraint</em>.</p>
<!-- Functions, constants, types, and modules may be optionally prefixed with a `pub` modifier denoting visibility outside the current scope / module. More on the module system later. -->
<p>Whitespace is significant but flexible: functions may be declared entirely on one line if so desired. A new level of indentation after certain tokens (<code>=</code>, <code>do</code>, <code>then</code>) denotes a new level of scope. There are some places where arbitrary indentation and line breaks are allowed - as a general rule of thumb, after operators, commas, and opening parentheses. The particular rules governing indentation may be found in the <a href="SYNTAX.html#indentation-rules">syntax guide</a>.</p>
<h2 id="uniform-function-call-syntax"><a class="header" href="#uniform-function-call-syntax">Uniform Function Call Syntax</a></h2>
<pre><code class="language-puck">func inc(self: list[int], by: int): list[int] =
  self.map(x =&gt; x + by)

print inc([1, 2, 3], len("four")) # 5, 6, 7
print [1, 2, 3].inc(1)  # 2, 3, 4
print [1].len # 1
</code></pre>
<p>Puck supports <em>uniform function call syntax</em>: and so any function may be called using the typical syntax for method calls, that is, the first parameter of any function may be appended with a <code>.</code> and moved to precede it, in the style of a typical method. (There are no methods in Puck. All functions are statically dispatched. This may change in the future.)</p>
<p>This allows for a number of syntactic cleanups. Arbitrary functions with compatible types may be chained with no need for a special pipe operator. Object field access, module member access, and function calls are unified, reducing the need for getters and setters. Given a first type, IDEs using dot-autocomplete can fill in all the functions defined for that type. Programmers from object-oriented languages may find the lack of object-oriented classes more bearable. UFCS is implemented in shockingly few languages, and so Puck joins the tiny club that previously consisted of just D, Nim, Koka, and Effekt.</p>
<h2 id="basic-types"><a class="header" href="#basic-types">Basic Types</a></h2>
<pre><code class="language-puck"></code></pre>
<p>Boolean logic and integer operations are standard and as one would expect out of a typed language: <code>and</code>, <code>or</code>, <code>xor</code>, <code>not</code>, <code>shl</code>, <code>shr</code>, <code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code>, <code>&gt;=</code>, <code>div</code>, <code>mod</code>, <code>rem</code>. Notably:</p>
<ul>
<li>the words <code>and</code>/<code>or</code>/<code>not</code>/<code>shl</code>/<code>shr</code> are used instead of the symbolic <code>&amp;&amp;</code>/<code>||</code>/<code>!</code>/<code>&lt;&lt;</code>/<code>&gt;&gt;</code></li>
<li>integer division is expressed with the keyword <code>div</code> while floating point division uses <code>/</code></li>
<li><code>%</code> is absent and replaced with distinct modulus and remainder operators</li>
<li>boolean operators are bitwise and also apply to integers and floats</li>
<li>more operators are available via the standard library (<code>std.math.exp</code> and <code>std.math.log</code>)</li>
</ul>
<p>The above operations are performed with <em>operators</em>, special functions that take a prefixed first argument and (often) a suffixed second argument. Custom operators may be implemented, but they must consist of only a combination of the symbols <code>=</code> <code>+</code> <code>-</code> <code>*</code> <code>/</code> <code>&lt;</code> <code>&gt;</code> <code>@</code> <code>$</code> <code>~</code> <code>&amp;</code> <code>%</code> <code>|</code> <code>!</code> <code>?</code> <code>^</code> <code>\</code> for the purpose of keeping the grammar context-free. They are are declared identically to functions.</p>
<p>Term (in)equality is expressed with the <code>==</code> and <code>!=</code> operators. Type equality is expressed with <code>is</code>. Subtyping relations may be queried with <code>of</code>, which has the additional property of introducing new bindings to the current scope in certain contexts (more on this in the <a href="TYPES.html">types document</a>).</p>
<pre><code class="language-puck">let phrase: str = "I am a string! Wheeee! ✨"
for c in phrase do
  stdout.write(c) # I am a string! Wheeee! ✨
for b in phrase.bytes() do
  stdout.write(b.char) # Error: cannot convert from byte to char
print phrase.last() # ✨
</code></pre>
<p>String concatenation uses a distinct <code>&amp;</code> operator rather than overloading the <code>+</code> operator (as the complement <code>-</code> has no natural meaning for strings). Strings are unified, mutable, internally a byte array, externally a char array, and are stored as a pointer to heap data after their length and capacity (fat pointer). Chars are four bytes and represent a Unicode character in UTF-8 encoding. Slices of strings are stored as a length followed by a pointer to string data, and have non-trivial interactions with the memory management system. More details can be found in the <a href="TYPES.html">type system overview</a>.</p>
<h2 id="conditionals-and-pattern-matching"><a class="header" href="#conditionals-and-pattern-matching">Conditionals and Pattern Matching</a></h2>
<pre><code class="language-puck"></code></pre>
<p>Basic conditional control flow uses standard <code>if</code>/<code>elif</code>/<code>else</code> statements. The <code>when</code> statement provides a compile-time <code>if</code>. It also takes <code>elif</code> and <code>else</code> branches and is syntactic sugar for an <code>if</code> statement within a <code>const</code> expression (more on those later).</p>
<p>All values in Puck must be handled, or explicitly discarded. This allows for conditional statements and many other control flow constructs to function as <em>expressions</em>: and evaluate to a value when an unbound value is left at the end of each of their branches' scopes. This is particularly relevant for <em>functions</em>, where it is often idiomatic to omit an explicit <code>return</code> statement. There is no attempt made to differentiate without context, and so expressions and statements often look identical in syntax.</p>
<pre><code class="language-puck"></code></pre>
<p>Exhaustive structural pattern matching is available with the <code>match</code>/<code>of</code> statement, and is particularly useful for the <code>struct</code> and <code>union</code> types. <code>of</code> branches of a <code>match</code> statement take a <em>pattern</em>, of which the unbound identifiers within will be injected into the branch's scope. Multiple patterns may be used for one branch provided they all bind the same identifiers of the same type. Branches may be <em>guarded</em> with the <code>where</code> keyword, which takes a conditional, and will necessarily remove the branch from exhaustivity checks.</p>
<!-- todo: structural matching of lists and arrays -->
<p>The <code>of</code> statement also stands on its own as an operator for querying subtype equality. Used as a conditional in <code>if</code> statements or <code>while</code> loops, it retains the variable injection properties of its <code>match</code> counterpart. This allows it to be used as a compact and coherent alternative to <code>if let</code> statements in other languages.</p>
<h2 id="error-handling"><a class="header" href="#error-handling">Error Handling</a></h2>
<pre><code class="language-puck">type Result[T] = Result[T, ref Err]
func may_fail: Result[T] = ...
</code></pre>
<p>Error handling is done via a fusion of functional monadic types and imperative exceptions, with much syntactic sugar. Functions may <code>raise</code> exceptions, but by convention should return <code>Option[T]</code> or <code>Result[T, E]</code> types instead: these may be handled in <code>match</code> or <code>if</code>/<code>of</code> statements. The effect system built into the compiler will track functions that <code>raise</code> errors, and warn on those that are not handled explicitly via <code>try</code>/<code>with</code> statements anywhere on the call stack.</p>
<p>A bevy of helper functions and macros are available for <code>Option</code>/<code>Result</code> types, and are documented and available in the <code>std.options</code> and <code>std.results</code> modules (included in the prelude by default). Two in particular are of note: the <code>?</code> macro accesses the inner value of a <code>Result[T, E]</code> or propagates (returns in context) the <code>Error(e)</code>, and the <code>!</code> accesses the inner value of an <code>Option[T]</code> / <code>Result[T, E]</code> or raises an error on <code>None</code> / the specific <code>Error(e)</code>. Both operators take one parameter and so are postfix. The <code>?</code> and <code>!</code> macros are overloaded and additionally function on types as shorthand for <code>Option[T]</code> and <code>Result[T]</code> respectively.</p>
<p>The utility of the <code>?</code> macro is readily apparent to anyone who has written code in Rust or Swift. The utility of the <code>!</code> function is perhaps less so obvious. These errors raised by <code>!</code>, however, are known to the compiler: and they may be comprehensively caught by a single or sequence of <code>with</code> statements. This allows for users used to a <code>try</code>/<code>with</code> error handling style to do so with ease, with only the need to add one additional character to a function call.</p>
<p>More details may be found in <a href="ERRORS.html">error handling overview</a>.</p>
<h2 id="blocks-and-loops"><a class="header" href="#blocks-and-loops">Blocks and Loops</a></h2>
<pre><code class="language-puck">loop
  print "This will never normally exit."
  break

for i in 0 .. 3 do # exclusive
  for j in 0 ..= 3 do # inclusive
    print "{} {}".fmt(i, j)
</code></pre>
<p>Three types of loops are available: <code>for</code> loops, <code>while</code> loops, and infinite loops (<code>loop</code> loops). For loops take a binding (which may be structural, see pattern matching) and an iterable object and will loop until the iterable object is spent. While loops take a condition that is executed upon the beginning of each iteration to determine whether to keep looping. Infinite loops are infinite are infinite are infinite are infinite are infinite are infinite and must be manually broken out of.</p>
<p>There is no special concept of iterators: iterable objects are any object that implements the <code>Iter[T]</code> class (more on those in <a href="TYPES.html">the type system document</a>): that is, provides a <code>self.next()</code> function returning an <code>Option[T]</code>. As such, iterators are first-class constructs. For loops can be thought of as while loops that unwrap the result of the <code>next()</code> function and end iteration upon a <code>None</code> value. While loops, in turn, can be thought of as infinite loops with an explicit conditional break.</p>
<p>The <code>break</code> keyword immediately breaks out of the current loop, and the <code>continue</code> keyword immediately jumps to the next iteration of the current loop. Loops may be used in conjunction with blocks for more fine-grained control flow manipulation.</p>
<pre><code class="language-puck">block
  statement

let x = block
  let y = read_input()
  transform_input(y)

block foo
  for i in 0 ..= 100 do
    block bar
      if i == 10 then break foo
      print i
</code></pre>
<p>Blocks provide arbitrary scope manipulation. They may be labelled or unlabelled. The <code>break</code> keyword additionally functions inside of blocks and without any parameters will jump out of the current enclosing block (or loop). It may also take a block label as a parameter for fine-grained scope control.</p>
<h2 id="module-system"><a class="header" href="#module-system">Module System</a></h2>
<pre><code class="language-puck"></code></pre>
<p>Code is segmented into modules. Modules may be made explicit with the <code>mod</code> keyword followed by a name, but there is also an implicit module structure in every codebase that follows the structure and naming of the local filesystem. For compatibility with filesystems, and for consistency, module names are exclusively lowercase (following the same rules as Windows).</p>
<p>A module can be imported into another module by use of the <code>use</code> keyword, taking a path to a module or modules. Contrary to the majority of languages ex. Python, unqualified imports are <em>encouraged</em> - in fact, are idiomatic (and the default) - type-based disambiguation and official LSP support are intended to remove any ambiguity.</p>
<p>Within a module, functions, types, constants, and other modules may be <em>exported</em> for use by other modules with the <code>pub</code> keyword. All such identifiers are private by default and only accessible module-locally without. Modules are first-class and may be bound, inspected, modified, and returned. As such, imported modules may be <em>re-exported</em> for use by other modules by binding them to a public constant.</p>
<p>More details may be found in the <a href="MODULES.html">modules document</a>.</p>
<h2 id="compile-time-programming"><a class="header" href="#compile-time-programming">Compile-time Programming</a></h2>
<pre><code class="language-puck">## Arbitrary code may execute at compile-time.
const compile_time =
  match std.os.platform # known at compile-time
    of Windows then "windows"
    of MacOS then "darwin"
    of Linux then "linux"
    of Wasi then "wasm"
    of _ then "unknown platform"

## The propagation operator is a macro so that `return` is injected into the function scope.
pub macro ?[T](self: Option[T]) =
  quote
    match `self`
    of Some(x) then x
    of None then return None

## Type annotations and overloading allow us to define syntactic sugar for `Option[T]`, too.
pub macro ?(T: type) =
  quote Option[`T`]
</code></pre>
<p>Compile-time programming may be done via the previously-mentioned <code>const</code> keyword and <code>when</code> statements: or via macros. Macros operate directly on the abstract syntax tree at compile-time: taking in syntax objects, transforming them, and returning them to be injected. They are <em>hygenic</em> and will not capture identifiers not passed as parameters. While parameters are syntax objects, they can be annotated with types to constrain applications of macros and allow for overloading. Macros are written in ordinary Puck: there is thus no need to learn a separate "macro language", as syntax objects are just standard <code>unions</code>. Additionally, support for <em>quoting</em> removes much of the need to operate on raw syntax objects. A full description may be found in the <a href="METAPROGRAMMING.html">metaprogramming document</a>.</p>
<h2 id="async-system-and-threading"><a class="header" href="#async-system-and-threading">Async System and Threading</a></h2>
<pre><code class="language-puck"></code></pre>
<p>The async system is <em>colourblind</em>: the special <code>async</code> macro will turn any function <em>call</em> returning a <code>T</code> into an asynchronous call returning a <code>Future[T]</code>. The special <code>await</code> function will wait for any <code>Future[T]</code> and return a <code>T</code> (or an error). Async support is included in the standard library in <code>std.async</code> in order to allow for competing implementations. More details may be found in the <a href="ASYNC.html">async document</a>.</p>
<p>Threading support is complex and also regulated to external libraries. OS-provided primitives will likely provide a <code>spawn</code> function, and there will be substantial restrictions for memory safety. I really haven't given much thought to this.</p>
<h2 id="memory-management"><a class="header" href="#memory-management">Memory Management</a></h2>
<pre><code class="language-puck"># Differences in Puck and Rust types in declarations and at call sights.
# note: this notation is not valid and is for illustrative purposes only
func foo(a:
  lent T → &amp;'a T
  mut T → &amp;'a mut T
  T → T
):
  lent T → &amp;'a T
  mut T → &amp;'a mut T
  T → T

let t: T = ...
foo( # this is usually elided
  lent t → &amp;t
  mut t → &amp;mut t
  t → t
)
</code></pre>
<p>Puck copies Rust-style ownership near verbatim. <code>&amp;T</code> corresponds to <code>lent T</code>, <code>&amp;mut T</code> to <code>mut T</code>, and <code>T</code> to <code>T</code>: with <code>T</code> implicitly convertible to <code>lent T</code> and <code>mut T</code> at call sites. A major goal of Puck is for all lifetimes to be inferred: there is no overt support for lifetime annotations, and it is likely code with strange lifetimes will be rejected before it can be inferred. (Total inference, however, <em>is</em> a goal.)</p>
<p>Another major difference is the consolidation of <code>Box</code>, <code>Rc</code>, <code>Arc</code>, <code>Cell</code>, <code>RefCell</code> into just two (magic) types: <code>ref</code> and <code>refc</code>. <code>ref</code> takes the role of <code>Box</code>, and <code>refc</code> both the role of <code>Rc</code> and <code>Arc</code>: while <code>Cell</code> and <code>RefCell</code> are disregarded. The underlying motivation for compiler-izing these types is to make deeper compiler optimizations accessible: particularly with <code>refc</code>, where the existing ownership framework is used to eliminate unnecessary counts. Details on memory safety, references and pointers, and deep optimizations may be found in the <a href="MEMORY_MANAGEMENT.html">memory management overview</a>.</p>
<h2 id="types-system"><a class="header" href="#types-system">Types System</a></h2>
<pre><code class="language-puck"># The type Foo is defined here as an alias to a list of bytes.
type Foo = list[byte]

# implicit conversion to Foo in declarations
let foo: Foo = [1, 2, 3]

func fancy_dbg(self: Foo) =
  print "Foo:"
  # iteration is defined for list[byte]
  # so it implicitly carries over: and is defined on Foo
  for elem in self do
    dbg(elem)

# NO implicit conversion to Foo on calls
[4, 5, 6].foo_dbg # this fails!

Foo([4, 5, 6]).foo_dbg # prints: Foo: 4 5 6
</code></pre>
<p>Finally, a few notes on the type system are in order. Types are declared with the <code>type</code> keyword and are aliases: all functions defined on a type carry over to its alias, though the opposite is not true. Functions defined on the alias <em>must</em> take an object known to be a type of that alias: exceptions are made for type declarations, but at call sites this means that conversion must be explicit.</p>
<pre><code class="language-puck"># We do not want functions defined on list[byte] to carry over,
# as strings function differently (operating on chars).
# So we declare `str` as a struct, rather than a type alias.
pub type str = struct
  data: list[byte]

# However, the underlying `empty` function is still useful.
# So we expose it in a one-liner alias.
# In the future, a `with` macro may be available to ease carryover.
pub func empty(self: str): bool = self.data.empty

# Alternatively, if we want total transparent type aliasing, we can use constants.
pub const MyAlias: type = VeryLongExampleType
</code></pre>
<p>If one wishes to define a new type <em>without</em> previous methods accessible, the newtype paradigm is preferred: declaring a single-field <code>struct</code>, and manually implementing functions that carry over. It can also be useful to have <em>transparent</em> type aliases, that is, simply a shorter name to refer to an existing type. These do not require type conversion, implicit or explicit, and can be used freely and interchangeably with their alias. This is done with constants.</p>
<p>Types, like functions, can be <em>generic</em>: declared with "holes" that may be filled in with other types upon usage. A type must have all its holes filled before it can be constructed. The syntax for generics in types much resembles the syntax for generics in functions, and generic <em>constraints</em> and the like also apply.</p>
<h2 id="structs-and-tuples"><a class="header" href="#structs-and-tuples">Structs and Tuples</a></h2>
<pre><code class="language-puck"># standard alternative syntax to inline declarations
type MyStruct = struct
  a: str
  b: str

# syntactic sugar for tuple[str, b: str]
type MyTuple = (str, b: str)

let a: MyTuple = ("hello", "world")
print a.1 # world
print a.b # world

let c: MyStruct = {a = a.0, b = a.1}
print c.b # world
</code></pre>
<p>Struct and tuple types are declared with <code>struct[&lt;fields&gt;]</code> and <code>tuple[&lt;fields&gt;]</code>, respectively. Their declarations make them look similar at a glance: but they differ fairly fundamentally. Structs are <em>unordered</em> and every field must be named. They may be constructed with brackets. Tuples are <em>ordered</em> and so field names are optional - names are just syntactic sugar for positional access. Tuples are both constructed and optionally <em>declared</em> with parentheses.</p>
<p>It is worth noting that there is no concept of <code>pub</code> at a field level on structs - a type is either fully transparent, or fully opaque. This is because such partial transparency breaks with structural initialization (how could one provide for hidden fields?). The <code>@[opaque]</code> attribute allows for expressing that the internal fields of a struct are not to be accessed or initialized: this, however, is only a compiler warning and can be totally suppressed with <code>@[allow(opaque)]</code>.</p>
<h2 id="unions-and-enums"><a class="header" href="#unions-and-enums">Unions and Enums</a></h2>
<pre><code class="language-puck">type Expr = union
  Literal(int)
  Variable(str)
  Abstraction(param: str, body: ref Expr)
  Application(body: ref Expr, arg: ref Expr)
</code></pre>
<p>Union types are composed of a list of <em>variants</em>. Each variant has a <em>tag</em> and an <em>inner type</em> the union wraps over. Before the inner type can be accessed, the tag must be pattern matched upon, in order to handle all possible values. These are also known as <em>sum types</em> or <em>tagged unions</em> in other languages.</p>
<p>Union types are the bread and butter of structural pattern matching. Composed with structs and tuples, unions provide for a very general programming construct commonly referred to as an <em>algebraic data type</em>.
This is often useful as an idiomatic and safer replacement for inheritance.</p>
<pre><code class="language-puck">type Opcode = enum
  BRK INC POP NIP SWP ROT DUP OVR EQU NEQ GTH LTH JMP JCN JSR STH JCI JMI
  LDZ STZ LDR STR LDA STA DEI DEO ADD SUB MUL DIV AND ORA EOR SFT JSI LIT

print Opcode.BRK # 0
...
</code></pre>
<p>Enum types are similarly composed of a list of <em>variants</em>. These variants, however, are static values: assigned at compile-time, and represented under the hood by a single integer. They function similarly to unions, and can be passed through to functions and pattern matched upon, however their underlying simplicity and default values mean they are much more useful for collecting constants and acting as flags than anything else.</p>
<h2 id="classes"><a class="header" href="#classes">Classes</a></h2>
<pre><code class="language-puck">pub type Iter[T] = class
  next(mut Self): T?

pub type Peek[T] = class
  next(mut Self): T?
  peek(mut Self): T?
  peek_nth(mut Self, int): T?
</code></pre>
<p>Class types function much as type classes in Haskell or traits in Rust do. They are not concrete types, and cannot be constructed - instead, their utility is via indirection, as parameters in functions or as <code>ref</code> types in structures, providing constraints that some concrete type must meet. They consist of a list of function signatures, implementations of which must exist for the given type passed in in order to compile.</p>
<p>Their major difference, however, is that Puck's classes are <em>implicit</em>: there is no <code>impl</code> block that implementations of their associated functions have to go under. If functions for a concrete type exist satisfying some class, the type implements that class. This does run the risk of accidentally implementing a class one does not desire to, but the author believes such situations are few and far between and well worth the decreased syntactic and semantic complexity. As a result, however, classes are entirely unable to guarantee any invariants hold (like <code>PartialOrd</code> or <code>Ord</code> in Rust do).</p>
<p>As the compiler makes no such distinction between fields and single-argument functions on a type when determining identifier conflicts, classes similarly make no such distinction. Structs may be described with their fields written as methods. They <em>do</em> distinguish borrowed/mutable/owned parameters, those being part of the type signature.</p>
<p>Classes are widely used throughout the standard library to provide general implementations of such conveniences like iteration, debug and display printing, generic error handling, and much more.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="syntax-a-casual-and-formal-look"><a class="header" href="#syntax-a-casual-and-formal-look">Syntax: A Casual and Formal Look</a></h1>
<h2 id="call-syntax"><a class="header" href="#call-syntax">Call Syntax</a></h2>
<p>There is little difference between a function, macro, and operator call. There are only a few forms such calls can take, too, though notably more than most other languages (due to, among other things, uniform function call syntax): hence this section.</p>
<pre><code class="language-puck"># The standard, unambiguous call.
routine(1, 2, 3, 4)
# The method call syntax equivalent.
1.routine(2, 3, 4)
# A block-based call. This is only really useful for macros taking in a body.
routine
  1
  2
  3
  4
# A parentheses-less call. This is only really useful for `print` and `dbg`.
# Only valid at the start of a line.
routine 1, 2, 3, 4
</code></pre>
<p>Binary operators have some special rules.</p>
<pre><code class="language-puck"># Valid call syntaxes for binary operators. What can constitute a binary
# operator is constrained for parsing's sake. Whitespace is optional.
1 + 2
1+2
+ 1, 2 # Only valid at the start of a line. Also, don't do this.
+(1, 2)
</code></pre>
<p>As do unary operators.</p>
<pre><code class="language-puck"># The standard call for unary operators. Postfix.
1?
?(1)
</code></pre>
<p>Method call syntax has a number of advantages: notably that it can be <em>chained</em>: acting as a natural pipe operator. Redundant parenthesis can also be omitted.</p>
<pre><code class="language-puck"># The following statements are equivalent:
foo.bar.baz
foo().bar().baz()
baz(bar(foo))
baz
  bar
    foo
baz bar(foo)
baz foo.bar
</code></pre>
<h2 id="indentation-rules"><a class="header" href="#indentation-rules">Indentation Rules</a></h2>
<p>The tokens <code>=</code>, <code>then</code>, <code>do</code>, <code>of</code>, <code>else</code>, <code>block</code>, <code>const</code>, <code>block X</code>, and <code>X</code> (where <code>X</code> is an identifier) are <em>scope tokens</em>. They denote a new scope for their associated expressions (functions/macros/declarations, control flow, loops). The tokens <code>,</code>, <code>.</code> (notably not <code>...</code>), and all default binary operators (notably not <code>not</code>) are <em>continuation tokens</em>. An expression beginning or ending in one of them would always be a syntactic error.</p>
<p>Line breaks are treated as the end of a statement, with several exceptions.</p>
<pre><code class="language-puck">pub func foo() =
  print "Hello, world!"
  print "This is from a function."

pub func inline_decl() = print "Hello, world!"
</code></pre>
<p>Indented lines following a line ending in a <em>scope token</em> are treated as belonging to a new scope. That is, indented lines following a line ending in a scope token form the body of the expression associated with the scope token.</p>
<p>Indentation is not obligatory after a scope token. However, this necessarily constrains the body of the associated expression to one line: no lines following will be treated as an extension of the body, only the expression associated with the original scope token. (This may change in the future.)</p>
<pre><code class="language-puck">pub func foo(really_long_parameter: ReallyLongType,
another_really_long_parameter: AnotherReallyLongType) = # no indentation! this is ok
  print really_long_parameter # this line is indented relative to the first line
  print really_long_type
</code></pre>
<p>Lines following a line ending in a <em>continuation token</em> (and, additionally <code>not</code> and <code>(</code>) are treated as a continuation of that line and can have any level of indentation (even negative). If they end in a scope token, however, the following lines must be indented relative to the indentation of the previous line.</p>
<pre><code class="language-puck">let really_long_parameter: ReallyLongType = ...
let another_really_long_parameter: AnotherReallyLongType = ...

really_long_parameter
  .foo(another_really_long_parameter) # some indentation! this is ok
</code></pre>
<p>Lines <em>beginning</em> in a continuation token (and, additionally <code>)</code>), too, are treated as a continuation of the previous line and can have any level of indentation. If they end in a scope token, the following lines must be indented relative to the indentation of the previous line.</p>
<pre><code class="language-puck">pub func foo() =
  print "Hello, world!"
pub func bar() = # this line is no longer in the above scope.
  print "Another function declaration."
</code></pre>
<p>Dedented lines <em>not</em> beginning or ending with a continuation token are treated as no longer in the previous scope, returning to the scope of the according indentation level.</p>
<pre><code class="language-puck">if cond then this
else that

match cond
of this then ...
of that then ...
</code></pre>
<p>A line beginning with a scope token is treated as attached to the previous expression.</p>
<pre><code class="language-puck"># Technically allowed. Please don't do this.
let foo
= ...

if cond then if cond then this
else that

for i
in iterable
do ...

match foo of this then ...
of that then ...

match foo of this
then ...
of that then ...
</code></pre>
<p>This <em>can</em> lead to some ugly possibilities for formatting that are best avoided.</p>
<pre><code class="language-puck"># Much preferred.

let foo =
  ...
let foo = ...

if cond then
  if cond then
    this
else that
if cond then
  if cond then this
else that

for i in iterable do
  ...
for i in iterable do ...

match foo
of this then ...
of that then ...
</code></pre>
<p>The indentation rules are complex, but the effect is such that long statements can be broken <em>almost</em> anywhere.</p>
<h2 id="expression-rules"><a class="header" href="#expression-rules">Expression Rules</a></h2>
<p>First, a word on the distinction between <em>expressions</em> and <em>statements</em>. Expressions return a value. Statements do not. That is all.</p>
<p>There are some syntactic constructs unambiguously recognizable as statements: all declarations, modules, and <code>use</code> statements. There are no syntactic constructs unambiguously recognizable as expressions. As calls returning <code>void</code> are treated as statements, and expressions that return a type could possibly return <code>void</code>, there is no explicit distinction between expressions and statements made in the parser: or anywhere before type-checking.</p>
<p>Expressions can go almost anywhere. Our indentation rules above allow for it.</p>
<pre><code class="language-puck"># Some different formulations of valid expressions.

if cond then
  this
else
  that

if cond then this
else that

if cond
then this
else that

if cond then this else that

let foo =
  if cond then
    this
  else
    that
</code></pre>
<pre><code class="language-puck"># Some different formulations of *invalid* expressions.
# These primarily break the rule that everything following a scope token
# (ex. `=`, `do`, `then`) not at the end of the line must be self-contained.

let foo = if cond then
    this
  else
    that

let foo = if cond then this
  else that

let foo = if cond then this
else that

# todo: how to handle this?
if cond then if cond then that
else that

# shrimple
if cond then
  if cond then that
else that

# this should be ok
if cond then this
else that

match foo of
this then ...
of that then ...
</code></pre>
<h2 id="reserved-keywords"><a class="header" href="#reserved-keywords">Reserved Keywords</a></h2>
<p>The following keywords are reserved:</p>
<ul>
<li>variables: <code>let</code> <code>var</code> <code>const</code></li>
<li>control flow: <code>if</code> <code>then</code> <code>elif</code> <code>else</code></li>
<li>pattern matching: <code>match</code> <code>of</code></li>
<li>error handling: <code>try</code> <code>with</code> <code>finally</code></li>
<li>loops: <code>while</code> <code>do</code> <code>for</code> <code>in</code></li>
<li>blocks: <code>loop</code> <code>block</code> <code>break</code> <code>continue</code> <code>return</code></li>
<li>modules: <code>pub</code> <code>mod</code> <code>use</code> <code>as</code></li>
<li>functions: <code>func</code> <code>varargs</code></li>
<li>metaprogramming: <code>macro</code> <code>quote</code> <code>when</code></li>
<li>ownership: <code>lent</code> <code>mut</code> <code>ref</code> <code>refc</code></li>
<li>types: <code>type</code> <code>struct</code> <code>tuple</code> <code>union</code> <code>enum</code> <code>class</code></li>
</ul>
<p>The following keywords are not reserved, but liable to become so.</p>
<ul>
<li><code>impl</code> <code>object</code> <code>interface</code> <code>concept</code> <code>auto</code> <code>effect</code> <code>case</code></li>
<li><code>suspend</code> <code>resume</code> <code>spawn</code> <code>pool</code> <code>thread</code> <code>closure</code> <code>static</code></li>
<li><code>cyclic</code> <code>acyclic</code> <code>sink</code> <code>move</code> <code>destroy</code> <code>copy</code> <code>trace</code> <code>deepcopy</code></li>
</ul>
<p>The following identifiers are in use by the standard prelude:</p>
<ul>
<li>logic: <code>not</code> <code>and</code> <code>or</code> <code>xor</code> <code>shl</code> <code>shr</code> <code>div</code> <code>mod</code> <code>rem</code></li>
<li>logic: <code>+</code> <code>-</code> <code>*</code> <code>/</code> <code>&lt;</code> <code>&gt;</code> <code>&lt;=</code> <code>&gt;=</code> <code>==</code> <code>!=</code> <code>is</code></li>
<li>async: <code>async</code> <code>await</code></li>
<li>types: <code>int</code> <code>uint</code> <code>float</code> <code>i[\d]+</code> <code>u[\d]+</code>
<ul>
<li><code>f32</code> <code>f64</code> <code>f128</code></li>
<li><code>dec64</code> <code>dec128</code></li>
</ul>
</li>
<li>types: <code>bool</code> <code>byte</code> <code>char</code> <code>str</code></li>
<li>types: <code>void</code> <code>never</code></li>
<li>strings: <code>&amp;</code> (string append)</li>
</ul>
<p>The following punctuation is taken:</p>
<ul>
<li><code>=</code> (assignment)</li>
<li><code>.</code> (chaining)</li>
<li><code>,</code> (parameters)</li>
<li><code>;</code> (statements)</li>
<li><code>:</code> (types)</li>
<li><code>#</code> (comment)</li>
<li><code>@</code> (attributes)</li>
<li><code>_</code> (unused bindings)</li>
<li><code>|</code> (generics)</li>
<li><code>\</code> (string/char escaping)</li>
<li><code>()</code> (parameters, tuples)</li>
<li><code>[]</code> (generics, lists)</li>
<li><code>{}</code> (scope, structs)</li>
<li><code>""</code> (strings)</li>
<li><code>''</code> (chars)</li>
<li><code>``</code> (unquoting)</li>
<li>unused on qwerty: <code>~</code> <code>%</code> <code>^</code> <code>$</code>
<ul>
<li>perhaps leave <code>$</code> unused. but <code>~</code>, <code>%</code>, and <code>^</code> totally could be...</li>
</ul>
</li>
</ul>
<h2 id="a-formal-grammar"><a class="header" href="#a-formal-grammar">A Formal Grammar</a></h2>
<p>We now shall take a look at a more formal description of Puck's syntax.</p>
<p>Syntax rules are described in <a href="https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form">extended Backus–Naur form</a> (EBNF): however, most rules surrounding whitespace, and scope, and line breaks, are modified to how they would appear after a lexing step.</p>
<h3 id="identifiers"><a class="header" href="#identifiers">Identifiers</a></h3>
<pre><code>Ident  ::= (Letter | '_') (Letter | Digit | '_')*
Letter ::= 'A'..'Z' | 'a'..'z' | '\x80'..'\xff' # todo
Digit  ::= '0'..'9'
</code></pre>
<h3 id="literals"><a class="header" href="#literals">Literals</a></h3>
<pre><code>Int ::= '-'? (DecLit | HexLit | OctLit | BinLit)
Float ::= '-'? DecLit '.' DecLit
BinLit ::= '0b' BinDigit ('_'? BinDigit)*
OctLit ::= '0o' OctDigit ('_'? OctDigit)*
HexLit ::= '0x' HexDigit ('_'? HexDigit)*
DecLit ::= Digit ('_'? Digit)*
BinDigit ::= '0'..'1'
OctDigit ::= '0'..'7'
HexDigit ::= Digit | 'A'..'F' | 'a'..'f'
</code></pre>
<h3 id="chars-strings-and-comments"><a class="header" href="#chars-strings-and-comments">Chars, Strings, and Comments</a></h3>
<pre><code>CHAR    ::= '\'' (PRINT - '\'' | '\\\'')* '\''
STRING  ::= SINGLE_LINE_STRING | MULTI_LINE_STRING
COMMENT ::= SINGLE_LINE_COMMENT | MULTI_LINE_COMMENT | EXPRESSION_COMMENT
SINGLE_LINE_STRING  ::= '"' (PRINT - '"' | '\\"')* '"'
MULTI_LINE_STRING   ::= '"""' (PRINT | '\n' | '\r')* '"""'
SINGLE_LINE_COMMENT ::= '#' PRINT*
MULTI_LINE_COMMENT  ::= '#[' (PRINT | '\n' | '\r' | MULTI_LINE_COMMENT)* ']#'
EXPRESSION_COMMENT  ::= '#;' SINGLE_STMT
PRINT ::= LETTER | DIGIT | OPR |
          '"' | '#' | "'" | '(' | ')' | # notably the dual of OPR
          ',' | ';' | '[' | ']' | '_' |
          '`' | '{' | '}' | ' ' | '\t'
</code></pre>
<h3 id="values"><a class="header" href="#values">Values</a></h3>
<pre><code>Value ::= Int | Float | String | Char | Array | Tuple | Struct
Array  ::= '[' (Expr (',' Expr)*)? ']'
Tuple  ::= '(' (Ident '=')? Expr (',' (Ident '=')? Expr)* ')'
Struct ::= '{' Ident '=' Expr (',' Ident '=' Expr)* '}'
</code></pre>
<h3 id="variables"><a class="header" href="#variables">Variables</a></h3>
<pre><code>Decl  ::= Let | Var | Const | Func | Type
Let   ::= 'let' Pattern (':' Type)? '=' Expr
Var   ::= 'var' Pattern (':' Type)? ('=' Expr)?
Const ::= 'pub'? 'const' Pattern (':' Type)? '=' Expr
Pattern ::= (Ident ('as' Ident)?) | Char | String | Number | Float |
            Ident? '(' Pattern (',' Pattern)* ')'
</code></pre>
<h3 id="declarations"><a class="header" href="#declarations">Declarations</a></h3>
<pre><code>Func  ::= 'pub'? 'func' Ident Generics? Parameters? (':' Type)? '=' Body
Macro ::= 'pub'? 'macro' Ident Generics? Parameters? (':' Type)? '=' Body
Generics   ::= '[' Ident (':' Type)? (',' Ident (':' Type)?)* ']'
Parameters ::= '(' Ident (':' Type)? (',' Ident (':' Type)?)* ')'
</code></pre>
<p>All arguments to functions must have a type. This is resolved at the semantic level, however. (Arguments to macros may lack types. This signifies a generic node.)</p>
<h3 id="types"><a class="header" href="#types">Types</a></h3>
<pre><code>TypeDecl ::= 'pub'? 'type' Ident Generics? '=' Type
Type     ::= TypeStruct | TypeTuple | TypeEnum | TypeUnion | SugarUnion |
             TypeClass | (Modifier* (Type | ('[' Type ']')))
TypeStruct ::= 'struct' ('[' Ident ':' Type (',' Ident ':' Type)* ']')?
TypeUnion  ::= 'union'  ('[' Ident ':' Type (',' Ident ':' Type)* ']')?
SugarUnion ::= '(' Ident ':' Type (',' Ident ':' Type)* ')'
TypeTuple  ::= 'tuple' ('[' (Ident ':')? Type (',' (Ident ':')? Type)* ']')?
TypeEnum   ::= 'enum'  ('[' Ident ('=' Expr)? (',' Ident ('=' Expr)?)* ']')?
TypeClass  ::= 'class' ('[' Signature (',' Signature)* ']')?
Modifier   ::= 'ref' | 'refc' | 'ptr' | 'lent' | 'mut' | 'const'
Signature  ::= Ident Generics? ('(' Type (',' Type)* ')')? (':' Type)?
</code></pre>
<h2 id="control-flow"><a class="header" href="#control-flow">Control Flow</a></h2>
<pre><code>If     ::= 'if' Expr 'then' Body ('elif' Expr 'then' Body)* ('else' Body)?
When   ::= 'when' Expr 'then' Body ('elif' Expr 'then' Body)* ('else' Body)?
Try    ::= 'try' Body ('with' Pattern (',' Pattern)* 'then' Body)+ ('finally' Body)?
Match  ::= 'match' Expr ('of' Pattern (',' Pattern)* ('where' Expr)? 'then' Body)+
While  ::= 'while' Expr 'do' Body
For    ::= 'for' Pattern 'in' Expr 'do' Body
Loop   ::= 'loop' Body
Block  ::= 'block' Ident? Body
Const  ::= 'const' Body
Quote  ::= 'quote' QuoteBody
</code></pre>
<h2 id="modules"><a class="header" href="#modules">Modules</a></h2>
<pre><code>Mod ::= 'pub'? 'mod' Ident '=' Body
Use ::= 'use' Ident ('.' Ident)* ('.' ('[' Ident (',' Ident)* ']'))?
</code></pre>
<h3 id="operators"><a class="header" href="#operators">Operators</a></h3>
<pre><code>Operator ::= 'and' | 'or' | 'not' | 'xor' | 'shl' | 'shr' |
             'div' | 'mod' | 'rem' | 'is' | 'in' | Opr+
Opr ::= '=' | '+' | '-' | '*' | '/' | '&lt;' | '&gt;' |
        '@' | '$' | '~' | '&amp;' | '%' | '|' |
        '!' | '?' | '^' | '.' | ':' | '\\'
</code></pre>
<h2 id="calls-and-expressions"><a class="header" href="#calls-and-expressions">Calls and Expressions</a></h2>
<p>This section is (quite) inaccurate due to complexities with respect to significant indentation. Heed caution.</p>
<pre><code>Call ::= Ident ('[' Call (',' Call)* ']')? ('(' (Ident '=')? Call (',' (Ident '=')? Call)* ')')? |
         Ident Call (',' Call)* |
         Call Operator Call? |
         Call Body
Stmt ::= Let | Var | Const | Func | Type | Mod | Use | Expr
Expr ::= Block | Const | For | While | Loop | If | When | Try | Match | Call
Body ::= (Stmt ';')* Expr
</code></pre>
<hr />
<p>References:</p>
<ul>
<li><a href="https://www.joshwcomeau.com/javascript/statements-vs-expressions/">Statements vs. Expressions</a></li>
<li><a href="https://docs.swift.org/swift-book/ReferenceManual/LexicalStructure.html">Swift's Lexical Structure</a></li>
<li><a href="https://nim-lang.github.io/Nim/manual.html">The Nim Programming Language</a></li>
<li><a href="https://pgrandinetti.github.io/compilers/">Pietro's Notes on Compilers</a></li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="typing-in-puck"><a class="header" href="#typing-in-puck">Typing in Puck</a></h1>
<blockquote>
<p>! This section <strong>needs a rewrite</strong>. Proceed with low standards.</p>
</blockquote>
<p>Puck has a comprehensive static type system, inspired by the likes of Nim, Rust, and Swift.</p>
<h2 id="basic-types-1"><a class="header" href="#basic-types-1">Basic types</a></h2>
<p>Basic types can be one-of:</p>
<ul>
<li><code>bool</code>: internally an enum.</li>
<li><code>int</code>: integer number. x bits of precision by default.
<ul>
<li><code>uint</code>: same as <code>int</code>, but unsigned for more precision.</li>
<li><code>i[\d]+</code>, <code>u[\d]+</code>: arbitrarily sized integers</li>
</ul>
</li>
<li><code>float</code>: floating-point number.
<ul>
<li><code>f32</code>, <code>f64</code>: specified float sizes</li>
</ul>
</li>
<li><code>decimal</code>: precision decimal number.
<ul>
<li><code>dec32</code>, <code>dec64</code>, <code>dec128</code>: specified decimal sizes</li>
</ul>
</li>
<li><code>byte</code>: an alias to <code>u8</code>.</li>
<li><code>char</code>: an alias to <code>u32</code>. For working with Unicode.</li>
<li><code>str</code>: a string type. mutable. packed: internally a byte-array, externally a char-array.</li>
<li><code>void</code>: an internal type designating the absence of a value. often elided.</li>
<li><code>never</code>: a type that denotes functions that do not return. distinct from returning nothing.</li>
</ul>
<p><code>bool</code> and <code>int</code>/<code>uint</code>/<code>float</code> and siblings (and subsequently <code>byte</code> and <code>char</code>) are all considered <strong>primitive types</strong> and are <em>always</em> copied (unless passed as mutable). More on when parameters are passed by value vs. passed by reference can be found in the <a href="MEMORY_MANAGEMENT.html">memory management document</a>.</p>
<p>Primitive types, alongside <code>str</code>, <code>void</code>, and <code>never</code>, form <strong>basic types</strong>. <code>void</code> and <code>never</code> will rarely be referenced by name: instead, the absence of a type typically implicitly denotes one or the other. Still, having a name is helpful in some situations.</p>
<h3 id="integers"><a class="header" href="#integers">integers</a></h3>
<p>todo</p>
<h3 id="strings"><a class="header" href="#strings">strings</a></h3>
<p>Strings are:</p>
<ul>
<li>mutable</li>
<li>internally a byte array</li>
<li>externally a char (four bytes) array</li>
<li>prefixed with their length and capacity</li>
<li>automatically resize</li>
</ul>
<p>They are also quite complicated. Puck has full support for Unicode and wishes to be intuitive, performant, and safe, as all languages wish to be. Strings present a problem that much effort has been expended on in (primarily) Swift and Rust to solve.</p>
<h2 id="abstract-types"><a class="header" href="#abstract-types">Abstract Types</a></h2>
<p>Abstract types, broadly speaking, are types described by their <em>behavior</em> rather than their <em>implementation</em>. They are more commonly know as abstract <em>data</em> types: which is confusingly similar to "algebraic data types", another term for the <a href="TYPES.html#advanced-types">advanced types</a> they are built out of under the hood. We refer to them here as "abstract types" to mitigate some confusion.</p>
<h3 id="iterable-types"><a class="header" href="#iterable-types">iterable types</a></h3>
<p>Iterable types can be one-of:</p>
<ul>
<li><code>array[T, size]</code>: Fixed-size arrays. Can only contain one type <code>T</code>. Of a fixed size <code>size</code> and cannot grow/shrink, but can mutate. Initialized in-place with <code>[a, b, c]</code>.</li>
<li><code>list[T]</code>: Dynamic arrays. Can only contain one type <code>T</code>. May grow/shrink dynamically. Initialized in-place with <code>[a, b, c]</code>. (this is the same as arrays!)</li>
<li><code>slice[T]</code>: Slices. Used to represent a "view" into some sequence of elements of type <code>T</code>. Cannot be directly constructed: they are <strong>unsized</strong>. Cannot grow/shrink, but their elements may be accessed and mutated. As they are underlyingly a reference to an array or list, they <strong>must not</strong> outlive the data they reference: this is non-trivial, and so slices interact in complex ways with the memory management system.</li>
<li><code>str</code>: Strings. Described above. They are alternatively treated as either <code>list[byte]</code> or <code>list[char]</code>, depending on who's asking. Initialized in-place with <code>"abc"</code>.</li>
</ul>
<p>These iterable types are commonly used, and bits and pieces of compiler magic are used here and there (mostly around initialization, and ownership) to ease use. All of these types are some sort of sequence: and implement the <code>Iter</code> interface, and so can be iterated (hence the name).</p>
<h3 id="other-abstract-types"><a class="header" href="#other-abstract-types">other abstract types</a></h3>
<p>Unlike the iterable types above, these abstract types do not have a necessarily straightforward or best implementation, and so multiple implementations are provided in the standard library.</p>
<p>These abstract data types can be one-of:</p>
<ul>
<li><code>BitSet[T]</code>: high-performance sets implemented as a bit array.
<ul>
<li>These have a maximum data size, at which point the compiler will suggest using a <code>HashSet[T]</code> instead.</li>
</ul>
</li>
<li><code>AssocTable[T, U]</code>: simple symbol tables implemented as an association list.
<ul>
<li>These do not have a maximum size. However, at some point the compiler will suggest using a <code>HashTable[T, U]</code> instead.</li>
</ul>
</li>
<li><code>HashSet[T]</code>: standard hash sets.</li>
<li><code>HashTable[T, U]</code>: standard hash tables.</li>
</ul>
<p>These abstract types do not have a natural <em>ordering</em>, unlike the iterable types above, and thus do not implement <code>Iter</code>. Despite this: for utility an <code>elems()</code> iterator based on a normalization of the elements is provided for <code>set</code> and <code>HashSet</code>, and <code>keys()</code>, <code>values()</code>, and <code>pairs()</code> iterators are provided for <code>table</code> and <code>HashTable</code> (based on a normalization of the keys). <!-- this is deterministic to prevent user reliance on shoddy randomization: see Go --></p>
<h2 id="parameter-types"><a class="header" href="#parameter-types">Parameter Types</a></h2>
<p>Some types are only valid when being passed to a function, or in similar contexts.
No variables may be assigned these types, nor may any function return them.
These are monomorphized into more specific functions at compile-time if needed.</p>
<p>Parameter types can be one-of:</p>
<ul>
<li>mutable: <code>func foo(a: mut str)</code>: Marks a parameter as mutable (parameters are immutable by default). Passed as a <code>ref</code> if not one already.</li>
<li>constant: <code>func foo(a: const str)</code>: Denotes a parameter whose value must be known at compile-time. Useful in macros, and with <code>when</code> for writing generic code.</li>
<li>generic: <code>func foo[T](a: list[T], b: T)</code>: The standard implementation of generics, where a parameter's exact type is not listed, and instead statically dispatched based on usage.</li>
<li>constrained: <code>func foo(a: str | int | float)</code>: A basic implementation of generics, where a parameter can be one-of several listed types. The only allowed operations on such parameters are those shared by each type. Makes for particularly straightforward monomorphization. <!-- - Separated with the bitwise or operator `|` rather than the symbolic or `||` or a raw `or` to give the impression that there isn't a corresponding "and" operation (the `&` operator is preoccupied with strings). --></li>
<li>functions: <code>func foo(a: (int, int) -&gt; int)</code>: First-class functions. All functions are first class - function declarations implicitly have this type, and may be bound in variable declarations. However, the function <em>type</em> is only terribly useful as a parameter type.</li>
<li>slices: <code>func foo(a: slice[...])</code>: Slices of existing lists, strings, and arrays. Generic over length. These are references under the hood, may be either immutable or mutable (with <code>mut</code>), and interact non-trivially with Puck's <a href="MEMORY_MANAGEMENT.html">ownership system</a>.</li>
<li>classes: <code>func foo(a: Stack[int])</code>: Implicit typeclasses. More in the <a href="TYPES.html#classes">classes section</a>.
<ul>
<li>ex. for above: <code>type Stack[T] = interface[push(mut Self, T); pop(mut Self): T]</code></li>
</ul>
</li>
<li>built-in interfaces: <code>func foo(a: struct)</code>: Included, special interfaces for being generic over <a href="TYPES.html#advanced-types">advanced types</a>. These include <code>struct</code>, <code>tuple</code>, <code>union</code>, <code>enum</code>, <code>interface</code>, and others.</li>
</ul>
<p>Several of these parameter types - specifically, slices, functions, and interfaces - share a common trait: they are not <em>sized</em>. The exact size of the type is not generally known until compilation - and in some cases, not even during compilation! As the size is not always rigorously known, problems arise when attempting to construct these parameter types or compose them with other types: and so this is disallowed. They may still be used with <em>indirection</em>, however - detailed in the <a href="TYPES.html#reference-types">section on reference types</a>.</p>
<h3 id="generic-types"><a class="header" href="#generic-types">generic types</a></h3>
<p>Functions can take a <em>generic</em> type, that is, be defined for a number of types at once:</p>
<pre><code class="language-puck"># fully generic. monomorphizes based on usage.
func add[T](a: list[T], b: T) = a.push(b)

# constrained generics. restricts possible operations to the intersection
# of defined methods on each type.
func length[T](a: str | list[T]) =
  a.len # both strings and lists have a `len` method

# alternative formulation: place the constraint on a generic parameter.
# this ensures both a and b are of the *same* type.
func add[T: int | float](a: T, b: T) = a + b
</code></pre>
<p>The syntax for generics is <code>func</code>, <code>ident</code>, followed by the names of the generic parameters in brackets <code>[T, U, V]</code>, followed by the function's parameters (which may then refer to the generic types). Generics are replaced with concrete types at compile time (monomorphization) based on their usage in function calls within the main function body.</p>
<p>Constrained generics have two syntaxes: the constraint can be defined directly on a parameter, leaving off the <code>[T]</code> box, or it may be defined within the box as <code>[T: int | float]</code> for easy reuse in the parameters.</p>
<p>Other constructions like type declarations themselves may also be generic over types. In the future, modules also may be generic: whether that is to be over types or over other modules is to be determined.</p>
<h2 id="reference-types"><a class="header" href="#reference-types">Reference Types</a></h2>
<p>Types are typically constructed by value on the stack. That is, without any level of indirection: and so type declarations that recursively refer to one another, or involve unsized types (notably including parameter types), would not be allowed. However, Puck provides several avenues for indirection.</p>
<p>Reference types can be one-of:</p>
<ul>
<li><code>ref T</code>: An owned reference to a type <code>T</code>. This is a pointer of size <code>uint</code> (native).</li>
<li><code>refc T</code>: A reference-counted reference to a type <code>T</code>. This allows escaping the borrow checker.</li>
<li><code>ptr T</code>: A manually-managed pointer to a type <code>T</code>. (very) unsafe. The compiler will yell at you.</li>
</ul>
<pre><code class="language-puck">type BinaryTree = ref struct
  left: BinaryTree
  right: BinaryTree

type AbstractTree[T] = class
  func left(self: Self): Option[AbstractTree[T]]
  func right(self: Self): Option[AbstractTree[T]]
  func data(self: Self): T

type AbstractRoot[T] = struct
  left: ref AbstractTree[T]
  right: ref AbstractTree[T]

# allowed, but unsafe &amp; strongly discouraged
type UnsafeTree = struct
  left: ptr UnsafeTree
  right: ptr UnsafeTree
</code></pre>
<p>The <code>ref</code> prefix may be placed at the top level of type declarations, or inside on a field of a structural type. <code>ref</code> types may often be more efficient when dealing with large data structures. They also provide for the usage of unsized types (functions, interfaces, slices) within type declarations.</p>
<p>The compiler abstracts over <code>ref</code> types to provide optimization for reference counts: and so a distinction between <code>Rc</code>/<code>Arc</code>/<code>Box</code> is not needed. Furthermore, access implicitly dereferences (with address access available via <code>.addr</code>), and so a <code>*</code> dereference operator is also not needed.</p>
<p>Much care has been given to make references efficient and safe, and so <code>ptr</code> should be avoided if at all possible. They are only usable inside functions explicitly marked with <code>#[safe]</code>.</p>
<p>The implementations of reference types are delved into in further detail in the <a href="MEMORY_MANAGEMENT.html">memory management document</a>.</p>
<h2 id="advanced-types"><a class="header" href="#advanced-types">Advanced Types</a></h2>
<p>The <code>type</code> keyword is used to declare aliases to custom data types. These types are <em>algebraic</em>: they function by <em>composition</em>. Such <em>algebraic data types</em> can be one-of:</p>
<ul>
<li><code>struct</code>: An unordered, named collection of types. May have default values.</li>
<li><code>tuple</code>: An ordered collection of types. Optionally named.</li>
<li><code>enum</code>: Ordinal labels, that may hold values. Their default values are their ordinality.</li>
<li><code>union</code>: Powerful matchable tagged unions a la Rust. Sum types.</li>
<li><code>class</code>: Implicit type classes. User-defined duck typing.</li>
</ul>
<p>All functions defined on the original type carry over. If this is not desired, the newtype paradigm is preferred: declaring a single-field <code>struct</code> and copying function declarations over.</p>
<p>Types may be explicitly to and from via the <code>Coerce</code> and <code>Convert</code> classes and provided <code>from</code> and <code>to</code> functions.</p>
<h3 id="structs"><a class="header" href="#structs">structs</a></h3>
<p>Structs are an <em>unordered</em> collection of named types.</p>
<p>They are declared with <code>struct[identifier: Type, ...]</code> and initialized with brackets: <code>{ field = "value", another = 500}</code>. Structs are <em>structural</em>: while the type system is fundamentally nominal, and different type declarations are treated as distinct, a struct object initialized with <code>{}</code> is usable in any context that expects a struct with the same fields.</p>
<pre><code class="language-puck">type LinkedNode[T] = ref struct
  previous: Option[LinkedNode[T]]
  next: Option[LinkedNode[T]]
  data: T

let node = { # inferred type: LinkedNode[int], from prints_data call
  previous = None, next = None
  data = 413
}

func pretty_print(node: LinkedNode[int]) =
  print node.data
  if node.next of Some(node) then
    node.pretty_print()

# structural typing!
prints_data(node)
</code></pre>
<h3 id="tuples"><a class="header" href="#tuples">tuples</a></h3>
<p>Tuples are an <em>ordered</em> collection of either named and/or unnamed types.</p>
<p>They are declared with <code>tuple[Type, identifier: Type, ...]</code> and initialized with parentheses: <code>(413, "hello", value: 40000)</code>. Syntactic sugar allows for them to be declared with <code>()</code> as well.</p>
<p>They are exclusively ordered - named types within tuples are just syntactic sugar for positional access. Passing a fully unnamed tuple into a context that expects a tuple with a named parameter is allowed (so long as the types line up).</p>
<pre><code class="language-puck">let grouping = (1, 2, 3)

func foo: tuple[str, str] = ("hello", "world")
dbg grouping.foo # prints '("hello", "world")'

func bar(a: (str, str)) = a.1
dbg grouping.bar # prints '"world"'
</code></pre>
<p>Tuples are particularly useful for "on-the-fly" types. Creating type declarations to tuples is discouraged - structs are generally a better choice, as they are fully named, support default values, and may have their layout optimized by the compiler.</p>
<h3 id="enums"><a class="header" href="#enums">enums</a></h3>
<p>Enums are <em>ordinal labels</em> that may have <em>associated values</em>.</p>
<p>They are declared with <code>enum[Label, AnotherLabel = 4, ...]</code> and are never initialized (their values are known statically). Enums may be accessed directly by their label, and are ordinal and iterable regardless of their associated value. They are useful in collecting large numbers of "magic values" that would otherwise be constants.</p>
<pre><code class="language-puck">type Keys = enum
  Left, Right, Up, Down
  A = "a"
  B = "b"
</code></pre>
<p>In the case of an identifier conflict (with other enum labels, or types, or...) they must be prefixed with the name of their associated type (separated by a dot). This is standard for identifier conflicts: and is discussed in more detail in the <a href="MODULES.html">modules document</a>.</p>
<h3 id="unions"><a class="header" href="#unions">unions</a></h3>
<p>Unions are <em>tagged</em> type unions. They provide a high-level wrapper over an inner type that must be safely accessed via pattern matching.</p>
<p>They are declared with <code>union[Variant(Type), ...]</code> and initialized with the name of a variant followed by its inner type constructor in brackets: <code>Square(side: 5)</code>. Tuples and structs are special-cased to eliminate extraneous parentheses.</p>
<pre><code class="language-puck">type Value = u64
type Ident = str
type Expr = ref union
  Literal(Value)
  Variable(Ident)
  Abstraction(param: Ident, body: Expr)
  Application(body: Expr, arg: Expr)
  Conditional(
    condition: Expr
    then_case: Expr
    else_case: Expr
  )
</code></pre>
<p>They take up as much space in memory as the largest variant, plus the size of the tag (one byte).</p>
<h4 id="pattern-matching"><a class="header" href="#pattern-matching">pattern matching</a></h4>
<p>Unions abstract over differing types. In order to <em>safely</em> be used, their inner types must be accessed via <em>pattern matching</em>: leaving no room for type confusion. Pattern matching in Puck relies on two syntactic constructs: the <code>match</code> statement, forcing qualification and handling of all possible types of a variable, and the <code>of</code> statement, querying type equality while simultaneously binding new identifiers to underspecified portions of variables.</p>
<pre><code class="language-puck">use std.tables

func eval(context: mut HashTable[Ident, Value], expr: Expr): Result[Value]
  match expr
  of Literal(value) then Okay(value)
  of Variable(ident) then
    context.get(ident).err("Variable not in context")
  of Application(body, arg) then
    if body of Abstraction(param, body as inner_body) then
      context.set(param, context.eval(arg)?) # from std.tables
      context.eval(inner_body)
    else
      Error("Expected Abstraction, found {}".fmt(body))
  of Conditional(condition, then_case, else_case) then
    if context.eval(condition)? == "true" then
      context.eval(then_case)
    else
      context.eval(else_case)
  of expr then
    Error("Invalid expression {}".fmt(expr))
</code></pre>
<p>The match statement takes exclusively a list of <code>of</code> sub-expressions, and checks for exhaustivity. The <code>expr of Type(binding)</code> syntax can be reused as a conditional, in <code>if</code> statements and elsewhere.</p>
<p>The <code>of</code> <em>operator</em> is similar to the <code>is</code> operator in that it queries type equality, returning a boolean. However, unbound identifiers within <code>of</code> expressions are bound to appropriate values (if matched) and injected into the scope. This allows for succinct handling of <code>union</code> types in situations where <code>match</code> is overkill.</p>
<p>Each branch of a match expression can also have a <em>guard</em>: an arbitrary conditional that must be met in order for it to match. Guards are written as <code>where cond</code> and immediately follow the last pattern in an <code>of</code> branch, preceding <code>then</code>.</p>
<h3 id="classes-1"><a class="header" href="#classes-1">classes</a></h3>
<p>Classes can be thought of as analogous to Rust's traits: without explicit <code>impl</code> blocks and without need for the <code>derive</code> macro. Types that have functions defined on them fulfilling the class requirements implicitly implement the associated class.</p>
<p>The <code>class</code> type is composed of a list of function signatures that refer to the special type <code>Self</code> that must exist for a type to be valid. The special type <code>Self</code> is replaced with the concrete type at compile time in order to typecheck. They are declared with <code>class[signature, ...]</code>.</p>
<pre><code class="language-puck">type Stack[T] = class
  push(self: mut Self, val: T)
  pop(self: mut Self): T
  peek(self: lent Self): lent T

func takes_any_stack(stack: Stack[int]) =
  # only stack.push, stack.pop, and stack.peek are available, regardless of the concrete type passed
</code></pre>
<p>Differing from Rust, Haskell, and many others, there is no explicit <code>impl</code> block. If there exist functions for a type that satisfy all of a class's signatures, it is considered to match and the class typechecks. This may seem strange and ambiguous - but again, static typing and uniform function call syntax help make this a more reasonable design. The purpose of explicit <code>impl</code> blocks in ex. Rust is three-fold: to provide a limited form of uniform function call syntax; to explicitly group together associated code; and to disambiguate. UFCS provides for the first, the module system provides for the second, and type-based disambiguation provides for the third, with such information exposed to the user via the language server protocol.</p>
<pre><code class="language-puck">type Set[T] = class
  in(lent Self, T): bool
  add(mut Self, T)
  remove(mut Self, T): Option[T]

type Foo = struct
  a: int
  b: ref Set[int] # indirection: now perfectly valid
</code></pre>
<p>Classes cannot be constructed, as they are <strong>unsized</strong>. They serve purely as a list of valid operations on a type: no information about their memory layout is relevant. The <em>concrete type</em> fulfilling a class is known at compile time, however, and so there are no issues surrounding the use of classes as parameters, just when attempted to be used as (part of) a concrete type in ex. a struct. They can be used with <em>indirection</em>, however: as references are sized (consisting of a memory address).</p>
<pre><code class="language-puck">## The Display class. Any type implementing `str` is printable.
## Any type that is Display must necessarily also implement Debug.
pub type Display = class
  str(Self): str
  dbg(Self): str

## The Debug class. Broadly implemented for every type with compiler magic.
## Types can (and should) override the generic implementations.
pub type Debug = class
  dbg(Self): str
</code></pre>
<p>Classes also <em>cannot</em> extend or rely upon other classes in any way, nor is there any concept of a parameter satisfying two classes. In the author's experience, while such constructions are powerful, they are also an immense source of complexity, leading to less-than-useful hierarchies seen in languages like Java, and yes, Rust. Instead, if one wishes to form an class that <em>also</em> satisfies another class, they must name a new class that explicitly includes all of the other class's associated functions. Given that classes in Puck overwhelmingly only have a small handful of associated functions, and if you're using more than one class you <em>really</em> should be using a concrete type: the hope is that this will provide for explicitness and reduce complexity.</p>
<p>Classes compose well with <a href="MODULES.html">modules</a> to offer fine grained access control.</p>
<h2 id="errata"><a class="header" href="#errata">Errata</a></h2>
<h3 id="default-values"><a class="header" href="#default-values">default values</a></h3>
<p>Puck does not have any concept of <code>null</code>: all values <em>must</em> be initialized.
But always explicitly initializing types is syntactically verbose, and so most types have an associated "default value".</p>
<p><strong>Default values</strong>:</p>
<ul>
<li><code>bool</code>: <code>false</code></li>
<li><code>int</code>, <code>uint</code>, etc: <code>0</code></li>
<li><code>float</code>, etc: <code>0.0</code></li>
<li><code>char</code>: <code>'\0'</code></li>
<li><code>str</code>: <code>""</code></li>
<li><code>void</code>, <code>never</code>: unconstructable</li>
<li><code>array[T]</code>, <code>list[T]</code>: <code>[]</code></li>
<li><code>set[T]</code>, <code>table[T, U]</code>: <code>{}</code></li>
<li><code>tuple[T, U, ...]</code>: <code>(default values of its fields)</code></li>
<li><code>struct[T, U, ...]</code>: <code>{default values of its fields}</code></li>
<li><code>enum[One, Two, ...]</code>: <strong>disallowed</strong></li>
<li><code>union[T, U, ...]</code>: <strong>disallowed</strong></li>
<li><code>slice[T]</code>, <code>func</code>: <strong>disallowed</strong></li>
<li><code>ref</code>, <code>refc</code>, <code>ptr</code>: <strong>disallowed</strong></li>
</ul>
<p>For unions, slices, references, and pointers, this is a bit trickier. They all have no reasonable "default" for these types <em>aside from</em> null.
Instead of giving in, the compiler instead disallows any non-initializations or other cases in which a default value would be inserted.</p>
<p>todo: consider user-defined defaults (ex. structs)</p>
<h3 id="signatures-and-overloading"><a class="header" href="#signatures-and-overloading">signatures and overloading</a></h3>
<p>Puck supports <em>overloading</em> - that is, there may exist multiple functions, or multiple types, or multiple modules, with the same name - so long as they have a different <em>signature</em>.
The signature of a function/type/module is important. Classes, among other constructs, depend on the user having some understanding of what the compiler considers to be a signature. So we state it here explicitly:</p>
<ul>
<li>The signature of a function is its name and the <em>types</em> of each of its parameters, in order, ignoring optional parameters. Generic parameters are ???
<ul>
<li>ex. ...</li>
</ul>
</li>
<li>The signature of a type is its name and the number of generic parameters.
<ul>
<li>ex. both <code>Result[T]</code> and <code>Result[T, E]</code> are defined in <code>std.results</code></li>
</ul>
</li>
<li>The signature of a module is just its name. This may change in the future.</li>
</ul>
<h3 id="structural-subtyping"><a class="header" href="#structural-subtyping">structural subtyping</a></h3>
<p>Mention of subtyping has been on occasion in contexts surrounding structural type systems, particularly the section on distinct types, but no explicit description of what the subtyping rules are have been given.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="modules-and-namespacing"><a class="header" href="#modules-and-namespacing">Modules and Namespacing</a></h1>
<blockquote>
<p>! This section is <strong>incomplete</strong>. Proceed with caution.</p>
</blockquote>
<p>Puck has a first-class module system, inspired by such expressive designs in the ML family.</p>
<h2 id="what-are-modules"><a class="header" href="#what-are-modules">What are modules?</a></h2>
<pre><code class="language-puck">pub mod stack =
  pub type Stack[T] = class
    init(static type Self): Stack[T]
    push(mut Self, val: T)
    pop(mut Self): T?
    peek(lent Self): lent T?

  pub mod list =
    type ListStack[T] = list[T]

    pub func init[T](self: static type ListStack[T]): Stack[T] = []
    pub func push[T](self: mut ListStack[T], val: T) = self.push(T)
    pub func pop[T](self: mut ListStack[T]): T? = self.pop
    pub func peek[T](self: lent ListStack[T]): lent T? =
      if self.len == 0 then None else Some(self.last)

use stack.list

let a = ListStack[int].init
print a.len # error: unable to access method on private type outside its module

a.push(5)
print a.pop # Some(5)
</code></pre>
<p>Modules package up code for use by others. Identifiers known at compile time may be part of a module: these being constants, functions, macros, types, and other modules themselves. Such identifiers may be made accessible outside of the module by prefixing them with the <code>pub</code> keyword.</p>
<p>Importantly, <em>files</em> are implicitly modules, public and named with their filename. The <code>mod</code> keyword followed by an identifier and an indented block of code explicitly defines a module, inside of the current module. Modules are first class: they may be bound to constants (having the type <code>: mod</code>) and publicly exported, or bound to local variables and passed into functions for who knows what purpose.</p>
<h2 id="using-modules"><a class="header" href="#using-modules">Using modules</a></h2>
<p>The <code>use</code> keyword lets you use other modules.</p>
<p>The <code>use</code> keyword imports public symbols from the specified module into the current scope <em>unqualified</em>. This runs contrary to expectations coming from most other languages: from Python to Standard ML, the standard notion of an "import" puts the imported symbols behind another symbol to avoid "polluting the namespace". As Puck is strongly typed and allows overloading, however, we see no reason for namespace pollution to be of concern. These unqualified imports have the added benefit of making <em>uniform function call syntax</em> more widely accessible. It is inevitable that identifier conflicts will exist on occasion, of course: when this happens, the compiler will force qualification (this then does restrict uniform function call syntax). We discuss this more later.</p>
<p>Nonetheless, if qualification of imports is so desired, an alternative approach is available - binding a module to a constant. Both the standard library and external libraries are available behind identifiers without use of <code>use</code>: <code>std</code> and <code>lib</code>, respectively. (FFI and local modules will likely use more identifiers, but this is not hammered out yet.) A submodule - for example, <code>std.net</code> - may be bound in a constant as <code>const net = std.net</code>, providing all of the modules' public identifiers for use, as fields of the constant <code>net</code>. We will see this construction to be extraordinarily helpful in crafting high-level public APIs for libraries later on.</p>
<pre><code class="language-puck">use std.[logs, test]
use lib.crypto, lib.http
</code></pre>
<p>Multiple modules can be imported at once. The standard namespaces deserve more than a passing mention. There are several of these: <code>std</code> for the standard library, <code>lib</code> for all external libraries, <code>pkg</code> for the top-level namespace of a project, <code>this</code> for the current containing module... In addition: there are a suite of <em>language</em> namespaces, for FFI - <code>rust</code>, <code>nim</code>, and <code>swift</code> preliminarily - that give access to libraries from other languages. Recall that imports are unqualified - so <code>use std</code> will allow use of the standard library without the <code>std</code> qualifier (not recommended: several modules have common names), and <code>use lib</code> will dump the name of every library it can find into the global namespace (even less recommended).</p>
<h2 id="implicit-modules"><a class="header" href="#implicit-modules">Implicit Modules</a></h2>
<p>A major goal of Puck's module system is to allow the same level of expressiveness as the ML family, while cutting down on the extraneous syntax and boilerplate needed to do so. As such, access modifiers are written directly inline with their declaration, and the file system structure is reused to form an implicit module system for internal use. This - particularly the former - <em>limits</em> the structure a module can expose at first glance, but we will see later that classes recoup much of this lost specificity.</p>
<p>We mentioned that the filesystem forms an implicit module structure. This begets a couple of design choices. Module names <strong>must</strong> be lowercase, for compatibility with case-insensitive filesystems. Both a file and a folder with the same name can exist. Files within the aforementioned folder are treated as submodules of the aforementioned file. This again restricts the sorts of module structures we can build, but we will see later that this restriction can be bypassed.</p>
<p>The <code>this</code> and <code>pkg</code> modules are useful for this implicit structure...</p>
<h2 id="defining-interfaces"><a class="header" href="#defining-interfaces">Defining interfaces</a></h2>
<p>...</p>
<h2 id="defining-an-external-api"><a class="header" href="#defining-an-external-api">Defining an external API</a></h2>
<p>The filesystem provides an implicit module structure, but it may not be the one you want to expose to users.</p>
<p>...</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="memory-management-1"><a class="header" href="#memory-management-1">Memory Management</a></h1>
<p>Puck's memory management system takes heavy inspiration from Rust.</p>
<p>The core borrowing semantics are copied 1:1. Puck's <code>lent T</code> is Rust's <code>&amp;T</code>, <code>mut T</code> is <code>&amp;mut T</code>, and <code>T</code> is <code>T</code>. There are several changes, however:</p>
<ul>
<li><code>T</code> is coerced into <code>lent T</code> and <code>mut T</code> whenever possible</li>
<li>all lifetimes are elided: indeterminate lifetimes are disallowed</li>
<li><code>Copy</code> types are implicit and automatically derived</li>
<li><code>Box</code> is <code>ref</code> and built-in</li>
<li><code>Rc</code> and <code>Arc</code> are unified under one compiler-optimized <code>refc</code> type</li>
</ul>
<p>I personally think that Rust's system of ownership is <strong>quite good</strong> and a joy to use. And more the matter: I can't think of anything better? Every tweak I try to make to Rust's system falls apart when I work through what it looks like in practice. Making ownership rather than borrowing annotated complicates things, because most of the time ownership <em>is</em> desired. Making references second class simplifies things, but not by all that much, and greatly restricts the expressiveness of the language.</p>
<p>The exceptions here being coercing to references (which is trivial) and eliding lifetimes. I have seen nothing to suggest total lifetime elision in Rust is impossible: rather, it seems to mostly be an intentional choice for the purpose of explicitness (and not needing to inspect function bodies). I don't like this, and will be attempting to see just how doable total elision is.</p>
<h2 id="refc-and-ownership-elision"><a class="header" href="#refc-and-ownership-elision"><code>refc</code> and ownership elision</a></h2>
<p>The <code>refc</code> type is special. Being a compiler built-in, it can take advantage of heavy optimizations: notably the count-eliding Perceus algorithm, used in Nim and Koka. The basic idea is to trace ownership throughout the program graph - and wherever the compiler can statically determine an object is moved, omit counts. And Puck has just the ownership framework to reuse!</p>
<h2 id="implicit-copy-types"><a class="header" href="#implicit-copy-types">implicit copy types</a></h2>
<p>There is a distinction between types that can be transparently <em>copied</em> - that is, directly duplicating bytes to form a new object is acceptable - and those not. Pointers to heap memory -</p>
<p><em>cannot</em> be copied,</p>
<h2 id="stack-oriented"><a class="header" href="#stack-oriented">stack-oriented</a></h2>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>fn foo(a:
  &amp;T → lent T
  &amp;mut T → mut T
  T → T
):
  &amp;T → lent T
  &amp;mut T → mut T
  T → T
<span class="boring">}</span></code></pre></pre>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let t: T
foo(
  &amp;t → lent t
  &amp;mut t → mut t
  t → t
)

let u =
  &amp;t → lent t
  &amp;mut t → mut t
  t → t

&amp;&amp;t → lent lent t
*t → deref t

type Foo[T] = struct
  x: lent T
<span class="boring">}</span></code></pre></pre>
<hr />
<p>I don't know what I want out of a memory management system!</p>
<p>There are quite a deal of interesting avenues to pursue here, and they all profoundly impact the rest of the language (particularly iteration). In no particular order, here are the ones I've been thinking a lot about.</p>
<h2 id="reference-counting-with-ownership-elision"><a class="header" href="#reference-counting-with-ownership-elision">reference counting with ownership elision</a></h2>
<p>Copy Nim/Koka. This is very easy to do: you implement standard reference counting, add a static ownership pass to track places of last use, and remove checks where possible. The benefits of this is that it's simple, deterministic, and performant. It leaves some performance on the table as opposed to Rust, but the usability benefits are high - in particular, you can use it just as you would use any other GC'd language. It's also well-documented by Koka, and lends itself decently well to further optimizations. I will probably end up going with it.</p>
<h2 id="first-class-references"><a class="header" href="#first-class-references">first-class references</a></h2>
<p>Copy Rust. This means you need to support stacked borrows and such. That is a bit unfortunate, both syntax and semantics-wise. You inherit all the benefits of Rust-style ownership - and the downsides, too. In particular, you now need to worry about lifetime elision, and whether that's universally possible.</p>
<p>I am actually really tempted to do this though. Rust + whitespace oriented syntax + better metaprogramming + better modules + overloading + seems fun.</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>fn foo(a:
  &amp;T → lent T
  &amp;mut T → mut T
  T → T
):
  &amp;T → lent T
  &amp;mut T → mut T
  T → T
<span class="boring">}</span></code></pre></pre>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let t: T
foo(
  &amp;t → lent t
  &amp;mut t → mut t
  t → t
)

let u =
  &amp;t → lent t
  &amp;mut t → mut t
  t → t

&amp;&amp;t → lent lent t
*t → deref t

type Foo[T] = struct
  x: lent T
<span class="boring">}</span></code></pre></pre>
<p>o fuk this is really tempting</p>
<h2 id="second-class-references"><a class="header" href="#second-class-references">second-class references</a></h2>
<p>Or, simplified borrowing. Much - nigh all - the complexity of ownership in Rust comes from references being <em>first-class</em>: you can return them, you can set aliases to them, you can create them on-the-fly. But what if they weren't first class? What if you couldn't return references? How much expressive power would you lose?</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>fn foo(a:
  &amp;T → lent T
  &amp;mut T → mut T
  T → T
):
  &amp;T → n/a
  &amp;mut T → n/a
  T → T
<span class="boring">}</span></code></pre></pre>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let t: T
foo(
  &amp;t → lent t // this could probably be elided
  &amp;mut t → mut t // this could probably also be elided
  t → t
)

let u =
  &amp;t →
  &amp;mut t → mut t
  t → t
<span class="boring">}</span></code></pre></pre>
<h2 id="reference-by-default"><a class="header" href="#reference-by-default">reference by default</a></h2>
<p>...</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>fn foo(a:
  &amp;'a T → T
  &amp;mut T → mut T
  T → sink T
):
  &amp;'a T → lent T
  &amp;'a mut T → ???
  T → T
<span class="boring">}</span></code></pre></pre>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let t: T
foo(
  &amp;t → t
  &amp;mut t → t
  t → t
)

let u =
  &amp;t → lent t
  &amp;mut t → mut t
  t → t
<span class="boring">}</span></code></pre></pre>
<p>Puck's <code>T</code>: Rust's <code>&amp;T</code>
Puck's <code>mut T</code>: Rust's <code>&amp;mut T</code>
Puck's <code>sink T</code> / <code>owned T</code>: Rust's <code>T</code>
Puck's <code>ref T</code>: ???
Puck's <code>ptr T</code>: ???</p>
<p>Types get coerced: no need to say <code>consumes(owned T)</code> (when called).</p>
<p>Puck's memory management system takes heavy inspiration from Lobster and Nim.
It is deterministic, requires no reference or lifetime annotations, and has zero runtime overhead (no garbage collector). It achieves this by a sophisticated ownership algorithm building off of ownership implementations in Rust, Nim, Lobster, Koka, and others, but also by <em>restricting</em> the actions of the programmer - in particular, there is no concept of returning a reference from a function or placing a reference within a datatype.</p>
<p>First, a recap of the problems and perils of memory management:</p>
<pre><code class="language-c"># Data is explicitly heap-allocated
type Data = ref struct[x: int, y: int, z: str]

# use-after-free


# double-free
func consumes_ptr(data: mut Data) =
  let more_data: Data = {x: 5, y: 6, z: "heap allocated!"}
  data = more_data
  #

let heap_ptr: Data = malloc(Data.sizeof)
consumes_ptr(heap_ptr)
free(heap_ptr) # heap_ptr was already freed! segfault
</code></pre>
<p>The above pseudo-code showcases the two fundamental errors that a safe memory management system aims to solve: <strong>double frees</strong> and <strong>use-after-frees</strong>.</p>
<p><strong>Garbage collected</strong> languages solve this by adding runtime overhead to programs: by injecting a <strong>check</strong> for other existing references before an object would be deallocated, or by periodically <strong>tracing</strong> references to the heap to determine what memory is not live and may be deallocated. But this overhead comes with a problem: there is a class of stubborn programmers who will take minmaxing performance over 70% fewer vulnerabilities any day of the week.</p>
<p>Thus, Rust's system of ownership - restricting...</p>
<p>Puck's primary</p>
<p>The cheapest form of memory management is not having to manage it at all.</p>
<blockquote>
<p>The best memory management is.. not to have to manage it at all!</p>
</blockquote>
<p>small structs</p>
<p>You can have references to heap-allocated memory in types, of course - but it's <em>owned</em> by that...</p>
<p>The whole language is subject to change. But the memory management system, particularly more so - I can sit here and describe how I think it works all day, but I'm inexperienced in the implementation of such systems, and so it's likely I will hit some implementation snags - and although I hope for the best, there is the possibility that some would prove to be fatal.</p>
<hr />
<p>should provide for the closure of such systems
i mean destructors. god</p>
<p>TL;DR: I think the best form of memory management is reference counting: it is deterministic and can be optimized down.</p>
<p>TL;DR: Puck uses semi-optimized reference counting that can be manually optimized into an ownership system.</p>
<p>First, a summary of existing memory systems:</p>
<ul>
<li>manual memory management: extremely unsafe!
<ul>
<li>extremely unsafe, again! but it can be useful/necessary to turn off safety...</li>
</ul>
</li>
<li>tracing garbage collection
<ul>
<li>scans live memory</li>
<li>typically inconsistent i.e. performance spikes</li>
</ul>
</li>
<li>reference counting
<ul>
<li>scans dead memory</li>
<li>typically slow: querying and updating reference counts is actually a fairly heavy operation</li>
</ul>
</li>
<li>ownership / move semantics
<ul>
<li>inflexible: implementing say, linked lists is really hard and has to be done in what amounts to another system</li>
</ul>
</li>
<li>regions?</li>
</ul>
<p>Examples of problems:</p>
<pre><code>x = 5
y = x
free(x)
</code></pre>
<p>puck's memory management should copy Lobster, and take inspiration from Rust.</p>
<p>We should be able to copy the same memory management algorithm as Rust, only instead of failing to compile throw an error</p>
<p>goal: avoid lifetime annotations: https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html</p>
<p>Access errors: invalid read/write of a pointer
Buffer overflow - out-of-bound writes can corrupt the content of adjacent objects, or internal data (like bookkeeping information for the heap) or return addresses.
Buffer over-read - out-of-bound reads can reveal sensitive data or help attackers bypass address space layout randomization.
Race condition - concurrent reads/writes to shared memory
Invalid page fault - accessing a pointer outside the virtual memory space. A null pointer dereference will often cause an exception or program termination in most environments, but can cause corruption in operating system kernels or systems without memory protection, or when use of the null pointer involves a large or negative offset.
Use after free - dereferencing a dangling pointer storing the address of an object that has been deleted.
Uninitialized variables - a variable that has not been assigned a value is used. It may contain an undesired or, in some languages, a corrupt value.
Null pointer dereference - dereferencing an invalid pointer or a pointer to memory that has not been allocated
Wild pointers arise when a pointer is used prior to initialization to some known state. They show the same erratic behavior as dangling pointers, though they are less likely to stay undetected.
Memory leak - when memory usage is not tracked or is tracked incorrectly
Stack exhaustion - occurs when a program runs out of stack space, typically because of too deep recursion. A guard page typically halts the program, preventing memory corruption, but functions with large stack frames may bypass the page.
Heap exhaustion - the program tries to allocate more memory than the amount available. In some languages, this condition must be checked for manually after each allocation.
Double free - repeated calls to free may prematurely free a new object at the same address. If the exact address has not been reused, other corruption may occur, especially in allocators that use free lists.
Invalid free - passing an invalid address to free can corrupt the heap.
Mismatched free - when multiple allocators are in use, attempting to free memory with a deallocation function of a different allocator[20]
Unwanted aliasing - when the same memory location is allocated and modified twice for unrelated purposes.</p>
<hr />
<p>look into: koka/nim (nim i believe is equivalent to koka? but koka has way more documentation)
rust, of course</p>
<h1 id="lifetimes"><a class="header" href="#lifetimes">Lifetimes</a></h1>
<p>no general specification overview, because i don't actually know how thee would work entirely</p>
<h2 id="notes"><a class="header" href="#notes">notes</a></h2>
<p><em>you do not need lifetime annotations</em>.
there <em>is</em> a minimally-correct set of lifetime parameters for any given program:
rust doesn't do this because it doesn't inspect inside function bodies i guess?</p>
<p>lifetimes are probably closely tied to move semantics</p>
<p>so lifetimes come up with things like constants, where everything has a static lifetime</p>
<p>this seems to me like a bit of a hack and really seems ugly, i'm sure you could do with much better with <code>const</code> blocks</p>
<p>in fact i simply must use const exprs i love them</p>
<p>You <em>cannot</em> return a reference from a function.</p>
<hr />
<p>The unsafe parts of the language are <code>ptr</code> and <code>unsafe</code>.</p>
<h2 id="size-of-types"><a class="header" href="#size-of-types">Size of types</a></h2>
<p>The only types where the size is not known at compile time are:</p>
<ul>
<li>interfaces</li>
</ul>
<p>types can become re-sized when used with ref</p>
<h2 id="ownership-and-threads"><a class="header" href="#ownership-and-threads">Ownership and Threads</a></h2>
<p>The only types that are not Send is Rc. The only types that are not Sync are</p>
<h2 id="copy-and-clonedeepcopy"><a class="header" href="#copy-and-clonedeepcopy">Copy and Clone/DeepCopy</a></h2>
<div style="break-before: page; page-break-before: always;"></div><h1 id="metaprogramming"><a class="header" href="#metaprogramming">Metaprogramming</a></h1>
<p>Puck has rich metaprogramming support, heavily inspired by Nim. Many features that would have to be at the compiler level in most languages (error propagation <code>?</code>, <code>std.fmt.print</code>, <code>?</code>, <code>!</code>, <code>-&gt;</code> type sugar, <code>=&gt;</code> closure sugar, <code>async</code>/<code>await</code>) are instead implemented as macros within the standard library.</p>
<p>Macros take in fragments of the AST within their scope, transform them with arbitrary compile-time code, and spit back out transformed AST fragments to be injected and checked for validity. This is similar to what the Lisp family of languages do. It has a number of benefits: there is no separate metaprogramming language, it is syntactically and semantically hygienic, and the underlying framework can be reused for all kinds of compile-time code execution.</p>
<p>By keeping an intentionally minimal AST, some things not possible to express in literal code may be expressible in the AST: in particular, bindings can be injected in many places they could not be injected in ordinarily. (A minimal AST also has the benefit of being quite predictable.)</p>
<h2 id="scope"><a class="header" href="#scope">Scope</a></h2>
<p>Macros may not change Puck's syntax: the syntax is flexible enough. They have the same scope as other routines, that is:</p>
<p><strong>function scope</strong>: takes the arguments within or following a function call</p>
<pre><code class="language-puck">macro print(params: varargs) =
  var res = Call("write", [stdout])
  for param in params do
    res.params.add(param)

print(1, 2, 3, 4)
print "hello", " ", "world", "!"
</code></pre>
<p><strong>block scope</strong>: takes the expression following a colon as a single argument</p>
<pre><code class="language-puck">macro my_macro(body)

my_macro
  1
  2
  3
  4
</code></pre>
<p><strong>operator scope</strong>: takes one or two parameters either as an infix (two parameters) or a postfix (one parameter) operator</p>
<pre><code class="language-puck"># operators are restricted to punctuation
macro +=(a, b) =
  Call("=", [a, Call("+", [a, b])])

a += b
</code></pre>
<h2 id="usage"><a class="header" href="#usage">Usage</a></h2>
<p>Macros typically take a list of parameters <em>without</em> types, but they optionally may be given a type to constrain the usage of a macro. Regardless: as macros operate at compile time, their parameters are not instances of a type, but rather an <code>Expr</code> expression representing a portion of the <em>abstract syntax tree</em>.
Similarly, macros always return an <code>Expr</code> to be injected into the abstract syntax tree despite the usual absence of an explicit return type, but the return type may be specified to additionally typecheck the returned <code>Expr</code>.</p>
<pre><code class="language-puck"></code></pre>
<p>As macros operate at compile time, they may not inspect the <em>values</em> that their parameters evaluate to. However, parameters may be marked <code>const</code>: in which case they will be treated like parameters in functions: as values. (note constant parameters may be written as <code>const[T]</code> or <code>const T</code>.)</p>
<pre><code class="language-puck">macro ?[T, E](self: Result[T, E]) =
  quote
    match `self`
    of Okay(x) then x
    of Error(e) then return Error(e)

func meow: Result[bool, ref Err] =
  let a = stdin.get()?
</code></pre>
<h2 id="quoting"><a class="header" href="#quoting">Quoting</a></h2>
<p>The <code>quote</code> macro is special. It takes in literal code and returns that code <strong>as the AST</strong>. Within quoted data, backticks may be used to break out in order to evaluate and inject arbitrary code: though the code must evaluate to an expression of type <code>Expr</code>. Thus, quoting is <em>structured</em>: one cannot simply quote any arbitrary section. Quoting is very powerful: most macros are implemented using it.</p>
<pre><code class="language-puck"></code></pre>
<p>The <code>Expr</code> type is available from <code>std.ast</code>, as are many helpers, and combined they provide the construction of arbitrary syntax trees (indeed, <code>quote</code> relies on and emits types of it). It is a <code>union</code> type with its variants directly corresponding to the variants of the internal AST of Puck.</p>
<pre><code class="language-puck"></code></pre>
<p>Construction of macros can be difficult: and so several helpers are provided to ease debugging. The <code>Debug</code> and <code>Display</code> interfaces are implemented for abstract syntax trees: <code>dbg</code> will print a representation of the passed syntax tree as an object, and <code>print</code> will print a best-effort representation as literal code. Together with <code>quote</code> and optionally with <code>const</code>, these can be used to quickly get the representation of arbitrary code.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="error-handling-1"><a class="header" href="#error-handling-1">Error Handling</a></h1>
<p>Puck's error handling is heavily inspired syntactically by Swift and semantically by the underlying effects system. It uses a combination of monadic error handling and effectful error propagation, with much in the way of syntactic sugar for conversion between the two, and leans somewhat heavily on Puck's metaprogramming capabilities. In comparison to Rust, it is considerably more dynamic by default.</p>
<p>There are several ways to handle errors in Puck. If the error is encoded in the type (as an <code>Option</code> or <code>Result</code> type), one can:</p>
<ol>
<li><code>match</code> on the error</li>
<li>compactly match on the error with <code>if ... of</code></li>
<li>propagate the error with <code>?</code></li>
<li>throw the error with <code>!</code></li>
</ol>
<p>If the error is thrown (encoded as an effect), one can:</p>
<ol>
<li>ignore the error, propagating it up the call stack</li>
<li>recover from the error in a <code>try</code> block</li>
<li>convert the error to a <code>Result[T]</code> (monadic form)</li>
</ol>
<p>If an error is thrown, one <em>must</em> explicitly handle it at some level of the stack, or risk runtime failure. This method of error handling may feel more familiar to Java programmers. The compiler will warn on - but not enforce catching - such unhandled errors.</p>
<h2 id="errors-as-monads"><a class="header" href="#errors-as-monads">Errors as monads</a></h2>
<p>Puck provides <a href="std/default/options.pk"><code>Option[T]</code></a> and a <a href="std/default/results.pk"><code>Result[T, E]</code></a> types, imported by default. These are <code>union</code> types under the hood and so must be pattern matched upon to be useful: but the standard library provides <a href="std/default/results.pk">a bevy of helper functions</a>.
Two in particular are of note. The <code>?</code> operator unwraps a Result or propagates its error up a function call (and may only be used in type-appropriate contexts). The <code>!</code> operator unwraps an Option or Result directly or throws an exception in the case of None or Error.</p>
<pre><code class="language-puck">pub macro ?[T, E](self: Result[T, E]) =
  quote
    match `self`
    of Okay(x) then x
    of Error(e) then return Error(e)
</code></pre>
<pre><code class="language-puck">pub func ![T](self: Option[T]): T =
  match self
  of Some(x) then x
  of None then raise "empty value"

pub func ![T, E](self: Result[T, E]): T =
  match self
  of Okay(x) then x
  of Error(e) then raise e
</code></pre>
<p>The utility of the provided helpers in <a href="std/default/options.pk"><code>std.options</code></a> and <a href="std/default/results.pk"><code>std.results</code></a> should not be understated. While encoding errors into the type system may appear restrictive at first glance, some syntactic sugar goes a long way in writing compact and idiomatic code. Java programmers in particular are urged to give type-first errors a try, before falling back on unwraps and <code>try</code>/<code>with</code>.</p>
<p>A notable helpful type is the aliasing of <code>Result[T]</code> to <code>Result[T, ref Err]</code>, for when the particular error does not matter. This breaks <code>match</code> exhaustion (as <code>ref Err</code> denotes a reference to <em>any</em> Error), but is particularly useful when used in conjunction with the propagation operator.</p>
<h2 id="errors-as-checked-exceptions"><a class="header" href="#errors-as-checked-exceptions">Errors as checked exceptions</a></h2>
<p>Some functions do not return a value but can still fail: for example, setters. This can make it difficult to do monadic error handling elegantly. One could return a <code>type Success[E] = Result[void, E]</code>, but such an approach is somewhat inelegant. Instead: we treat an <code>assert</code> within a function as having an <em>effect</em>: a possible failure, that can be handled and recovered from at any point in the call stack. If a possible exception is not handled within a function body, the function is implicitly marked by the compiler as throwing that exception.</p>
<pre><code class="language-puck">pub type list[T] = struct
  data: ptr T
  capacity: uint
  length: uint

@[safe]
pub func set[T](self: list[T], i: uint, val: T) =
  if i &gt; self.length then
    raise IndexOutOfBounds
  self.data.set(offset = i, val)

var foo = ["Hello", "world"]
foo.set(0, "Goodbye") # set can panic
# this propagates an IndexOutOfBounds effect up the call stack.
</code></pre>
<p>Despite functioning here as exceptions: errors remain types. An error thrown from an unwrapped <code>Result[T, E]</code> is of type <code>E</code>. <code>with</code> statements, then, may pattern match upon possible errors, behaving semantically and syntactically similarly to <code>of</code> branches: though notably not requiring exhaustion.</p>
<pre><code class="language-puck">try
  foo.set(0, "Goodbye")
with IndexOutOfBounds(index) then
  dbg "Index out of bounds at {}".fmt(index)
  panic
finally
  ...
</code></pre>
<p>This creates a distinction between two types of error handling, working in sync: functional error handling with <a href="https://en.wikipedia.org/wiki/Option_type">Option</a> and <a href="https://en.wikipedia.org/wiki/Result_type">Result</a> types, and <a href="https://en.wikipedia.org/wiki/Exception_handling">object-oriented error handling</a> with <a href="...">algebraic effects</a>. These styles may be swapped between with minimal syntactic overhead. It is up to libraries to determine which classes of errors are exceptional and best given the effect treatment and which should be explicitly handled monadically. Libraries should tend towards using <code>Option</code>/<code>Result</code> as this provides the best support for both styles (thanks to the <code>!</code> operator).</p>
<h2 id="unrecoverable-exceptions"><a class="header" href="#unrecoverable-exceptions">Unrecoverable exceptions</a></h2>
<p>There exist errors from which a program can not reasonably recover. These are the following:</p>
<ul>
<li><code>Assertation Failure</code>: a call to an unhandled <code>assert</code> function has returned false at runtime.</li>
<li><code>Out of Memory</code>: the executable is out of memory.</li>
<li><code>Stack Overflow</code>: the executable has overflowed the stack.</li>
<li>any others?</li>
</ul>
<p>They are not recoverable, and not handled within the effects system, but the user should be aware of them as possible failure conditions.</p>
<hr />
<p>References</p>
<ul>
<li><a href="https://docs.swift.org/swift-book/documentation/the-swift-programming-language/errorhandling">Error Handling in Swift</a></li>
<li><a href="https://overreacted.io/algebraic-effects-for-the-rest-of-us/">Algebraic Effects for the rest of us</a></li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="asynchronous-programming"><a class="header" href="#asynchronous-programming">Asynchronous Programming</a></h1>
<blockquote>
<p>! This section is a <strong>draft</strong>. Many important details have yet to be ironed out.</p>
</blockquote>
<p>Puck has <a href="https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function/">colourless</a> async/await, heavily inspired by <a href="https://kristoff.it/blog/zig-colorblind-async-await/">Zig's implementation</a>.</p>
<pre><code class="language-puck">pub func fetch(url: str): str = ...

let a: Future[T] = async fetch_html()
let b: T = a.await
let c: T = await async fetch_html()
</code></pre>
<p>Puck's async implementation relies heavily on its metaprogramming system.</p>
<p>The <code>async</code> macro will wrap a call returning <code>T</code> in a <code>Future[T]</code> and compute it asynchronously. The <code>await</code> function takes in a <code>Future[T]</code> and will block until it returns a value (or error). The <code>Future[T]</code> type is opaque, containing internal information useful for the <code>async</code> and <code>await</code> routines.</p>
<pre><code class="language-puck">pub macro async(self): Future[T] =
  ... todo ...
</code></pre>
<pre><code class="language-puck">pub func await[T](self: Future[T]): T =
  while not self.ready do
    # block
  self.value! # apply callbacks?
</code></pre>
<p>This implementation differs from standard async/await implementations quite a bit.
In particular, this means there is no concept of an "async function" - any block of computation that resolves to a value can be made asynchronous. This allows for "anonymous" async functions, among other things.</p>
<p>This (packaging up blocks of code to suspend and resume arbitrarily) is <em>hard</em>, and requires particular portable intermediate structures out of the compiler. Luckily, Zig is doing all of the R&amp;D here. Some design decisions to consider revolve around <em>APIs</em>. The Linux kernel interface (among other things) provides both synchronous and asynchronous versions of its API, and fast code will use one or the other, depending if it is in an async context. Zig works around this by way of a known global constant that low-level functions read at compile time to determine whether to operate on synchronous APIs or asynchronous APIs. This is... not great. But what's better?</p>
<!-- Asynchronous programming is hard to design and hard to use. Even Rust doesn't do a great job. It *shouldn't* need built-in language support - we should be able to encode it as a type and provide any special syntax via macros. Note that async is not just threading! threading is solved well by Rust's rayon and Go's (blugh) goroutines. -->
<h2 id="threading"><a class="header" href="#threading">Threading</a></h2>
<p>It should be noted that async is <em>not</em> the same as threading, <em>nor</em> is it solely useful in the presence of threads...</p>
<p>How threads work deserves somewhat of a mention...</p>
<p>References:</p>
<ul>
<li><a href="https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function/">What color is your function?</a></li>
<li><a href="https://kristoff.it/blog/zig-colorblind-async-await/">What is Zig's "colorblind" async/await?</a></li>
<li><a href="https://ziglearn.org/chapter-5/">Zig Learn: Async</a></li>
<li><a href="https://morestina.net/blog/1686/rust-async-is-colored">Rust async is colored and that's not a big deal</a></li>
<li><a href="https://old.reddit.com/r/elixir/np688d/">Why is there no need for async/await in Elixir?</a></li>
<li><a href="https://en.wikipedia.org/wiki/Async/await">Async/await on Wikipedia</a></li>
<li><a href="https://github.com/status-im/nim-chronos">nim-chronos</a></li>
<li><a href="https://github.com/nim-works/cps">nim-cps</a></li>
<li><a href="https://tokio.rs/tokio/tutorial">tokio</a></li>
<li><a href="https://forum.nim-lang.org/t/7347">Zig-style async/await for Nim</a></li>
</ul>
<p>Is async worth having separate from effect handlers? I think so...</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="interop-with-other-languages"><a class="header" href="#interop-with-other-languages">Interop with Other Languages</a></h1>
<blockquote>
<p>! This section is a <strong>draft</strong>. Many important details have yet to be ironed out.</p>
</blockquote>
<p>A major goal of Puck is <em>minimal-overhead language interoperability</em> while maintaining type safety.</p>
<h2 id="the-problems-of-interop"><a class="header" href="#the-problems-of-interop">The problems of interop</a></h2>
<p>There are three issues that complicate language interop:</p>
<ol>
<li>The language of communication, i.e. the C ABI.</li>
<li>Conflicting type systems, i.e. Python vs. Rust</li>
<li>Conflicting memory management systems, i.e. tracing / reference counting vs. ownership</li>
</ol>
<p>For the first, Puck is being written at the same time as the crABI ABI spec is in development. crABI promises a C-ABI-compatible, cross-language ABI spec: which would <em>dramatically</em> simplify the task of linking to object files produced by other languages (so long as languages actually conform to the ABI). It is being led by the Rust language team, and both Nim and Swift developers have expressed interest in it, which bodes quite well for its future.</p>
<p>For the second, Puck has a type system of similar capability to that of Rust, Nim, and Swift: and thus interop with those languages should be a straightforward exchange of types. Its type system is strictly more powerful than that of Python or C, and so interop requires additional help. Its type system is equally as powerful as but somewhat orthogonal to Java's, and so interop will be a little more difficult.</p>
<p>For the third: Puck uses what amounts to a combination of ownership and reference counting: and thus it is exchangeable in this regard with Rust. Nim and Swift, by contrast, use reference counting: which is not directly compatible with ownership, as attempting to use an owned type as a GC'd reference will immediately lead to a use-after-free. Puck may have to explore some form of gradual typing at linking-time to accommodate making its functions available for use. Using functions from GC'd languages, however, is perfectly doable with the <code>refc</code> type: though this may necessitate copying object graphs over the call boundary.</p>
<p>There is additional significant work being put into the use of Wasm as a language runtime. Wasm allows for - among other things - the <em>sharing</em> of garbage collectors, which means that any garbage-collected language compiling to it can simply use the primitive <code>refc</code> type to denote a garbage-collected reference. This does not, however, immediately work off the bat with ownership: as ownership necessitates certain invariants that garbage collection does not preserve. There is active research into fixing this: notably RichWasm, which retrofits a structural type system with ownership atop Wasm. Such extensions necessitate the runtime environment to implement them, however, and so Puck may have to explore some form of gradual typing for the broader Wasm ecosystem.</p>
<h2 id="usability"><a class="header" href="#usability">Usability</a></h2>
<pre><code class="language-puck">use std.io
use rust.os.linux
use nim.os.sleep
...
</code></pre>
<p>Languages often focus on interop from purely technical details. This <em>is</em> very important: but typically little thought is given to usability (and often none can be, for necessity of compiler support), and so using foreign function interfaces very much feel like using <em>foreign</em> function interfaces. Puck attempts to change that.</p>
<pre><code class="language-puck">@[form(this-function)]
pub func this_function() = ...
</code></pre>
<p>A trivial concern is that identifiers are not always the same across languages: for example, in Racket <code>this-function</code> is a valid identifier, while in Puck the <code>-</code> character is disallowed outright. Matters of convention are issues, too: in Puck, <code>snake_case</code> is preferred for functions and <code>PamelCase</code> for types, but this is certainly not always the case. Puck addresses this at an individual level by attributes allowing for rewriting: and at a language level by consistent rewrite rules.</p>
<p>...todo...</p>
<hr />
<p>Existing systems to learn from:</p>
<ul>
<li><a href="https://doc.rust-lang.org/reference/abi.html">The Rust ABI</a></li>
<li><a href="https://www.hobofan.com/rust-interop/">rust-interop</a></li>
<li><a href="https://github.com/eqrion/cbindgen">CBindGen</a></li>
<li><a href="https://github.com/chinedufn/swift-bridge">swift-bridge</a></li>
<li><a href="https://kotlinlang.org/docs/native-c-interop.html">Kotlin C interop</a></li>
<li><a href="https://github.com/crackcomm/rust-lang-interop">rust-lang-interop</a></li>
<li><a href="https://doc.rust-lang.org/reference/items/functions.html#extern-function-qualifier">extern in Rust</a></li>
<li><a href="https://github.com/yglukhov/nimpy">NimPy</a></li>
<li><a href="https://github.com/yglukhov/jnim">JNim</a></li>
<li><a href="https://github.com/PMunch/futhark">Futhark</a></li>
<li><a href="https://lib.haxe.org/p/callfunc/">Haxe's <code>callfunc</code></a></li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="example-programs"><a class="header" href="#example-programs">Example Programs</a></h1>
<p>These are taken directly from the (work-in-progress) stdlib.</p>
<h2 id="stdoptions"><a class="header" href="#stdoptions">std.options</a></h2>
<pre><code class="language-puck">## std.options: Optional types.
## This module is imported by default.

use std.format

## The `Option` type.
## A type that represents either the presence or absence of a value.
pub type Option[T] = union
  Some(T)
  None

## Syntactic sugar for optional type declarations.
pub macro ?(T: type) =
  quote Option[`T`]

## Directly accesses the inner value. Throws an exception if None.
pub func ![T](self: T?): T =
  if self of Some(x) then x
  else raise "empty"

## Indirect access. Propagates `None`.
pub macro ?[T](self: Option[T]) =
  quote
    match `self`
    of Some(x) then x
    of None then return None

## Checks if a type is present within an `Option` type.
pub func is_some[T](self: T?): bool =
  self of Some(_)
## Checks if a type is not present within an `Option` type.
pub func is_none[T](self: T?): bool =
  self of None

## Converts an `Option[T]` to a `Result[T, E]` given a user-provided error.
pub func err[T, E](self: T?, error: E): Result[T, E] =
  if self of Some(x) then
    Okay(x)
  else
    Error(error)

## Applies a function to `T`, if it exists.
pub func map[T, U](self: T?, fn: T -&gt; U): U? =
  if self of Some(x) then
    Some(fn(x))
  else
    None
## Converts `T` to a `None`, if `fn` returns false and it exists.
pub func filter[T](self: T?, fn: T -&gt; bool): T? =
  if self of Some(x) and fn(x) then
    Some(x)
  else
    None

## Applies a function to T, if it exists. Equivalent to `self.map(fn).flatten`.
pub func flatmap[T, U](self: T?, fn: T -&gt; U?): U? =
  if self of Some(x) then
    fn(x)
  else
    None
## Converts from Option[Option[T]] to Option[T].
pub func flatten[T](self: T??): T? =
  if self of Some(Some(x)) then
    Some(x)
  else
    None

## Returns the inner value or a default.
pub func get_or[T](self: T?, default: T): T =
  if self of Some(x) then x
  else default

## Overloads the `==` operation for use on Options.
pub func ==[T](a, b: T?): bool =
  if (a, b) of (Some(x), Some(y)) then
    x == y
  else
    false

## Overloads the `str()` function for use on Options.
pub func str[T: Display](self: T?): str =
  if self of Some(x) then
    "Some({})".fmt(x.str)
  else
    "None"

# references:
# https://nim-lang.github.io/Nim/options.html
# https://doc.rust-lang.org/std/option/enum.Option.html
</code></pre>
<h2 id="stdresults"><a class="header" href="#stdresults">std.results</a></h2>
<pre><code class="language-puck">## std.results: Result types.
## This module is imported by default.

use std.[options, format]

## The Result type. Represents either success or failure.
pub type Result[T, E] = union
  Okay(T)
  Error(E)

## The Err class. Useful for dynamically dispatching errors.
pub type Err = class
  str(Self): str
  dbg(Self): str

## A `Result` type that uses dynamically dispatched errors.
## The `Error` may be any type implementing `Err`.
pub type Result[T] = Result[T, ref Err]
## A `Result` type that only checks for success.
## Does not contain a value.
# pub type Success[E] = Result[void, E]
## A `Result` type that only checks for success.
## Does not contain a value. Dynamically dispatched.
# pub type Success = Result[void]

## Syntactic sugar for dynamic result type declarations.
pub macro !(T: type) =
  quote Result[`T`]

## Indirect access. Propagates `Error`.
pub macro ?[T, E](self: Result[T, E]) =
  quote
    match `self`
    of Okay(x) then x
    of Error(e) then return Error(e)

## Checks if a `Result` type was successful.
pub func is_ok[T, E](self: Result[T, E]): bool =
  self of Okay(_)
## Checks if a `Result` type was not successful.
pub func is_err[T, E](self: Result[T, E]): bool =
  self of Error(_)

## Converts from a `Result[T, E]` to an `Option[T]`.
pub func ok[T, E](self: Result[T, E]): T? =
  if self of Okay(x) then
    Some(x)
  else
    None
## Converts from a `Result[T, E]` to an `Option[E]`.
pub func err[T, E](self: Result[T, E]): E? =
  if self of Error(x) then
    Some(x)
  else
    None

## Applies a function to `T`, if self is `Okay`.
pub func map[T, E, U](self: Result[T, E], fn: T -&gt; U): Result[U, E] =
  match self
  of Okay(x) then
    Okay(fn(x))
  of Error(e) then
    Error(e)
## Applies a function to `E`, if self is `Error`.
pub func map_err[T, E, F](self: Result[T, E], fn: E -&gt; F): Result[T, F] =
  match self
  of Error(e) then
    Error(fn(e))
  of Okay(x) then
    Okay(x)

## Applies a function to `T`, if it exists. Equivalent to `self.map(fn).flatten`.
pub func flatmap[T, E, U](self: Result[T, E], fn: T -&gt; Result[U, E]): Result[U, E] =
  match self
  of Okay(x) then
    fn(x)
  of Error(e) then
    Error(e)
## Converts from a `Result[Result[T, E], E]` to a `Result[T, E]`.
pub func flatten[T, E](self: Result[Result[T, E], E]): Result[T, E] =
  match self
  of Okay(Okay(x)) then
    Okay(x)
  of Okay(Error(e)), Error(e) then
    Error(e)

## Transposes a `Result[Option[T], E]` to an `Option[Result[T, E]]`.
pub func transpose[T, E](self: Result[T?, E]): Result[T, E]? =
  match self
  of Okay(Some(x)) then
    Some(Okay(x))
  of Okay(None), Error(_) then
    None
## Transposes an `Option[Result[T, E]]` to a `Result[Option[T], E]`. Takes a default error.
pub func transpose[T, E](self: Result[T, E]?, error: E): Result[T?, E] =
  match self
  of Some(Okay(x)) then Okay(Some(x))
  of Some(Error(e)) then Error(e)
  of None then Error(error)

## Returns the inner value or a default.
pub func get_or[T, E](self: Result[T, E], default: T): T =
  if self of Okay(x) then x
  else default

## Directly accesses the inner value. Throws an exception if `Error`.
pub func ![T, E](self: Result[T, E]): T =
  match self
  of Okay(x) then x
  of Error(e) then raise e
## Directly accesses the inner error. Throws an exception of type T if `Okay`.
pub func get_err[T, E](self: Result[T, E]): E =
  match self
  of Error(e) then e
  of Okay(x) then raise x

## Overloads the `==` operation for use on Results.
pub func ==[T, E, F](a: Result[T, E], b: Result[T, F]): bool =
  if (a, b) of (Okay(x), Okay(y)) then
    x == y
  else
    false

## Overloads the `str()` function for use on Results.
pub func str[T: Display, E: Display](self: Result[T, E]): str =
  match self
  of Some(x) then
    "Okay({})".fmt(x.str)
  of Error(e) then
    "Error({})".fmt(e.str)

# references:
# https://doc.rust-lang.org/std/result/enum.Result.html
# https://github.com/arnetheduck/nim-results
# https://github.com/codex-storage/questionable
</code></pre>
<h2 id="stdformat"><a class="header" href="#stdformat">std.format</a></h2>
<pre><code class="language-puck">## std.format: Niceties around printing and debugging.
## This module is imported by default.

## The Display class. Any type implementing `str` is printable.
## Any type that is Display must necessarily also implement Debug.
pub type Display = class
  str(Self): str
  dbg(Self): str

## The Debug class. Broadly implemented for every type with compiler magic.
## Types can (and should) override the generic implementations.
pub type Debug = class
  dbg(Self): str

## Prints all of its arguments to the command line.
pub func print(params: varargs[Display]) =
  stdout.write(params.map(x =&gt; x.str).join(" "), "\n")

## Prints all of its arguments to the command line, in Debug form.
##
## Note: this function is special! It does not count as a side effect.
## This breaks effect tracking, of course: but `dbg` is for debugging.
## It will produce a warning in code compiled for release.
@[pure]
pub func dbg(params: varargs[Debug]) =
  stdout.write(params.map(x =&gt; x.dbg).join(" "), "\n")

## A dummy implementation of the Display class for strings.
pub func str(self: str): str = self
## An implementation of the Debug class for strings.
pub func dbg(self: str): str = "\"" &amp; self &amp; "\""

## An implementation of the Debug class for all structs.
## Uses the special `struct` typeclass.
pub func dbg[T: Debug](self: struct[T]): str =
  "{{}}".fmt(self.fields.map((key, val) =&gt; key &amp; ":" &amp; val.dbg))

## An implementation of the Debug class for all tuples.
## Uses the special `tuple` typeclass.
pub func dbg[T: Debug](self: tuple[T]): str =
  "({})".fmt(self.fields.map((key, val) =&gt;
    key.map(x =&gt; x &amp; ":").get_or("") &amp; val.dbg).join(", "))

## An implementation of the Debug class for all arrays and lists.
pub func dbg[T: Debug](self: Iter[T]): str =
  "[{}]".fmt(self.map(x =&gt; x.dbg).join(", "))

## The fmt macro. Builds a formatted string from its arguments.
pub macro fmt(self: const str, args: varargs[Display]): str =
  let parts = self.split("{}")
  if parts.len != args.len + 1 then
    macro_error("wrong number of arguments")
  use std.ast
  var res = parts.get(0)!
  for i, arg in args do
    res &amp;= quote(`parts` &amp; str(`arg`) &amp;) # fixme
  res &amp;= parts.last()!
  res
</code></pre>
<h2 id="stddebug"><a class="header" href="#stddebug">std.debug</a></h2>
<pre><code class="language-puck">## std.debug: Useful functions for debugging.
## This module is imported by default.

## The `assert` macro checks that a provided assertation is true,
## and panics and dumps information if it is not.
## Asserts remain in release builds. If not desired, see `dbg_assert`
pub macro assert(cond: bool) =
  quote
    if not `cond` then
      panic "assertation failed!\n {}".fmt(dbg(`cond`))

## The `dbg_assert` function provides an assert that is compiled out in release builds.
## This is useful for debugging performance-critical code.
pub macro dbg_assert(cond: bool) =
  quote
    when debug then # fixme: where is this constant coming from?
      assert `cond`

## The `discard` function consumes an object of any type.
## Useful for throwing away the result of a computation.
pub func discard[T](self: T) =
  return

## The `panic` function prints a message to `stderr` and quits.
pub func panic(message: str): never =
  stderr.write(message, "\n")
  std.os.exit(1)

## The special ... syntax is used to mark unimplemented parts of code.
## Such code will compile, but panic upon being called at runtime.
## It is usable almost anywhere, including in type declarations, thanks to compiler magic.
@[magic]
pub func ...: never =
  panic("unimplemented")
</code></pre>
<h2 id="stdlists"><a class="header" href="#stdlists">std.lists</a></h2>
<pre><code class="language-puck">## std.lists: Dynamic arrays.
## This module is imported by default.

## The fundamental list type. Heap-allocated.
## Equivalent to Vec&lt;T&gt; in other languages.
@[opaque] # opaque on a struct tells us raw field access breaks invariants.
pub type list[T] = struct
  data: ptr T
  capacity: uint
  length: uint

## A transparent, common alias for a list of bytes.
pub type bytes = list[byte]

## Initialize and return an empty list with inner type T.
pub func init[T]: list[T] =
  { data = nil, capacity = 0, length = 0 } # fixme: nil!!!!!

## Gets the length of a list.
@[inline] # idk what to do with attributes
pub func len[T](self: lent list[T]): uint =
  self.length

pub func empty[T](self: lent list[T]): bool =
  self.length == 0

## Gets the internal capacity of a list.
func cap[T](self: lent list[T]): uint =
  self.capacity

## Expands the capacity of a list.
@[safe]
func grow[T](self: mut list[T]) =
  self.capacity = max(self.length + 1, self.capacity * 2)
  self.data = self.data.realloc(self.capacity * sizeof(T))

## Pushes a new element to the end of a list.
@[safe]
pub func push[T](self: mut list[T], val: T) =
  if self.capacity == self.length then self.grow()
  self.data.set(val, offset = self.length)
  self.length += 1

## Takes ownership of and pushes all the values of a list into another list.
pub func push[T](self: mut list[T], values: list[T]) =
  for val in values do
    self.push(val)

## Removes &amp; returns an element from the end of a list, if it exists.
@[safe]
pub func pop[T](self: mut list[T]): T? =
  if self.length == 0 then
    None
  else
    self.length -= 1
    Some(self.data.get(offset = self.length))

## Returns a reference to an element of a list, if in range.
@[safe]
pub func get[T](self: lent list[T], i: uint): lent T? =
  if i &gt; self.length then
    None
  else # fixme: interior mutability
    Some(lent self.data.get(offset = i))
## Returns a mutable reference to an element of a list, if in range.
@[safe]
pub func get[T](self: mut list[T], i: uint): mut T? =
  if i &gt; self.length then
    None
  else # fixme: interior mutability
    Some(mut self.data.get(offset = i))

## Sets the element of a list to a value.
@[safe]
pub func set[T](self: mut list[T], i: uint, val: T) =
  assert i &lt;= self.length, "index out of bounds"
  Okay(self.data.set(offset = i, val))

## Inserts a value at a location and shifts elements of the list accordingly.
@[safe]
pub func insert[T](self: mut list[T], i: uint, val: T) =
  assert i &lt;= self.length, "index out of bounds"
  if self.capacity == self.length then self.grow()
  self.data.offset(i).copy(self.data.offset(i + 1), self.length - i)
  self.data.set(i, val)
  self.length += 1
## Inserts a list of values at a location and shifts elements of the list accordingly.
pub func insert[T](self: mut list[T], i: uint, vals: list[T]) =
  for val in vals.rev: # inserting backwards avoids counting
    self.insert(val, i)

## Removes a value at a location and shifts elements of the list accordingly.
@[safe]
pub func remove[T](self: mut list[T], i: uint): T? =
  if index &lt; self.length then None
  else
    self.length -= 1
    let res = self.data.get(i)
    self.data.offset(i + 1).copy(self.data.offset(i), self.length - i)
    res

## Gets the last element of a list, if it exists.
pub func last[T](self: lent list[T]): lent T? =
  self.get(self.len - 1)
## Gets the last element of a list mutably, if it exists.
pub func last[T](self: mut list[T]): mut T? =
  self.get(self.len - 1)

# reference: https://doc.rust-lang.org/nomicon/vec/vec.html
</code></pre>
<h2 id="stdstrings"><a class="header" href="#stdstrings">std.strings</a></h2>
<pre><code class="language-puck">## std.strings: The standard implementation of strings.
## This module is imported by default.

## A primitive string type.
##
## We do not want methods defined on `list[byte]` to carry over,
## so we define `str` as a newtype.
@[opaque]
pub type str = struct
  data: list[byte]

## Initialize and return an empty string.
pub func init: str = { data = [] }

## Gets the length of a string.
## This is an O(n) operation, due to UTF-8 encoding.
pub func len(self: lent str): uint =
  var res: uint
  for _ in self do
    res += 1
  res

## Pushes a character to the end of a mutable string.
pub func push(self: mut str, val: char) =
  self.data.push(val.byte) # todo: obsolete by from/to conversion??

## Pushes an owned string to the end of a mutable string.
pub func push(self: mut str, val: str) =
  self.data.push(val.bytes) # todo: obsolete by from/to conversion??

## Removes and returns the last character of a string, if it exists.
##
## SAFETY: We return early upon an empty string.
## And decrement by one char for a non-empty string.
@[safe]
pub func pop(self: mut str): char? =
  let char = self.chars.rev.next?
  self.data.set_len(self.len - char.len) # this is normally unsafe.
  Some(char)

## Returns the character at the provided index, if it exists.
pub func get(self: str, i: uint): char? =
  ...

## Sets the character at the provided index, if it exists.
## As strings are packed, this may call str.grow and reallocate.
## oh fuck we have to insert + remove anyway
pub func set(self: mut str, i: uint, val: char) =
  ...

## Inserts a character at an arbitrary position within a string.
## Panics on failure. (todo: can we do better?)
pub func insert(self: mut str, i: uint, val: char) =
  ...

## Removes and returns a character at an arbitrary position within a string.
## Panics on failure. (todo: can we do better?)
pub func remove(self: mut str, i: uint): char? =
  ...

## Syntactic sugar for string appending.
pub func &amp;=(a: mut str, b: str) =
  a.push(b)

## The concatenation operator. Consumes two strings.
pub func &amp;(a: str, b: str): str =
  a.push(b)
  a

## Conversion from a string to a list of bytes. Zero-cost.
pub func to(self: str): list[byte] = self.data
## Conversion from a str to a list[char]. Reallocates.
pub func to(self: str): list[char] =
  var res: list[char]
  for char in self do res.push(char)
  res
## Conversion from a char to an array of bytes. Zero-cost.
@[safe] # possibly unsafe?? depends on repr of arrays
pub func to(self: char): array[byte, 4] =
  self.cast[array[byte, 4]]

# reference: https://doc.rust-lang.org/std/string/struct.String.html
</code></pre>
<h2 id="stdcompare"><a class="header" href="#stdcompare">std.compare</a></h2>
<pre><code class="language-puck">## std.compare: Classes for comparable types.

## The Eq class. For types with some notion of equivalence.
pub type Eq = class
  ==(Self, Self): bool

## A blanket implementation of a corresponding not-equal function.
pub !=[T: Eq](a: T, b: T): bool =
  not(a == b)

## The Compare class. For a type comparable with itself.
pub type Compare = class
  &lt;(a: Self, b: Self): bool

## A blanket implementation of a corresponding greater-than function.
## Note to self: do NOT inline!
pub func &gt;[T: Compare](a: T, b: T): bool =
  b &lt; a

## The Ord class. For types with some notion of equivalence and comparision.
##
## Note: This is *not* a mathematical notion of an order!
## No invariants on `&lt;` nor `==` are guaranteed to hold, as classes
## are implicitly implementable.
pub type Ord = class
  &lt;(a: Self, b: Self): bool
  ==(a: Self, b: Self): bool

## A blanket implementation of a corresponding less-than-or-equal function.
pub func &lt;=[T: Ord](a: T, b: T): bool =
  a &lt; b or a == b

## A blanket implementation of a corresponding greater-than-or-equal function.
pub func &gt;=[T: Ord](a: T, b: T): bool =
  a &gt; b or a == b

# reference: https://doc.rust-lang.org/std/cmp
</code></pre>
<h2 id="stdconvert"><a class="header" href="#stdconvert">std.convert</a></h2>
<pre><code class="language-puck">## std.convert: Classes for type coersion and conversion.
## This module is imported by default.

## The Coerce class is used for type conversion that will not fail.
## Its associated methods, `from` and `into`, are used internally
## by the compiler for implicit type conversion (coersion).
pub type Coerce[T] = class
  to(Self): T
  # from(T): Self

## The `from` function is automatically implemented for all types that
## implement `to`: that is, all types T that are convertable to U.
pub func from[T: Coerce[U], U](self: U): T =
  to(self)

## The Convert class is used for type conversion that may fail.
# We'll see what this breaks.
pub type Convert[T, E] = class
  to(Self): Result[T, E]
</code></pre>
<h2 id="stdranges"><a class="header" href="#stdranges">std.ranges</a></h2>
<pre><code class="language-puck">## std.ranges: Ranges of integers and other things. For iteration.
## This module is imported by default.

type Range[T] = struct
  start: T
  end: T

type RangeIncl[T] = struct
  start: T
  end: T
  done: bool

## Exclusive ranges. Useful for iteration.
## Includes `from`, does not include `to`.
pub func ..(from: int, to: int): Range[int] = { from, to }

## Inclusive ranges. Useful for ranges.
## Includes `from` and `to`.
pub func ..=(from: int, to: int): RangeIncl[int] = { from, to, done = false }

# todo: implement for all types that can increment or smth idk
pub func next[T: int](self: mut Range[T]): T? =
  if self.start &lt; self.end then
    self.start += 1
    Some(self.start - 1)
  else
    None

# todo: We don't need a mutable Range here to peek.
# How does this interact with classes?
pub func peek[T: int](self: mut Range[T]): T? =
  self.peek_nth(0)

pub func peek_nth[T: int](self: mut Range[T], i: uint): T? =
  let res = self.start + i
  if res &lt; self.end then
    Some(res)
  else
    None

pub func next[T: int](self: mut RangeIncl[T]): T? =
  if self.done then
    None
  elif self.start &lt; self.end then
    let res = self.start
    self.start += 1
    Some(res)
  elif self.start == self.end then
    self.done = true
    Some(self.start)
  else
    self.done = true
    None

pub func peek[T: int](self: mut RangeIncl[T]): T? =
  self.peek_nth(0)

pub func peek_nth[T: int](self: mut RangeIncl[T], i: uint): T? =
  let res = self.start + i
  if res &lt;= self.end
  then Some(res)
  else None
</code></pre>
<h2 id="stdast"><a class="header" href="#stdast">std.ast</a></h2>
<pre><code class="language-puck">## std.ast: Exposes the AST for building and operating on with macros.

## The `Expr` type represents the abstract syntax tree of Puck itself.
## It notably lacks type information. It is also not necessarily syntactically
## correct-by-construction: Cond, Try, and Match expressions must have at least
## one branch in their branches (yet this is not expressible here).
pub type Expr = union
  # Terms
  Ident(str)
  Number(int)
  Float(float)
  Char(char)
  String(str)
  Struct(list[(field: str, value: Expr)]) # {...}
  Tuple(list[(field: str?, value: Expr)]) # (...)
  List(list[Expr]) # [...]
  # Bindings
  Let(id: Pattern, kind: Type?, value: ref Expr)
  Var(id: Pattern, kind: Type?, value: ref[Expr]?)
  Constant(public: bool, id: Pattern, kind: Type?, value: ref Expr)
  FuncDecl(
    public: bool,
    id: str,
    generics: list[(id: str, kind: Type?)],
    params: list[(id: str, kind: Type)],
    kind: Type?,
    body: list[Expr])
  MacroDecl(
    public: bool,
    id: str,
    generics: list[(id: str, kind: Type?)],
    params: list[(id: str, kind: Type?)],
    kind: Type?,
    body: list[Expr])
  TypeDecl(
    public: bool,
    id: str,
    generics: list[str],
    body: Type)
  Module(
    public: bool,
    id: str,
    generics: list[str], # always empty for now
    body: list[Expr])
  Use(modules: list[(path: str, alias: str?)])
  # Control Flow
  Call(id: str, params: list[Expr])
  Cond(
    branches: list[(cond: Expr, body: list[Expr])],
    else_body: list[Expr])
  Try(
    try_body: list[Expr],
    catches: list[(exceptions: list[str], body: list[Expr])],
    finally_body: list[Expr]) # todo: throw this out
  Match(
    item: ref Expr,
    branches: list[(pattern: Pattern, guard: Expr?, body: list[Expr])])
  Block(id: str?, body: list[Expr])
  Static(body: list[Expr])
  For(binding: Pattern, range: ref Expr, body: list[Expr])
  While(cond: ref Expr, body: list[Expr])
  Loop(body: list[Expr])
  Attribute(on: ref Expr)
  Quote(body: ref Expr)
  Unquote(body: ref Expr)

pub type Type = ref union
  Never
  Int(size: uint)
  Dec(size: uint)
  Float(size: uint)
  Func(from: list[Type], to: Type)
  Struct(list[(id: str, kind: Type)])
  Tuple(list[(id: str?, kind: Type)])
  Union(list[(id: str, kind: Type)])
  Class(list[(id: str, from: list[Type], to: Type?)])
  Array(size: uint, kind: Type)
  List(Type)
  Slice(Type) # todo: plus ownership
  Alias(str) # todo: params?? huh?
  Const(Type)
  Lent(Type)
  Mut(Type)
  Ref(Type)
  Refc(Type)
  Ptr(Type)

pub type Pattern = union
  Ident(str)
  Number(int), Float(float), Char(char), String(str)
  Struct(name: str, params: list[Pattern])
  Tuple(list[Pattern])
  List(list[Pattern])

@[magic]
pub func quote(body): Expr
</code></pre>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->


                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">

            </nav>

        </div>




        <script>
            window.playground_copyable = true;
        </script>


        <script src="elasticlunr.min.js"></script>
        <script src="mark.min.js"></script>
        <script src="searcher.js"></script>

        <script src="clipboard.min.js"></script>
        <script src="highlight.js"></script>
        <script src="book.js"></script>

        <!-- Custom JS scripts -->

        <script>
        window.addEventListener('load', function() {
            window.setTimeout(window.print, 100);
        });
        </script>

    </div>
    </body>
</html>
generated by cgit v1.2.3-70-g09d2 (git 2.47.1) at 2024-12-22 16:07:50 +0000