summaryrefslogtreecommitdiff
path: root/docs/users_guide/glasgow_exts.rst
blob: 8ec105f3a0331537727a435a12a4618ad8685ea4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
4828
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
4941
4942
4943
4944
4945
4946
4947
4948
4949
4950
4951
4952
4953
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
5002
5003
5004
5005
5006
5007
5008
5009
5010
5011
5012
5013
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
5624
5625
5626
5627
5628
5629
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
5661
5662
5663
5664
5665
5666
5667
5668
5669
5670
5671
5672
5673
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
5694
5695
5696
5697
5698
5699
5700
5701
5702
5703
5704
5705
5706
5707
5708
5709
5710
5711
5712
5713
5714
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
5742
5743
5744
5745
5746
5747
5748
5749
5750
5751
5752
5753
5754
5755
5756
5757
5758
5759
5760
5761
5762
5763
5764
5765
5766
5767
5768
5769
5770
5771
5772
5773
5774
5775
5776
5777
5778
5779
5780
5781
5782
5783
5784
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
5809
5810
5811
5812
5813
5814
5815
5816
5817
5818
5819
5820
5821
5822
5823
5824
5825
5826
5827
5828
5829
5830
5831
5832
5833
5834
5835
5836
5837
5838
5839
5840
5841
5842
5843
5844
5845
5846
5847
5848
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
5882
5883
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
5905
5906
5907
5908
5909
5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
5920
5921
5922
5923
5924
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935
5936
5937
5938
5939
5940
5941
5942
5943
5944
5945
5946
5947
5948
5949
5950
5951
5952
5953
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
6119
6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218
6219
6220
6221
6222
6223
6224
6225
6226
6227
6228
6229
6230
6231
6232
6233
6234
6235
6236
6237
6238
6239
6240
6241
6242
6243
6244
6245
6246
6247
6248
6249
6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
6261
6262
6263
6264
6265
6266
6267
6268
6269
6270
6271
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
6291
6292
6293
6294
6295
6296
6297
6298
6299
6300
6301
6302
6303
6304
6305
6306
6307
6308
6309
6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
6357
6358
6359
6360
6361
6362
6363
6364
6365
6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
6429
6430
6431
6432
6433
6434
6435
6436
6437
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
6535
6536
6537
6538
6539
6540
6541
6542
6543
6544
6545
6546
6547
6548
6549
6550
6551
6552
6553
6554
6555
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
7001
7002
7003
7004
7005
7006
7007
7008
7009
7010
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021
7022
7023
7024
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
7035
7036
7037
7038
7039
7040
7041
7042
7043
7044
7045
7046
7047
7048
7049
7050
7051
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
7063
7064
7065
7066
7067
7068
7069
7070
7071
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
7083
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
7098
7099
7100
7101
7102
7103
7104
7105
7106
7107
7108
7109
7110
7111
7112
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124
7125
7126
7127
7128
7129
7130
7131
7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162
7163
7164
7165
7166
7167
7168
7169
7170
7171
7172
7173
7174
7175
7176
7177
7178
7179
7180
7181
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
7197
7198
7199
7200
7201
7202
7203
7204
7205
7206
7207
7208
7209
7210
7211
7212
7213
7214
7215
7216
7217
7218
7219
7220
7221
7222
7223
7224
7225
7226
7227
7228
7229
7230
7231
7232
7233
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243
7244
7245
7246
7247
7248
7249
7250
7251
7252
7253
7254
7255
7256
7257
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287
7288
7289
7290
7291
7292
7293
7294
7295
7296
7297
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
7347
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357
7358
7359
7360
7361
7362
7363
7364
7365
7366
7367
7368
7369
7370
7371
7372
7373
7374
7375
7376
7377
7378
7379
7380
7381
7382
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400
7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
7411
7412
7413
7414
7415
7416
7417
7418
7419
7420
7421
7422
7423
7424
7425
7426
7427
7428
7429
7430
7431
7432
7433
7434
7435
7436
7437
7438
7439
7440
7441
7442
7443
7444
7445
7446
7447
7448
7449
7450
7451
7452
7453
7454
7455
7456
7457
7458
7459
7460
7461
7462
7463
7464
7465
7466
7467
7468
7469
7470
7471
7472
7473
7474
7475
7476
7477
7478
7479
7480
7481
7482
7483
7484
7485
7486
7487
7488
7489
7490
7491
7492
7493
7494
7495
7496
7497
7498
7499
7500
7501
7502
7503
7504
7505
7506
7507
7508
7509
7510
7511
7512
7513
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555
7556
7557
7558
7559
7560
7561
7562
7563
7564
7565
7566
7567
7568
7569
7570
7571
7572
7573
7574
7575
7576
7577
7578
7579
7580
7581
7582
7583
7584
7585
7586
7587
7588
7589
7590
7591
7592
7593
7594
7595
7596
7597
7598
7599
7600
7601
7602
7603
7604
7605
7606
7607
7608
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618
7619
7620
7621
7622
7623
7624
7625
7626
7627
7628
7629
7630
7631
7632
7633
7634
7635
7636
7637
7638
7639
7640
7641
7642
7643
7644
7645
7646
7647
7648
7649
7650
7651
7652
7653
7654
7655
7656
7657
7658
7659
7660
7661
7662
7663
7664
7665
7666
7667
7668
7669
7670
7671
7672
7673
7674
7675
7676
7677
7678
7679
7680
7681
7682
7683
7684
7685
7686
7687
7688
7689
7690
7691
7692
7693
7694
7695
7696
7697
7698
7699
7700
7701
7702
7703
7704
7705
7706
7707
7708
7709
7710
7711
7712
7713
7714
7715
7716
7717
7718
7719
7720
7721
7722
7723
7724
7725
7726
7727
7728
7729
7730
7731
7732
7733
7734
7735
7736
7737
7738
7739
7740
7741
7742
7743
7744
7745
7746
7747
7748
7749
7750
7751
7752
7753
7754
7755
7756
7757
7758
7759
7760
7761
7762
7763
7764
7765
7766
7767
7768
7769
7770
7771
7772
7773
7774
7775
7776
7777
7778
7779
7780
7781
7782
7783
7784
7785
7786
7787
7788
7789
7790
7791
7792
7793
7794
7795
7796
7797
7798
7799
7800
7801
7802
7803
7804
7805
7806
7807
7808
7809
7810
7811
7812
7813
7814
7815
7816
7817
7818
7819
7820
7821
7822
7823
7824
7825
7826
7827
7828
7829
7830
7831
7832
7833
7834
7835
7836
7837
7838
7839
7840
7841
7842
7843
7844
7845
7846
7847
7848
7849
7850
7851
7852
7853
7854
7855
7856
7857
7858
7859
7860
7861
7862
7863
7864
7865
7866
7867
7868
7869
7870
7871
7872
7873
7874
7875
7876
7877
7878
7879
7880
7881
7882
7883
7884
7885
7886
7887
7888
7889
7890
7891
7892
7893
7894
7895
7896
7897
7898
7899
7900
7901
7902
7903
7904
7905
7906
7907
7908
7909
7910
7911
7912
7913
7914
7915
7916
7917
7918
7919
7920
7921
7922
7923
7924
7925
7926
7927
7928
7929
7930
7931
7932
7933
7934
7935
7936
7937
7938
7939
7940
7941
7942
7943
7944
7945
7946
7947
7948
7949
7950
7951
7952
7953
7954
7955
7956
7957
7958
7959
7960
7961
7962
7963
7964
7965
7966
7967
7968
7969
7970
7971
7972
7973
7974
7975
7976
7977
7978
7979
7980
7981
7982
7983
7984
7985
7986
7987
7988
7989
7990
7991
7992
7993
7994
7995
7996
7997
7998
7999
8000
8001
8002
8003
8004
8005
8006
8007
8008
8009
8010
8011
8012
8013
8014
8015
8016
8017
8018
8019
8020
8021
8022
8023
8024
8025
8026
8027
8028
8029
8030
8031
8032
8033
8034
8035
8036
8037
8038
8039
8040
8041
8042
8043
8044
8045
8046
8047
8048
8049
8050
8051
8052
8053
8054
8055
8056
8057
8058
8059
8060
8061
8062
8063
8064
8065
8066
8067
8068
8069
8070
8071
8072
8073
8074
8075
8076
8077
8078
8079
8080
8081
8082
8083
8084
8085
8086
8087
8088
8089
8090
8091
8092
8093
8094
8095
8096
8097
8098
8099
8100
8101
8102
8103
8104
8105
8106
8107
8108
8109
8110
8111
8112
8113
8114
8115
8116
8117
8118
8119
8120
8121
8122
8123
8124
8125
8126
8127
8128
8129
8130
8131
8132
8133
8134
8135
8136
8137
8138
8139
8140
8141
8142
8143
8144
8145
8146
8147
8148
8149
8150
8151
8152
8153
8154
8155
8156
8157
8158
8159
8160
8161
8162
8163
8164
8165
8166
8167
8168
8169
8170
8171
8172
8173
8174
8175
8176
8177
8178
8179
8180
8181
8182
8183
8184
8185
8186
8187
8188
8189
8190
8191
8192
8193
8194
8195
8196
8197
8198
8199
8200
8201
8202
8203
8204
8205
8206
8207
8208
8209
8210
8211
8212
8213
8214
8215
8216
8217
8218
8219
8220
8221
8222
8223
8224
8225
8226
8227
8228
8229
8230
8231
8232
8233
8234
8235
8236
8237
8238
8239
8240
8241
8242
8243
8244
8245
8246
8247
8248
8249
8250
8251
8252
8253
8254
8255
8256
8257
8258
8259
8260
8261
8262
8263
8264
8265
8266
8267
8268
8269
8270
8271
8272
8273
8274
8275
8276
8277
8278
8279
8280
8281
8282
8283
8284
8285
8286
8287
8288
8289
8290
8291
8292
8293
8294
8295
8296
8297
8298
8299
8300
8301
8302
8303
8304
8305
8306
8307
8308
8309
8310
8311
8312
8313
8314
8315
8316
8317
8318
8319
8320
8321
8322
8323
8324
8325
8326
8327
8328
8329
8330
8331
8332
8333
8334
8335
8336
8337
8338
8339
8340
8341
8342
8343
8344
8345
8346
8347
8348
8349
8350
8351
8352
8353
8354
8355
8356
8357
8358
8359
8360
8361
8362
8363
8364
8365
8366
8367
8368
8369
8370
8371
8372
8373
8374
8375
8376
8377
8378
8379
8380
8381
8382
8383
8384
8385
8386
8387
8388
8389
8390
8391
8392
8393
8394
8395
8396
8397
8398
8399
8400
8401
8402
8403
8404
8405
8406
8407
8408
8409
8410
8411
8412
8413
8414
8415
8416
8417
8418
8419
8420
8421
8422
8423
8424
8425
8426
8427
8428
8429
8430
8431
8432
8433
8434
8435
8436
8437
8438
8439
8440
8441
8442
8443
8444
8445
8446
8447
8448
8449
8450
8451
8452
8453
8454
8455
8456
8457
8458
8459
8460
8461
8462
8463
8464
8465
8466
8467
8468
8469
8470
8471
8472
8473
8474
8475
8476
8477
8478
8479
8480
8481
8482
8483
8484
8485
8486
8487
8488
8489
8490
8491
8492
8493
8494
8495
8496
8497
8498
8499
8500
8501
8502
8503
8504
8505
8506
8507
8508
8509
8510
8511
8512
8513
8514
8515
8516
8517
8518
8519
8520
8521
8522
8523
8524
8525
8526
8527
8528
8529
8530
8531
8532
8533
8534
8535
8536
8537
8538
8539
8540
8541
8542
8543
8544
8545
8546
8547
8548
8549
8550
8551
8552
8553
8554
8555
8556
8557
8558
8559
8560
8561
8562
8563
8564
8565
8566
8567
8568
8569
8570
8571
8572
8573
8574
8575
8576
8577
8578
8579
8580
8581
8582
8583
8584
8585
8586
8587
8588
8589
8590
8591
8592
8593
8594
8595
8596
8597
8598
8599
8600
8601
8602
8603
8604
8605
8606
8607
8608
8609
8610
8611
8612
8613
8614
8615
8616
8617
8618
8619
8620
8621
8622
8623
8624
8625
8626
8627
8628
8629
8630
8631
8632
8633
8634
8635
8636
8637
8638
8639
8640
8641
8642
8643
8644
8645
8646
8647
8648
8649
8650
8651
8652
8653
8654
8655
8656
8657
8658
8659
8660
8661
8662
8663
8664
8665
8666
8667
8668
8669
8670
8671
8672
8673
8674
8675
8676
8677
8678
8679
8680
8681
8682
8683
8684
8685
8686
8687
8688
8689
8690
8691
8692
8693
8694
8695
8696
8697
8698
8699
8700
8701
8702
8703
8704
8705
8706
8707
8708
8709
8710
8711
8712
8713
8714
8715
8716
8717
8718
8719
8720
8721
8722
8723
8724
8725
8726
8727
8728
8729
8730
8731
8732
8733
8734
8735
8736
8737
8738
8739
8740
8741
8742
8743
8744
8745
8746
8747
8748
8749
8750
8751
8752
8753
8754
8755
8756
8757
8758
8759
8760
8761
8762
8763
8764
8765
8766
8767
8768
8769
8770
8771
8772
8773
8774
8775
8776
8777
8778
8779
8780
8781
8782
8783
8784
8785
8786
8787
8788
8789
8790
8791
8792
8793
8794
8795
8796
8797
8798
8799
8800
8801
8802
8803
8804
8805
8806
8807
8808
8809
8810
8811
8812
8813
8814
8815
8816
8817
8818
8819
8820
8821
8822
8823
8824
8825
8826
8827
8828
8829
8830
8831
8832
8833
8834
8835
8836
8837
8838
8839
8840
8841
8842
8843
8844
8845
8846
8847
8848
8849
8850
8851
8852
8853
8854
8855
8856
8857
8858
8859
8860
8861
8862
8863
8864
8865
8866
8867
8868
8869
8870
8871
8872
8873
8874
8875
8876
8877
8878
8879
8880
8881
8882
8883
8884
8885
8886
8887
8888
8889
8890
8891
8892
8893
8894
8895
8896
8897
8898
8899
8900
8901
8902
8903
8904
8905
8906
8907
8908
8909
8910
8911
8912
8913
8914
8915
8916
8917
8918
8919
8920
8921
8922
8923
8924
8925
8926
8927
8928
8929
8930
8931
8932
8933
8934
8935
8936
8937
8938
8939
8940
8941
8942
8943
8944
8945
8946
8947
8948
8949
8950
8951
8952
8953
8954
8955
8956
8957
8958
8959
8960
8961
8962
8963
8964
8965
8966
8967
8968
8969
8970
8971
8972
8973
8974
8975
8976
8977
8978
8979
8980
8981
8982
8983
8984
8985
8986
8987
8988
8989
8990
8991
8992
8993
8994
8995
8996
8997
8998
8999
9000
9001
9002
9003
9004
9005
9006
9007
9008
9009
9010
9011
9012
9013
9014
9015
9016
9017
9018
9019
9020
9021
9022
9023
9024
9025
9026
9027
9028
9029
9030
9031
9032
9033
9034
9035
9036
9037
9038
9039
9040
9041
9042
9043
9044
9045
9046
9047
9048
9049
9050
9051
9052
9053
9054
9055
9056
9057
9058
9059
9060
9061
9062
9063
9064
9065
9066
9067
9068
9069
9070
9071
9072
9073
9074
9075
9076
9077
9078
9079
9080
9081
9082
9083
9084
9085
9086
9087
9088
9089
9090
9091
9092
9093
9094
9095
9096
9097
9098
9099
9100
9101
9102
9103
9104
9105
9106
9107
9108
9109
9110
9111
9112
9113
9114
9115
9116
9117
9118
9119
9120
9121
9122
9123
9124
9125
9126
9127
9128
9129
9130
9131
9132
9133
9134
9135
9136
9137
9138
9139
9140
9141
9142
9143
9144
9145
9146
9147
9148
9149
9150
9151
9152
9153
9154
9155
9156
9157
9158
9159
9160
9161
9162
9163
9164
9165
9166
9167
9168
9169
9170
9171
9172
9173
9174
9175
9176
9177
9178
9179
9180
9181
9182
9183
9184
9185
9186
9187
9188
9189
9190
9191
9192
9193
9194
9195
9196
9197
9198
9199
9200
9201
9202
9203
9204
9205
9206
9207
9208
9209
9210
9211
9212
9213
9214
9215
9216
9217
9218
9219
9220
9221
9222
9223
9224
9225
9226
9227
9228
9229
9230
9231
9232
9233
9234
9235
9236
9237
9238
9239
9240
9241
9242
9243
9244
9245
9246
9247
9248
9249
9250
9251
9252
9253
9254
9255
9256
9257
9258
9259
9260
9261
9262
9263
9264
9265
9266
9267
9268
9269
9270
9271
9272
9273
9274
9275
9276
9277
9278
9279
9280
9281
9282
9283
9284
9285
9286
9287
9288
9289
9290
9291
9292
9293
9294
9295
9296
9297
9298
9299
9300
9301
9302
9303
9304
9305
9306
9307
9308
9309
9310
9311
9312
9313
9314
9315
9316
9317
9318
9319
9320
9321
9322
9323
9324
9325
9326
9327
9328
9329
9330
9331
9332
9333
9334
9335
9336
9337
9338
9339
9340
9341
9342
9343
9344
9345
9346
9347
9348
9349
9350
9351
9352
9353
9354
9355
9356
9357
9358
9359
9360
9361
9362
9363
9364
9365
9366
9367
9368
9369
9370
9371
9372
9373
9374
9375
9376
9377
9378
9379
9380
9381
9382
9383
9384
9385
9386
9387
9388
9389
9390
9391
9392
9393
9394
9395
9396
9397
9398
9399
9400
9401
9402
9403
9404
9405
9406
9407
9408
9409
9410
9411
9412
9413
9414
9415
9416
9417
9418
9419
9420
9421
9422
9423
9424
9425
9426
9427
9428
9429
9430
9431
9432
9433
9434
9435
9436
9437
9438
9439
9440
9441
9442
9443
9444
9445
9446
9447
9448
9449
9450
9451
9452
9453
9454
9455
9456
9457
9458
9459
9460
9461
9462
9463
9464
9465
9466
9467
9468
9469
9470
9471
9472
9473
9474
9475
9476
9477
9478
9479
9480
9481
9482
9483
9484
9485
9486
9487
9488
9489
9490
9491
9492
9493
9494
9495
9496
9497
9498
9499
9500
9501
9502
9503
9504
9505
9506
9507
9508
9509
9510
9511
9512
9513
9514
9515
9516
9517
9518
9519
9520
9521
9522
9523
9524
9525
9526
9527
9528
9529
9530
9531
9532
9533
9534
9535
9536
9537
9538
9539
9540
9541
9542
9543
9544
9545
9546
9547
9548
9549
9550
9551
9552
9553
9554
9555
9556
9557
9558
9559
9560
9561
9562
9563
9564
9565
9566
9567
9568
9569
9570
9571
9572
9573
9574
9575
9576
9577
9578
9579
9580
9581
9582
9583
9584
9585
9586
9587
9588
9589
9590
9591
9592
9593
9594
9595
9596
9597
9598
9599
9600
9601
9602
9603
9604
9605
9606
9607
9608
9609
9610
9611
9612
9613
9614
9615
9616
9617
9618
9619
9620
9621
9622
9623
9624
9625
9626
9627
9628
9629
9630
9631
9632
9633
9634
9635
9636
9637
9638
9639
9640
9641
9642
9643
9644
9645
9646
9647
9648
9649
9650
9651
9652
9653
9654
9655
9656
9657
9658
9659
9660
9661
9662
9663
9664
9665
9666
9667
9668
9669
9670
9671
9672
9673
9674
9675
9676
9677
9678
9679
9680
9681
9682
9683
9684
9685
9686
9687
9688
9689
9690
9691
9692
9693
9694
9695
9696
9697
9698
9699
9700
9701
9702
9703
9704
9705
9706
9707
9708
9709
9710
9711
9712
9713
9714
9715
9716
9717
9718
9719
9720
9721
9722
9723
9724
9725
9726
9727
9728
9729
9730
9731
9732
9733
9734
9735
9736
9737
9738
9739
9740
9741
9742
9743
9744
9745
9746
9747
9748
9749
9750
9751
9752
9753
9754
9755
9756
9757
9758
9759
9760
9761
9762
9763
9764
9765
9766
9767
9768
9769
9770
9771
9772
9773
9774
9775
9776
9777
9778
9779
9780
9781
9782
9783
9784
9785
9786
9787
9788
9789
9790
9791
9792
9793
9794
9795
9796
9797
9798
9799
9800
9801
9802
9803
9804
9805
9806
9807
9808
9809
9810
9811
9812
9813
9814
9815
9816
9817
9818
9819
9820
9821
9822
9823
9824
9825
9826
9827
9828
9829
9830
9831
9832
9833
9834
9835
9836
9837
9838
9839
9840
9841
9842
9843
9844
9845
9846
9847
9848
9849
9850
9851
9852
9853
9854
9855
9856
9857
9858
9859
9860
9861
9862
9863
9864
9865
9866
9867
9868
9869
9870
9871
9872
9873
9874
9875
9876
9877
9878
9879
9880
9881
9882
9883
9884
9885
9886
9887
9888
9889
9890
9891
9892
9893
9894
9895
9896
9897
9898
9899
9900
9901
9902
9903
9904
9905
9906
9907
9908
9909
9910
9911
9912
9913
9914
9915
9916
9917
9918
9919
9920
9921
9922
9923
9924
9925
9926
9927
9928
9929
9930
9931
9932
9933
9934
9935
9936
9937
9938
9939
9940
9941
9942
9943
9944
9945
9946
9947
9948
9949
9950
9951
9952
9953
9954
9955
9956
9957
9958
9959
9960
9961
9962
9963
9964
9965
9966
9967
9968
9969
9970
9971
9972
9973
9974
9975
9976
9977
9978
9979
9980
9981
9982
9983
9984
9985
9986
9987
9988
9989
9990
9991
9992
9993
9994
9995
9996
9997
9998
9999
10000
10001
10002
10003
10004
10005
10006
10007
10008
10009
10010
10011
10012
10013
10014
10015
10016
10017
10018
10019
10020
10021
10022
10023
10024
10025
10026
10027
10028
10029
10030
10031
10032
10033
10034
10035
10036
10037
10038
10039
10040
10041
10042
10043
10044
10045
10046
10047
10048
10049
10050
10051
10052
10053
10054
10055
10056
10057
10058
10059
10060
10061
10062
10063
10064
10065
10066
10067
10068
10069
10070
10071
10072
10073
10074
10075
10076
10077
10078
10079
10080
10081
10082
10083
10084
10085
10086
10087
10088
10089
10090
10091
10092
10093
10094
10095
10096
10097
10098
10099
10100
10101
10102
10103
10104
10105
10106
10107
10108
10109
10110
10111
10112
10113
10114
10115
10116
10117
10118
10119
10120
10121
10122
10123
10124
10125
10126
10127
10128
10129
10130
10131
10132
10133
10134
10135
10136
10137
10138
10139
10140
10141
10142
10143
10144
10145
10146
10147
10148
10149
10150
10151
10152
10153
10154
10155
10156
10157
10158
10159
10160
10161
10162
10163
10164
10165
10166
10167
10168
10169
10170
10171
10172
10173
10174
10175
10176
10177
10178
10179
10180
10181
10182
10183
10184
10185
10186
10187
10188
10189
10190
10191
10192
10193
10194
10195
10196
10197
10198
10199
10200
10201
10202
10203
10204
10205
10206
10207
10208
10209
10210
10211
10212
10213
10214
10215
10216
10217
10218
10219
10220
10221
10222
10223
10224
10225
10226
10227
10228
10229
10230
10231
10232
10233
10234
10235
10236
10237
10238
10239
10240
10241
10242
10243
10244
10245
10246
10247
10248
10249
10250
10251
10252
10253
10254
10255
10256
10257
10258
10259
10260
10261
10262
10263
10264
10265
10266
10267
10268
10269
10270
10271
10272
10273
10274
10275
10276
10277
10278
10279
10280
10281
10282
10283
10284
10285
10286
10287
10288
10289
10290
10291
10292
10293
10294
10295
10296
10297
10298
10299
10300
10301
10302
10303
10304
10305
10306
10307
10308
10309
10310
10311
10312
10313
10314
10315
10316
10317
10318
10319
10320
10321
10322
10323
10324
10325
10326
10327
10328
10329
10330
10331
10332
10333
10334
10335
10336
10337
10338
10339
10340
10341
10342
10343
10344
10345
10346
10347
10348
10349
10350
10351
10352
10353
10354
10355
10356
10357
10358
10359
10360
10361
10362
10363
10364
10365
10366
10367
10368
10369
10370
10371
10372
10373
10374
10375
10376
10377
10378
10379
10380
10381
10382
10383
10384
10385
10386
10387
10388
10389
10390
10391
10392
10393
10394
10395
10396
10397
10398
10399
10400
10401
10402
10403
10404
10405
10406
10407
10408
10409
10410
10411
10412
10413
10414
10415
10416
10417
10418
10419
10420
10421
10422
10423
10424
10425
10426
10427
10428
10429
10430
10431
10432
10433
10434
10435
10436
10437
10438
10439
10440
10441
10442
10443
10444
10445
10446
10447
10448
10449
10450
10451
10452
10453
10454
10455
10456
10457
10458
10459
10460
10461
10462
10463
10464
10465
10466
10467
10468
10469
10470
10471
10472
10473
10474
10475
10476
10477
10478
10479
10480
10481
10482
10483
10484
10485
10486
10487
10488
10489
10490
10491
10492
10493
10494
10495
10496
10497
10498
10499
10500
10501
10502
10503
10504
10505
10506
10507
10508
10509
10510
10511
10512
10513
10514
10515
10516
10517
10518
10519
10520
10521
10522
10523
10524
10525
10526
10527
10528
10529
10530
10531
10532
10533
10534
10535
10536
10537
10538
10539
10540
10541
10542
10543
10544
10545
10546
10547
10548
10549
10550
10551
10552
10553
10554
10555
10556
10557
10558
10559
10560
10561
10562
10563
10564
10565
10566
10567
10568
10569
10570
10571
10572
10573
10574
10575
10576
10577
10578
10579
10580
10581
10582
10583
10584
10585
10586
10587
10588
10589
10590
10591
10592
10593
10594
10595
10596
10597
10598
10599
10600
10601
10602
10603
10604
10605
10606
10607
10608
10609
10610
10611
10612
10613
10614
10615
10616
10617
10618
10619
10620
10621
10622
10623
10624
10625
10626
10627
10628
10629
10630
10631
10632
10633
10634
10635
10636
10637
10638
10639
10640
10641
10642
10643
10644
10645
10646
10647
10648
10649
10650
10651
10652
10653
10654
10655
10656
10657
10658
10659
10660
10661
10662
10663
10664
10665
10666
10667
10668
10669
10670
10671
10672
10673
10674
10675
10676
10677
10678
10679
10680
10681
10682
10683
10684
10685
10686
10687
10688
10689
10690
10691
10692
10693
10694
10695
10696
10697
10698
10699
10700
10701
10702
10703
10704
10705
10706
10707
10708
10709
10710
10711
10712
10713
10714
10715
10716
10717
10718
10719
10720
10721
10722
10723
10724
10725
10726
10727
10728
10729
10730
10731
10732
10733
10734
10735
10736
10737
10738
10739
10740
10741
10742
10743
10744
10745
10746
10747
10748
10749
10750
10751
10752
10753
10754
10755
10756
10757
10758
10759
10760
10761
10762
10763
10764
10765
10766
10767
10768
10769
10770
10771
10772
10773
10774
10775
10776
10777
10778
10779
10780
10781
10782
10783
10784
10785
10786
10787
10788
10789
10790
10791
10792
10793
10794
10795
10796
10797
10798
10799
10800
10801
10802
10803
10804
10805
10806
10807
10808
10809
10810
10811
10812
10813
10814
10815
10816
10817
10818
10819
10820
10821
10822
10823
10824
10825
10826
10827
10828
10829
10830
10831
10832
10833
10834
10835
10836
10837
10838
10839
10840
10841
10842
10843
10844
10845
10846
10847
10848
10849
10850
10851
10852
10853
10854
10855
10856
10857
10858
10859
10860
10861
10862
10863
10864
10865
10866
10867
10868
10869
10870
10871
10872
10873
10874
10875
10876
10877
10878
10879
10880
10881
10882
10883
10884
10885
10886
10887
10888
10889
10890
10891
10892
10893
10894
10895
10896
10897
10898
10899
10900
10901
10902
10903
10904
10905
10906
10907
10908
10909
10910
10911
10912
10913
10914
10915
10916
10917
10918
10919
10920
10921
10922
10923
10924
10925
10926
10927
10928
10929
10930
10931
10932
10933
10934
10935
10936
10937
10938
10939
10940
10941
10942
10943
10944
10945
10946
10947
10948
10949
10950
10951
10952
10953
10954
10955
10956
10957
10958
10959
10960
10961
10962
10963
10964
10965
10966
10967
10968
10969
10970
10971
10972
10973
10974
10975
10976
10977
10978
10979
10980
10981
10982
10983
10984
10985
10986
10987
10988
10989
10990
10991
10992
10993
10994
10995
10996
10997
10998
10999
11000
11001
11002
11003
11004
11005
11006
11007
11008
11009
11010
11011
11012
11013
11014
11015
11016
11017
11018
11019
11020
11021
11022
11023
11024
11025
11026
11027
11028
11029
11030
11031
11032
11033
11034
11035
11036
11037
11038
11039
11040
11041
11042
11043
11044
11045
11046
11047
11048
11049
11050
11051
11052
11053
11054
11055
11056
11057
11058
11059
11060
11061
11062
11063
11064
11065
11066
11067
11068
11069
11070
11071
11072
11073
11074
11075
11076
11077
11078
11079
11080
11081
11082
11083
11084
11085
11086
11087
11088
11089
11090
11091
11092
11093
11094
11095
11096
11097
11098
11099
11100
11101
11102
11103
11104
11105
11106
11107
11108
11109
11110
11111
11112
11113
11114
11115
11116
11117
11118
11119
11120
11121
11122
11123
11124
11125
11126
11127
11128
11129
11130
11131
11132
11133
11134
11135
11136
11137
11138
11139
11140
11141
11142
11143
11144
11145
11146
11147
11148
11149
11150
11151
11152
11153
11154
11155
11156
11157
11158
11159
11160
11161
11162
11163
11164
11165
11166
11167
11168
11169
11170
11171
11172
11173
11174
11175
11176
11177
11178
11179
11180
11181
11182
11183
11184
11185
11186
11187
11188
11189
11190
11191
11192
11193
11194
11195
11196
11197
11198
11199
11200
11201
11202
11203
11204
11205
11206
11207
11208
11209
11210
11211
11212
11213
11214
11215
11216
11217
11218
11219
11220
11221
11222
11223
11224
11225
11226
11227
11228
11229
11230
11231
11232
11233
11234
11235
11236
11237
11238
11239
11240
11241
11242
11243
11244
11245
11246
11247
11248
11249
11250
11251
11252
11253
11254
11255
11256
11257
11258
11259
11260
11261
11262
11263
11264
11265
11266
11267
11268
11269
11270
11271
11272
11273
11274
11275
11276
11277
11278
11279
11280
11281
11282
11283
11284
11285
11286
11287
11288
11289
11290
11291
11292
11293
11294
11295
11296
11297
11298
11299
11300
11301
11302
11303
11304
11305
11306
11307
11308
11309
11310
11311
11312
11313
11314
11315
11316
11317
11318
11319
11320
11321
11322
11323
11324
11325
11326
11327
11328
11329
11330
11331
11332
11333
11334
11335
11336
11337
11338
11339
11340
11341
11342
11343
11344
11345
11346
11347
11348
11349
11350
11351
11352
11353
11354
11355
11356
11357
11358
11359
11360
11361
11362
11363
11364
11365
11366
11367
11368
11369
11370
11371
11372
11373
11374
11375
11376
11377
11378
11379
11380
11381
11382
11383
11384
11385
11386
11387
11388
11389
11390
11391
11392
11393
11394
11395
11396
11397
11398
11399
11400
11401
11402
11403
11404
11405
11406
11407
11408
11409
11410
11411
11412
11413
11414
11415
11416
11417
11418
11419
11420
11421
11422
11423
11424
11425
11426
11427
11428
11429
11430
11431
11432
11433
11434
11435
11436
11437
11438
11439
11440
11441
11442
11443
11444
11445
11446
11447
11448
11449
11450
11451
11452
11453
11454
11455
11456
11457
11458
11459
11460
11461
11462
11463
11464
11465
11466
11467
11468
11469
11470
11471
11472
11473
11474
11475
11476
11477
11478
11479
11480
11481
11482
11483
11484
11485
11486
11487
11488
11489
11490
11491
11492
11493
11494
11495
11496
11497
11498
11499
11500
11501
11502
11503
11504
11505
11506
11507
11508
11509
11510
11511
11512
11513
11514
11515
11516
11517
11518
11519
11520
11521
11522
11523
11524
11525
11526
11527
11528
11529
11530
11531
11532
11533
11534
11535
11536
11537
11538
11539
11540
11541
11542
11543
11544
11545
11546
11547
11548
11549
11550
11551
11552
11553
11554
11555
11556
11557
11558
11559
11560
11561
11562
11563
11564
11565
11566
11567
11568
11569
11570
11571
11572
11573
11574
11575
11576
11577
11578
11579
11580
11581
11582
11583
11584
11585
11586
11587
11588
11589
11590
11591
11592
11593
11594
11595
11596
11597
11598
11599
11600
11601
11602
11603
11604
11605
11606
11607
11608
11609
11610
11611
11612
11613
11614
11615
11616
11617
11618
11619
11620
11621
11622
11623
11624
11625
11626
11627
11628
11629
11630
11631
11632
11633
11634
11635
11636
11637
11638
11639
11640
11641
11642
11643
11644
11645
11646
11647
11648
11649
11650
11651
11652
11653
11654
11655
11656
11657
11658
11659
11660
11661
11662
11663
11664
11665
11666
11667
11668
11669
11670
11671
11672
11673
11674
11675
11676
11677
11678
11679
11680
11681
11682
11683
11684
11685
11686
11687
11688
11689
11690
11691
11692
11693
11694
11695
11696
11697
11698
11699
11700
11701
11702
11703
11704
11705
11706
11707
11708
11709
11710
11711
11712
11713
11714
11715
11716
11717
11718
11719
11720
11721
11722
11723
11724
11725
11726
11727
11728
11729
11730
11731
11732
11733
11734
11735
11736
11737
11738
11739
11740
11741
11742
11743
11744
11745
11746
11747
11748
11749
11750
11751
11752
11753
11754
11755
11756
11757
11758
11759
11760
11761
11762
11763
11764
11765
11766
11767
11768
11769
11770
11771
11772
11773
11774
11775
11776
11777
11778
11779
11780
11781
11782
11783
11784
11785
11786
11787
11788
11789
11790
11791
11792
11793
11794
11795
11796
11797
11798
11799
11800
11801
11802
11803
11804
11805
11806
11807
11808
11809
11810
11811
11812
11813
11814
11815
11816
11817
11818
11819
11820
11821
11822
11823
11824
11825
11826
11827
11828
11829
11830
11831
11832
11833
11834
11835
11836
11837
11838
11839
11840
11841
11842
11843
11844
11845
11846
11847
11848
11849
11850
11851
11852
11853
11854
11855
11856
11857
11858
11859
11860
11861
11862
11863
11864
11865
11866
11867
11868
11869
11870
11871
11872
11873
11874
11875
11876
11877
11878
11879
11880
11881
11882
11883
11884
11885
11886
11887
11888
11889
11890
11891
11892
11893
11894
11895
11896
11897
11898
11899
11900
11901
11902
11903
11904
11905
11906
11907
11908
11909
11910
11911
11912
11913
11914
11915
11916
11917
11918
11919
11920
11921
11922
11923
11924
11925
11926
11927
11928
11929
11930
11931
11932
11933
11934
11935
11936
11937
11938
11939
11940
11941
11942
11943
11944
11945
11946
11947
11948
11949
11950
11951
11952
11953
11954
11955
11956
11957
11958
11959
11960
11961
11962
11963
11964
11965
11966
11967
11968
11969
11970
11971
11972
11973
11974
11975
11976
11977
11978
11979
11980
11981
11982
11983
11984
11985
11986
11987
11988
11989
11990
11991
11992
11993
11994
11995
11996
11997
11998
11999
12000
12001
12002
12003
12004
12005
12006
12007
12008
12009
12010
12011
12012
12013
12014
12015
12016
12017
12018
12019
12020
12021
12022
12023
12024
12025
12026
12027
12028
12029
12030
12031
12032
12033
12034
12035
12036
12037
12038
12039
12040
12041
12042
12043
12044
12045
12046
12047
12048
12049
12050
12051
12052
12053
12054
12055
12056
12057
12058
12059
12060
12061
12062
12063
12064
12065
12066
12067
12068
12069
12070
12071
12072
12073
12074
12075
12076
12077
12078
12079
12080
12081
12082
12083
12084
12085
12086
12087
12088
12089
12090
12091
12092
12093
12094
12095
12096
12097
12098
12099
12100
12101
12102
12103
12104
12105
12106
12107
12108
12109
12110
12111
12112
12113
12114
12115
12116
12117
12118
12119
12120
12121
12122
12123
12124
12125
12126
12127
12128
12129
12130
12131
12132
12133
12134
12135
12136
12137
12138
12139
12140
12141
12142
12143
12144
12145
12146
12147
12148
12149
12150
12151
12152
12153
12154
12155
12156
12157
12158
12159
12160
12161
12162
12163
12164
12165
12166
12167
12168
12169
12170
12171
12172
12173
12174
12175
12176
12177
12178
12179
12180
12181
12182
12183
12184
12185
12186
12187
12188
12189
12190
12191
12192
12193
12194
12195
12196
12197
12198
12199
12200
12201
12202
12203
12204
12205
12206
12207
12208
12209
12210
12211
12212
12213
12214
12215
12216
12217
12218
12219
12220
12221
12222
12223
12224
12225
12226
12227
12228
12229
12230
12231
12232
12233
12234
12235
12236
12237
12238
12239
12240
12241
12242
12243
12244
12245
12246
12247
12248
12249
12250
12251
12252
12253
12254
12255
12256
12257
12258
12259
12260
12261
12262
12263
12264
12265
12266
12267
12268
12269
12270
12271
12272
12273
12274
12275
12276
12277
12278
12279
12280
12281
12282
12283
12284
12285
12286
12287
12288
12289
12290
12291
12292
12293
12294
12295
12296
12297
12298
12299
12300
12301
12302
12303
12304
12305
12306
12307
12308
12309
12310
12311
12312
12313
12314
12315
12316
12317
12318
12319
12320
12321
12322
12323
12324
12325
12326
12327
12328
12329
12330
12331
12332
12333
12334
12335
12336
12337
12338
12339
12340
12341
12342
12343
12344
12345
12346
12347
12348
12349
12350
12351
12352
12353
12354
12355
12356
12357
12358
12359
12360
12361
12362
12363
12364
12365
12366
12367
12368
12369
12370
12371
12372
12373
12374
12375
12376
12377
12378
12379
12380
12381
12382
12383
12384
12385
12386
12387
12388
12389
12390
12391
12392
12393
12394
12395
12396
12397
12398
12399
12400
12401
12402
12403
12404
12405
12406
12407
12408
12409
12410
12411
12412
12413
12414
12415
12416
12417
12418
12419
12420
12421
12422
12423
12424
12425
12426
12427
12428
12429
12430
12431
12432
12433
12434
12435
12436
12437
12438
12439
12440
12441
12442
12443
12444
12445
12446
12447
12448
12449
12450
12451
12452
12453
12454
12455
12456
12457
12458
12459
12460
12461
12462
12463
12464
12465
12466
12467
12468
12469
12470
12471
12472
12473
12474
12475
12476
12477
12478
12479
12480
12481
12482
12483
12484
12485
12486
12487
12488
12489
12490
12491
12492
12493
12494
12495
12496
12497
12498
12499
12500
12501
12502
12503
12504
12505
12506
12507
12508
12509
12510
12511
12512
12513
12514
12515
12516
12517
12518
12519
12520
12521
12522
12523
12524
12525
12526
12527
12528
12529
12530
12531
12532
12533
12534
12535
12536
12537
12538
12539
12540
12541
12542
12543
12544
12545
12546
12547
12548
12549
12550
12551
12552
12553
12554
12555
12556
12557
12558
12559
12560
12561
12562
12563
12564
12565
12566
12567
12568
12569
12570
12571
12572
12573
12574
12575
12576
12577
12578
12579
12580
12581
12582
12583
12584
12585
12586
12587
12588
12589
12590
12591
12592
12593
12594
12595
12596
12597
12598
12599
12600
12601
12602
12603
12604
12605
12606
12607
12608
12609
12610
12611
12612
12613
12614
12615
12616
12617
12618
12619
12620
12621
12622
12623
12624
12625
12626
12627
12628
12629
12630
12631
12632
12633
12634
12635
12636
12637
12638
12639
12640
12641
12642
12643
12644
12645
12646
12647
12648
12649
12650
12651
12652
12653
12654
12655
12656
12657
12658
12659
12660
12661
12662
12663
12664
12665
12666
12667
12668
12669
12670
12671
12672
12673
12674
12675
12676
12677
12678
12679
12680
12681
12682
12683
12684
12685
12686
12687
12688
12689
12690
12691
12692
12693
12694
12695
12696
12697
12698
12699
12700
12701
12702
12703
12704
12705
12706
12707
12708
12709
12710
12711
12712
12713
12714
12715
12716
12717
12718
12719
12720
12721
12722
12723
12724
12725
12726
12727
12728
12729
12730
12731
12732
12733
12734
12735
12736
12737
12738
12739
12740
12741
12742
12743
12744
12745
12746
12747
12748
12749
12750
12751
12752
12753
12754
12755
12756
12757
12758
12759
12760
12761
12762
12763
12764
12765
12766
12767
12768
12769
12770
12771
12772
12773
12774
12775
12776
12777
12778
12779
12780
12781
12782
12783
12784
12785
12786
12787
12788
12789
12790
12791
12792
12793
12794
12795
12796
12797
12798
12799
12800
12801
12802
12803
12804
12805
12806
12807
12808
12809
12810
12811
12812
12813
12814
12815
12816
12817
12818
12819
12820
12821
12822
12823
12824
12825
12826
12827
12828
12829
12830
12831
12832
12833
12834
12835
12836
12837
12838
12839
12840
12841
12842
12843
12844
12845
12846
12847
12848
12849
12850
12851
12852
12853
12854
12855
12856
12857
12858
12859
12860
12861
12862
12863
12864
12865
12866
12867
12868
12869
12870
12871
12872
12873
12874
12875
12876
12877
12878
12879
12880
12881
12882
12883
12884
12885
12886
12887
12888
12889
12890
12891
12892
12893
12894
12895
12896
12897
12898
12899
12900
12901
12902
12903
12904
12905
12906
12907
12908
12909
12910
12911
12912
12913
12914
12915
12916
12917
12918
12919
12920
12921
12922
12923
12924
12925
12926
12927
12928
12929
12930
12931
12932
12933
12934
12935
12936
12937
12938
12939
12940
12941
12942
12943
12944
12945
12946
12947
12948
12949
12950
12951
12952
12953
12954
12955
12956
12957
12958
12959
12960
12961
12962
12963
12964
12965
12966
12967
12968
12969
12970
12971
12972
12973
12974
12975
12976
12977
12978
12979
12980
12981
12982
12983
12984
12985
12986
12987
12988
12989
12990
12991
12992
12993
12994
12995
12996
12997
12998
12999
13000
13001
13002
13003
13004
13005
13006
13007
13008
13009
13010
13011
13012
13013
13014
13015
13016
13017
13018
13019
13020
13021
13022
13023
13024
13025
13026
13027
13028
13029
13030
13031
13032
13033
13034
13035
13036
13037
13038
13039
13040
13041
13042
13043
13044
13045
13046
13047
13048
13049
13050
13051
13052
13053
13054
13055
13056
13057
13058
13059
13060
13061
13062
13063
13064
13065
13066
13067
13068
13069
13070
13071
13072
13073
13074
13075
13076
13077
13078
13079
13080
13081
13082
13083
13084
13085
13086
13087
13088
13089
13090
13091
13092
13093
13094
13095
13096
13097
13098
13099
13100
13101
13102
13103
13104
13105
13106
13107
13108
13109
13110
13111
13112
13113
13114
13115
13116
13117
13118
13119
13120
13121
13122
13123
13124
13125
13126
13127
13128
13129
13130
13131
13132
13133
13134
13135
13136
13137
13138
13139
13140
13141
13142
13143
13144
13145
13146
13147
13148
13149
13150
13151
13152
13153
13154
13155
13156
13157
13158
13159
13160
13161
13162
13163
13164
13165
13166
13167
13168
13169
13170
13171
13172
13173
13174
13175
13176
13177
13178
13179
13180
13181
13182
13183
13184
13185
13186
13187
13188
13189
13190
13191
13192
13193
13194
13195
13196
13197
13198
13199
13200
13201
13202
13203
13204
13205
13206
13207
13208
13209
13210
13211
13212
13213
13214
13215
13216
13217
13218
13219
13220
13221
13222
13223
13224
13225
13226
13227
13228
13229
13230
13231
13232
13233
13234
13235
13236
13237
13238
13239
13240
13241
13242
13243
13244
13245
13246
13247
13248
13249
13250
13251
13252
13253
13254
13255
13256
13257
13258
13259
13260
13261
13262
13263
13264
13265
13266
13267
13268
13269
13270
13271
13272
13273
13274
13275
13276
13277
13278
13279
13280
13281
13282
13283
13284
13285
13286
13287
13288
13289
13290
13291
13292
13293
13294
13295
13296
13297
13298
13299
13300
13301
13302
13303
13304
13305
13306
13307
13308
13309
13310
13311
13312
13313
13314
13315
13316
13317
13318
13319
13320
13321
13322
13323
13324
13325
13326
13327
13328
13329
13330
13331
13332
13333
13334
13335
13336
13337
13338
13339
13340
13341
13342
13343
13344
13345
13346
13347
13348
13349
13350
13351
13352
13353
13354
13355
13356
13357
13358
13359
13360
13361
13362
13363
13364
13365
13366
13367
13368
13369
13370
13371
13372
13373
13374
13375
13376
13377
13378
13379
13380
13381
13382
13383
13384
13385
13386
13387
13388
13389
13390
13391
13392
13393
13394
13395
13396
13397
13398
13399
13400
13401
13402
13403
13404
13405
13406
13407
13408
13409
13410
13411
13412
13413
13414
13415
13416
13417
13418
13419
13420
13421
13422
13423
13424
13425
13426
13427
13428
13429
13430
13431
13432
13433
13434
13435
13436
13437
13438
13439
13440
13441
13442
13443
13444
13445
13446
13447
13448
13449
13450
13451
13452
13453
13454
13455
13456
13457
13458
13459
13460
13461
13462
13463
13464
13465
13466
13467
13468
13469
13470
13471
13472
13473
13474
13475
13476
13477
13478
13479
13480
13481
13482
13483
13484
13485
13486
13487
13488
13489
13490
13491
13492
13493
13494
13495
13496
13497
13498
13499
13500
13501
13502
13503
13504
13505
13506
13507
13508
13509
13510
13511
13512
13513
13514
13515
13516
13517
13518
13519
13520
13521
13522
13523
13524
13525
13526
13527
13528
13529
13530
13531
13532
13533
13534
13535
13536
13537
13538
13539
13540
13541
13542
13543
13544
13545
13546
13547
13548
13549
13550
13551
13552
13553
13554
13555
13556
13557
13558
13559
13560
13561
13562
13563
13564
13565
13566
13567
13568
13569
13570
13571
13572
13573
13574
13575
13576
13577
13578
13579
13580
13581
13582
13583
13584
13585
13586
13587
13588
13589
13590
13591
13592
13593
13594
13595
13596
13597
13598
13599
13600
13601
13602
13603
13604
13605
13606
13607
13608
13609
13610
13611
13612
13613
13614
13615
13616
13617
13618
13619
13620
13621
13622
13623
13624
13625
13626
13627
13628
13629
13630
13631
13632
13633
13634
13635
13636
13637
13638
13639
13640
13641
13642
13643
13644
13645
13646
13647
13648
13649
13650
13651
13652
13653
13654
13655
13656
13657
13658
13659
13660
13661
13662
13663
13664
13665
13666
13667
13668
13669
13670
13671
13672
13673
13674
13675
13676
13677
13678
13679
13680
13681
13682
13683
13684
13685
13686
13687
13688
13689
13690
13691
13692
13693
13694
13695
13696
13697
13698
13699
13700
13701
13702
13703
13704
13705
13706
13707
13708
13709
13710
13711
13712
13713
13714
13715
13716
13717
13718
13719
13720
13721
13722
13723
13724
13725
13726
13727
13728
13729
13730
13731
13732
13733
13734
13735
13736
13737
13738
13739
13740
13741
13742
13743
13744
13745
13746
13747
13748
13749
13750
13751
13752
13753
13754
13755
13756
13757
13758
13759
13760
13761
13762
13763
13764
13765
13766
13767
13768
13769
13770
13771
13772
13773
13774
13775
13776
13777
13778
13779
13780
13781
13782
13783
13784
13785
13786
13787
13788
13789
13790
13791
13792
13793
13794
13795
13796
13797
13798
13799
13800
13801
13802
13803
13804
13805
13806
13807
13808
13809
13810
13811
13812
13813
13814
13815
13816
13817
13818
13819
13820
13821
13822
13823
13824
13825
13826
13827
13828
13829
13830
13831
13832
13833
13834
13835
13836
13837
13838
13839
13840
13841
13842
13843
13844
13845
13846
13847
13848
13849
13850
13851
13852
13853
13854
13855
13856
13857
13858
13859
13860
13861
13862
13863
13864
13865
13866
13867
13868
13869
13870
13871
13872
13873
13874
13875
13876
13877
13878
13879
13880
13881
13882
13883
13884
13885
13886
13887
13888
13889
13890
13891
13892
13893
13894
13895
13896
13897
13898
13899
13900
13901
13902
13903
13904
13905
13906
13907
13908
13909
13910
13911
13912
13913
13914
13915
13916
13917
13918
13919
13920
13921
13922
13923
13924
13925
13926
13927
13928
13929
13930
13931
13932
13933
13934
13935
13936
13937
13938
13939
13940
13941
13942
13943
13944
13945
13946
13947
13948
13949
13950
13951
13952
13953
13954
13955
13956
13957
13958
13959
13960
13961
13962
13963
13964
13965
13966
13967
13968
13969
13970
13971
13972
13973
13974
13975
13976
13977
13978
13979
13980
13981
13982
13983
13984
13985
13986
13987
13988
13989
13990
13991
13992
13993
13994
13995
13996
13997
13998
13999
14000
14001
14002
14003
14004
14005
14006
14007
14008
14009
14010
14011
14012
14013
14014
14015
14016
14017
14018
14019
14020
14021
14022
14023
14024
14025
14026
14027
14028
14029
14030
14031
14032
14033
14034
14035
14036
14037
14038
14039
14040
14041
14042
14043
14044
14045
14046
14047
14048
14049
14050
14051
14052
14053
14054
14055
14056
14057
14058
14059
14060
14061
14062
14063
14064
14065
14066
14067
14068
14069
14070
14071
14072
14073
14074
14075
14076
14077
14078
14079
14080
14081
14082
14083
14084
14085
14086
14087
14088
14089
14090
14091
14092
14093
14094
14095
14096
14097
14098
14099
14100
14101
14102
14103
14104
14105
14106
14107
14108
14109
14110
14111
14112
14113
14114
14115
14116
14117
14118
14119
14120
14121
14122
14123
14124
14125
14126
14127
14128
14129
14130
14131
14132
14133
14134
14135
14136
14137
14138
14139
14140
14141
14142
14143
14144
14145
14146
14147
14148
14149
14150
14151
14152
14153
14154
14155
14156
14157
14158
14159
14160
14161
14162
14163
14164
14165
14166
14167
14168
14169
14170
14171
14172
14173
14174
14175
14176
14177
14178
14179
14180
14181
14182
14183
14184
14185
14186
14187
14188
14189
14190
14191
14192
14193
14194
14195
14196
14197
14198
14199
14200
14201
14202
14203
14204
14205
14206
14207
14208
14209
14210
14211
14212
14213
14214
14215
14216
14217
14218
14219
14220
14221
14222
14223
14224
14225
14226
14227
14228
14229
14230
14231
14232
14233
14234
14235
14236
14237
14238
14239
14240
14241
14242
14243
14244
14245
14246
14247
14248
14249
14250
14251
14252
14253
14254
14255
14256
14257
14258
14259
14260
14261
14262
14263
14264
14265
14266
14267
14268
14269
14270
14271
14272
14273
14274
14275
14276
14277
14278
14279
14280
14281
14282
14283
14284
14285
14286
14287
14288
14289
14290
14291
14292
14293
14294
14295
14296
14297
14298
14299
14300
14301
14302
14303
14304
14305
14306
14307
14308
14309
14310
14311
14312
14313
14314
14315
14316
14317
14318
14319
14320
14321
14322
14323
14324
14325
14326
14327
14328
14329
14330
14331
14332
14333
14334
14335
14336
14337
14338
14339
14340
14341
14342
14343
14344
14345
14346
14347
14348
14349
14350
14351
14352
14353
14354
14355
14356
14357
14358
14359
14360
14361
14362
14363
14364
14365
14366
14367
14368
14369
14370
14371
14372
14373
14374
14375
14376
14377
14378
14379
14380
14381
14382
14383
14384
14385
14386
14387
14388
14389
14390
14391
14392
14393
14394
14395
14396
14397
14398
14399
14400
14401
14402
14403
14404
14405
14406
14407
14408
14409
14410
14411
14412
14413
14414
14415
14416
14417
14418
14419
14420
14421
14422
14423
14424
14425
14426
14427
14428
14429
14430
14431
14432
14433
14434
14435
14436
14437
14438
14439
14440
14441
14442
14443
14444
14445
14446
14447
14448
14449
14450
14451
14452
14453
14454
14455
14456
14457
14458
14459
14460
14461
14462
14463
14464
14465
14466
14467
14468
14469
14470
14471
14472
14473
14474
14475
14476
14477
14478
14479
14480
14481
14482
14483
14484
14485
14486
14487
14488
14489
14490
14491
14492
14493
14494
14495
14496
14497
14498
14499
14500
14501
14502
14503
14504
14505
14506
14507
14508
14509
14510
14511
14512
14513
14514
14515
14516
14517
14518
14519
14520
14521
14522
14523
14524
14525
14526
14527
14528
14529
14530
14531
14532
14533
14534
14535
14536
14537
14538
14539
14540
14541
14542
14543
14544
14545
14546
14547
14548
14549
14550
14551
14552
14553
14554
14555
14556
14557
14558
14559
14560
14561
14562
14563
14564
14565
14566
14567
14568
14569
14570
14571
14572
14573
14574
14575
14576
14577
14578
14579
14580
14581
14582
14583
14584
14585
14586
14587
14588
14589
14590
14591
14592
14593
14594
14595
14596
14597
14598
14599
14600
14601
14602
14603
14604
14605
14606
14607
14608
14609
14610
14611
14612
14613
14614
14615
14616
14617
14618
14619
14620
14621
14622
14623
14624
14625
14626
14627
14628
14629
14630
14631
14632
14633
14634
14635
14636
14637
14638
14639
14640
14641
14642
14643
14644
14645
14646
14647
14648
14649
14650
14651
14652
14653
14654
14655
14656
14657
14658
14659
14660
14661
14662
14663
14664
14665
14666
14667
14668
14669
14670
14671
14672
14673
14674
14675
14676
14677
14678
14679
14680
14681
14682
14683
14684
14685
14686
14687
14688
14689
14690
14691
14692
14693
14694
14695
14696
14697
14698
14699
14700
14701
14702
14703
14704
14705
14706
14707
14708
14709
14710
14711
14712
14713
14714
14715
14716
14717
14718
14719
14720
14721
14722
14723
14724
14725
14726
14727
14728
14729
14730
14731
14732
14733
14734
14735
14736
14737
14738
14739
14740
14741
14742
14743
14744
14745
14746
14747
14748
14749
14750
14751
14752
14753
14754
14755
14756
14757
14758
14759
14760
14761
14762
14763
14764
14765
14766
14767
14768
14769
14770
14771
14772
14773
14774
14775
14776
14777
14778
14779
14780
14781
14782
14783
14784
14785
14786
14787
14788
14789
14790
14791
14792
14793
14794
14795
14796
14797
14798
14799
14800
14801
14802
14803
14804
14805
14806
14807
14808
14809
14810
14811
14812
14813
14814
14815
14816
14817
14818
14819
14820
14821
14822
14823
14824
14825
14826
14827
14828
14829
14830
14831
14832
14833
14834
14835
14836
14837
14838
14839
14840
14841
14842
14843
14844
14845
14846
14847
14848
14849
14850
14851
14852
14853
14854
14855
14856
14857
14858
14859
14860
14861
14862
14863
14864
14865
14866
14867
14868
14869
14870
14871
14872
14873
14874
14875
14876
14877
14878
14879
14880
14881
14882
14883
14884
14885
14886
14887
14888
14889
14890
14891
14892
14893
14894
14895
14896
14897
14898
14899
14900
14901
14902
14903
14904
14905
14906
14907
14908
14909
14910
14911
14912
14913
14914
14915
14916
14917
14918
14919
14920
14921
14922
14923
14924
14925
14926
14927
14928
14929
14930
14931
14932
14933
14934
14935
14936
14937
14938
14939
14940
14941
14942
14943
14944
14945
14946
14947
14948
14949
14950
14951
14952
14953
14954
14955
14956
14957
14958
14959
14960
14961
14962
14963
14964
14965
14966
14967
14968
14969
14970
14971
14972
14973
14974
14975
14976
14977
14978
14979
14980
14981
14982
14983
14984
14985
14986
14987
14988
14989
14990
14991
14992
14993
14994
14995
14996
14997
14998
14999
15000
15001
15002
15003
15004
15005
15006
15007
15008
15009
15010
15011
15012
15013
15014
15015
15016
15017
15018
15019
15020
15021
15022
15023
15024
15025
15026
15027
15028
15029
15030
15031
15032
15033
15034
15035
15036
15037
15038
15039
15040
15041
15042
15043
15044
15045
15046
15047
15048
15049
15050
15051
15052
15053
15054
15055
15056
15057
15058
15059
15060
15061
15062
15063
15064
15065
15066
15067
15068
15069
15070
15071
15072
15073
15074
15075
15076
15077
15078
15079
15080
15081
15082
15083
15084
15085
15086
15087
15088
15089
15090
15091
15092
15093
15094
15095
15096
15097
15098
15099
15100
15101
15102
15103
15104
15105
15106
15107
15108
15109
15110
15111
15112
15113
15114
15115
15116
15117
15118
15119
15120
15121
15122
15123
15124
15125
15126
15127
15128
15129
15130
15131
15132
15133
15134
15135
15136
15137
15138
15139
15140
15141
15142
15143
15144
15145
15146
15147
15148
15149
15150
15151
15152
15153
15154
15155
15156
15157
15158
15159
15160
15161
15162
15163
15164
15165
15166
15167
15168
15169
15170
15171
15172
15173
15174
15175
15176
15177
15178
15179
15180
15181
15182
15183
15184
15185
15186
15187
15188
15189
15190
15191
15192
15193
15194
15195
15196
15197
15198
15199
15200
15201
15202
15203
15204
15205
15206
15207
15208
15209
15210
15211
15212
15213
15214
15215
15216
15217
15218
15219
15220
15221
15222
15223
15224
15225
15226
15227
15228
15229
15230
15231
15232
15233
15234
15235
15236
15237
15238
15239
15240
15241
15242
15243
15244
15245
15246
15247
15248
15249
15250
15251
15252
15253
15254
15255
15256
15257
15258
15259
15260
15261
15262
15263
15264
15265
15266
15267
15268
15269
15270
15271
15272
15273
15274
15275
15276
15277
15278
15279
15280
15281
15282
15283
15284
15285
15286
15287
15288
15289
15290
15291
15292
15293
15294
15295
15296
15297
15298
15299
15300
15301
15302
15303
15304
15305
15306
15307
15308
15309
15310
15311
15312
15313
15314
15315
15316
15317
15318
15319
15320
15321
15322
15323
15324
15325
15326
15327
15328
15329
15330
15331
15332
15333
15334
15335
15336
15337
15338
15339
15340
15341
15342
15343
15344
15345
15346
15347
15348
15349
15350
15351
15352
15353
15354
15355
15356
15357
15358
15359
15360
15361
15362
15363
15364
15365
15366
15367
15368
15369
15370
15371
15372
15373
15374
15375
15376
15377
15378
15379
15380
15381
15382
15383
15384
15385
15386
15387
15388
15389
15390
15391
15392
15393
15394
15395
15396
15397
15398
15399
15400
15401
15402
15403
15404
15405
15406
15407
15408
15409
15410
15411
15412
15413
15414
15415
15416
15417
15418
15419
15420
15421
15422
15423
15424
15425
15426
15427
15428
15429
15430
15431
15432
15433
15434
15435
15436
15437
15438
15439
15440
15441
15442
15443
15444
15445
15446
15447
15448
15449
15450
15451
15452
15453
15454
15455
15456
15457
15458
15459
15460
15461
15462
15463
15464
15465
15466
15467
15468
15469
15470
15471
15472
15473
15474
15475
15476
15477
15478
15479
15480
15481
15482
15483
15484
15485
15486
15487
15488
15489
15490
15491
15492
15493
15494
15495
15496
15497
15498
15499
15500
15501
15502
15503
15504
15505
15506
15507
15508
15509
15510
15511
15512
15513
15514
15515
15516
15517
15518
15519
15520
15521
15522
15523
15524
15525
15526
15527
15528
15529
15530
15531
15532
15533
15534
15535
15536
15537
15538
15539
15540
15541
15542
15543
15544
15545
15546
15547
15548
15549
15550
15551
15552
15553
15554
15555
15556
15557
15558
15559
15560
15561
15562
15563
15564
15565
15566
15567
15568
15569
15570
15571
15572
15573
15574
15575
15576
15577
15578
15579
15580
15581
15582
15583
15584
15585
15586
15587
15588
15589
15590
15591
15592
15593
15594
15595
15596
15597
15598
15599
15600
15601
15602
15603
15604
15605
15606
15607
15608
15609
15610
15611
15612
15613
15614
15615
15616
15617
15618
15619
15620
15621
15622
15623
15624
15625
15626
15627
15628
15629
15630
15631
15632
15633
15634
15635
15636
15637
15638
15639
15640
15641
15642
15643
15644
15645
15646
15647
15648
15649
15650
15651
15652
15653
15654
15655
15656
15657
15658
15659
15660
15661
15662
15663
15664
15665
15666
15667
15668
15669
15670
15671
15672
15673
15674
15675
15676
15677
15678
15679
15680
15681
15682
15683
15684
15685
15686
15687
15688
15689
15690
15691
15692
15693
15694
15695
15696
15697
15698
15699
15700
15701
15702
15703
15704
15705
15706
15707
15708
15709
15710
15711
15712
15713
15714
15715
15716
15717
15718
15719
15720
15721
15722
15723
15724
15725
15726
15727
15728
15729
15730
15731
15732
15733
15734
15735
15736
15737
15738
15739
15740
15741
15742
15743
15744
15745
15746
15747
15748
15749
15750
15751
15752
15753
15754
15755
15756
15757
15758
15759
15760
15761
15762
15763
15764
15765
15766
15767
15768
15769
15770
15771
15772
15773
15774
15775
15776
15777
15778
15779
15780
15781
15782
15783
15784
15785
15786
15787
15788
15789
15790
15791
15792
15793
15794
15795
15796
15797
15798
15799
15800
15801
15802
15803
15804
15805
15806
15807
15808
15809
15810
15811
15812
15813
15814
15815
15816
15817
15818
15819
15820
15821
15822
15823
15824
15825
15826
15827
15828
15829
15830
15831
15832
15833
15834
15835
15836
15837
15838
15839
15840
15841
15842
15843
15844
15845
15846
15847
15848
15849
15850
15851
15852
15853
15854
15855
15856
15857
15858
15859
15860
15861
15862
15863
15864
15865
15866
15867
15868
15869
15870
15871
15872
15873
15874
15875
15876
15877
15878
15879
15880
15881
15882
15883
15884
15885
15886
15887
15888
15889
15890
15891
15892
15893
15894
15895
15896
15897
15898
15899
15900
15901
15902
15903
15904
15905
15906
15907
15908
15909
15910
15911
15912
15913
15914
15915
15916
15917
15918
15919
15920
15921
15922
15923
15924
15925
15926
15927
15928
15929
15930
15931
15932
15933
15934
15935
15936
15937
15938
15939
15940
15941
15942
15943
15944
15945
15946
15947
15948
15949
15950
15951
15952
15953
15954
15955
15956
15957
15958
15959
15960
15961
15962
15963
15964
15965
15966
15967
15968
15969
15970
15971
15972
15973
15974
15975
15976
15977
15978
15979
15980
15981
15982
15983
15984
15985
15986
15987
15988
15989
15990
15991
15992
15993
15994
15995
15996
15997
15998
15999
16000
16001
16002
16003
16004
16005
16006
16007
16008
16009
16010
16011
16012
16013
16014
16015
16016
16017
16018
16019
16020
16021
16022
16023
16024
16025
16026
16027
16028
16029
16030
16031
16032
16033
16034
16035
16036
16037
16038
16039
16040
16041
16042
16043
16044
16045
16046
16047
16048
16049
16050
16051
16052
16053
16054
16055
16056
16057
16058
16059
16060
16061
16062
16063
16064
16065
16066
16067
16068
16069
16070
16071
16072
16073
16074
16075
16076
16077
16078
16079
16080
16081
16082
16083
16084
16085
16086
16087
16088
16089
16090
16091
16092
16093
16094
16095
16096
16097
16098
16099
16100
16101
16102
16103
16104
16105
16106
16107
16108
16109
16110
16111
16112
16113
16114
16115
16116
16117
16118
16119
16120
16121
16122
16123
16124
16125
16126
16127
16128
16129
16130
16131
16132
16133
16134
16135
16136
16137
16138
16139
16140
16141
16142
16143
16144
16145
16146
16147
16148
16149
16150
16151
16152
16153
16154
16155
16156
16157
16158
16159
16160
16161
16162
16163
16164
16165
16166
16167
16168
16169
16170
16171
16172
16173
16174
16175
16176
16177
16178
16179
16180
16181
16182
16183
16184
16185
16186
16187
16188
16189
16190
16191
16192
16193
16194
16195
16196
16197
16198
16199
16200
16201
16202
16203
16204
16205
16206
16207
16208
16209
16210
16211
16212
16213
16214
16215
16216
16217
16218
16219
16220
16221
16222
16223
16224
16225
16226
16227
16228
16229
16230
16231
16232
16233
16234
16235
16236
16237
16238
16239
16240
16241
16242
16243
16244
16245
16246
16247
16248
16249
16250
16251
16252
16253
16254
16255
16256
16257
16258
16259
16260
16261
16262
16263
16264
16265
16266
16267
16268
16269
16270
16271
16272
16273
16274
16275
16276
16277
16278
16279
16280
16281
16282
16283
16284
16285
16286
16287
16288
16289
16290
16291
16292
16293
16294
16295
16296
16297
16298
16299
16300
16301
16302
16303
16304
16305
16306
16307
16308
16309
16310
16311
16312
16313
16314
16315
16316
16317
16318
16319
16320
16321
16322
16323
16324
16325
16326
16327
16328
16329
16330
16331
16332
16333
16334
16335
16336
16337
16338
16339
16340
16341
16342
16343
16344
16345
16346
16347
16348
16349
16350
16351
16352
16353
16354
16355
16356
16357
16358
16359
16360
16361
16362
16363
16364
16365
16366
16367
16368
16369
16370
16371
16372
16373
16374
16375
16376
16377
16378
16379
16380
16381
16382
16383
16384
16385
16386
16387
16388
16389
16390
16391
16392
16393
16394
16395
16396
16397
16398
16399
16400
16401
16402
16403
16404
16405
16406
16407
16408
16409
16410
16411
16412
16413
16414
16415
16416
16417
16418
16419
16420
16421
16422
16423
16424
16425
16426
16427
16428
16429
16430
16431
16432
16433
16434
16435
16436
16437
16438
16439
16440
16441
16442
16443
16444
16445
16446
16447
16448
16449
16450
16451
16452
16453
16454
16455
16456
16457
16458
16459
16460
16461
16462
16463
16464
16465
16466
16467
16468
16469
16470
16471
16472
16473
16474
16475
16476
16477
16478
16479
16480
16481
16482
16483
16484
16485
16486
16487
16488
16489
16490
16491
16492
16493
16494
16495
16496
16497
16498
16499
16500
16501
16502
16503
16504
16505
16506
16507
16508
16509
16510
16511
16512
16513
16514
16515
16516
16517
16518
16519
16520
16521
16522
16523
16524
16525
16526
16527
16528
16529
16530
16531
16532
16533
16534
16535
16536
16537
16538
16539
16540
16541
16542
16543
16544
16545
16546
16547
16548
16549
16550
16551
16552
16553
16554
16555
16556
16557
16558
16559
16560
16561
16562
16563
16564
16565
16566
16567
16568
16569
16570
16571
16572
16573
16574
16575
16576
16577
16578
16579
16580
16581
16582
16583
16584
16585
16586
16587
16588
16589
16590
16591
16592
16593
16594
16595
16596
16597
16598
16599
16600
16601
16602
16603
16604
16605
16606
16607
16608
16609
16610
16611
16612
16613
16614
16615
16616
16617
16618
16619
16620
16621
16622
16623
16624
16625
16626
16627
16628
16629
16630
16631
16632
16633
16634
16635
16636
16637
16638
16639
16640
16641
16642
16643
16644
16645
16646
16647
16648
16649
16650
16651
16652
16653
16654
16655
16656
16657
16658
16659
16660
16661
16662
16663
16664
16665
16666
16667
16668
16669
16670
16671
16672
16673
16674
16675
16676
16677
16678
16679
16680
16681
16682
16683
16684
16685
16686
16687
.. index::
   single: language, GHC extensions

As with all known Haskell systems, GHC implements some extensions to the
standard Haskell language. They can all be enabled or disabled by command line
flags or language pragmas. By default GHC understands the most recent Haskell
version it supports, plus a handful of extensions.

Some of the Glasgow extensions serve to give you access to the
underlying facilities with which we implement Haskell. Thus, you can get
at the Raw Iron, if you are willing to write some non-portable code at a
more primitive level. You need not be “stuck” on performance because of
the implementation costs of Haskell's "high-level" features—you can
always code "under" them. In an extreme case, you can write all your
time-critical code in C, and then just glue it together with Haskell!

Before you get too carried away working at the lowest level (e.g.,
sloshing ``MutableByteArray#``\ s around your program), you may wish to
check if there are libraries that provide a "Haskellised veneer" over
the features you want. The separate
`libraries documentation <../libraries/index.html>`__ describes all the
libraries that come with GHC.

.. _options-language:

Language options
================

.. index::
   single: language; option
   single: options; language
   single: extensions; options controlling

The language extensions control what variation of the language are
permitted.

Language options can be controlled in two ways:

-  Every language option can switched on by a command-line flag
   "``-X...``" (e.g. ``-XTemplateHaskell``), and switched off by the
   flag "``-XNo...``"; (e.g. ``-XNoTemplateHaskell``).

-  Language options recognised by Cabal can also be enabled using the
   ``LANGUAGE`` pragma, thus ``{-# LANGUAGE TemplateHaskell #-}`` (see
   :ref:`language-pragma`).

GHC supports these language options:

.. extension-print::
    :type: table

Although not recommended, the deprecated :ghc-flag:`-fglasgow-exts` flag enables
a large swath of the extensions supported by GHC at once.

.. ghc-flag:: -fglasgow-exts
    :shortdesc: Deprecated. Enable most language extensions;
        see :ref:`options-language` for exactly which ones.
    :type: dynamic
    :reverse: -fno-glasgow-exts
    :category: misc

    The flag ``-fglasgow-exts`` is equivalent to enabling the following extensions:

    .. include:: what_glasgow_exts_does.rst

    Enabling these options is the *only* effect of ``-fglasgow-exts``. We are trying
    to move away from this portmanteau flag, and towards enabling features
    individually.

.. _primitives:

Unboxed types and primitive operations
======================================

GHC is built on a raft of primitive data types and operations;
"primitive" in the sense that they cannot be defined in Haskell itself.
While you really can use this stuff to write fast code, we generally
find it a lot less painful, and more satisfying in the long run, to use
higher-level language features and libraries. With any luck, the code
you write will be optimised to the efficient unboxed version in any
case. And if it isn't, we'd like to know about it.

All these primitive data types and operations are exported by the
library ``GHC.Prim``, for which there is
:ghc-prim-ref:`detailed online documentation <GHC.Prim.>`. (This
documentation is generated from the file ``compiler/prelude/primops.txt.pp``.)

If you want to mention any of the primitive data types or operations in
your program, you must first import ``GHC.Prim`` to bring them into
scope. Many of them have names ending in ``#``, and to mention such names
you need the :extension:`MagicHash` extension.

The primops make extensive use of `unboxed types <#glasgow-unboxed>`__
and `unboxed tuples <#unboxed-tuples>`__, which we briefly summarise
here.

.. _glasgow-unboxed:

Unboxed types
-------------

Most types in GHC are boxed, which means that values of that type are
represented by a pointer to a heap object. The representation of a
Haskell ``Int``, for example, is a two-word heap object. An unboxed
type, however, is represented by the value itself, no pointers or heap
allocation are involved.

Unboxed types correspond to the “raw machine” types you would use in C:
``Int#`` (long int), ``Double#`` (double), ``Addr#`` (void \*), etc. The
*primitive operations* (PrimOps) on these types are what you might
expect; e.g., ``(+#)`` is addition on ``Int#``\ s, and is the
machine-addition that we all know and love—usually one instruction.

Primitive (unboxed) types cannot be defined in Haskell, and are
therefore built into the language and compiler. Primitive types are
always unlifted; that is, a value of a primitive type cannot be bottom.
(Note: a "boxed" type means that a value is represented by a pointer to a heap
object; a "lifted" type means that terms of that type may be bottom. See
the next paragraph for an example.)
We use the convention (but it is only a convention) that primitive
types, values, and operations have a ``#`` suffix (see
:ref:`magic-hash`). For some primitive types we have special syntax for
literals, also described in the `same section <#magic-hash>`__.

Primitive values are often represented by a simple bit-pattern, such as
``Int#``, ``Float#``, ``Double#``. But this is not necessarily the case:
a primitive value might be represented by a pointer to a heap-allocated
object. Examples include ``Array#``, the type of primitive arrays. Thus,
``Array#`` is an unlifted, boxed type. A
primitive array is heap-allocated because it is too big a value to fit
in a register, and would be too expensive to copy around; in a sense, it
is accidental that it is represented by a pointer. If a pointer
represents a primitive value, then it really does point to that value:
no unevaluated thunks, no indirections. Nothing can be at the other end
of the pointer than the primitive value. A numerically-intensive program
using unboxed types can go a *lot* faster than its “standard”
counterpart—we saw a threefold speedup on one example.

Unboxed type kinds
------------------

Because unboxed types are represented without the use of pointers, we
cannot store them in use a polymorphic datatype at an unboxed type.
For example, the ``Just`` node
of ``Just 42#`` would have to be different from the ``Just`` node of
``Just 42``; the former stores an integer directly, while the latter
stores a pointer. GHC currently does not support this variety of ``Just``
nodes (nor for any other datatype). Accordingly, the *kind* of an unboxed
type is different from the kind of a boxed type.

The Haskell Report describes that ``*`` (spelled ``Type`` and imported from
``Data.Kind`` in the GHC dialect of Haskell) is the kind of ordinary datatypes,
such as ``Int``. Furthermore, type constructors can have kinds with arrows; for
example, ``Maybe`` has kind ``Type -> Type``. Unboxed types have a kind that
specifies their runtime representation. For example, the type ``Int#`` has kind
``TYPE 'IntRep`` and ``Double#`` has kind ``TYPE 'DoubleRep``. These kinds say
that the runtime representation of an ``Int#`` is a machine integer, and the
runtime representation of a ``Double#`` is a machine double-precision floating
point. In contrast, the kind ``Type`` is actually just a synonym for ``TYPE
'LiftedRep``. More details of the ``TYPE`` mechanisms appear in the `section
on runtime representation polymorphism <#runtime-rep>`__.

Given that ``Int#``'s kind is not ``Type``, it then it follows that ``Maybe
Int#`` is disallowed. Similarly, because type variables tend to be of kind
``Type`` (for example, in ``(.) :: (b -> c) -> (a -> b) -> a -> c``, all the
type variables have kind ``Type``), polymorphism tends not to work over
primitive types. Stepping back, this makes some sense, because a polymorphic
function needs to manipulate the pointers to its data, and most primitive types
are unboxed.

There are some restrictions on the use of primitive types:

-  You cannot define a newtype whose representation type (the argument
   type of the data constructor) is an unboxed type. Thus, this is
   illegal:

   ::

         newtype A = MkA Int#

   However, this restriction can be relaxed by enabling
   :extension:`UnliftedNewtypes`.  The `section on unlifted newtypes
   <#unlifted-newtypes>`__ details the behavior of such types.

-  You cannot bind a variable with an unboxed type in a *top-level*
   binding.

-  You cannot bind a variable with an unboxed type in a *recursive*
   binding.

-  You may bind unboxed variables in a (non-recursive, non-top-level)
   pattern binding, but you must make any such pattern-match strict.
   (Failing to do so emits a warning :ghc-flag:`-Wunbanged-strict-patterns`.)
   For example, rather than:

   ::

         data Foo = Foo Int Int#

         f x = let (Foo a b, w) = ..rhs.. in ..body..

   you must write:

   ::

         data Foo = Foo Int Int#

         f x = let !(Foo a b, w) = ..rhs.. in ..body..

   since ``b`` has type ``Int#``.

.. _unboxed-tuples:

Unboxed tuples
--------------

.. extension:: UnboxedTuples
    :shortdesc: Enable the use of unboxed tuple syntax.

    :since: 6.8.1


Unboxed tuples aren't really exported by ``GHC.Exts``; they are a
syntactic extension (:extension:`UnboxedTuples`). An
unboxed tuple looks like this: ::

    (# e_1, ..., e_n #)

where ``e_1..e_n`` are expressions of any type (primitive or
non-primitive). The type of an unboxed tuple looks the same.

Note that when unboxed tuples are enabled, ``(#`` is a single lexeme, so
for example when using operators like ``#`` and ``#-`` you need to write
``( # )`` and ``( #- )`` rather than ``(#)`` and ``(#-)``.

Unboxed tuples are used for functions that need to return multiple
values, but they avoid the heap allocation normally associated with
using fully-fledged tuples. When an unboxed tuple is returned, the
components are put directly into registers or on the stack; the unboxed
tuple itself does not have a composite representation. Many of the
primitive operations listed in ``primops.txt.pp`` return unboxed tuples.
In particular, the ``IO`` and ``ST`` monads use unboxed tuples to avoid
unnecessary allocation during sequences of operations.

There are some restrictions on the use of unboxed tuples:

-  The typical use of unboxed tuples is simply to return multiple
   values, binding those multiple results with a ``case`` expression,
   thus:

   ::

         f x y = (# x+1, y-1 #)
         g x = case f x x of { (# a, b #) -> a + b }

   You can have an unboxed tuple in a pattern binding, thus

   ::

         f x = let (# p,q #) = h x in ..body..

   If the types of ``p`` and ``q`` are not unboxed, the resulting
   binding is lazy like any other Haskell pattern binding. The above
   example desugars like this:

   ::

         f x = let t = case h x of { (# p,q #) -> (p,q) }
                   p = fst t
                   q = snd t
               in ..body..

   Indeed, the bindings can even be recursive.

.. _unboxed-sums:

Unboxed sums
------------

.. extension:: UnboxedSums
    :shortdesc: Enable unboxed sums.

    :since: 8.2.1

    Enable the use of unboxed sum syntax.

`-XUnboxedSums` enables new syntax for anonymous, unboxed sum types. The syntax
for an unboxed sum type with N alternatives is ::

    (# t_1 | t_2 | ... | t_N #)

where ``t_1`` ... ``t_N`` are types (which can be unlifted, including unboxed
tuples and sums).

Unboxed tuples can be used for multi-arity alternatives. For example: ::

    (# (# Int, String #) | Bool #)

The term level syntax is similar. Leading and preceding bars (`|`) indicate which
alternative it is. Here are two terms of the type shown above: ::

    (# (# 1, "foo" #) | #) -- first alternative

    (# | True #) -- second alternative

The pattern syntax reflects the term syntax: ::

    case x of
      (# (# i, str #) | #) -> ...
      (# | bool #) -> ...

Unboxed sums are "unboxed" in the sense that, instead of allocating sums in the
heap and representing values as pointers, unboxed sums are represented as their
components, just like unboxed tuples. These "components" depend on alternatives
of a sum type. Like unboxed tuples, unboxed sums are lazy in their lifted
components.

The code generator tries to generate as compact layout as possible for each
unboxed sum. In the best case, size of an unboxed sum is size of its biggest
alternative plus one word (for a tag). The algorithm for generating the memory
layout for a sum type works like this:

- All types are classified as one of these classes: 32bit word, 64bit word,
  32bit float, 64bit float, pointer.

- For each alternative of the sum type, a layout that consists of these fields
  is generated. For example, if an alternative has ``Int``, ``Float#`` and
  ``String`` fields, the layout will have an 32bit word, 32bit float and
  pointer fields.

- Layout fields are then overlapped so that the final layout will be as compact
  as possible. For example, suppose we have the unboxed sum: ::

    (# (# Word32#, String, Float# #)
    |  (# Float#, Float#, Maybe Int #) #)

  The final layout will be something like ::

    Int32, Float32, Float32, Word32, Pointer

  The first ``Int32`` is for the tag. There are two ``Float32`` fields because
  floating point types can't overlap with other types, because of limitations of
  the code generator that we're hoping to overcome in the future. The second
  alternative needs two ``Float32`` fields: The ``Word32`` field is for the
  ``Word32#`` in the first alternative. The ``Pointer`` field is shared between
  ``String`` and ``Maybe Int`` values of the alternatives.

  As another example, this is the layout for the unboxed version of ``Maybe a``
  type, ``(# (# #) | a #)``: ::

    Int32, Pointer

  The ``Pointer`` field is not used when tag says that it's ``Nothing``.
  Otherwise ``Pointer`` points to the value in ``Just``. As mentioned
  above, this type is lazy in its lifted field. Therefore, the type ::

    data Maybe' a = Maybe' (# (# #) | a #)

  is *precisely* isomorphic to the type ``Maybe a``, although its memory
  representation is different.

  In the degenerate case where all the alternatives have zero width, such
  as the ``Bool``-like ``(# (# #) | (# #) #)``, the unboxed sum layout only
  has an ``Int32`` tag field (i.e., the whole thing is represented by an integer).

.. _unlifted-newtypes:

Unlifted Newtypes
-----------------

.. extension:: UnliftedNewtypes
    :shortdesc: Enable unlifted newtypes.

    :since: 8.10.1

    Enable the use of newtypes over types with non-lifted runtime representations.

GHC implements an :extension:`UnliftedNewtypes` extension as specified in
`this GHC proposal <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0013-unlifted-newtypes.rst>`_.
:extension:`UnliftedNewtypes` relaxes the restrictions around what types can appear inside
of a `newtype`. For example, the type ::

    newtype A = MkA Int#

is accepted when this extension is enabled. This creates a type
``A :: TYPE 'IntRep`` and a data constructor ``MkA :: Int# -> A``.
Although the kind of ``A`` is inferred by GHC, there is nothing visually
distictive about this type that indicated that is it not of kind ``Type``
like newtypes typically are. `GADTSyntax <#gadt-style>`__ can be used to
provide a kind signature for additional clarity ::

    newtype A :: TYPE 'IntRep where
      MkA :: Int# -> A

The ``Coercible`` machinery works with unlifted newtypes just like it does with
lifted types. In either of the equivalent formulations of ``A`` given above,
users would additionally have access to a coercion between ``A`` and ``Int#``.

As a consequence of the
`levity-polymorphic binder restriction <#levity-polymorphic-restrictions>`__,
levity-polymorphic fields are disallowed in data constructors
of data types declared using ``data``. However, since ``newtype`` data
constructor application is implemented as a coercion instead of as function
application, this restriction does not apply to the field inside a ``newtype``
data constructor. Thus, the type checker accepts ::

    newtype Identity# :: forall (r :: RuntimeRep). TYPE r -> TYPE r where
      MkIdentity# :: forall (r :: RuntimeRep) (a :: TYPE r). a -> Identity# a

And with `UnboxedSums <#unboxed-sums>`__ enabled ::

    newtype Maybe# :: forall (r :: RuntimeRep). TYPE r -> TYPE (SumRep '[r, TupleRep '[]]) where
      MkMaybe# :: forall (r :: RuntimeRep) (a :: TYPE r). (# a | (# #) #) -> Maybe# a

This extension also relaxes some of the restrictions around data family
instances. In particular, :extension:`UnliftedNewtypes` permits a
``newtype instance`` to be given a return kind of ``TYPE r``, not just
``Type``. For example, the following ``newtype instance`` declarations would be
permitted: ::

     class Foo a where
       data FooKey a :: TYPE 'IntRep
     class Bar (r :: RuntimeRep) where
       data BarType r :: TYPE r

     instance Foo Bool where
       newtype FooKey Bool = FooKeyBoolC Int#
     instance Bar 'WordRep where
       newtype BarType 'WordRep = BarTypeWordRepC Word#

It is worth noting that :extension:`UnliftedNewtypes` is *not* required to give
the data families themselves return kinds involving ``TYPE``, such as the
``FooKey`` and ``BarType`` examples above. The extension is
only required for ``newtype instance`` declarations, such as ``FooKeyBoolC``
and ``BarTypeWorkRepC`` above.

This extension impacts the determination of whether or not a newtype has
a Complete User-Specified Kind Signature (CUSK). The exact impact is specified
`the section on CUSKs <#complete-kind-signatures>`__.

.. _syntax-extns:

Syntactic extensions
====================

.. _unicode-syntax:

Unicode syntax
--------------

.. extension:: UnicodeSyntax
    :shortdesc: Enable unicode syntax.

    :since: 6.8.1

    Enable the use of Unicode characters in place of their equivalent ASCII
    sequences.

The language extension :extension:`UnicodeSyntax` enables
Unicode characters to be used to stand for certain ASCII character
sequences. The following alternatives are provided:

+--------------+---------------+-------------+-----------------------------------------+
| ASCII        | Unicode       | Code point  | Name                                    |
|              | alternative   |             |                                         |
+==============+===============+=============+=========================================+
| ``::``       | ∷             | 0x2237      | PROPORTION                              |
+--------------+---------------+-------------+-----------------------------------------+
| ``=>``       | ⇒             | 0x21D2      | RIGHTWARDS DOUBLE ARROW                 |
+--------------+---------------+-------------+-----------------------------------------+
| ``->``       | →             | 0x2192      | RIGHTWARDS ARROW                        |
+--------------+---------------+-------------+-----------------------------------------+
| ``<-``       | ←             | 0x2190      | LEFTWARDS ARROW                         |
+--------------+---------------+-------------+-----------------------------------------+
| ``>-``       | ⤚             | 0x291a      | RIGHTWARDS ARROW-TAIL                   |
+--------------+---------------+-------------+-----------------------------------------+
| ``-<``       | ⤙             | 0x2919      | LEFTWARDS ARROW-TAIL                    |
+--------------+---------------+-------------+-----------------------------------------+
| ``>>-``      | ⤜             | 0x291C      | RIGHTWARDS DOUBLE ARROW-TAIL            |
+--------------+---------------+-------------+-----------------------------------------+
| ``-<<``      | ⤛             | 0x291B      | LEFTWARDS DOUBLE ARROW-TAIL             |
+--------------+---------------+-------------+-----------------------------------------+
| ``*``        | ★             | 0x2605      | BLACK STAR                              |
+--------------+---------------+-------------+-----------------------------------------+
| ``forall``   | ∀             | 0x2200      | FOR ALL                                 |
+--------------+---------------+-------------+-----------------------------------------+
| ``(|``       | ⦇             | 0x2987      | Z NOTATION LEFT IMAGE BRACKET           |
+--------------+---------------+-------------+-----------------------------------------+
| ``|)``       | ⦈             | 0x2988      | Z NOTATION RIGHT IMAGE BRACKET          |
+--------------+---------------+-------------+-----------------------------------------+
| ``[|``       | ⟦             | 0x27E6      | MATHEMATICAL LEFT WHITE SQUARE BRACKET  |
+--------------+---------------+-------------+-----------------------------------------+
| ``|]``       | ⟧             | 0x27E7      | MATHEMATICAL RIGHT WHITE SQUARE BRACKET |
+--------------+---------------+-------------+-----------------------------------------+

.. _magic-hash:

The magic hash
--------------

.. extension:: MagicHash
    :shortdesc: Allow ``#`` as a postfix modifier on identifiers.

    :since: 6.8.1

    Enables the use of the hash character (``#``) as an identifier suffix.

The language extension :extension:`MagicHash` allows ``#`` as a postfix modifier
to identifiers. Thus, ``x#`` is a valid variable, and ``T#`` is a valid type
constructor or data constructor.

The hash sign does not change semantics at all. We tend to use variable
names ending in "#" for unboxed values or types (e.g. ``Int#``), but
there is no requirement to do so; they are just plain ordinary
variables. Nor does the :extension:`MagicHash` extension bring anything into
scope. For example, to bring ``Int#`` into scope you must import
``GHC.Prim`` (see :ref:`primitives`); the :extension:`MagicHash` extension then
allows you to *refer* to the ``Int#`` that is now in scope. Note that
with this option, the meaning of ``x#y = 0`` is changed: it defines a
function ``x#`` taking a single argument ``y``; to define the operator
``#``, put a space: ``x # y = 0``.

The :extension:`MagicHash` also enables some new forms of literals (see
:ref:`glasgow-unboxed`):

-  ``'x'#`` has type ``Char#``

-  ``"foo"#`` has type ``Addr#``

-  ``3#`` has type ``Int#``. In general, any Haskell integer lexeme
   followed by a ``#`` is an ``Int#`` literal, e.g. ``-0x3A#`` as well as
   ``32#``.

-  ``3##`` has type ``Word#``. In general, any non-negative Haskell
   integer lexeme followed by ``##`` is a ``Word#``.

-  ``3.2#`` has type ``Float#``.

-  ``3.2##`` has type ``Double#``

.. _negative-literals:

Negative literals
-----------------

.. extension:: NegativeLiterals
    :shortdesc: Enable support for negative literals.

    :since: 7.8.1

    Enable the use of un-parenthesized negative numeric literals.

The literal ``-123`` is, according to Haskell98 and Haskell 2010,
desugared as ``negate (fromInteger 123)``. The language extension
:extension:`NegativeLiterals` means that it is instead desugared as
``fromInteger (-123)``.

This can make a difference when the positive and negative range of a
numeric data type don't match up. For example, in 8-bit arithmetic -128
is representable, but +128 is not. So ``negate (fromInteger 128)`` will
elicit an unexpected integer-literal-overflow message.

.. _num-decimals:

Fractional looking integer literals
-----------------------------------

.. extension:: NumDecimals
    :shortdesc: Enable support for 'fractional' integer literals.

    :since: 7.8.1

    Allow the use of floating-point literal syntax for integral types.

Haskell 2010 and Haskell 98 define floating literals with the syntax
``1.2e6``. These literals have the type ``Fractional a => a``.

The language extension :extension:`NumDecimals` allows you to also use the
floating literal syntax for instances of ``Integral``, and have values
like ``(1.2e6 :: Num a => a)``

.. _binary-literals:

Binary integer literals
-----------------------

.. extension:: BinaryLiterals
    :shortdesc: Enable support for binary literals.

    :since: 7.10.1

    Allow the use of binary notation in integer literals.

Haskell 2010 and Haskell 98 allows for integer literals to be given in
decimal, octal (prefixed by ``0o`` or ``0O``), or hexadecimal notation
(prefixed by ``0x`` or ``0X``).

The language extension :extension:`BinaryLiterals` adds support for expressing
integer literals in binary notation with the prefix ``0b`` or ``0B``. For
instance, the binary integer literal ``0b11001001`` will be desugared into
``fromInteger 201`` when :extension:`BinaryLiterals` is enabled.

.. _hex-float-literals:

Hexadecimal floating point literals
-----------------------------------

.. extension:: HexFloatLiterals
    :shortdesc: Enable support for :ref:`hexadecimal floating point literals <hex-float-literals>`.

    :since: 8.4.1

    Allow writing floating point literals using hexadecimal notation.

The hexadecimal notation for floating point literals is useful when you
need to specify floating point constants precisely, as the literal notation
corresponds closely to the underlying bit-encoding of the number.

In this notation floating point numbers are written using hexadecimal digits,
and so the digits are interpreted using base 16, rather then the usual 10.
This means that digits left of the decimal point correspond to positive
powers of 16, while the ones to the right correspond to negative ones.

You may also write an explicit exponent, which is similar to the exponent
in decimal notation with the following differences:
- the exponent begins with ``p`` instead of ``e``
- the exponent is written in base ``10`` (**not** 16)
- the base of the exponent is ``2`` (**not** 16).

In terms of the underlying bit encoding, each hexadecimal digit corresponds
to 4 bits, and you may think of the exponent as "moving" the floating point
by one bit left (negative) or right (positive).  Here are some examples:

-  ``0x0.1``     is the same as ``1/16``
-  ``0x0.01``    is the same as ``1/256``
-  ``0xF.FF``    is the same as ``15 + 15/16 + 15/256``
-  ``0x0.1p4``   is the same as ``1``
-  ``0x0.1p-4``  is the same as ``1/256``
-  ``0x0.1p12``  is the same as ``256``




.. _numeric-underscores:

Numeric underscores
-------------------

.. extension:: NumericUnderscores
    :shortdesc: Enable support for :ref:`numeric underscores <numeric-underscores>`.

    :since: 8.6.1

    Allow the use of underscores in numeric literals.

GHC allows for numeric literals to be given in decimal, octal, hexadecimal,
binary, or float notation.

The language extension :extension:`NumericUnderscores` adds support for expressing
underscores in numeric literals.
For instance, the numeric literal ``1_000_000`` will be parsed into
``1000000`` when :extension:`NumericUnderscores` is enabled.
That is, underscores in numeric literals are ignored when
:extension:`NumericUnderscores` is enabled.
See also :ghc-ticket:`14473`.

For example:

.. code-block:: none

    -- decimal
    million    = 1_000_000
    billion    = 1_000_000_000
    lightspeed = 299_792_458
    version    = 8_04_1
    date       = 2017_12_31

    -- hexadecimal
    red_mask = 0xff_00_00
    size1G   = 0x3fff_ffff

    -- binary
    bit8th   = 0b01_0000_0000
    packbits = 0b1_11_01_0000_0_111
    bigbits  = 0b1100_1011__1110_1111__0101_0011

    -- float
    pi       = 3.141_592_653_589_793
    faraday  = 96_485.332_89
    avogadro = 6.022_140_857e+23

    -- function
    isUnderMillion = (< 1_000_000)

    clip64M x
        | x > 0x3ff_ffff = 0x3ff_ffff
        | otherwise = x

    test8bit x = (0b01_0000_0000 .&. x) /= 0

About validity:

.. code-block:: none

    x0 = 1_000_000   -- valid
    x1 = 1__000000   -- valid
    x2 = 1000000_    -- invalid
    x3 = _1000000    -- invalid

    e0 = 0.0001      -- valid
    e1 = 0.000_1     -- valid
    e2 = 0_.0001     -- invalid
    e3 = _0.0001     -- invalid
    e4 = 0._0001     -- invalid
    e5 = 0.0001_     -- invalid

    f0 = 1e+23       -- valid
    f1 = 1_e+23      -- valid
    f2 = 1__e+23     -- valid
    f3 = 1e_+23      -- invalid

    g0 = 1e+23       -- valid
    g1 = 1e+_23      -- invalid
    g2 = 1e+23_      -- invalid

    h0 = 0xffff      -- valid
    h1 = 0xff_ff     -- valid
    h2 = 0x_ffff     -- valid
    h3 = 0x__ffff    -- valid
    h4 = _0xffff     -- invalid

.. _pattern-guards:

Pattern guards
--------------

.. extension:: NoPatternGuards
    :shortdesc: Disable pattern guards.
        Implied by :extension:`Haskell98`.

    :implied by: :extension:`Haskell98`
    :since: 6.8.1

Disable `pattern guards
<http://www.haskell.org/onlinereport/haskell2010/haskellch3.html#x8-460003.13>`__.

.. _view-patterns:

View patterns
-------------

.. extension:: ViewPatterns
    :shortdesc: Enable view patterns.

    :since: 6.10.1

    Allow use of view pattern syntax.

View patterns are enabled by the language extension :extension:`ViewPatterns`. More
information and examples of view patterns can be found on the
:ghc-wiki:`Wiki page <view-patterns>`.

View patterns are somewhat like pattern guards that can be nested inside
of other patterns. They are a convenient way of pattern-matching against
values of abstract types. For example, in a programming language
implementation, we might represent the syntax of the types of the
language as follows: ::

    type Typ

    data TypView = Unit
                 | Arrow Typ Typ

    view :: Typ -> TypView

    -- additional operations for constructing Typ's ...

The representation of Typ is held abstract, permitting implementations
to use a fancy representation (e.g., hash-consing to manage sharing).
Without view patterns, using this signature is a little inconvenient: ::

    size :: Typ -> Integer
    size t = case view t of
      Unit -> 1
      Arrow t1 t2 -> size t1 + size t2

It is necessary to iterate the case, rather than using an equational
function definition. And the situation is even worse when the matching
against ``t`` is buried deep inside another pattern.

View patterns permit calling the view function inside the pattern and
matching against the result: ::

    size (view -> Unit) = 1
    size (view -> Arrow t1 t2) = size t1 + size t2

That is, we add a new form of pattern, written ⟨expression⟩ ``->``
⟨pattern⟩ that means "apply the expression to whatever we're trying to
match against, and then match the result of that application against the
pattern". The expression can be any Haskell expression of function type,
and view patterns can be used wherever patterns are used.

The semantics of a pattern ``(`` ⟨exp⟩ ``->`` ⟨pat⟩ ``)`` are as
follows:

-  Scoping:
   The variables bound by the view pattern are the variables bound by
   ⟨pat⟩.

   Any variables in ⟨exp⟩ are bound occurrences, but variables bound "to
   the left" in a pattern are in scope. This feature permits, for
   example, one argument to a function to be used in the view of another
   argument. For example, the function ``clunky`` from
   :ref:`pattern-guards` can be written using view patterns as follows: ::

       clunky env (lookup env -> Just val1) (lookup env -> Just val2) = val1 + val2
       ...other equations for clunky...

   More precisely, the scoping rules are:

   -  In a single pattern, variables bound by patterns to the left of a
      view pattern expression are in scope. For example: ::

          example :: Maybe ((String -> Integer,Integer), String) -> Bool
          example (Just ((f,_), f -> 4)) = True

      Additionally, in function definitions, variables bound by matching
      earlier curried arguments may be used in view pattern expressions
      in later arguments: ::

          example :: (String -> Integer) -> String -> Bool
          example f (f -> 4) = True

      That is, the scoping is the same as it would be if the curried
      arguments were collected into a tuple.

   -  In mutually recursive bindings, such as ``let``, ``where``, or the
      top level, view patterns in one declaration may not mention
      variables bound by other declarations. That is, each declaration
      must be self-contained. For example, the following program is not
      allowed: ::

          let {(x -> y) = e1 ;
               (y -> x) = e2 } in x

   (For some amplification on this design choice see :ghc-ticket:`4061`.

-  Typing: If ⟨exp⟩ has type ⟨T1⟩ ``->`` ⟨T2⟩ and ⟨pat⟩ matches a ⟨T2⟩,
   then the whole view pattern matches a ⟨T1⟩.

-  Matching: To the equations in Section 3.17.3 of the `Haskell 98
   Report <http://www.haskell.org/onlinereport/>`__, add the following: ::

       case v of { (e -> p) -> e1 ; _ -> e2 }
        =
       case (e v) of { p -> e1 ; _ -> e2 }

   That is, to match a variable ⟨v⟩ against a pattern ``(`` ⟨exp⟩ ``->``
   ⟨pat⟩ ``)``, evaluate ``(`` ⟨exp⟩ ⟨v⟩ ``)`` and match the result
   against ⟨pat⟩.

-  Efficiency: When the same view function is applied in multiple
   branches of a function definition or a case expression (e.g., in
   ``size`` above), GHC makes an attempt to collect these applications
   into a single nested case expression, so that the view function is
   only applied once. Pattern compilation in GHC follows the matrix
   algorithm described in Chapter 4 of `The Implementation of Functional
   Programming
   Languages <http://research.microsoft.com/~simonpj/Papers/slpj-book-1987/>`__.
   When the top rows of the first column of a matrix are all view
   patterns with the "same" expression, these patterns are transformed
   into a single nested case. This includes, for example, adjacent view
   patterns that line up in a tuple, as in

   ::

       f ((view -> A, p1), p2) = e1
       f ((view -> B, p3), p4) = e2

   The current notion of when two view pattern expressions are "the
   same" is very restricted: it is not even full syntactic equality.
   However, it does include variables, literals, applications, and
   tuples; e.g., two instances of ``view ("hi", "there")`` will be
   collected. However, the current implementation does not compare up to
   alpha-equivalence, so two instances of ``(x, view x -> y)`` will not
   be coalesced.

.. _n-k-patterns:

n+k patterns
------------

.. extension:: NPlusKPatterns
    :shortdesc: Enable support for ``n+k`` patterns.
        Implied by :extension:`Haskell98`.

    :implied by: :extension:`Haskell98`
    :since: 6.12.1

    Enable use of ``n+k`` patterns.

.. _recursive-do-notation:

The recursive do-notation
-------------------------

.. extension:: RecursiveDo
    :shortdesc: Enable recursive do (mdo) notation.

    :since: 6.8.1

    Allow the use of recursive ``do`` notation.

The do-notation of Haskell 98 does not allow *recursive bindings*, that
is, the variables bound in a do-expression are visible only in the
textually following code block. Compare this to a let-expression, where
bound variables are visible in the entire binding group.

It turns out that such recursive bindings do indeed make sense for a
variety of monads, but not all. In particular, recursion in this sense
requires a fixed-point operator for the underlying monad, captured by
the ``mfix`` method of the ``MonadFix`` class, defined in
``Control.Monad.Fix`` as follows: ::

    class Monad m => MonadFix m where
       mfix :: (a -> m a) -> m a

Haskell's ``Maybe``, ``[]`` (list), ``ST`` (both strict and lazy
versions), ``IO``, and many other monads have ``MonadFix`` instances. On
the negative side, the continuation monad, with the signature
``(a -> r) -> r``, does not.

For monads that do belong to the ``MonadFix`` class, GHC provides an
extended version of the do-notation that allows recursive bindings. The
:extension:`RecursiveDo` (language pragma: ``RecursiveDo``) provides the
necessary syntactic support, introducing the keywords ``mdo`` and
``rec`` for higher and lower levels of the notation respectively. Unlike
bindings in a ``do`` expression, those introduced by ``mdo`` and ``rec``
are recursively defined, much like in an ordinary let-expression. Due to
the new keyword ``mdo``, we also call this notation the *mdo-notation*.

Here is a simple (albeit contrived) example:

::

    {-# LANGUAGE RecursiveDo #-}
    justOnes = mdo { xs <- Just (1:xs)
                   ; return (map negate xs) }

or equivalently

::

    {-# LANGUAGE RecursiveDo #-}
    justOnes = do { rec { xs <- Just (1:xs) }
                  ; return (map negate xs) }

As you can guess ``justOnes`` will evaluate to ``Just [-1,-1,-1,...``.

GHC's implementation the mdo-notation closely follows the original
translation as described in the paper `A recursive do for
Haskell <http://leventerkok.github.io/papers/recdo.pdf>`__, which
in turn is based on the work `Value Recursion in Monadic
Computations <http://leventerkok.github.io/papers/erkok-thesis.pdf>`__.
Furthermore, GHC extends the syntax described in the former paper with a
lower level syntax flagged by the ``rec`` keyword, as we describe next.

Recursive binding groups
~~~~~~~~~~~~~~~~~~~~~~~~

The extension :extension:`RecursiveDo` also introduces a new keyword ``rec``, which
wraps a mutually-recursive group of monadic statements inside a ``do``
expression, producing a single statement. Similar to a ``let`` statement
inside a ``do``, variables bound in the ``rec`` are visible throughout
the ``rec`` group, and below it. For example, compare

::

        do { a <- getChar            do { a <- getChar
           ; let { r1 = f a r2          ; rec { r1 <- f a r2
           ;     ; r2 = g r1 }          ;     ; r2 <- g r1 }
           ; return (r1 ++ r2) }        ; return (r1 ++ r2) }

In both cases, ``r1`` and ``r2`` are available both throughout the
``let`` or ``rec`` block, and in the statements that follow it. The
difference is that ``let`` is non-monadic, while ``rec`` is monadic. (In
Haskell ``let`` is really ``letrec``, of course.)

The semantics of ``rec`` is fairly straightforward. Whenever GHC finds a
``rec`` group, it will compute its set of bound variables, and will
introduce an appropriate call to the underlying monadic value-recursion
operator ``mfix``, belonging to the ``MonadFix`` class. Here is an
example:

::

    rec { b <- f a c     ===>    (b,c) <- mfix (\ ~(b,c) -> do { b <- f a c
        ; c <- f b a }                                         ; c <- f b a
                                                               ; return (b,c) })

As usual, the meta-variables ``b``, ``c`` etc., can be arbitrary
patterns. In general, the statement ``rec ss`` is desugared to the
statement

::

    vs <- mfix (\ ~vs -> do { ss; return vs })

where ``vs`` is a tuple of the variables bound by ``ss``.

Note in particular that the translation for a ``rec`` block only
involves wrapping a call to ``mfix``: it performs no other analysis on
the bindings. The latter is the task for the ``mdo`` notation, which is
described next.

The ``mdo`` notation
~~~~~~~~~~~~~~~~~~~~

A ``rec``-block tells the compiler where precisely the recursive knot
should be tied. It turns out that the placement of the recursive knots
can be rather delicate: in particular, we would like the knots to be
wrapped around as minimal groups as possible. This process is known as
*segmentation*, and is described in detail in Section 3.2 of `A
recursive do for
Haskell <http://leventerkok.github.io/papers/recdo.pdf>`__.
Segmentation improves polymorphism and reduces the size of the recursive
knot. Most importantly, it avoids unnecessary interference caused by a
fundamental issue with the so-called *right-shrinking* axiom for monadic
recursion. In brief, most monads of interest (IO, strict state, etc.) do
*not* have recursion operators that satisfy this axiom, and thus not
performing segmentation can cause unnecessary interference, changing the
termination behavior of the resulting translation. (Details can be found
in Sections 3.1 and 7.2.2 of `Value Recursion in Monadic
Computations <http://leventerkok.github.io/papers/erkok-thesis.pdf>`__.)

The ``mdo`` notation removes the burden of placing explicit ``rec``
blocks in the code. Unlike an ordinary ``do`` expression, in which
variables bound by statements are only in scope for later statements,
variables bound in an ``mdo`` expression are in scope for all statements
of the expression. The compiler then automatically identifies minimal
mutually recursively dependent segments of statements, treating them as
if the user had wrapped a ``rec`` qualifier around them.

The definition is syntactic:

-  A generator ⟨g⟩ *depends* on a textually following generator ⟨g'⟩, if

   -  ⟨g'⟩ defines a variable that is used by ⟨g⟩, or

   -  ⟨g'⟩ textually appears between ⟨g⟩ and ⟨g''⟩, where ⟨g⟩ depends on
      ⟨g''⟩.

-  A *segment* of a given ``mdo``-expression is a minimal sequence of
   generators such that no generator of the sequence depends on an
   outside generator. As a special case, although it is not a generator,
   the final expression in an ``mdo``-expression is considered to form a
   segment by itself.

Segments in this sense are related to *strongly-connected components*
analysis, with the exception that bindings in a segment cannot be
reordered and must be contiguous.

Here is an example ``mdo``-expression, and its translation to ``rec``
blocks:

::

    mdo { a <- getChar      ===> do { a <- getChar
        ; b <- f a c                ; rec { b <- f a c
        ; c <- f b a                ;     ; c <- f b a }
        ; z <- h a b                ; z <- h a b
        ; d <- g d e                ; rec { d <- g d e
        ; e <- g a z                ;     ; e <- g a z }
        ; putChar c }               ; putChar c }

Note that a given ``mdo`` expression can cause the creation of multiple
``rec`` blocks. If there are no recursive dependencies, ``mdo`` will
introduce no ``rec`` blocks. In this latter case an ``mdo`` expression
is precisely the same as a ``do`` expression, as one would expect.

In summary, given an ``mdo`` expression, GHC first performs
segmentation, introducing ``rec`` blocks to wrap over minimal recursive
groups. Then, each resulting ``rec`` is desugared, using a call to
``Control.Monad.Fix.mfix`` as described in the previous section. The
original ``mdo``-expression typechecks exactly when the desugared
version would do so.

Here are some other important points in using the recursive-do notation:

-  It is enabled with the extension :extension:`RecursiveDo`, or the
   ``LANGUAGE RecursiveDo`` pragma. (The same extension enables both
   ``mdo``-notation, and the use of ``rec`` blocks inside ``do``
   expressions.)

-  ``rec`` blocks can also be used inside ``mdo``-expressions, which
   will be treated as a single statement. However, it is good style to
   either use ``mdo`` or ``rec`` blocks in a single expression.

-  If recursive bindings are required for a monad, then that monad must
   be declared an instance of the ``MonadFix`` class.

-  The following instances of ``MonadFix`` are automatically provided:
   List, Maybe, IO. Furthermore, the ``Control.Monad.ST`` and
   ``Control.Monad.ST.Lazy`` modules provide the instances of the
   ``MonadFix`` class for Haskell's internal state monad (strict and
   lazy, respectively).

-  Like ``let`` and ``where`` bindings, name shadowing is not allowed
   within an ``mdo``-expression or a ``rec``-block; that is, all the
   names bound in a single ``rec`` must be distinct. (GHC will complain
   if this is not the case.)

.. _applicative-do:

Applicative do-notation
-----------------------

.. index::
   single: Applicative do-notation
   single: do-notation; Applicative

.. extension:: ApplicativeDo
    :shortdesc: Enable Applicative do-notation desugaring

    :since: 8.0.1

    Allow use of ``Applicative`` ``do`` notation.

The language option :extension:`ApplicativeDo` enables an alternative translation for
the do-notation, which uses the operators ``<$>``, ``<*>``, along with ``join``
as far as possible. There are two main reasons for wanting to do this:

-  We can use do-notation with types that are an instance of ``Applicative`` and
   ``Functor``, but not ``Monad``
-  In some monads, using the applicative operators is more efficient than monadic
   bind. For example, it may enable more parallelism.

Applicative do-notation desugaring preserves the original semantics, provided
that the ``Applicative`` instance satisfies ``<*> = ap`` and ``pure = return``
(these are true of all the common monadic types). Thus, you can normally turn on
:extension:`ApplicativeDo` without fear of breaking your program. There is one pitfall
to watch out for; see :ref:`applicative-do-pitfall`.

There are no syntactic changes with :extension:`ApplicativeDo`. The only way it shows
up at the source level is that you can have a ``do`` expression that doesn't
require a ``Monad`` constraint. For example, in GHCi: ::

    Prelude> :set -XApplicativeDo
    Prelude> :t \m -> do { x <- m; return (not x) }
    \m -> do { x <- m; return (not x) }
      :: Functor f => f Bool -> f Bool

This example only requires ``Functor``, because it is translated into ``(\x ->
not x) <$> m``. A more complex example requires ``Applicative``, ::

    Prelude> :t \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) }
    \m -> do { x <- m 'a'; y <- m 'b'; return (x || y) }
      :: Applicative f => (Char -> f Bool) -> f Bool

Here GHC has translated the expression into ::

    (\x y -> x || y) <$> m 'a' <*> m 'b'

It is possible to see the actual translation by using :ghc-flag:`-ddump-ds`, but be
warned, the output is quite verbose.

Note that if the expression can't be translated into uses of ``<$>``, ``<*>``
only, then it will incur a ``Monad`` constraint as usual. This happens when
there is a dependency on a value produced by an earlier statement in the
``do``-block: ::

    Prelude> :t \m -> do { x <- m True; y <- m x; return (x || y) }
    \m -> do { x <- m True; y <- m x; return (x || y) }
      :: Monad m => (Bool -> m Bool) -> m Bool

Here, ``m x`` depends on the value of ``x`` produced by the first statement, so
the expression cannot be translated using ``<*>``.

In general, the rule for when a ``do`` statement incurs a ``Monad`` constraint
is as follows. If the do-expression has the following form: ::

    do p1 <- E1; ...; pn <- En; return E

where none of the variables defined by ``p1...pn`` are mentioned in ``E1...En``,
and ``p1...pn`` are all variables or lazy patterns,
then the expression will only require ``Applicative``. Otherwise, the expression
will require ``Monad``. The block may return a pure expression ``E`` depending
upon the results ``p1...pn`` with either ``return`` or ``pure``.

Note: the final statement must match one of these patterns exactly:

- ``return E``
- ``return $ E``
- ``pure E``
- ``pure $ E``

otherwise GHC cannot recognise it as a ``return`` statement, and the
transformation to use ``<$>`` that we saw above does not apply.  In
particular, slight variations such as ``return . Just $ x`` or ``let x
= e in return x`` would not be recognised.

If the final statement is not of one of these forms, GHC falls back to
standard ``do`` desugaring, and the expression will require a
``Monad`` constraint.

When the statements of a ``do`` expression have dependencies between
them, and ``ApplicativeDo`` cannot infer an ``Applicative`` type, it
uses a heuristic algorithm to try to use ``<*>`` as much as possible.
This algorithm usually finds the best solution, but in rare complex
cases it might miss an opportunity.  There is an algorithm that finds
the optimal solution, provided as an option:

.. ghc-flag:: -foptimal-applicative-do
    :shortdesc: Use a slower but better algorithm for ApplicativeDo
    :type: dynamic
    :reverse: -fno-optimal-applicative-do
    :category: optimization

    :since: 8.0.1

    Enables an alternative algorithm for choosing where to use ``<*>``
    in conjunction with the ``ApplicativeDo`` language extension.
    This algorithm always finds the optimal solution, but it is
    expensive: ``O(n^3)``, so this option can lead to long compile
    times when there are very large ``do`` expressions (over 100
    statements).  The default ``ApplicativeDo`` algorithm is ``O(n^2)``.


.. _applicative-do-strict:

Strict patterns
~~~~~~~~~~~~~~~


A strict pattern match in a bind statement prevents
``ApplicativeDo`` from transforming that statement to use
``Applicative``.  This is because the transformation would change the
semantics by making the expression lazier.

For example, this code will require a ``Monad`` constraint::

    > :t \m -> do { (x:xs) <- m; return x }
    \m -> do { (x:xs) <- m; return x } :: Monad m => m [b] -> m b

but making the pattern match lazy allows it to have a ``Functor`` constraint::

    > :t \m -> do { ~(x:xs) <- m; return x }
    \m -> do { ~(x:xs) <- m; return x } :: Functor f => f [b] -> f b

A "strict pattern match" is any pattern match that can fail.  For
example, ``()``, ``(x:xs)``, ``!z``, and ``C x`` are strict patterns,
but ``x`` and ``~(1,2)`` are not.  For the purposes of
``ApplicativeDo``, a pattern match against a ``newtype`` constructor
is considered strict.

When there's a strict pattern match in a sequence of statements,
``ApplicativeDo`` places a ``>>=`` between that statement and the one
that follows it.  The sequence may be transformed to use ``<*>``
elsewhere, but the strict pattern match and the following statement
will always be connected with ``>>=``, to retain the same strictness
semantics as the standard do-notation.  If you don't want this, simply
put a ``~`` on the pattern match to make it lazy.

.. _applicative-do-pitfall:

Things to watch out for
~~~~~~~~~~~~~~~~~~~~~~~

Your code should just work as before when :extension:`ApplicativeDo` is enabled,
provided you use conventional ``Applicative`` instances. However, if you define
a ``Functor`` or ``Applicative`` instance using do-notation, then it will likely
get turned into an infinite loop by GHC. For example, if you do this: ::

    instance Functor MyType where
        fmap f m = do x <- m; return (f x)

Then applicative desugaring will turn it into ::

    instance Functor MyType where
        fmap f m = fmap (\x -> f x) m

And the program will loop at runtime. Similarly, an ``Applicative`` instance
like this ::

    instance Applicative MyType where
        pure = return
        x <*> y = do f <- x; a <- y; return (f a)

will result in an infinte loop when ``<*>`` is called.

Just as you wouldn't define a ``Monad`` instance using the do-notation, you
shouldn't define ``Functor`` or ``Applicative`` instance using do-notation (when
using ``ApplicativeDo``) either. The correct way to define these instances in
terms of ``Monad`` is to use the ``Monad`` operations directly, e.g. ::

    instance Functor MyType where
        fmap f m = m >>= return . f

    instance Applicative MyType where
        pure = return
        (<*>) = ap


.. _parallel-list-comprehensions:

Parallel List Comprehensions
----------------------------

.. index::
   single: list comprehensions; parallel
   single: parallel list comprehensions

.. extension:: ParallelListComp
    :shortdesc: Enable parallel list comprehensions.

    :since: 6.8.1

    Allow parallel list comprehension syntax.

Parallel list comprehensions are a natural extension to list
comprehensions. List comprehensions can be thought of as a nice syntax
for writing maps and filters. Parallel comprehensions extend this to
include the ``zipWith`` family.

A parallel list comprehension has multiple independent branches of
qualifier lists, each separated by a ``|`` symbol. For example, the
following zips together two lists: ::

       [ (x, y) | x <- xs | y <- ys ]

The behaviour of parallel list comprehensions follows that of zip, in
that the resulting list will have the same length as the shortest
branch.

We can define parallel list comprehensions by translation to regular
comprehensions. Here's the basic idea:

Given a parallel comprehension of the form: ::

       [ e | p1 <- e11, p2 <- e12, ...
           | q1 <- e21, q2 <- e22, ...
           ...
       ]

This will be translated to: ::

       [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...]
                                             [(q1,q2) | q1 <- e21, q2 <- e22, ...]
                                             ...
       ]

where ``zipN`` is the appropriate zip for the given number of branches.

.. _generalised-list-comprehensions:

Generalised (SQL-like) List Comprehensions
------------------------------------------

.. index::
   single: list comprehensions; generalised
   single: extended list comprehensions
   single: group
   single: SQL

.. extension:: TransformListComp
    :shortdesc: Enable generalised list comprehensions.

    :since: 6.10.1

    Allow use of generalised list (SQL-like) comprehension syntax. This
    introduces the ``group``, ``by``, and ``using`` keywords.

Generalised list comprehensions are a further enhancement to the list
comprehension syntactic sugar to allow operations such as sorting and
grouping which are familiar from SQL. They are fully described in the
paper `Comprehensive comprehensions: comprehensions with "order by" and
"group by" <https://www.microsoft.com/en-us/research/wp-content/uploads/2007/09/list-comp.pdf>`__,
except that the syntax we use differs slightly from the paper.

The extension is enabled with the extension :extension:`TransformListComp`.

Here is an example:

::

    employees = [ ("Simon", "MS", 80)
                , ("Erik", "MS", 100)
                , ("Phil", "Ed", 40)
                , ("Gordon", "Ed", 45)
                , ("Paul", "Yale", 60) ]

    output = [ (the dept, sum salary)
             | (name, dept, salary) <- employees
             , then group by dept using groupWith
             , then sortWith by (sum salary)
             , then take 5 ]

In this example, the list ``output`` would take on the value:

::

    [("Yale", 60), ("Ed", 85), ("MS", 180)]

There are three new keywords: ``group``, ``by``, and ``using``. (The
functions ``sortWith`` and ``groupWith`` are not keywords; they are
ordinary functions that are exported by ``GHC.Exts``.)

There are five new forms of comprehension qualifier, all introduced by
the (existing) keyword ``then``:

-  ::

       then f

   This statement requires that
   f
   have the type
   forall a. [a] -> [a]
   . You can see an example of its use in the motivating example, as
   this form is used to apply
   take 5
   .
-  ::

       then f by e

   This form is similar to the previous one, but allows you to create a
   function which will be passed as the first argument to f. As a
   consequence f must have the type
   ``forall a. (a -> t) -> [a] -> [a]``. As you can see from the type,
   this function lets f "project out" some information from the elements
   of the list it is transforming.

   An example is shown in the opening example, where ``sortWith`` is
   supplied with a function that lets it find out the ``sum salary`` for
   any item in the list comprehension it transforms.

-  ::

       then group by e using f

   This is the most general of the grouping-type statements. In this
   form, f is required to have type
   ``forall a. (a -> t) -> [a] -> [[a]]``. As with the ``then f by e``
   case above, the first argument is a function supplied to f by the
   compiler which lets it compute e on every element of the list being
   transformed. However, unlike the non-grouping case, f additionally
   partitions the list into a number of sublists: this means that at
   every point after this statement, binders occurring before it in the
   comprehension refer to *lists* of possible values, not single values.
   To help understand this, let's look at an example:

   ::

       -- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first
       groupRuns :: Eq b => (a -> b) -> [a] -> [[a]]
       groupRuns f = groupBy (\x y -> f x == f y)

       output = [ (the x, y)
       | x <- ([1..3] ++ [1..2])
       , y <- [4..6]
       , then group by x using groupRuns ]

   This results in the variable ``output`` taking on the value below:

   ::

       [(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])]

   Note that we have used the ``the`` function to change the type of x
   from a list to its original numeric type. The variable y, in
   contrast, is left unchanged from the list form introduced by the
   grouping.

-  ::

       then group using f

   With this form of the group statement, f is required to simply have
   the type ``forall a. [a] -> [[a]]``, which will be used to group up
   the comprehension so far directly. An example of this form is as
   follows:

   ::

       output = [ x
       | y <- [1..5]
       , x <- "hello"
       , then group using inits]

   This will yield a list containing every prefix of the word "hello"
   written out 5 times:

   ::

       ["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...]

.. _monad-comprehensions:

Monad comprehensions
--------------------

.. index::
   single: monad comprehensions

.. extension:: MonadComprehensions
    :shortdesc: Enable monad comprehensions.

    :since: 7.2.1

    Enable list comprehension syntax for arbitrary monads.

Monad comprehensions generalise the list comprehension notation,
including parallel comprehensions (:ref:`parallel-list-comprehensions`)
and transform comprehensions (:ref:`generalised-list-comprehensions`) to
work for any monad.

Monad comprehensions support:

-  Bindings: ::

       [ x + y | x <- Just 1, y <- Just 2 ]

   Bindings are translated with the ``(>>=)`` and ``return`` functions
   to the usual do-notation: ::

       do x <- Just 1
          y <- Just 2
          return (x+y)

-  Guards: ::

       [ x | x <- [1..10], x <= 5 ]

   Guards are translated with the ``guard`` function, which requires a
   ``MonadPlus`` instance: ::

       do x <- [1..10]
          guard (x <= 5)
          return x

-  Transform statements (as with :extension:`TransformListComp`): ::

       [ x+y | x <- [1..10], y <- [1..x], then take 2 ]

   This translates to: ::

       do (x,y) <- take 2 (do x <- [1..10]
                              y <- [1..x]
                              return (x,y))
          return (x+y)

-  Group statements (as with :extension:`TransformListComp`):

   ::

       [ x | x <- [1,1,2,2,3], then group by x using GHC.Exts.groupWith ]
       [ x | x <- [1,1,2,2,3], then group using myGroup ]

-  Parallel statements (as with :extension:`ParallelListComp`):

   ::

       [ (x+y) | x <- [1..10]
               | y <- [11..20]
               ]

   Parallel statements are translated using the ``mzip`` function, which
   requires a ``MonadZip`` instance defined in
   :base-ref:`Control.Monad.Zip.`:

   ::

       do (x,y) <- mzip (do x <- [1..10]
                            return x)
                        (do y <- [11..20]
                            return y)
          return (x+y)

All these features are enabled by default if the :extension:`MonadComprehensions`
extension is enabled. The types and more detailed examples on how to use
comprehensions are explained in the previous chapters
:ref:`generalised-list-comprehensions` and
:ref:`parallel-list-comprehensions`. In general you just have to replace
the type ``[a]`` with the type ``Monad m => m a`` for monad
comprehensions.

.. note::
    Even though most of these examples are using the list monad, monad
    comprehensions work for any monad. The ``base`` package offers all
    necessary instances for lists, which make :extension:`MonadComprehensions`
    backward compatible to built-in, transform and parallel list
    comprehensions.

More formally, the desugaring is as follows. We write ``D[ e | Q]`` to
mean the desugaring of the monad comprehension ``[ e | Q]``:

.. code-block:: none

    Expressions: e
    Declarations: d
    Lists of qualifiers: Q,R,S

    -- Basic forms
    D[ e | ]               = return e
    D[ e | p <- e, Q ]  = e >>= \p -> D[ e | Q ]
    D[ e | e, Q ]          = guard e >> \p -> D[ e | Q ]
    D[ e | let d, Q ]      = let d in D[ e | Q ]

    -- Parallel comprehensions (iterate for multiple parallel branches)
    D[ e | (Q | R), S ]    = mzip D[ Qv | Q ] D[ Rv | R ] >>= \(Qv,Rv) -> D[ e | S ]

    -- Transform comprehensions
    D[ e | Q then f, R ]                  = f D[ Qv | Q ] >>= \Qv -> D[ e | R ]

    D[ e | Q then f by b, R ]             = f (\Qv -> b) D[ Qv | Q ] >>= \Qv -> D[ e | R ]

    D[ e | Q then group using f, R ]      = f D[ Qv | Q ] >>= \ys ->
                                            case (fmap selQv1 ys, ..., fmap selQvn ys) of
                                             Qv -> D[ e | R ]

    D[ e | Q then group by b using f, R ] = f (\Qv -> b) D[ Qv | Q ] >>= \ys ->
                                            case (fmap selQv1 ys, ..., fmap selQvn ys) of
                                               Qv -> D[ e | R ]

    where  Qv is the tuple of variables bound by Q (and used subsequently)
           selQvi is a selector mapping Qv to the ith component of Qv

    Operator     Standard binding       Expected type
    --------------------------------------------------------------------
    return       GHC.Base               t1 -> m t2
    (>>=)        GHC.Base               m1 t1 -> (t2 -> m2 t3) -> m3 t3
    (>>)         GHC.Base               m1 t1 -> m2 t2         -> m3 t3
    guard        Control.Monad          t1 -> m t2
    fmap         GHC.Base               forall a b. (a->b) -> n a -> n b
    mzip         Control.Monad.Zip      forall a b. m a -> m b -> m (a,b)

The comprehension should typecheck when its desugaring would typecheck,
except that (as discussed in :ref:`generalised-list-comprehensions`) in the
"then ``f``" and "then group using ``f``" clauses, when the "by ``b``" qualifier
is omitted, argument ``f`` should have a polymorphic type. In particular, "then
``Data.List.sort``" and "then group using ``Data.List.group``" are
insufficiently polymorphic.

Monad comprehensions support rebindable syntax
(:ref:`rebindable-syntax`). Without rebindable syntax, the operators
from the "standard binding" module are used; with rebindable syntax, the
operators are looked up in the current lexical scope. For example,
parallel comprehensions will be typechecked and desugared using whatever
"``mzip``" is in scope.

The rebindable operators must have the "Expected type" given in the
table above. These types are surprisingly general. For example, you can
use a bind operator with the type

::

    (>>=) :: T x y a -> (a -> T y z b) -> T x z b

In the case of transform comprehensions, notice that the groups are
parameterised over some arbitrary type ``n`` (provided it has an
``fmap``, as well as the comprehension being over an arbitrary monad.

.. _monadfail-desugaring:

New monadic failure desugaring mechanism
----------------------------------------

.. extension:: MonadFailDesugaring
    :shortdesc: Enable monadfail desugaring.

    :since: 8.0.1

    Use the ``MonadFail.fail`` instead of the legacy ``Monad.fail`` function
    when desugaring refutable patterns in ``do`` blocks.

The ``-XMonadFailDesugaring`` extension switches the desugaring of
``do``-blocks to use ``MonadFail.fail`` instead of ``Monad.fail``.

This extension is enabled by default since GHC 8.6.1, under the
`MonadFail Proposal (MFP)
<https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.

This extension is temporary, and will be deprecated in a future release.

.. _rebindable-syntax:

Rebindable syntax and the implicit Prelude import
-------------------------------------------------

.. extension:: NoImplicitPrelude
    :shortdesc: Don't implicitly ``import Prelude``.
        Implied by :extension:`RebindableSyntax`.

    :since: 6.8.1

    Don't import ``Prelude`` by default.

GHC normally imports ``Prelude.hi`` files for
you. If you'd rather it didn't, then give it a ``-XNoImplicitPrelude``
option. The idea is that you can then import a Prelude of your own. (But
don't call it ``Prelude``; the Haskell module namespace is flat, and you
must not conflict with any Prelude module.)

.. extension:: RebindableSyntax
    :shortdesc: Employ rebindable syntax.
        Implies :extension:`NoImplicitPrelude`.

    :implies: :extension:`NoImplicitPrelude`
    :since: 7.0.1

    Enable rebinding of a variety of usually-built-in operations.

Suppose you are importing a Prelude of your own in order to define your
own numeric class hierarchy. It completely defeats that purpose if the
literal "1" means "``Prelude.fromInteger 1``", which is what the Haskell
Report specifies. So the :extension:`RebindableSyntax` extension causes the
following pieces of built-in syntax to refer to *whatever is in scope*,
not the Prelude versions:

-  An integer literal ``368`` means "``fromInteger (368::Integer)``",
   rather than "``Prelude.fromInteger (368::Integer)``".

-  Fractional literals are handled in just the same way, except that the
   translation is ``fromRational (3.68::Rational)``.

-  String literals are also handled the same way, except that the
   translation is ``fromString ("368"::String)``.

-  The equality test in an overloaded numeric pattern uses whatever
   ``(==)`` is in scope.

-  The subtraction operation, and the greater-than-or-equal test, in
   ``n+k`` patterns use whatever ``(-)`` and ``(>=)`` are in scope.

-  Negation (e.g. "``- (f x)``") means "``negate (f x)``", both in
   numeric patterns, and expressions.

-  Conditionals (e.g. "``if`` e1 ``then`` e2 ``else`` e3") means
   "``ifThenElse`` e1 e2 e3". However ``case`` expressions are
   unaffected.

-  "Do" notation is translated using whatever functions ``(>>=)``,
   ``(>>)``, and ``fail``, are in scope (not the Prelude versions). List
   comprehensions, ``mdo`` (:ref:`recursive-do-notation`), and parallel
   array comprehensions, are unaffected.

-  Arrow notation (see :ref:`arrow-notation`) uses whatever ``arr``,
   ``(>>>)``, ``first``, ``app``, ``(|||)`` and ``loop`` functions are
   in scope. But unlike the other constructs, the types of these
   functions must match the Prelude types very closely. Details are in
   flux; if you want to use this, ask!

-  List notation, such as ``[x,y]`` or ``[m..n]`` can also be treated
   via rebindable syntax if you use `-XOverloadedLists`;
   see :ref:`overloaded-lists`.

-  An overloaded label "``#foo``" means "``fromLabel @"foo"``", rather than
   "``GHC.OverloadedLabels.fromLabel @"foo"``" (see :ref:`overloaded-labels`).

:extension:`RebindableSyntax` implies :extension:`NoImplicitPrelude`.

In all cases (apart from arrow notation), the static semantics should be
that of the desugared form, even if that is a little unexpected. For
example, the static semantics of the literal ``368`` is exactly that of
``fromInteger (368::Integer)``; it's fine for ``fromInteger`` to have
any of the types: ::

    fromInteger :: Integer -> Integer
    fromInteger :: forall a. Foo a => Integer -> a
    fromInteger :: Num a => a -> Integer
    fromInteger :: Integer -> Bool -> Bool

Be warned: this is an experimental facility, with fewer checks than
usual. Use ``-dcore-lint`` to typecheck the desugared program. If Core
Lint is happy you should be all right.

Things unaffected by :extension:`RebindableSyntax`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:extension:`RebindableSyntax` does not apply to any code generated from a
``deriving`` clause or declaration. To see why, consider the following code: ::

    {-# LANGUAGE RebindableSyntax, OverloadedStrings #-}
    newtype Text = Text String

    fromString :: String -> Text
    fromString = Text

    data Foo = Foo deriving Show

This will generate code to the effect of: ::

    instance Show Foo where
      showsPrec _ Foo = showString "Foo"

But because :extension:`RebindableSyntax` and :extension:`OverloadedStrings`
are enabled, the ``"Foo"`` string literal would now be of type ``Text``, not
``String``, which ``showString`` doesn't accept! This causes the generated
``Show`` instance to fail to typecheck. It's hard to imagine any scenario where
it would be desirable have :extension:`RebindableSyntax` behavior within
derived code, so GHC simply ignores :extension:`RebindableSyntax` entirely
when checking derived code.

.. _postfix-operators:

Postfix operators
-----------------

.. extension:: PostfixOperators
    :shortdesc: Enable postfix operators.

    :since: 7.10.1

    Allow the use of post-fix operators

The :extension:`PostfixOperators` extension enables a small extension to the syntax
of left operator sections, which allows you to define postfix operators.
The extension is this: the left section ::

      (e !)

is equivalent (from the point of view of both type checking and
execution) to the expression ::

      ((!) e)

(for any expression ``e`` and operator ``(!)``. The strict Haskell 98
interpretation is that the section is equivalent to ::

      (\y -> (!) e y)

That is, the operator must be a function of two arguments. GHC allows it
to take only one argument, and that in turn allows you to write the
function postfix.

The extension does not extend to the left-hand side of function
definitions; you must define such a function in prefix form.

.. _tuple-sections:

Tuple sections
--------------

.. extension:: TupleSections
    :shortdesc: Enable tuple sections.

    :since: 6.12

    Allow the use of tuple section syntax

The :extension:`TupleSections` extension enables partially applied
tuple constructors. For example, the following program ::

      (, True)

is considered to be an alternative notation for the more unwieldy
alternative ::

      \x -> (x, True)

You can omit any combination of arguments to the tuple, as in the
following ::

      (, "I", , , "Love", , 1337)

which translates to ::

      \a b c d -> (a, "I", b, c, "Love", d, 1337)

If you have `unboxed tuples <#unboxed-tuples>`__ enabled, tuple sections
will also be available for them, like so ::

      (# , True #)

Because there is no unboxed unit tuple, the following expression ::

      (# #)

continues to stand for the unboxed singleton tuple data constructor.

.. _lambda-case:

Lambda-case
-----------

.. extension:: LambdaCase
    :shortdesc: Enable lambda-case expressions.

    :since: 7.6.1

    Allow the use of lambda-case syntax.

The :extension:`LambdaCase` extension enables expressions of the form ::

      \case { p1 -> e1; ...; pN -> eN }

which is equivalent to ::

      \freshName -> case freshName of { p1 -> e1; ...; pN -> eN }

Note that ``\case`` starts a layout, so you can write ::

      \case
        p1 -> e1
        ...
        pN -> eN

.. _empty-case:

Empty case alternatives
-----------------------

.. extension:: EmptyCase
    :shortdesc: Allow empty case alternatives.

    :since: 7.8.1

    Allow empty case expressions.

The :extension:`EmptyCase` extension enables case expressions, or lambda-case
expressions, that have no alternatives, thus: ::

    case e of { }   -- No alternatives

or ::

    \case { }       -- -XLambdaCase is also required

This can be useful when you know that the expression being scrutinised
has no non-bottom values. For example:

::

      data Void
      f :: Void -> Int
      f x = case x of { }

With dependently-typed features it is more useful (see :ghc-ticket:`2431`). For
example, consider these two candidate definitions of ``absurd``:

::

    data a :~: b where
      Refl :: a :~: a

    absurd :: True :~: False -> a
    absurd x = error "absurd"    -- (A)
    absurd x = case x of {}      -- (B)

We much prefer (B). Why? Because GHC can figure out that
``(True :~: False)`` is an empty type. So (B) has no partiality and GHC
is able to compile with :ghc-flag:`-Wincomplete-patterns` and
:ghc-flag:`-Werror`. On the other hand (A) looks dangerous, and GHC doesn't
check to make sure that, in fact, the function can never get called.

.. _multi-way-if:

Multi-way if-expressions
------------------------

.. extension:: MultiWayIf
    :shortdesc: Enable multi-way if-expressions.

    :since: 7.6.1

    Allow the use of multi-way-``if`` syntax.

With :extension:`MultiWayIf` extension GHC accepts conditional expressions with
multiple branches: ::

      if | guard1 -> expr1
         | ...
         | guardN -> exprN

which is roughly equivalent to ::

      case () of
        _ | guard1 -> expr1
        ...
        _ | guardN -> exprN

Multi-way if expressions introduce a new layout context. So the example
above is equivalent to: ::

      if { | guard1 -> expr1
         ; | ...
         ; | guardN -> exprN
         }

The following behaves as expected: ::

      if | guard1 -> if | guard2 -> expr2
                        | guard3 -> expr3
         | guard4 -> expr4

because layout translates it as ::

      if { | guard1 -> if { | guard2 -> expr2
                          ; | guard3 -> expr3
                          }
         ; | guard4 -> expr4
         }

Layout with multi-way if works in the same way as other layout contexts,
except that the semi-colons between guards in a multi-way if are
optional. So it is not necessary to line up all the guards at the same
column; this is consistent with the way guards work in function
definitions and case expressions.

.. _local-fixity-declarations:

Local Fixity Declarations
-------------------------

A careful reading of the Haskell 98 Report reveals that fixity
declarations (``infix``, ``infixl``, and ``infixr``) are permitted to
appear inside local bindings such those introduced by ``let`` and
``where``. However, the Haskell Report does not specify the semantics of
such bindings very precisely.

In GHC, a fixity declaration may accompany a local binding: ::

    let f = ...
        infixr 3 `f`
    in
        ...

and the fixity declaration applies wherever the binding is in scope. For
example, in a ``let``, it applies in the right-hand sides of other
``let``-bindings and the body of the ``let``\ C. Or, in recursive ``do``
expressions (:ref:`recursive-do-notation`), the local fixity
declarations of a ``let`` statement scope over other statements in the
group, just as the bound name does.

Moreover, a local fixity declaration *must* accompany a local binding
of that name: it is not possible to revise the fixity of name bound
elsewhere, as in ::

    let infixr 9 $ in ...

Because local fixity declarations are technically Haskell 98, no extension is
necessary to enable them.

.. _package-imports:

Import and export extensions
----------------------------

Hiding things the imported module doesn't export
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Technically in Haskell 2010 this is illegal: ::

    module A( f ) where
      f = True

    module B where
      import A hiding( g )  -- A does not export g
      g = f

The ``import A hiding( g )`` in module ``B`` is technically an error
(`Haskell Report,
5.3.1 <http://www.haskell.org/onlinereport/haskell2010/haskellch5.html#x11-1020005.3.1>`__)
because ``A`` does not export ``g``. However GHC allows it, in the
interests of supporting backward compatibility; for example, a newer
version of ``A`` might export ``g``, and you want ``B`` to work in
either case.

The warning :ghc-flag:`-Wdodgy-imports`, which is off by default but included
with :ghc-flag:`-W`, warns if you hide something that the imported module does
not export.

.. _package-qualified-imports:

Package-qualified imports
~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: PackageImports
    :shortdesc: Enable package-qualified imports.

    :since: 6.10.1

    Allow the use of package-qualified ``import`` syntax.

With the :extension:`PackageImports` extension, GHC allows import declarations to be
qualified by the package name that the module is intended to be imported
from. For example: ::

    import "network" Network.Socket

would import the module ``Network.Socket`` from the package ``network``
(any version). This may be used to disambiguate an import when the same
module is available from multiple packages, or is present in both the
current package being built and an external package.

The special package name ``this`` can be used to refer to the current
package being built.

.. note::
   You probably don't need to use this feature, it was added mainly so that we
   can build backwards-compatible versions of packages when APIs change. It can
   lead to fragile dependencies in the common case: modules occasionally move
   from one package to another, rendering any package-qualified imports broken.
   See also :ref:`package-thinning-and-renaming` for an alternative way of
   disambiguating between module names.

.. _safe-imports-ext:

Safe imports
~~~~~~~~~~~~

.. extension:: Safe
    :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Safe mode.
    :noindex:

    :since: 7.2.1

    Declare the Safe Haskell state of the current module.

.. extension:: Trustworthy
    :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Trustworthy mode.
    :noindex:

    :since: 7.2.1

    Declare the Safe Haskell state of the current module.

.. extension:: Unsafe
    :shortdesc: Enable Safe Haskell Unsafe mode.
    :noindex:

    :since: 7.4.1

    Declare the Safe Haskell state of the current module.

With the :extension:`Safe`, :extension:`Trustworthy` and :extension:`Unsafe`
language flags, GHC extends the import declaration syntax to take an optional
``safe`` keyword after the ``import`` keyword. This feature is part of the Safe
Haskell GHC extension. For example: ::

    import safe qualified Network.Socket as NS

would import the module ``Network.Socket`` with compilation only
succeeding if ``Network.Socket`` can be safely imported. For a description of
when a import is considered safe see :ref:`safe-haskell`.

.. _explicit-namespaces:

Explicit namespaces in import/export
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: ExplicitNamespaces
    :shortdesc: Enable using the keyword ``type`` to specify the namespace of
        entries in imports and exports (:ref:`explicit-namespaces`).
        Implied by :extension:`TypeOperators` and :extension:`TypeFamilies`.

    :since: 7.6.1

    Enable use of explicit namespaces in module export lists.

In an import or export list, such as ::

      module M( f, (++) ) where ...
        import N( f, (++) )
        ...

the entities ``f`` and ``(++)`` are *values*. However, with type
operators (:ref:`type-operators`) it becomes possible to declare
``(++)`` as a *type constructor*. In that case, how would you export or
import it?

The :extension:`ExplicitNamespaces` extension allows you to prefix the name of
a type constructor in an import or export list with "``type``" to
disambiguate this case, thus: ::

      module M( f, type (++) ) where ...
        import N( f, type (++) )
        ...
      module N( f, type (++) ) where
        data family a ++ b = L a | R b

The extension :extension:`ExplicitNamespaces` is implied by
:extension:`TypeOperators` and (for some reason) by :extension:`TypeFamilies`.

In addition, with :extension:`PatternSynonyms` you can prefix the name of a
data constructor in an import or export list with the keyword
``pattern``, to allow the import or export of a data constructor without
its parent type constructor (see :ref:`patsyn-impexp`).

.. _importqualifiedpost:

Writing qualified in postpositive position
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: ImportQualifiedPost
    :shortdesc: ``ImportQualifiedPost`` allows the syntax ``import M qualified``

    :since: 8.10.1

    ``ImportQualifiedPost`` allows the syntax ``import M qualified``, that is, to annotate a module as qualified by writing ``qualified`` after the module name.

To import a qualified module usually you must specify ``qualified`` in prepositive position : ``import qualified M``. This often leads to a "hanging indent" (which is automatically inserted by some autoformatters and common in many code bases. For example:

.. code-block::  none

 import qualified A
 import           B
 import           C

The ``ImportQualifiedPost`` extension allows ``qualified`` to appear in postpositive position : ``import M qualified``. With this extension enabled, one can write:

.. code-block:: none

   import A qualified
   import B
   import C

It is an error if ``qualified`` appears in both pre and postpositive positions.

The warning ``-Wprepositive-qualified-syntax`` (off by default) reports on any occurrences of imports annotated ``qualified`` using prepositive syntax.

.. _block-arguments:

More liberal syntax for function arguments
------------------------------------------

.. extension:: BlockArguments
    :shortdesc: Allow ``do`` blocks and other constructs as function arguments.

    :since: 8.6.1

    Allow ``do`` expressions, lambda expressions, etc. to be directly used as
    a function argument.

In Haskell 2010, certain kinds of expressions can be used without parentheses
as an argument to an operator, but not as an argument to a function.
They include ``do``, lambda, ``if``, ``case``, and ``let``
expressions. Some GHC extensions also define language constructs of this type:
``mdo`` (:ref:`recursive-do-notation`), ``\case`` (:ref:`lambda-case`), and
``proc`` (:ref:`arrow-notation`).

The :extension:`BlockArguments` extension allows these constructs to be directly
used as a function argument. For example::

    when (x > 0) do
      print x
      exitFailure

will be parsed as::

    when (x > 0) (do
      print x
      exitFailure)

and

::

    withForeignPtr fptr \ptr -> c_memcpy buf ptr size

will be parsed as::

    withForeignPtr fptr (\ptr -> c_memcpy buf ptr size)

Changes to the grammar
~~~~~~~~~~~~~~~~~~~~~~

The Haskell report `defines
<https://www.haskell.org/onlinereport/haskell2010/haskellch3.html#x8-220003>`_
the ``lexp`` nonterminal thus (``*`` indicates a rule of interest)::

    lexp  →  \ apat1 … apatn -> exp            (lambda abstraction, n ≥ 1)  *
          |  let decls in exp                  (let expression)             *
          |  if exp [;] then exp [;] else exp  (conditional)                *
          |  case exp of { alts }              (case expression)            *
          |  do { stmts }                      (do expression)              *
          |  fexp

    fexp  →  [fexp] aexp                       (function application)

    aexp  →  qvar                              (variable)
          |  gcon                              (general constructor)
          |  literal
          |  ( exp )                           (parenthesized expression)
          |  qcon { fbind1 … fbindn }          (labeled construction)
          |  aexp { fbind1 … fbindn }          (labelled update)
          |  …

The :extension:`BlockArguments` extension moves these production rules under
``aexp``::

    lexp  →  fexp

    fexp  →  [fexp] aexp                       (function application)

    aexp  →  qvar                              (variable)
          |  gcon                              (general constructor)
          |  literal
          |  ( exp )                           (parenthesized expression)
          |  qcon { fbind1 … fbindn }          (labeled construction)
          |  aexp { fbind1 … fbindn }          (labelled update)
          |  \ apat1 … apatn -> exp            (lambda abstraction, n ≥ 1)  *
          |  let decls in exp                  (let expression)             *
          |  if exp [;] then exp [;] else exp  (conditional)                *
          |  case exp of { alts }              (case expression)            *
          |  do { stmts }                      (do expression)              *
          |  …

Now the ``lexp`` nonterminal is redundant and can be dropped from the grammar.

Note that this change relies on an existing meta-rule to resolve ambiguities:

    The grammar is ambiguous regarding the extent of lambda abstractions, let
    expressions, and conditionals. The ambiguity is resolved by the meta-rule
    that each of these constructs extends as far to the right as possible.

For example, ``f \a -> a b`` will be parsed as ``f (\a -> a b)``, not as ``f
(\a -> a) b``.

.. _syntax-stolen:

Summary of stolen syntax
------------------------

Turning on an option that enables special syntax *might* cause working
Haskell 98 code to fail to compile, perhaps because it uses a variable
name which has become a reserved word. This section lists the syntax
that is "stolen" by language extensions. We use notation and nonterminal
names from the Haskell 98 lexical syntax (see the Haskell 98 Report). We
only list syntax changes here that might affect existing working
programs (i.e. "stolen" syntax). Many of these extensions will also
enable new context-free syntax, but in all cases programs written to use
the new syntax would not be compilable without the option enabled.

There are two classes of special syntax:

-  New reserved words and symbols: character sequences which are no
   longer available for use as identifiers in the program.

-  Other special syntax: sequences of characters that have a different
   meaning when this particular option is turned on.

The following syntax is stolen:

``forall``
    .. index::
       single: forall

    Stolen (in types) by default (see :ref:`infelicities-lexical`). ``forall`` is
    a reserved keyword and never a type variable, in accordance with `GHC Proposal #43
    <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0043-forall-keyword.rst>`__.


``mdo``
    .. index::
       single: mdo

    Stolen by: :extension:`RecursiveDo`

``foreign``
    .. index::
       single: foreign

    Stolen by: :extension:`ForeignFunctionInterface`

``rec``, ``proc``, ``-<``, ``>-``, ``-<<``, ``>>-``, ``(|``, ``|)``
    .. index::
       single: proc

    Stolen by: :extension:`Arrows`

``?varid``
    .. index::
       single: implicit parameters

    Stolen by: :extension:`ImplicitParams`

``[|``, ``[e|``, ``[p|``, ``[d|``, ``[t|``, ``[||``, ``[e||``
    .. index::
       single: Quasi-quotes

    Stolen by: :extension:`QuasiQuotes`. Moreover, this introduces an ambiguity
    with list comprehension syntax. See the
    :ref:`discussion on quasi-quoting <quasi-quotes-list-comprehension-ambiguity>`
    for details.

``$(``, ``$$(``, ``$varid``, ``$$varid``
    .. index::
       single: Template Haskell

    Stolen by: :extension:`TemplateHaskell`

``[varid|``
    .. index::
       single: quasi-quotation

    Stolen by: :extension:`QuasiQuotes`

⟨varid⟩, ``#``\ ⟨char⟩, ``#``, ⟨string⟩, ``#``, ⟨integer⟩, ``#``, ⟨float⟩, ``#``, ⟨float⟩, ``##``
    Stolen by: :extension:`MagicHash`

``(#``, ``#)``
    Stolen by: :extension:`UnboxedTuples`

⟨varid⟩, ``!``, ⟨varid⟩
    Stolen by: :extension:`BangPatterns`

``pattern``
    Stolen by: :extension:`PatternSynonyms`

``static``
    Stolen by: :extension:`StaticPointers`

.. _data-type-extensions:

Extensions to data types and type synonyms
==========================================

.. _nullary-types:

Data types with no constructors
-------------------------------

.. extension:: EmptyDataDecls
    :shortdesc: Allow definition of empty ``data`` types.

    :since: 6.8.1

    Allow definition of empty ``data`` types.

With the :extension:`EmptyDataDecls` extension, GHC lets you declare a
data type with no constructors.

You only need to enable this extension if the language you're using
is Haskell 98, in which a data type must have at least one constructor.
Haskell 2010 relaxed this rule to allow data types with no constructors,
and thus :extension:`EmptyDataDecls` is enabled by default when the
language is Haskell 2010.

For example: ::

      data S      -- S :: Type
      data T a    -- T :: Type -> Type

Syntactically, the declaration lacks the "= constrs" part. The type can be
parameterised over types of any kind, but if the kind is not ``Type`` then an
explicit kind annotation must be used (see :ref:`kinding`).

Such data types have only one value, namely bottom. Nevertheless, they
can be useful when defining "phantom types".

In conjunction with the :ghc-flag:`-XEmptyDataDeriving` extension, empty data
declarations can also derive instances of standard type classes
(see :ref:`empty-data-deriving`).

.. _datatype-contexts:

Data type contexts
------------------

.. extension:: DatatypeContexts
    :shortdesc: Allow contexts on ``data`` types.

    :since: 7.0.1

    Allow contexts on ``data`` types.

Haskell allows datatypes to be given contexts, e.g. ::

    data Eq a => Set a = NilSet | ConsSet a (Set a)

give constructors with types: ::

    NilSet :: Set a
    ConsSet :: Eq a => a -> Set a -> Set a

This is widely considered a misfeature, and is going to be removed from
the language. In GHC, it is controlled by the deprecated extension
``DatatypeContexts``.

.. _infix-tycons:

Infix type constructors, classes, and type variables
----------------------------------------------------

GHC allows type constructors, classes, and type variables to be
operators, and to be written infix, very much like expressions. More
specifically:

-  A type constructor or class can be any non-reserved operator.
   Symbols used in types are always like capitalized identifiers; they
   are never variables. Note that this is different from the lexical
   syntax of data constructors, which are required to begin with a
   ``:``.

-  Data type and type-synonym declarations can be written infix,
   parenthesised if you want further arguments. E.g. ::

         data a :*: b = Foo a b
         type a :+: b = Either a b
         class a :=: b where ...

         data (a :**: b) x = Baz a b x
         type (a :++: b) y = Either (a,b) y

-  Types, and class constraints, can be written infix. For example ::

         x :: Int :*: Bool
         f :: (a :=: b) => a -> b

-  Back-quotes work as for expressions, both for type constructors and
   type variables; e.g. ``Int `Either` Bool``, or ``Int `a` Bool``.
   Similarly, parentheses work the same; e.g. ``(:*:) Int Bool``.

-  Fixities may be declared for type constructors, or classes, just as
   for data constructors. However, one cannot distinguish between the
   two in a fixity declaration; a fixity declaration sets the fixity for
   a data constructor and the corresponding type constructor. For
   example: ::

         infixl 7 T, :*:

   sets the fixity for both type constructor ``T`` and data constructor
   ``T``, and similarly for ``:*:``. ``Int `a` Bool``.

-  The function arrow ``->`` is ``infixr`` with fixity -1.

.. _type-operators:

Type operators
--------------

.. extension:: TypeOperators
    :shortdesc: Enable type operators.
        Implies :extension:`ExplicitNamespaces`.

    :implies: :extension:`ExplicitNamespaces`
    :since: 6.8.1

    Allow the use and definition of types with operator names.

In types, an operator symbol like ``(+)`` is normally treated as a type
*variable*, just like ``a``. Thus in Haskell 98 you can say

::

    type T (+) = ((+), (+))
    -- Just like: type T a = (a,a)

    f :: T Int -> Int
    f (x,y)= x

As you can see, using operators in this way is not very useful, and
Haskell 98 does not even allow you to write them infix.

The language :extension:`TypeOperators` changes this behaviour:

-  Operator symbols become type *constructors* rather than type
   *variables*.

-  Operator symbols in types can be written infix, both in definitions
   and uses. For example: ::

       data a + b = Plus a b
       type Foo = Int + Bool

-  There is now some potential ambiguity in import and export lists; for
   example if you write ``import M( (+) )`` do you mean the *function*
   ``(+)`` or the *type constructor* ``(+)``? The default is the former,
   but with :extension:`ExplicitNamespaces` (which is implied by
   :extension:`TypeOperators`) GHC allows you to specify the latter by
   preceding it with the keyword ``type``, thus: ::

       import M( type (+) )

   See :ref:`explicit-namespaces`.

-  The fixity of a type operator may be set using the usual fixity
   declarations but, as in :ref:`infix-tycons`, the function and type
   constructor share a single fixity.

.. _type-synonyms:

Liberalised type synonyms
-------------------------

.. extension:: LiberalTypeSynonyms
    :shortdesc: Enable liberalised type synonyms.

    :implies: :extension:`ExplicitForAll`
    :since: 6.8.1

    Relax many of the Haskell 98 rules on type synonym definitions.

Type synonyms are like macros at the type level, but Haskell 98 imposes
many rules on individual synonym declarations. With the
:extension:`LiberalTypeSynonyms` extension, GHC does validity checking on types
*only after expanding type synonyms*. That means that GHC can be very
much more liberal about type synonyms than Haskell 98.

-  You can write a ``forall`` (including overloading) in a type synonym,
   thus: ::

         type Discard a = forall b. Show b => a -> b -> (a, String)

         f :: Discard a
         f x y = (x, show y)

         g :: Discard Int -> (Int,String)    -- A rank-2 type
         g f = f 3 True

-  If you also use :extension:`UnboxedTuples`, you can write an unboxed tuple
   in a type synonym: ::

         type Pr = (# Int, Int #)

         h :: Int -> Pr
         h x = (# x, x #)

-  You can apply a type synonym to a forall type: ::

         type Foo a = a -> a -> Bool

         f :: Foo (forall b. b->b)

   After expanding the synonym, ``f`` has the legal (in GHC) type: ::

         f :: (forall b. b->b) -> (forall b. b->b) -> Bool

-  You can apply a type synonym to a partially applied type synonym: ::

         type Generic i o = forall x. i x -> o x
         type Id x = x

         foo :: Generic Id []

   After expanding the synonym, ``foo`` has the legal (in GHC) type: ::

         foo :: forall x. x -> [x]

GHC currently does kind checking before expanding synonyms (though even
that could be changed).

After expanding type synonyms, GHC does validity checking on types,
looking for the following malformedness which isn't detected simply by
kind checking:

-  Type constructor applied to a type involving for-alls (if
   :extension:`ImpredicativeTypes` is off)

-  Partially-applied type synonym.

So, for example, this will be rejected: ::

      type Pr = forall a. a

      h :: [Pr]
      h = ...

because GHC does not allow type constructors applied to for-all types.

.. _existential-quantification:

Existentially quantified data constructors
------------------------------------------

.. extension:: ExistentialQuantification
    :shortdesc: Enable liberalised type synonyms.

    :implies: :extension:`ExplicitForAll`
    :since: 6.8.1

    Allow existentially quantified type variables in types.

The idea of using existential quantification in data type declarations
was suggested by Perry, and implemented in Hope+ (Nigel Perry, *The
Implementation of Practical Functional Programming Languages*, PhD
Thesis, University of London, 1991). It was later formalised by Laufer
and Odersky (*Polymorphic type inference and abstract data types*,
TOPLAS, 16(5), pp. 1411-1430, 1994). It's been in Lennart Augustsson's
``hbc`` Haskell compiler for several years, and proved very useful.
Here's the idea. Consider the declaration: ::

      data Foo = forall a. MkFoo a (a -> Bool)
               | Nil

The data type ``Foo`` has two constructors with types: ::

      MkFoo :: forall a. a -> (a -> Bool) -> Foo
      Nil   :: Foo

Notice that the type variable ``a`` in the type of ``MkFoo`` does not
appear in the data type itself, which is plain ``Foo``. For example, the
following expression is fine: ::

      [MkFoo 3 even, MkFoo 'c' isUpper] :: [Foo]

Here, ``(MkFoo 3 even)`` packages an integer with a function ``even``
that maps an integer to ``Bool``; and ``MkFoo 'c'
isUpper`` packages a character with a compatible function. These two
things are each of type ``Foo`` and can be put in a list.

What can we do with a value of type ``Foo``? In particular, what
happens when we pattern-match on ``MkFoo``? ::

      f (MkFoo val fn) = ???

Since all we know about ``val`` and ``fn`` is that they are compatible,
the only (useful) thing we can do with them is to apply ``fn`` to
``val`` to get a boolean. For example: ::

      f :: Foo -> Bool
      f (MkFoo val fn) = fn val

What this allows us to do is to package heterogeneous values together
with a bunch of functions that manipulate them, and then treat that
collection of packages in a uniform manner. You can express quite a bit
of object-oriented-like programming this way.

.. _existential:

Why existential?
~~~~~~~~~~~~~~~~

What has this to do with *existential* quantification? Simply that
``MkFoo`` has the (nearly) isomorphic type ::

      MkFoo :: (exists a . (a, a -> Bool)) -> Foo

But Haskell programmers can safely think of the ordinary *universally*
quantified type given above, thereby avoiding adding a new existential
quantification construct.

.. _existential-with-context:

Existentials and type classes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An easy extension is to allow arbitrary contexts before the constructor.
For example: ::

    data Baz = forall a. Eq a => Baz1 a a
             | forall b. Show b => Baz2 b (b -> b)

The two constructors have the types you'd expect: ::

    Baz1 :: forall a. Eq a => a -> a -> Baz
    Baz2 :: forall b. Show b => b -> (b -> b) -> Baz

But when pattern matching on ``Baz1`` the matched values can be compared
for equality, and when pattern matching on ``Baz2`` the first matched
value can be converted to a string (as well as applying the function to
it). So this program is legal: ::

      f :: Baz -> String
      f (Baz1 p q) | p == q    = "Yes"
                   | otherwise = "No"
      f (Baz2 v fn)            = show (fn v)

Operationally, in a dictionary-passing implementation, the constructors
``Baz1`` and ``Baz2`` must store the dictionaries for ``Eq`` and
``Show`` respectively, and extract it on pattern matching.

.. _existential-records:

Record Constructors
~~~~~~~~~~~~~~~~~~~

GHC allows existentials to be used with records syntax as well. For
example: ::

    data Counter a = forall self. NewCounter
        { _this    :: self
        , _inc     :: self -> self
        , _display :: self -> IO ()
        , tag      :: a
        }

Here ``tag`` is a public field, with a well-typed selector function
``tag :: Counter a -> a``. The ``self`` type is hidden from the outside;
any attempt to apply ``_this``, ``_inc`` or ``_display`` as functions
will raise a compile-time error. In other words, *GHC defines a record
selector function only for fields whose type does not mention the
existentially-quantified variables*. (This example used an underscore in
the fields for which record selectors will not be defined, but that is
only programming style; GHC ignores them.)

To make use of these hidden fields, we need to create some helper
functions: ::

    inc :: Counter a -> Counter a
    inc (NewCounter x i d t) = NewCounter
        { _this = i x, _inc = i, _display = d, tag = t }

    display :: Counter a -> IO ()
    display NewCounter{ _this = x, _display = d } = d x

Now we can define counters with different underlying implementations: ::

    counterA :: Counter String
    counterA = NewCounter
        { _this = 0, _inc = (1+), _display = print, tag = "A" }

    counterB :: Counter String
    counterB = NewCounter
        { _this = "", _inc = ('#':), _display = putStrLn, tag = "B" }

    main = do
        display (inc counterA)         -- prints "1"
        display (inc (inc counterB))   -- prints "##"

Record update syntax is supported for existentials (and GADTs): ::

    setTag :: Counter a -> a -> Counter a
    setTag obj t = obj{ tag = t }

The rule for record update is this:

    the types of the updated fields may mention only the universally-quantified
    type variables of the data constructor. For GADTs, the field may mention
    only types that appear as a simple type-variable argument in the
    constructor's result type.

For example: ::

    data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential
    upd1 t x = t { f1=x }   -- OK:   upd1 :: T a b -> a' -> T a' b
    upd2 t x = t { f3=x }   -- BAD   (f3's type mentions c, which is
                            --        existentially quantified)

    data G a b where { G1 { g1::a, g2::c } :: G a [c] }
    upd3 g x = g { g1=x }   -- OK:   upd3 :: G a b -> c -> G c b
    upd4 g x = g { g2=x }   -- BAD (f2's type mentions c, which is not a simple
                            --      type-variable argument in G1's result type)

Restrictions
~~~~~~~~~~~~

There are several restrictions on the ways in which existentially-quantified
constructors can be used.

-  When pattern matching, each pattern match introduces a new, distinct,
   type for each existential type variable. These types cannot be
   unified with any other type, nor can they escape from the scope of
   the pattern match. For example, these fragments are incorrect: ::

       f1 (MkFoo a f) = a

   Here, the type bound by ``MkFoo`` "escapes", because ``a`` is the
   result of ``f1``. One way to see why this is wrong is to ask what
   type ``f1`` has: ::

         f1 :: Foo -> a             -- Weird!

   What is this "``a``" in the result type? Clearly we don't mean this: ::

         f1 :: forall a. Foo -> a   -- Wrong!

   The original program is just plain wrong. Here's another sort of
   error ::

         f2 (Baz1 a b) (Baz1 p q) = a==q

   It's ok to say ``a==b`` or ``p==q``, but ``a==q`` is wrong because it
   equates the two distinct types arising from the two ``Baz1``
   constructors.

-  You can't pattern-match on an existentially quantified constructor in
   a ``let`` or ``where`` group of bindings. So this is illegal: ::

         f3 x = a==b where { Baz1 a b = x }

   Instead, use a ``case`` expression: ::

         f3 x = case x of Baz1 a b -> a==b

   In general, you can only pattern-match on an existentially-quantified
   constructor in a ``case`` expression or in the patterns of a function
   definition. The reason for this restriction is really an
   implementation one. Type-checking binding groups is already a
   nightmare without existentials complicating the picture. Also an
   existential pattern binding at the top level of a module doesn't make
   sense, because it's not clear how to prevent the
   existentially-quantified type "escaping". So for now, there's a
   simple-to-state restriction. We'll see how annoying it is.

-  You can't use existential quantification for ``newtype``
   declarations. So this is illegal: ::

         newtype T = forall a. Ord a => MkT a

   Reason: a value of type ``T`` must be represented as a pair of a
   dictionary for ``Ord t`` and a value of type ``t``. That contradicts
   the idea that ``newtype`` should have no concrete representation. You
   can get just the same efficiency and effect by using ``data`` instead
   of ``newtype``. If there is no overloading involved, then there is
   more of a case for allowing an existentially-quantified ``newtype``,
   because the ``data`` version does carry an implementation cost, but
   single-field existentially quantified constructors aren't much use.
   So the simple restriction (no existential stuff on ``newtype``)
   stands, unless there are convincing reasons to change it.

-  You can't use ``deriving`` to define instances of a data type with
   existentially quantified data constructors. Reason: in most cases it
   would not make sense. For example:; ::

       data T = forall a. MkT [a] deriving( Eq )

   To derive ``Eq`` in the standard way we would need to have equality
   between the single component of two ``MkT`` constructors: ::

       instance Eq T where
         (MkT a) == (MkT b) = ???

   But ``a`` and ``b`` have distinct types, and so can't be compared.
   It's just about possible to imagine examples in which the derived
   instance would make sense, but it seems altogether simpler simply to
   prohibit such declarations. Define your own instances!

.. _gadt-style:

Declaring data types with explicit constructor signatures
---------------------------------------------------------

.. extension:: GADTSyntax
    :shortdesc: Enable generalised algebraic data type syntax.

    :since: 7.2.1

    Allow the use of GADT syntax in data type definitions (but not GADTs
    themselves; for this see :extension:`GADTs`)

When the ``GADTSyntax`` extension is enabled, GHC allows you to declare
an algebraic data type by giving the type signatures of constructors
explicitly. For example: ::

      data Maybe a where
          Nothing :: Maybe a
          Just    :: a -> Maybe a

The form is called a "GADT-style declaration" because Generalised
Algebraic Data Types, described in :ref:`gadt`, can only be declared
using this form.

Notice that GADT-style syntax generalises existential types
(:ref:`existential-quantification`). For example, these two declarations
are equivalent: ::

      data Foo = forall a. MkFoo a (a -> Bool)
      data Foo' where { MKFoo :: a -> (a->Bool) -> Foo' }

Any data type that can be declared in standard Haskell 98 syntax can
also be declared using GADT-style syntax. The choice is largely
stylistic, but GADT-style declarations differ in one important respect:
they treat class constraints on the data constructors differently.
Specifically, if the constructor is given a type-class context, that
context is made available by pattern matching. For example: ::

      data Set a where
        MkSet :: Eq a => [a] -> Set a

      makeSet :: Eq a => [a] -> Set a
      makeSet xs = MkSet (nub xs)

      insert :: a -> Set a -> Set a
      insert a (MkSet as) | a `elem` as = MkSet as
                          | otherwise   = MkSet (a:as)

A use of ``MkSet`` as a constructor (e.g. in the definition of
``makeSet``) gives rise to a ``(Eq a)`` constraint, as you would expect.
The new feature is that pattern-matching on ``MkSet`` (as in the
definition of ``insert``) makes *available* an ``(Eq a)`` context. In
implementation terms, the ``MkSet`` constructor has a hidden field that
stores the ``(Eq a)`` dictionary that is passed to ``MkSet``; so when
pattern-matching that dictionary becomes available for the right-hand
side of the match. In the example, the equality dictionary is used to
satisfy the equality constraint generated by the call to ``elem``, so
that the type of ``insert`` itself has no ``Eq`` constraint.

For example, one possible application is to reify dictionaries: ::

       data NumInst a where
         MkNumInst :: Num a => NumInst a

       intInst :: NumInst Int
       intInst = MkNumInst

       plus :: NumInst a -> a -> a -> a
       plus MkNumInst p q = p + q

Here, a value of type ``NumInst a`` is equivalent to an explicit
``(Num a)`` dictionary.

All this applies to constructors declared using the syntax of
:ref:`existential-with-context`. For example, the ``NumInst`` data type
above could equivalently be declared like this: ::

       data NumInst a
          = Num a => MkNumInst (NumInst a)

Notice that, unlike the situation when declaring an existential, there
is no ``forall``, because the ``Num`` constrains the data type's
universally quantified type variable ``a``. A constructor may have both
universal and existential type variables: for example, the following two
declarations are equivalent: ::

       data T1 a
        = forall b. (Num a, Eq b) => MkT1 a b
       data T2 a where
        MkT2 :: (Num a, Eq b) => a -> b -> T2 a

All this behaviour contrasts with Haskell 98's peculiar treatment of
contexts on a data type declaration (Section 4.2.1 of the Haskell 98
Report). In Haskell 98 the definition ::

      data Eq a => Set' a = MkSet' [a]

gives ``MkSet'`` the same type as ``MkSet`` above. But instead of
*making available* an ``(Eq a)`` constraint, pattern-matching on
``MkSet'`` *requires* an ``(Eq a)`` constraint! GHC faithfully
implements this behaviour, odd though it is. But for GADT-style
declarations, GHC's behaviour is much more useful, as well as much more
intuitive.

The rest of this section gives further details about GADT-style data
type declarations.

-  The result type of each data constructor must begin with the type
   constructor being defined. If the result type of all constructors has
   the form ``T a1 ... an``, where ``a1 ... an`` are distinct type
   variables, then the data type is *ordinary*; otherwise is a
   *generalised* data type (:ref:`gadt`).

-  As with other type signatures, you can give a single signature for
   several data constructors. In this example we give a single signature
   for ``T1`` and ``T2``: ::

         data T a where
           T1,T2 :: a -> T a
           T3 :: T a

-  The type signature of each constructor is independent, and is
   implicitly universally quantified as usual. In particular, the type
   variable(s) in the "``data T a where``" header have no scope, and
   different constructors may have different universally-quantified type
   variables: ::

         data T a where        -- The 'a' has no scope
           T1,T2 :: b -> T b   -- Means forall b. b -> T b
           T3 :: T a           -- Means forall a. T a

-  A constructor signature may mention type class constraints, which can
   differ for different constructors. For example, this is fine: ::

         data T a where
           T1 :: Eq b => b -> b -> T b
           T2 :: (Show c, Ix c) => c -> [c] -> T c

   When pattern matching, these constraints are made available to
   discharge constraints in the body of the match. For example: ::

         f :: T a -> String
         f (T1 x y) | x==y      = "yes"
                    | otherwise = "no"
         f (T2 a b)             = show a

   Note that ``f`` is not overloaded; the ``Eq`` constraint arising from
   the use of ``==`` is discharged by the pattern match on ``T1`` and
   similarly the ``Show`` constraint arising from the use of ``show``.

-  Unlike a Haskell-98-style data type declaration, the type variable(s)
   in the "``data Set a where``" header have no scope. Indeed, one can
   write a kind signature instead: ::

         data Set :: Type -> Type where ...

   or even a mixture of the two: ::

         data Bar a :: (Type -> Type) -> Type where ...

   The type variables (if given) may be explicitly kinded, so we could
   also write the header for ``Foo`` like this: ::

         data Bar a (b :: Type -> Type) where ...

-  You can use strictness annotations, in the obvious places in the
   constructor type: ::

         data Term a where
             Lit    :: !Int -> Term Int
             If     :: Term Bool -> !(Term a) -> !(Term a) -> Term a
             Pair   :: Term a -> Term b -> Term (a,b)

-  You can use a ``deriving`` clause on a GADT-style data type
   declaration. For example, these two declarations are equivalent ::

         data Maybe1 a where {
             Nothing1 :: Maybe1 a ;
             Just1    :: a -> Maybe1 a
           } deriving( Eq, Ord )

         data Maybe2 a = Nothing2 | Just2 a
              deriving( Eq, Ord )

-  The type signature may have quantified type variables that do not
   appear in the result type: ::

         data Foo where
            MkFoo :: a -> (a->Bool) -> Foo
            Nil   :: Foo

   Here the type variable ``a`` does not appear in the result type of
   either constructor. Although it is universally quantified in the type
   of the constructor, such a type variable is often called
   "existential". Indeed, the above declaration declares precisely the
   same type as the ``data Foo`` in :ref:`existential-quantification`.

   The type may contain a class context too, of course: ::

         data Showable where
           MkShowable :: Show a => a -> Showable

-  You can use record syntax on a GADT-style data type declaration: ::

         data Person where
             Adult :: { name :: String, children :: [Person] } -> Person
             Child :: Show a => { name :: !String, funny :: a } -> Person

   As usual, for every constructor that has a field ``f``, the type of
   field ``f`` must be the same (modulo alpha conversion). The ``Child``
   constructor above shows that the signature may have a context,
   existentially-quantified variables, and strictness annotations, just
   as in the non-record case. (NB: the "type" that follows the
   double-colon is not really a type, because of the record syntax and
   strictness annotations. A "type" of this form can appear only in a
   constructor signature.)

-  Record updates are allowed with GADT-style declarations, only fields
   that have the following property: the type of the field mentions no
   existential type variables.

-  As in the case of existentials declared using the Haskell-98-like
   record syntax (:ref:`existential-records`), record-selector functions
   are generated only for those fields that have well-typed selectors.
   Here is the example of that section, in GADT-style syntax: ::

       data Counter a where
           NewCounter :: { _this    :: self
                         , _inc     :: self -> self
                         , _display :: self -> IO ()
                         , tag      :: a
                         } -> Counter a

   As before, only one selector function is generated here, that for
   ``tag``. Nevertheless, you can still use all the field names in
   pattern matching and record construction.

-  In a GADT-style data type declaration there is no obvious way to
   specify that a data constructor should be infix, which makes a
   difference if you derive ``Show`` for the type. (Data constructors
   declared infix are displayed infix by the derived ``show``.) So GHC
   implements the following design: a data constructor declared in a
   GADT-style data type declaration is displayed infix by ``Show`` iff
   (a) it is an operator symbol, (b) it has two arguments, (c) it has a
   programmer-supplied fixity declaration. For example

   ::

          infix 6 (:--:)
          data T a where
            (:--:) :: Int -> Bool -> T Int

.. _gadt:

Generalised Algebraic Data Types (GADTs)
----------------------------------------

.. extension:: GADTs
    :shortdesc: Enable generalised algebraic data types.
        Implies :extension:`GADTSyntax` and :extension:`MonoLocalBinds`.

    :implies: :extension:`MonoLocalBinds`, :extension:`GADTSyntax`
    :since: 6.8.1

    Allow use of Generalised Algebraic Data Types (GADTs).

Generalised Algebraic Data Types generalise ordinary algebraic data
types by allowing constructors to have richer return types. Here is an
example: ::

      data Term a where
          Lit    :: Int -> Term Int
          Succ   :: Term Int -> Term Int
          IsZero :: Term Int -> Term Bool
          If     :: Term Bool -> Term a -> Term a -> Term a
          Pair   :: Term a -> Term b -> Term (a,b)

Notice that the return type of the constructors is not always
``Term a``, as is the case with ordinary data types. This generality
allows us to write a well-typed ``eval`` function for these ``Terms``: ::

      eval :: Term a -> a
      eval (Lit i)      = i
      eval (Succ t)     = 1 + eval t
      eval (IsZero t)   = eval t == 0
      eval (If b e1 e2) = if eval b then eval e1 else eval e2
      eval (Pair e1 e2) = (eval e1, eval e2)

The key point about GADTs is that *pattern matching causes type
refinement*. For example, in the right hand side of the equation ::

      eval :: Term a -> a
      eval (Lit i) =  ...

the type ``a`` is refined to ``Int``. That's the whole point! A precise
specification of the type rules is beyond what this user manual aspires
to, but the design closely follows that described in the paper `Simple
unification-based type inference for
GADTs <http://research.microsoft.com/%7Esimonpj/papers/gadt/>`__, (ICFP
2006). The general principle is this: *type refinement is only carried
out based on user-supplied type annotations*. So if no type signature is
supplied for ``eval``, no type refinement happens, and lots of obscure
error messages will occur. However, the refinement is quite general. For
example, if we had: ::

      eval :: Term a -> a -> a
      eval (Lit i) j =  i+j

the pattern match causes the type ``a`` to be refined to ``Int``
(because of the type of the constructor ``Lit``), and that refinement
also applies to the type of ``j``, and the result type of the ``case``
expression. Hence the addition ``i+j`` is legal.

These and many other examples are given in papers by Hongwei Xi, and Tim
Sheard. There is a longer introduction `on the
wiki <http://www.haskell.org/haskellwiki/GADT>`__, and Ralf Hinze's `Fun
with phantom
types <http://www.cs.ox.ac.uk/ralf.hinze/publications/With.pdf>`__ also
has a number of examples. Note that papers may use different notation to
that implemented in GHC.

The rest of this section outlines the extensions to GHC that support
GADTs. The extension is enabled with :extension:`GADTs`. The :extension:`GADTs` extension
also sets :extension:`GADTSyntax` and :extension:`MonoLocalBinds`.

-  A GADT can only be declared using GADT-style syntax
   (:ref:`gadt-style`); the old Haskell 98 syntax for data declarations
   always declares an ordinary data type. The result type of each
   constructor must begin with the type constructor being defined, but
   for a GADT the arguments to the type constructor can be arbitrary
   monotypes. For example, in the ``Term`` data type above, the type of
   each constructor must end with ``Term ty``, but the ``ty`` need not
   be a type variable (e.g. the ``Lit`` constructor).

-  It is permitted to declare an ordinary algebraic data type using
   GADT-style syntax. What makes a GADT into a GADT is not the syntax,
   but rather the presence of data constructors whose result type is not
   just ``T a b``.

-  You cannot use a ``deriving`` clause for a GADT; only for an ordinary
   data type.

-  As mentioned in :ref:`gadt-style`, record syntax is supported. For
   example:

   ::

         data Term a where
             Lit    :: { val  :: Int }      -> Term Int
             Succ   :: { num  :: Term Int } -> Term Int
             Pred   :: { num  :: Term Int } -> Term Int
             IsZero :: { arg  :: Term Int } -> Term Bool
             Pair   :: { arg1 :: Term a
                       , arg2 :: Term b
                       }                    -> Term (a,b)
             If     :: { cnd  :: Term Bool
                       , tru  :: Term a
                       , fls  :: Term a
                       }                    -> Term a

   However, for GADTs there is the following additional constraint:
   every constructor that has a field ``f`` must have the same result
   type (modulo alpha conversion) Hence, in the above example, we cannot
   merge the ``num`` and ``arg`` fields above into a single name.
   Although their field types are both ``Term Int``, their selector
   functions actually have different types:

   ::

         num :: Term Int -> Term Int
         arg :: Term Bool -> Term Int

-  When pattern-matching against data constructors drawn from a GADT,
   for example in a ``case`` expression, the following rules apply:

   -  The type of the scrutinee must be rigid.

   -  The type of the entire ``case`` expression must be rigid.

   -  The type of any free variable mentioned in any of the ``case``
      alternatives must be rigid.

   A type is "rigid" if it is completely known to the compiler at its
   binding site. The easiest way to ensure that a variable a rigid type
   is to give it a type signature. For more precise details see `Simple
   unification-based type inference for
   GADTs <http://research.microsoft.com/%7Esimonpj/papers/gadt/>`__. The
   criteria implemented by GHC are given in the Appendix.

.. _record-system-extensions:

Extensions to the record system
===============================

.. _traditional-record-syntax:

Traditional record syntax
-------------------------

.. extension:: NoTraditionalRecordSyntax
    :shortdesc: Disable support for traditional record syntax
        (as supported by Haskell 98) ``C {f = x}``

    :since: 7.4.1

    Disallow use of record syntax.

Traditional record syntax, such as ``C {f = x}``, is enabled by default.
To disable it, you can use the :extension:`NoTraditionalRecordSyntax` extension.

.. _disambiguate-fields:

Record field disambiguation
---------------------------

.. extension:: DisambiguateRecordFields
    :shortdesc: Enable record field disambiguation.
        Implied by :extension:`RecordWildCards`.

    :since: 6.8.1

    Allow the compiler to automatically choose between identically-named
    record selectors based on type (if the choice is unambiguous).

In record construction and record pattern matching it is entirely
unambiguous which field is referred to, even if there are two different
data types in scope with a common field name. For example:

::

    module M where
      data S = MkS { x :: Int, y :: Bool }

    module Foo where
      import M

      data T = MkT { x :: Int }

      ok1 (MkS { x = n }) = n+1   -- Unambiguous
      ok2 n = MkT { x = n+1 }     -- Unambiguous

      bad1 k = k { x = 3 }        -- Ambiguous
      bad2 k = x k                -- Ambiguous

Even though there are two ``x``'s in scope, it is clear that the ``x``
in the pattern in the definition of ``ok1`` can only mean the field
``x`` from type ``S``. Similarly for the function ``ok2``. However, in
the record update in ``bad1`` and the record selection in ``bad2`` it is
not clear which of the two types is intended.

Haskell 98 regards all four as ambiguous, but with the
:extension:`DisambiguateRecordFields` extension, GHC will accept the former two. The
rules are precisely the same as those for instance declarations in
Haskell 98, where the method names on the left-hand side of the method
bindings in an instance declaration refer unambiguously to the method of
that class (provided they are in scope at all), even if there are other
variables in scope with the same name. This reduces the clutter of
qualified names when you import two records from different modules that
use the same field name.

Some details:

-  Field disambiguation can be combined with punning (see
   :ref:`record-puns`). For example: ::

       module Foo where
         import M
         x=True
         ok3 (MkS { x }) = x+1   -- Uses both disambiguation and punning

-  With :extension:`DisambiguateRecordFields` you can use *unqualified* field
   names even if the corresponding selector is only in scope *qualified*
   For example, assuming the same module ``M`` as in our earlier
   example, this is legal: ::

       module Foo where
         import qualified M    -- Note qualified

         ok4 (M.MkS { x = n }) = n+1   -- Unambiguous

   Since the constructor ``MkS`` is only in scope qualified, you must
   name it ``M.MkS``, but the field ``x`` does not need to be qualified
   even though ``M.x`` is in scope but ``x`` is not (In effect, it is
   qualified by the constructor).

.. _duplicate-record-fields:

Duplicate record fields
-----------------------

.. extension:: DuplicateRecordFields
    :shortdesc: Allow definition of record types with identically-named fields.

    :implies: :extension:`DisambiguateRecordFields`
    :since: 8.0.1

    Allow definition of record types with identically-named fields.

Going beyond :extension:`DisambiguateRecordFields` (see :ref:`disambiguate-fields`),
the :extension:`DuplicateRecordFields` extension allows multiple datatypes to be
declared using the same field names in a single module. For example, it allows
this: ::

    module M where
      data S = MkS { x :: Int }
      data T = MkT { x :: Bool }

Uses of fields that are always unambiguous because they mention the constructor,
including construction and pattern-matching, may freely use duplicated field
names. For example, the following are permitted (just as with
:extension:`DisambiguateRecordFields`): ::

    s = MkS { x = 3 }

    f (MkT { x = b }) = b

Field names used as selector functions or in record updates must be unambiguous,
either because there is only one such field in scope, or because a type
signature is supplied, as described in the following sections.

Selector functions
~~~~~~~~~~~~~~~~~~

Fields may be used as selector functions only if they are unambiguous, so this
is still not allowed if both ``S(x)`` and ``T(x)`` are in scope: ::

    bad r = x r

An ambiguous selector may be disambiguated by the type being "pushed down" to
the occurrence of the selector (see :ref:`higher-rank-type-inference` for more
details on what "pushed down" means). For example, the following are permitted: ::

    ok1 = x :: S -> Int

    ok2 :: S -> Int
    ok2 = x

    ok3 = k x -- assuming we already have k :: (S -> Int) -> _

In addition, the datatype that is meant may be given as a type signature on the
argument to the selector: ::

    ok4 s = x (s :: S)

However, we do not infer the type of the argument to determine the datatype, or
have any way of deferring the choice to the constraint solver. Thus the
following is ambiguous: ::

    bad :: S -> Int
    bad s = x s

Even though a field label is duplicated in its defining module, it may be
possible to use the selector unambiguously elsewhere. For example, another
module could import ``S(x)`` but not ``T(x)``, and then use ``x`` unambiguously.

Record updates
~~~~~~~~~~~~~~

In a record update such as ``e { x = 1 }``, if there are multiple ``x`` fields
in scope, then the type of the context must fix which record datatype is
intended, or a type annotation must be supplied. Consider the following
definitions: ::

    data S = MkS { foo :: Int }
    data T = MkT { foo :: Int, bar :: Int }
    data U = MkU { bar :: Int, baz :: Int }

Without :extension:`DuplicateRecordFields`, an update mentioning ``foo`` will always be
ambiguous if all these definitions were in scope. When the extension is enabled,
there are several options for disambiguating updates:

- Check for types that have all the fields being updated. For example: ::

      f x = x { foo = 3, bar = 2 }

  Here ``f`` must be updating ``T`` because neither ``S`` nor ``U`` have both
  fields.

- Use the type being pushed in to the record update, as in the following: ::

      g1 :: T -> T
      g1 x = x { foo = 3 }

      g2 x = x { foo = 3 } :: T

      g3 = k (x { foo = 3 }) -- assuming we already have k :: T -> _

- Use an explicit type signature on the record expression, as in: ::

      h x = (x :: T) { foo = 3 }

The type of the expression being updated will not be inferred, and no
constraint-solving will be performed, so the following will be rejected as
ambiguous: ::

    let x :: T
        x = blah
    in x { foo = 3 }

    \x -> [x { foo = 3 },  blah :: T ]

    \ (x :: T) -> x { foo = 3 }

Import and export of record fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When :extension:`DuplicateRecordFields` is enabled, an ambiguous field must be exported
as part of its datatype, rather than at the top level. For example, the
following is legal: ::

    module M (S(x), T(..)) where
      data S = MkS { x :: Int }
      data T = MkT { x :: Bool }

However, this would not be permitted, because ``x`` is ambiguous: ::

    module M (x) where ...

Similar restrictions apply on import.

.. _record-puns:

Record puns
-----------

.. extension:: NamedFieldPuns
    :shortdesc: Enable record puns.

    :since: 6.10.1

    Allow use of record puns.

Record puns are enabled by the language extension :extension:`NamedFieldPuns`.

When using records, it is common to write a pattern that binds a
variable with the same name as a record field, such as: ::

    data C = C {a :: Int}
    f (C {a = a}) = a

Record punning permits the variable name to be elided, so one can simply
write ::

    f (C {a}) = a

to mean the same pattern as above. That is, in a record pattern, the
pattern ``a`` expands into the pattern ``a = a`` for the same name
``a``.

Note that:

-  Record punning can also be used in an expression, writing, for
   example, ::

       let a = 1 in C {a}

   instead of ::

       let a = 1 in C {a = a}

   The expansion is purely syntactic, so the expanded right-hand side
   expression refers to the nearest enclosing variable that is spelled
   the same as the field name.

-  Puns and other patterns can be mixed in the same record: ::

       data C = C {a :: Int, b :: Int}
       f (C {a, b = 4}) = a

-  Puns can be used wherever record patterns occur (e.g. in ``let``
   bindings or at the top-level).

-  A pun on a qualified field name is expanded by stripping off the
   module qualifier. For example: ::

       f (C {M.a}) = a

   means ::

       f (M.C {M.a = a}) = a

   (This is useful if the field selector ``a`` for constructor ``M.C``
   is only in scope in qualified form.)

.. _record-wildcards:

Record wildcards
----------------

.. extension:: RecordWildCards
    :shortdesc: Enable record wildcards.
        Implies :extension:`DisambiguateRecordFields`.

    :implies: :extension:`DisambiguateRecordFields`.
    :since: 6.8.1

    Allow the use of wildcards in record construction and pattern matching.

Record wildcards are enabled by the language extension :extension:`RecordWildCards`. This
exension implies :extension:`DisambiguateRecordFields`.

For records with many fields, it can be tiresome to write out each field
individually in a record pattern, as in ::

    data C = C {a :: Int, b :: Int, c :: Int, d :: Int}
    f (C {a = 1, b = b, c = c, d = d}) = b + c + d

Record wildcard syntax permits a "``..``" in a record pattern, where
each elided field ``f`` is replaced by the pattern ``f = f``. For
example, the above pattern can be written as ::

    f (C {a = 1, ..}) = b + c + d

More details:

-  Record wildcards in patterns can be mixed with other patterns,
   including puns (:ref:`record-puns`); for example, in a pattern
   ``(C {a = 1, b, ..})``. Additionally, record wildcards can be used
   wherever record patterns occur, including in ``let`` bindings and at
   the top-level. For example, the top-level binding ::

       C {a = 1, ..} = e

   defines ``b``, ``c``, and ``d``.

-  Record wildcards can also be used in an expression, when constructing
   a record. For example, ::

       let {a = 1; b = 2; c = 3; d = 4} in C {..}

   in place of ::

       let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d}

   The expansion is purely syntactic, so the record wildcard expression
   refers to the nearest enclosing variables that are spelled the same
   as the omitted field names.

-  For both pattern and expression wildcards, the "``..``" expands to
   the missing *in-scope* record fields. Specifically the expansion of
   "``C {..}``" includes ``f`` if and only if:

   -  ``f`` is a record field of constructor ``C``.

   -  The record field ``f`` is in scope somehow (either qualified or
      unqualified).

   These rules restrict record wildcards to the situations in which the
   user could have written the expanded version. For example ::

       module M where
         data R = R { a,b,c :: Int }
       module X where
         import M( R(R,a,c) )
         f a b = R { .. }

   The ``R{..}`` expands to ``R{a=a}``, omitting ``b`` since the
   record field is not in scope, and omitting ``c`` since the variable
   ``c`` is not in scope (apart from the binding of the record selector
   ``c``, of course).

-  When record wildcards are use in record construction, a field ``f``
   is initialised only if ``f`` is in scope,
   and is not imported or bound at top level.
   For example, ``f`` can be bound by an enclosing pattern match or
   let/where-binding. For example ::

        module M where
          import A( a )

          data R = R { a,b,c,d :: Int }

          c = 3 :: Int

          f b = R { .. }  -- Expands to R { b = b, d = d }
            where
              d = b+1

   Here, ``a`` is imported, and ``c`` is bound at top level, so neither
   contribute to the expansion of the "``..``".
   The motivation here is that it should be
   easy for the reader to figure out what the "``..``" expands to.

-  Record wildcards cannot be used (a) in a record update construct, and
   (b) for data constructors that are not declared with record fields.
   For example: ::

       f x = x { v=True, .. }   -- Illegal (a)

       data T = MkT Int Bool
       g = MkT { .. }           -- Illegal (b)
       h (MkT { .. }) = True    -- Illegal (b)


.. _record-field-selector-polymorphism:

Record field selector polymorphism
----------------------------------

The module :base-ref:`GHC.Records.` defines the following: ::

  class HasField (x :: k) r a | x r -> a where
    getField :: r -> a

A ``HasField x r a`` constraint represents the fact that ``x`` is a
field of type ``a`` belonging to a record type ``r``.  The
``getField`` method gives the record selector function.

This allows definitions that are polymorphic over record types with a specified
field.  For example, the following works with any record type that has a field
``name :: String``: ::

  foo :: HasField "name" r String => r -> String
  foo r = reverse (getField @"name" r)

``HasField`` is a magic built-in typeclass (similar to ``Coercible``, for
example).  It is given special treatment by the constraint solver (see
:ref:`solving-hasfield-constraints`).  Users may define their own instances of
``HasField`` also (see :ref:`virtual-record-fields`).

.. _solving-hasfield-constraints:

Solving HasField constraints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the constraint solver encounters a constraint ``HasField x r a``
where ``r`` is a concrete datatype with a field ``x`` in scope, it
will automatically solve the constraint using the field selector as
the dictionary, unifying ``a`` with the type of the field if
necessary.  This happens irrespective of which extensions are enabled.

For example, if the following datatype is in scope ::

  data Person = Person { name :: String }

the end result is rather like having an instance ::

  instance HasField "name" Person String where
    getField = name

except that this instance is not actually generated anywhere, rather
the constraint is solved directly by the constraint solver.

A field must be in scope for the corresponding ``HasField`` constraint
to be solved.  This retains the existing representation hiding
mechanism, whereby a module may choose not to export a field,
preventing client modules from accessing or updating it directly.

Solving ``HasField`` constraints depends on the field selector functions that
are generated for each datatype definition:

-  If a record field does not have a selector function because its type would allow
   an existential variable to escape, the corresponding ``HasField`` constraint
   will not be solved.  For example, ::

     {-# LANGUAGE ExistentialQuantification #-}
     data Exists t = forall x . MkExists { unExists :: t x }

   does not give rise to a selector ``unExists :: Exists t -> t x`` and we will not
   solve ``HasField "unExists" (Exists t) a`` automatically.

-  If a record field has a polymorphic type (and hence the selector function is
   higher-rank), the corresponding ``HasField`` constraint will not be solved,
   because doing so would violate the functional dependency on ``HasField`` and/or
   require impredicativity.  For example, ::

     {-# LANGUAGE RankNTypes #-}
     data Higher = MkHigher { unHigher :: forall t . t -> t }

   gives rise to a selector ``unHigher :: Higher -> (forall t . t -> t)`` but does
   not lead to solution of the constraint ``HasField "unHigher" Higher a``.

-  A record GADT may have a restricted type for a selector function, which may lead
   to additional unification when solving ``HasField`` constraints.  For example, ::

     {-# LANGUAGE GADTs #-}
     data Gadt t where
       MkGadt :: { unGadt :: Maybe v } -> Gadt [v]

   gives rise to a selector ``unGadt :: Gadt [v] -> Maybe v``, so the solver will reduce
   the constraint ``HasField "unGadt" (Gadt t) b`` by unifying ``t ~ [v]`` and
   ``b ~ Maybe v`` for some fresh metavariable ``v``, rather as if we had an instance ::

     instance (t ~ [v], b ~ Maybe v) => HasField "unGadt" (Gadt t) b

-  If a record type has an old-fashioned datatype context, the ``HasField``
   constraint will be reduced to solving the constraints from the context.
   For example, ::

     {-# LANGUAGE DatatypeContexts #-}
     data Eq a => Silly a = MkSilly { unSilly :: a }

   gives rise to a selector ``unSilly :: Eq a => Silly a -> a``, so
   the solver will reduce the constraint ``HasField "unSilly" (Silly a) b`` to
   ``Eq a`` (and unify ``a`` with ``b``), rather as if we had an instance ::

     instance (Eq a, a ~ b) => HasField "unSilly" (Silly a) b

.. _virtual-record-fields:

Virtual record fields
~~~~~~~~~~~~~~~~~~~~~

Users may define their own instances of ``HasField``, provided they do
not conflict with the built-in constraint solving behaviour.  This
allows "virtual" record fields to be defined for datatypes that do not
otherwise have them.

For example, this instance would make the ``name`` field of ``Person``
accessible using ``#fullname`` as well: ::

  instance HasField "fullname" Person String where
    getField = name

More substantially, an anonymous records library could provide
``HasField`` instances for its anonymous records, and thus be
compatible with the polymorphic record selectors introduced by this
proposal.  For example, something like this makes it possible to use
``getField`` to access ``Record`` values with the appropriate
string in the type-level list of fields: ::

  data Record (xs :: [(k, Type)]) where
    Nil  :: Record '[]
    Cons :: Proxy x -> a -> Record xs -> Record ('(x, a) ': xs)

  instance HasField x (Record ('(x, a) ': xs)) a where
    getField (Cons _ v _) = v
  instance HasField x (Record xs) a => HasField x (Record ('(y, b) ': xs)) a where
    getField (Cons _ _ r) = getField @x r

  r :: Record '[ '("name", String) ]
  r = Cons Proxy "R" Nil)

  x = getField @"name" r

Since representations such as this can support field labels with kinds other
than ``Symbol``, the ``HasField`` class is poly-kinded (even though the built-in
constraint solving works only at kind ``Symbol``).  In particular, this allows
users to declare scoped field labels such as in the following example: ::

  data PersonFields = Name

  s :: Record '[ '(Name, String) ]
  s = Cons Proxy "S" Nil

  y = getField @Name s

In order to avoid conflicting with the built-in constraint solving,
the following user-defined ``HasField`` instances are prohibited (in
addition to the usual rules, such as the prohibition on type
families appearing in instance heads):

-  ``HasField _ r _`` where ``r`` is a variable;

-  ``HasField _ (T ...) _`` if ``T`` is a data family (because it
   might have fields introduced later, using data instance declarations);

-  ``HasField x (T ...) _`` if ``x`` is a variable and ``T`` has any
   fields at all (but this instance is permitted if ``T`` has no fields);

-  ``HasField "foo" (T ...) _`` if ``T`` has a field ``foo`` (but this
   instance is permitted if it does not).

If a field has a higher-rank or existential type, the corresponding ``HasField``
constraint will not be solved automatically (as described above), but in the
interests of simplicity we do not permit users to define their own instances
either.  If a field is not in scope, the corresponding instance is still
prohibited, to avoid conflicts in downstream modules.


.. _deriving:

Extensions to the "deriving" mechanism
======================================

Haskell 98 allows the programmer to add a deriving clause to a data type
declaration, to generate a standard instance declaration for specified class.
GHC extends this mechanism along several axes:

* The derivation mechanism can be used separately from the data type
  declaration, using the `standalone deriving mechanism
  <#stand-alone-deriving>`__.

* In Haskell 98, the only derivable classes are ``Eq``,
  ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and ``Show``. `Various
  language extensions <#deriving-extra>`__ extend this list.

* Besides the stock approach to deriving instances by generating all method
  definitions, GHC supports two additional deriving strategies, which can
  derive arbitrary classes:

  * `Generalised newtype deriving <#newtype-deriving>`__ for newtypes and
  * `deriving any class <#derive-any-class>`__ using an empty instance
    declaration.

  The user can optionally declare the desired `deriving strategy
  <#deriving-stragies>`__, especially if the compiler chooses the wrong
  one `by default <#default-deriving-strategy>`__.

.. _empty-data-deriving:

Deriving instances for empty data types
---------------------------------------

.. ghc-flag:: -XEmptyDataDeriving
    :shortdesc: Allow deriving instances of standard type classes for
                empty data types.
    :type: dynamic
    :reverse: -XNoEmptyDataDeriving
    :category:

    :since: 8.4.1

    Allow deriving instances of standard type classes for empty data types.

One can write data types with no constructors using the
:ghc-flag:`-XEmptyDataDecls` flag (see :ref:`nullary-types`), which is on by
default in Haskell 2010. What is not on by default is the ability to derive
type class instances for these types. This ability is enabled through use of
the :ghc-flag:`-XEmptyDataDeriving` flag. For instance, this lets one write: ::

    data Empty deriving (Eq, Ord, Read, Show)

This would generate the following instances: ::

    instance Eq Empty where
      _ == _ = True

    instance Ord Empty where
      compare _ _ = EQ

    instance Read Empty where
      readPrec = pfail

    instance Show Empty where
      showsPrec _ x = case x of {}

The :ghc-flag:`-XEmptyDataDeriving` flag is only required to enable deriving
of these four "standard" type classes (which are mentioned in the Haskell
Report). Other extensions to the ``deriving`` mechanism, which are explained
below in greater detail, do not require :ghc-flag:`-XEmptyDataDeriving` to be
used in conjunction with empty data types. These include:

* :ghc-flag:`-XStandaloneDeriving` (see :ref:`stand-alone-deriving`)
* Type classes which require their own extensions to be enabled to be derived,
  such as :ghc-flag:`-XDeriveFunctor` (see :ref:`deriving-extra`)
* :ghc-flag:`-XDeriveAnyClass` (see :ref:`derive-any-class`)

.. _deriving-inferred:

Inferred context for deriving clauses
-------------------------------------

The Haskell Report is vague about exactly when a ``deriving`` clause is
legal. For example: ::

      data T0 f a = MkT0 a         deriving( Eq )
      data T1 f a = MkT1 (f a)     deriving( Eq )
      data T2 f a = MkT2 (f (f a)) deriving( Eq )

The natural generated ``Eq`` code would result in these instance
declarations: ::

      instance Eq a         => Eq (T0 f a) where ...
      instance Eq (f a)     => Eq (T1 f a) where ...
      instance Eq (f (f a)) => Eq (T2 f a) where ...

The first of these is obviously fine. The second is still fine, although
less obviously. The third is not Haskell 98, and risks losing
termination of instances.

GHC takes a conservative position: it accepts the first two, but not the
third. The rule is this: each constraint in the inferred instance
context must consist only of type variables, with no repetitions.

This rule is applied regardless of flags. If you want a more exotic
context, you can write it yourself, using the `standalone deriving
mechanism <#stand-alone-deriving>`__.

.. _stand-alone-deriving:

Stand-alone deriving declarations
---------------------------------

.. extension:: StandaloneDeriving
    :shortdesc: Enable standalone deriving.

    :since: 6.8.1

    Allow the use of stand-alone ``deriving`` declarations.

GHC allows stand-alone ``deriving`` declarations, enabled by
:extension:`StandaloneDeriving`: ::

      data Foo a = Bar a | Baz String

      deriving instance Eq a => Eq (Foo a)

The syntax is identical to that of an ordinary instance declaration
apart from (a) the keyword ``deriving``, and (b) the absence of the
``where`` part.

However, standalone deriving differs from a ``deriving`` clause in a
number of important ways:

-  The standalone deriving declaration does not need to be in the same
   module as the data type declaration. (But be aware of the dangers of
   orphan instances (:ref:`orphan-modules`).

-  In most cases, you must supply an explicit context (in the example the
   context is ``(Eq a)``), exactly as you would in an ordinary instance
   declaration. (In contrast, in a ``deriving`` clause attached to a
   data type declaration, the context is inferred.)

   The exception to this rule is that the context of a standalone deriving
   declaration can infer its context when a single, extra-wildcards constraint
   is used as the context, such as in: ::

         deriving instance _ => Eq (Foo a)

   This is essentially the same as if you had written ``deriving Eq`` after
   the declaration for ``data Foo a``. Using this feature requires the use of
   :extension:`PartialTypeSignatures` (:ref:`partial-type-signatures`).

-  Unlike a ``deriving`` declaration attached to a ``data`` declaration,
   the instance can be more specific than the data type (assuming you
   also use :extension:`FlexibleInstances`, :ref:`instance-rules`). Consider
   for example ::

         data Foo a = Bar a | Baz String

         deriving instance Eq a => Eq (Foo [a])
         deriving instance Eq a => Eq (Foo (Maybe a))

   This will generate a derived instance for ``(Foo [a])`` and
   ``(Foo (Maybe a))``, but other types such as ``(Foo (Int,Bool))``
   will not be an instance of ``Eq``.

-  Unlike a ``deriving`` declaration attached to a ``data`` declaration,
   GHC does not restrict the form of the data type. Instead, GHC simply
   generates the appropriate boilerplate code for the specified class,
   and typechecks it. If there is a type error, it is your problem. (GHC
   will show you the offending code if it has a type error.)

   The merit of this is that you can derive instances for GADTs and
   other exotic data types, providing only that the boilerplate code
   does indeed typecheck. For example: ::

         data T a where
            T1 :: T Int
            T2 :: T Bool

         deriving instance Show (T a)

   In this example, you cannot say ``... deriving( Show )`` on the data
   type declaration for ``T``, because ``T`` is a GADT, but you *can*
   generate the instance declaration using stand-alone deriving.

   The down-side is that, if the boilerplate code fails to typecheck,
   you will get an error message about that code, which you did not
   write. Whereas, with a ``deriving`` clause the side-conditions are
   necessarily more conservative, but any error message may be more
   comprehensible.

-  Under most circumstances, you cannot use standalone deriving to create an
   instance for a data type whose constructors are not all in scope. This is
   because the derived instance would generate code that uses the constructors
   behind the scenes, which would break abstraction.

   The one exception to this rule is :extension:`DeriveAnyClass`, since
   deriving an instance via :extension:`DeriveAnyClass` simply generates
   an empty instance declaration, which does not require the use of any
   constructors. See the `deriving any class <#derive-any-class>`__ section
   for more details.

In other ways, however, a standalone deriving obeys the same rules as
ordinary deriving:

-  A ``deriving instance`` declaration must obey the same rules
   concerning form and termination as ordinary instance declarations,
   controlled by the same flags; see :ref:`instance-decls`.

-  The stand-alone syntax is generalised for newtypes in exactly the
   same way that ordinary ``deriving`` clauses are generalised
   (:ref:`newtype-deriving`). For example: ::

         newtype Foo a = MkFoo (State Int a)

         deriving instance MonadState Int Foo

   GHC always treats the *last* parameter of the instance (``Foo`` in
   this example) as the type whose instance is being derived.

.. _deriving-extra:

Deriving instances of extra classes (``Data``, etc.)
----------------------------------------------------

Haskell 98 allows the programmer to add "``deriving( Eq, Ord )``" to a
data type declaration, to generate a standard instance declaration for
classes specified in the ``deriving`` clause. In Haskell 98, the only
classes that may appear in the ``deriving`` clause are the standard
classes ``Eq``, ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and
``Show``.

GHC extends this list with several more classes that may be
automatically derived:

-  With :extension:`DeriveGeneric`, you can derive instances of the classes
   ``Generic`` and ``Generic1``, defined in ``GHC.Generics``. You can
   use these to define generic functions, as described in
   :ref:`generic-programming`.

-  With :extension:`DeriveFunctor`, you can derive instances of the class
   ``Functor``, defined in ``GHC.Base``.

-  With :extension:`DeriveDataTypeable`, you can derive instances of the class
   ``Data``, defined in ``Data.Data``.

-  With :extension:`DeriveFoldable`, you can derive instances of the class
   ``Foldable``, defined in ``Data.Foldable``.

-  With :extension:`DeriveTraversable`, you can derive instances of the class
   ``Traversable``, defined in ``Data.Traversable``. Since the
   ``Traversable`` instance dictates the instances of ``Functor`` and
   ``Foldable``, you'll probably want to derive them too, so
   :extension:`DeriveTraversable` implies :extension:`DeriveFunctor` and
   :extension:`DeriveFoldable`.

-  With :extension:`DeriveLift`, you can derive instances of the class ``Lift``,
   defined in the ``Language.Haskell.TH.Syntax`` module of the
   ``template-haskell`` package.

You can also use a standalone deriving declaration instead (see
:ref:`stand-alone-deriving`).

In each case the appropriate class must be in scope before it can be
mentioned in the ``deriving`` clause.

.. _deriving-functor:

Deriving ``Functor`` instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: DeriveFunctor
    :shortdesc: Enable deriving for the Functor class.
        Implied by :extension:`DeriveTraversable`.

    :since: 7.10.1

    Allow automatic deriving of instances for the ``Functor`` typeclass.


With :extension:`DeriveFunctor`, one can derive ``Functor`` instances for data types
of kind ``Type -> Type``. For example, this declaration::

    data Example a = Ex a Char (Example a) (Example Char)
      deriving Functor

would generate the following instance: ::

    instance Functor Example where
      fmap f (Ex a1 a2 a3 a4) = Ex (f a1) a2 (fmap f a3) a4

The basic algorithm for :extension:`DeriveFunctor` walks the arguments of each
constructor of a data type, applying a mapping function depending on the type
of each argument. If a plain type variable is found that is syntactically
equivalent to the last type parameter of the data type (``a`` in the above
example), then we apply the function ``f`` directly to it. If a type is
encountered that is not syntactically equivalent to the last type parameter
*but does mention* the last type parameter somewhere in it, then a recursive
call to ``fmap`` is made. If a type is found which doesn't mention the last
type parameter at all, then it is left alone.

The second of those cases, in which a type is unequal to the type parameter but
does contain the type parameter, can be surprisingly tricky. For example, the
following example compiles::

    newtype Right a = Right (Either Int a) deriving Functor

Modifying the code slightly, however, produces code which will not compile::

    newtype Wrong a = Wrong (Either a Int) deriving Functor

The difference involves the placement of the last type parameter, ``a``. In the
``Right`` case, ``a`` occurs within the type ``Either Int a``, and moreover, it
appears as the last type argument of ``Either``. In the ``Wrong`` case,
however, ``a`` is not the last type argument to ``Either``; rather, ``Int`` is.

This distinction is important because of the way :extension:`DeriveFunctor` works. The
derived ``Functor Right`` instance would be::

    instance Functor Right where
      fmap f (Right a) = Right (fmap f a)

Given a value of type ``Right a``, GHC must produce a value of type
``Right b``. Since the argument to the ``Right`` constructor has type
``Either Int a``, the code recursively calls ``fmap`` on it to produce a value
of type ``Either Int b``, which is used in turn to construct a final value of
type ``Right b``.

The generated code for the ``Functor Wrong`` instance would look exactly the
same, except with ``Wrong`` replacing every occurrence of ``Right``. The
problem is now that ``fmap`` is being applied recursively to a value of type
``Either a Int``. This cannot possibly produce a value of type
``Either b Int``, as ``fmap`` can only change the last type parameter! This
causes the generated code to be ill-typed.

As a general rule, if a data type has a derived ``Functor`` instance and its
last type parameter occurs on the right-hand side of the data declaration, then
either it must (1) occur bare (e.g., ``newtype Id a = Id a``), or (2) occur as the
last argument of a type constructor (as in ``Right`` above).

There are two exceptions to this rule:

#. Tuple types. When a non-unit tuple is used on the right-hand side of a data
   declaration, :extension:`DeriveFunctor` treats it as a product of distinct types.
   In other words, the following code::

       newtype Triple a = Triple (a, Int, [a]) deriving Functor

   Would result in a generated ``Functor`` instance like so::

       instance Functor Triple where
         fmap f (Triple a) =
           Triple (case a of
                        (a1, a2, a3) -> (f a1, a2, fmap f a3))

   That is, :extension:`DeriveFunctor` pattern-matches its way into tuples and maps
   over each type that constitutes the tuple. The generated code is
   reminiscent of what would be generated from
   ``data Triple a = Triple a Int [a]``, except with extra machinery to handle
   the tuple.

#. Function types. The last type parameter can appear anywhere in a function
   type as long as it occurs in a *covariant* position. To illustrate what this
   means, consider the following three examples::

       newtype CovFun1 a = CovFun1 (Int -> a) deriving Functor
       newtype CovFun2 a = CovFun2 ((a -> Int) -> a) deriving Functor
       newtype CovFun3 a = CovFun3 (((Int -> a) -> Int) -> a) deriving Functor

   All three of these examples would compile without issue. On the other hand::

       newtype ContraFun1 a = ContraFun1 (a -> Int) deriving Functor
       newtype ContraFun2 a = ContraFun2 ((Int -> a) -> Int) deriving Functor
       newtype ContraFun3 a = ContraFun3 (((a -> Int) -> a) -> Int) deriving Functor

   While these examples look similar, none of them would successfully compile.
   This is because all occurrences of the last type parameter ``a`` occur in *contravariant* positions, not covariant ones.

   Intuitively, a covariant type is *produced*, and a contravariant type is
   *consumed*. Most types in Haskell are covariant, but the function type is
   special in that the lefthand side of a function arrow reverses variance. If
   a function type ``a -> b`` appears in a covariant position (e.g.,
   ``CovFun1`` above), then ``a`` is in a contravariant position and ``b`` is
   in a covariant position. Similarly, if ``a -> b`` appears in a contravariant
   position (e.g., ``CovFun2`` above), then ``a`` is in ``a`` covariant
   position and ``b`` is in a contravariant position.

   To see why a data type with a contravariant occurrence of its last type
   parameter cannot have a derived ``Functor`` instance, let's suppose that a
   ``Functor ContraFun1`` instance exists. The implementation would look
   something like this::

       instance Functor ContraFun1 where
         fmap f (ContraFun g) = ContraFun (\x -> _)

   We have ``f :: a -> b``, ``g :: a -> Int``, and ``x :: b``. Using these, we
   must somehow fill in the hole (denoted with an underscore) with a value of
   type ``Int``. What are our options?

   We could try applying ``g`` to ``x``. This won't work though, as ``g``
   expects an argument of type ``a``, and ``x :: b``. Even worse, we can't turn
   ``x`` into something of type ``a``, since ``f`` also needs an argument of
   type ``a``! In short, there's no good way to make this work.

   On the other hand, a derived ``Functor`` instances for the ``CovFun``\ s are
   within the realm of possibility::

       instance Functor CovFun1 where
         fmap f (CovFun1 g) = CovFun1 (\x -> f (g x))

       instance Functor CovFun2 where
         fmap f (CovFun2 g) = CovFun2 (\h -> f (g (\x -> h (f x))))

       instance Functor CovFun3 where
         fmap f (CovFun3 g) = CovFun3 (\h -> f (g (\k -> h (\x -> f (k x)))))

There are some other scenarios in which a derived ``Functor`` instance will
fail to compile:

#. A data type has no type parameters (e.g., ``data Nothing = Nothing``).

#. A data type's last type variable is used in a :extension:`DatatypeContexts`
   constraint (e.g., ``data Ord a => O a = O a``).

#. A data type's last type variable is used in an
   :extension:`ExistentialQuantification` constraint, or is refined in a GADT. For
   example, ::

       data T a b where
           T4 :: Ord b => b -> T a b
           T5 :: b -> T b b
           T6 :: T a (b,b)

       deriving instance Functor (T a)

   would not compile successfully due to the way in which ``b`` is constrained.

When the last type parameter has a phantom role (see :ref:`roles`), the derived
``Functor`` instance will not be produced using the usual algorithm. Instead,
the entire value will be coerced. ::

    data Phantom a = Z | S (Phantom a) deriving Functor

will produce the following instance: ::

    instance Functor Phantom where
      fmap _ = coerce

When a type has no constructors, the derived ``Functor`` instance will
simply force the (bottom) value of the argument using
:extension:`EmptyCase`. ::

    data V a deriving Functor
    type role V nominal

will produce

    instance Functor V where
      fmap _ z = case z of

.. _deriving-foldable:

Deriving ``Foldable`` instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: DeriveFoldable
    :shortdesc: Enable deriving for the Foldable class.
        Implied by :extension:`DeriveTraversable`.

    :since: 7.10.1

    Allow automatic deriving of instances for the ``Foldable`` typeclass.

With :extension:`DeriveFoldable`, one can derive ``Foldable`` instances for data types
of kind ``Type -> Type``. For example, this declaration::

    data Example a = Ex a Char (Example a) (Example Char)
      deriving Foldable

would generate the following instance::

    instance Foldable Example where
      foldr f z (Ex a1 a2 a3 a4) = f a1 (foldr f z a3)
      foldMap f (Ex a1 a2 a3 a4) = mappend (f a1) (foldMap f a3)

The algorithm for :extension:`DeriveFoldable` is adapted from the
:extension:`DeriveFunctor` algorithm, but it generates definitions for
``foldMap``, ``foldr``, and ``null`` instead of ``fmap``. In addition,
:extension:`DeriveFoldable` filters out all constructor arguments on the RHS
expression whose types do not mention the last type parameter, since those
arguments do not need to be folded over.

When the type parameter has a phantom role (see :ref:`roles`),
:extension:`DeriveFoldable` derives a trivial instance. For example, this
declaration: ::

    data Phantom a = Z | S (Phantom a)

will generate the following instance. ::

    instance Foldable Phantom where
      foldMap _ _ = mempty

Similarly, when the type has no constructors, :extension:`DeriveFoldable` will
derive a trivial instance: ::

    data V a deriving Foldable
    type role V nominal

will generate the following. ::

    instance Foldable V where
      foldMap _ _ = mempty

Here are the differences between the generated code for ``Functor`` and
``Foldable``:

#. When a bare type variable ``a`` is encountered, :extension:`DeriveFunctor`
would generate ``f a`` for an ``fmap`` definition. :extension:`DeriveFoldable`
would generate ``f a z`` for ``foldr``, ``f a`` for ``foldMap``, and ``False``
for ``null``.

#. When a type that is not syntactically equivalent to ``a``, but which does
   contain ``a``, is encountered, :extension:`DeriveFunctor` recursively calls
   ``fmap`` on it. Similarly, :extension:`DeriveFoldable` would recursively call
   ``foldr`` and ``foldMap``. Depending on the context, ``null`` may recursively
   call ``null`` or ``all null``. For example, given ::

       data F a = F (P a)
       data G a = G (P (a, Int))
       data H a = H (P (Q a))

   ``Foldable`` deriving will produce ::

       null (F x) = null x
       null (G x) = null x
       null (H x) = all null x

#. :extension:`DeriveFunctor` puts everything back together again at the end by
   invoking the constructor. :extension:`DeriveFoldable`, however, builds up a value
   of some type. For ``foldr``, this is accomplished by chaining applications
   of ``f`` and recursive ``foldr`` calls on the state value ``z``. For
   ``foldMap``, this happens by combining all values with ``mappend``. For ``null``,
   the values are usually combined with ``&&``. However, if any of the values is
   known to be ``False``, all the rest will be dropped. For example, ::

       data SnocList a = Nil | Snoc (SnocList a) a

   will not produce ::

       null (Snoc xs _) = null xs && False

   (which would walk the whole list), but rather ::

       null (Snoc _ _) = False

There are some other differences regarding what data types can have derived
``Foldable`` instances:

#. Data types containing function types on the right-hand side cannot have
   derived ``Foldable`` instances.

#. ``Foldable`` instances can be derived for data types in which the last type
   parameter is existentially constrained or refined in a GADT. For example,
   this data type::

       data E a where
           E1 :: (a ~ Int) => a   -> E a
           E2 ::              Int -> E Int
           E3 :: (a ~ Int) => a   -> E Int
           E4 :: (a ~ Int) => Int -> E a

       deriving instance Foldable E

   would have the following generated ``Foldable`` instance::

       instance Foldable E where
           foldr f z (E1 e) = f e z
           foldr f z (E2 e) = z
           foldr f z (E3 e) = z
           foldr f z (E4 e) = z

           foldMap f (E1 e) = f e
           foldMap f (E2 e) = mempty
           foldMap f (E3 e) = mempty
           foldMap f (E4 e) = mempty

   Notice how every constructor of ``E`` utilizes some sort of existential
   quantification, but only the argument of ``E1`` is actually "folded over".
   This is because we make a deliberate choice to only fold over universally
   polymorphic types that are syntactically equivalent to the last type
   parameter. In particular:

  -  We don't fold over the arguments of ``E1`` or ``E4`` because even though
     ``(a ~ Int)``, ``Int`` is not syntactically equivalent to ``a``.

  -  We don't fold over the argument of ``E3`` because ``a`` is not universally
     polymorphic. The ``a`` in ``E3`` is (implicitly) existentially quantified,
     so it is not the same as the last type parameter of ``E``.

.. _deriving-traversable:

Deriving ``Traversable`` instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


.. extension:: DeriveTraversable
    :shortdesc: Enable deriving for the Traversable class.
        Implies :extension:`DeriveFunctor` and :extension:`DeriveFoldable`.

    :implies: :extension:`DeriveFoldable`, :extension:`DeriveFunctor`
    :since: 7.10.1

    Allow automatic deriving of instances for the ``Traversable`` typeclass.

With :extension:`DeriveTraversable`, one can derive ``Traversable`` instances for data
types of kind ``Type -> Type``. For example, this declaration::

    data Example a = Ex a Char (Example a) (Example Char)
      deriving (Functor, Foldable, Traversable)

would generate the following ``Traversable`` instance::

    instance Traversable Example where
      traverse f (Ex a1 a2 a3 a4)
        = fmap (\b1 b3 -> Ex b1 a2 b3 a4) (f a1) <*> traverse f a3

The algorithm for :extension:`DeriveTraversable` is adapted from the
:extension:`DeriveFunctor` algorithm, but it generates a definition for ``traverse``
instead of ``fmap``. In addition, :extension:`DeriveTraversable` filters out
all constructor arguments on the RHS expression whose types do not mention the
last type parameter, since those arguments do not produce any effects in a
traversal.

When the type parameter has a phantom role (see :ref:`roles`),
:extension:`DeriveTraversable` coerces its argument. For example, this
declaration::

    data Phantom a = Z | S (Phantom a) deriving Traversable

will generate the following instance::

    instance Traversable Phantom where
      traverse _ z = pure (coerce z)

When the type has no constructors, :extension:`DeriveTraversable` will
derive the laziest instance it can. ::

    data V a deriving Traversable
    type role V nominal

will generate the following, using :extension:`EmptyCase`: ::

    instance Traversable V where
      traverse _ z = pure (case z of)

Here are the differences between the generated code in each
extension:

#. When a bare type variable ``a`` is encountered, both :extension:`DeriveFunctor` and
   :extension:`DeriveTraversable` would generate ``f a`` for an ``fmap`` and
   ``traverse`` definition, respectively.

#. When a type that is not syntactically equivalent to ``a``, but which does
   contain ``a``, is encountered, :extension:`DeriveFunctor` recursively calls
   ``fmap`` on it. Similarly, :extension:`DeriveTraversable` would recursively call
   ``traverse``.

#. :extension:`DeriveFunctor` puts everything back together again at the end by
   invoking the constructor. :extension:`DeriveTraversable` does something similar,
   but it works in an ``Applicative`` context by chaining everything together
   with ``(<*>)``.

Unlike :extension:`DeriveFunctor`, :extension:`DeriveTraversable` cannot be used on data
types containing a function type on the right-hand side.

For a full specification of the algorithms used in :extension:`DeriveFunctor`,
:extension:`DeriveFoldable`, and :extension:`DeriveTraversable`, see
:ghc-wiki:`this wiki page <commentary/compiler/derive-functor>`.

.. _deriving-data:

Deriving ``Data`` instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: DeriveDataTypeable
    :shortdesc: Enable deriving for the Data class.
       Implied by (deprecated) :extension:`AutoDeriveTypeable`.

    :since: 6.8.1

    Enable automatic deriving of instances for the ``Data`` typeclass

.. _deriving-typeable:

Deriving ``Typeable`` instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The class ``Typeable`` is very special:

-  ``Typeable`` is kind-polymorphic (see :ref:`kind-polymorphism`).

-  GHC has a custom solver for discharging constraints that involve
   class ``Typeable``, and handwritten instances are forbidden. This
   ensures that the programmer cannot subvert the type system by writing
   bogus instances.

-  Derived instances of ``Typeable`` may be declared if the
   :extension:`DeriveDataTypeable` extension is enabled, but they are ignored,
   and they may be reported as an error in a later version of the compiler.

-  The rules for solving \`Typeable\` constraints are as follows:

   -  A concrete type constructor applied to some types. ::

          instance (Typeable t1, .., Typeable t_n) =>
            Typeable (T t1 .. t_n)

      This rule works for any concrete type constructor, including type
      constructors with polymorphic kinds. The only restriction is that
      if the type constructor has a polymorphic kind, then it has to be
      applied to all of its kinds parameters, and these kinds need to be
      concrete (i.e., they cannot mention kind variables).

   -  A type variable applied to some types::

          instance (Typeable f, Typeable t1, .., Typeable t_n) =>
            Typeable (f t1 .. t_n)

   -  A concrete type literal.::

          instance Typeable 0       -- Type natural literals
          instance Typeable "Hello" -- Type-level symbols

.. _deriving-lift:

Deriving ``Lift`` instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: DeriveLift
    :shortdesc: Enable deriving for the Lift class

    :since: 8.0.1

    Enable automatic deriving of instances for the ``Lift`` typeclass for
    Template Haskell.

The class ``Lift``, unlike other derivable classes, lives in
``template-haskell`` instead of ``base``. Having a data type be an instance of
``Lift`` permits its values to be promoted to Template Haskell expressions (of
type ``ExpQ`` and ``TExpQ a``), which can then be spliced into Haskell source
code.

Here is an example of how one can derive ``Lift``:

::

    {-# LANGUAGE DeriveLift #-}
    module Bar where

    import Language.Haskell.TH.Syntax

    data Foo a = Foo a | a :^: a deriving Lift

    {-
    instance (Lift a) => Lift (Foo a) where
        lift (Foo a) = [| Foo a |]
        lift ((:^:) u v) = [| (:^:) u v |]

        liftTyped (Foo a) = [|| Foo a ||]
        liftTyped ((:^:) u v) = [|| (:^:) u v ||]
    -}

    -----
    {-# LANGUAGE TemplateHaskell #-}
    module Baz where

    import Bar
    import Language.Haskell.TH.Lift

    foo :: Foo String
    foo = $(lift $ Foo "foo")

    fooExp :: Lift a => Foo a -> Q Exp
    fooExp f = [| f |]

Note that the ``Lift`` typeclass takes advantage of :ref:`runtime-rep` in order
to support instances involving unboxed types. This means :extension:`DeriveLift`
also works for these types:

::

    {-# LANGUAGE DeriveLift, MagicHash #-}
    module Unboxed where

    import GHC.Exts
    import Language.Haskell.TH.Syntax

    data IntHash = IntHash Int# deriving Lift

    {-
    instance Lift IntHash where
        lift (IntHash i) = [| IntHash i |]
        liftTyped (IntHash i) = [|| IntHash i ||]
    -}


.. _newtype-deriving:

Generalised derived instances for newtypes
------------------------------------------

.. extension:: GeneralisedNewtypeDeriving
               GeneralizedNewtypeDeriving
    :shortdesc: Enable newtype deriving.

    :since: 6.8.1. British spelling since 8.6.1.

    Enable GHC's cunning generalised deriving mechanism for ``newtype``\s

When you define an abstract type using ``newtype``, you may want the new
type to inherit some instances from its representation. In Haskell 98,
you can inherit instances of ``Eq``, ``Ord``, ``Enum`` and ``Bounded``
by deriving them, but for any other classes you have to write an
explicit instance declaration. For example, if you define ::

      newtype Dollars = Dollars Int

and you want to use arithmetic on ``Dollars``, you have to explicitly
define an instance of ``Num``: ::

      instance Num Dollars where
        Dollars a + Dollars b = Dollars (a+b)
        ...

All the instance does is apply and remove the ``newtype`` constructor.
It is particularly galling that, since the constructor doesn't appear at
run-time, this instance declaration defines a dictionary which is
*wholly equivalent* to the ``Int`` dictionary, only slower!

:extension:`DerivingVia` (see :ref:`deriving-via`) is a generalization of
this idea.

.. _generalized-newtype-deriving:

Generalising the deriving clause
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GHC now permits such instances to be derived instead, using the extension
:extension:`GeneralizedNewtypeDeriving`, so one can write ::

      newtype Dollars = Dollars { getDollars :: Int } deriving (Eq,Show,Num)

and the implementation uses the *same* ``Num`` dictionary for
``Dollars`` as for ``Int``. In other words, GHC will generate something that
resembles the following code ::

      instance Num Int => Num Dollars

and then attempt to simplify the ``Num Int`` context as much as possible.
GHC knows that there is a ``Num Int`` instance in scope, so it is able to
discharge the ``Num Int`` constraint, leaving the code that GHC actually
generates ::

      instance Num Dollars

One can think of this instance being implemented with the same code as the
``Num Int`` instance, but with ``Dollars`` and ``getDollars`` added wherever
necessary in order to make it typecheck. (In practice, GHC uses a somewhat
different approach to code generation. See the :ref:`precise-gnd-specification`
section below for more details.)

We can also derive instances of constructor classes in a similar way.
For example, suppose we have implemented state and failure monad
transformers, such that ::

      instance Monad m => Monad (State s m)
      instance Monad m => Monad (Failure m)

In Haskell 98, we can define a parsing monad by ::

      type Parser tok m a = State [tok] (Failure m) a

which is automatically a monad thanks to the instance declarations
above. With the extension, we can make the parser type abstract, without
needing to write an instance of class ``Monad``, via ::

      newtype Parser tok m a = Parser (State [tok] (Failure m) a)
                             deriving Monad

In this case the derived instance declaration is of the form ::

      instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)

Notice that, since ``Monad`` is a constructor class, the instance is a
*partial application* of the newtype, not the entire left hand side. We
can imagine that the type declaration is "eta-converted" to generate the
context of the instance declaration.

We can even derive instances of multi-parameter classes, provided the
newtype is the last class parameter. In this case, a "partial
application" of the class appears in the ``deriving`` clause. For
example, given the class ::

      class StateMonad s m | m -> s where ...
      instance Monad m => StateMonad s (State s m) where ...

then we can derive an instance of ``StateMonad`` for ``Parser`` by ::

      newtype Parser tok m a = Parser (State [tok] (Failure m) a)
                             deriving (Monad, StateMonad [tok])

The derived instance is obtained by completing the application of the
class to the new type: ::

      instance StateMonad [tok] (State [tok] (Failure m)) =>
               StateMonad [tok] (Parser tok m)

As a result of this extension, all derived instances in newtype
declarations are treated uniformly (and implemented just by reusing the
dictionary for the representation type), *except* ``Show`` and ``Read``,
which really behave differently for the newtype and its representation.

.. note::

    It is sometimes necessary to enable additional language extensions when
    deriving instances via :extension:`GeneralizedNewtypeDeriving`. For instance,
    consider a simple class and instance using :extension:`UnboxedTuples`
    syntax: ::

        {-# LANGUAGE UnboxedTuples #-}

        module Lib where

        class AClass a where
          aMethod :: a -> (# Int, a #)

        instance AClass Int where
          aMethod x = (# x, x #)

    The following will fail with an "Illegal unboxed tuple" error, since the
    derived instance produced by the compiler makes use of unboxed tuple syntax,
    ::

        {-# LANGUAGE GeneralizedNewtypeDeriving #-}

        import Lib

        newtype Int' = Int' Int
                     deriving (AClass)

    However, enabling the :extension:`UnboxedTuples` extension allows the module
    to compile. Similar errors may occur with a variety of extensions,
    including:

      * :extension:`UnboxedTuples`
      * :extension:`PolyKinds`
      * :extension:`MultiParamTypeClasses`
      * :extension:`FlexibleContexts`

.. _precise-gnd-specification:

A more precise specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A derived instance is derived only for declarations of these forms
(after expansion of any type synonyms) ::

      newtype T v1..vn                   = MkT (t vk+1..vn) deriving (C t1..tj)
      newtype instance T s1..sk vk+1..vn = MkT (t vk+1..vn) deriving (C t1..tj)

where

-  ``v1..vn`` are type variables, and ``t``, ``s1..sk``, ``t1..tj`` are
   types.

-  The ``(C t1..tj)`` is a partial applications of the class ``C``,
   where the arity of ``C`` is exactly ``j+1``. That is, ``C`` lacks
   exactly one type argument.

-  ``k`` is chosen so that ``C t1..tj (T v1...vk)`` is well-kinded. (Or,
   in the case of a ``data instance``, so that ``C t1..tj (T s1..sk)``
   is well kinded.)

-  The type ``t`` is an arbitrary type.

-  The type variables ``vk+1...vn`` do not occur in the types ``t``,
   ``s1..sk``, or ``t1..tj``.

-  ``C`` is not ``Read``, ``Show``, ``Typeable``, or ``Data``. These
   classes should not "look through" the type or its constructor. You
   can still derive these classes for a newtype, but it happens in the
   usual way, not via this new mechanism. Confer with
   :ref:`default-deriving-strategy`.

-  It is safe to coerce each of the methods of ``C``. That is, the
   missing last argument to ``C`` is not used at a nominal role in any
   of the ``C``'s methods. (See :ref:`roles`.)

- ``C`` is allowed to have associated type families, provided they meet the
  requirements laid out in the section on :ref:`GND and associated types
  <gnd-and-associated-types>`.

Then the derived instance declaration is of the form ::

      instance C t1..tj t => C t1..tj (T v1...vk)

Note that if ``C`` does not contain any class methods, the instance context
is wholly unnecessary, and as such GHC will instead generate: ::

      instance C t1..tj (T v1..vk)

As an example which does *not* work, consider ::

      newtype NonMonad m s = NonMonad (State s m s) deriving Monad

Here we cannot derive the instance ::

      instance Monad (State s m) => Monad (NonMonad m)

because the type variable ``s`` occurs in ``State s m``, and so cannot
be "eta-converted" away. It is a good thing that this ``deriving``
clause is rejected, because ``NonMonad m`` is not, in fact, a monad ---
for the same reason. Try defining ``>>=`` with the correct type: you
won't be able to.

Notice also that the *order* of class parameters becomes important,
since we can only derive instances for the last one. If the
``StateMonad`` class above were instead defined as ::

      class StateMonad m s | m -> s where ...

then we would not have been able to derive an instance for the
``Parser`` type above. We hypothesise that multi-parameter classes
usually have one "main" parameter for which deriving new instances is
most interesting.

Lastly, all of this applies only for classes other than ``Read``,
``Show``, ``Typeable``, and ``Data``, for which the stock derivation
applies (section 4.3.3. of the Haskell Report). (For the standard
classes ``Eq``, ``Ord``, ``Ix``, and ``Bounded`` it is immaterial
whether the stock method is used or the one described here.)

.. _gnd-and-associated-types:

Associated type families
~~~~~~~~~~~~~~~~~~~~~~~~

:extension:`GeneralizedNewtypeDeriving` also works for some type classes with
associated type families. Here is an example: ::

      class HasRing a where
        type Ring a

      newtype L1Norm a = L1Norm a
        deriving HasRing

The derived ``HasRing`` instance would look like ::

      instance HasRing (L1Norm a) where
        type Ring (L1Norm a) = Ring a

To be precise, if the class being derived is of the form ::

      class C c_1 c_2 ... c_m where
        type T1 t1_1 t1_2 ... t1_n
        ...
        type Tk tk_1 tk_2 ... tk_p

and the newtype is of the form ::

      newtype N n_1 n_2 ... n_q = MkN <rep-type>

then you can derive a ``C c_1 c_2 ... c_(m-1)`` instance for
``N n_1 n_2 ... n_q``, provided that:

- The type parameter ``c_m`` occurs once in each of the type variables of
  ``T1`` through ``Tk``. Imagine a class where this condition didn't hold.
  For example: ::

      class Bad a b where
        type B a

      instance Bad Int a where
        type B Int = Char

      newtype Foo a = Foo a
        deriving (Bad Int)

  For the derived ``Bad Int`` instance, GHC would need to generate something
  like this: ::

      instance Bad Int (Foo a) where
        type B Int = B ???

  Now we're stuck, since we have no way to refer to ``a`` on the right-hand
  side of the ``B`` family instance, so this instance doesn't really make sense
  in a :extension:`GeneralizedNewtypeDeriving` setting.

- ``C`` does not have any associated data families (only type families). To
  see why data families are forbidden, imagine the following scenario: ::

      class Ex a where
        data D a

      instance Ex Int where
        data D Int = DInt Bool

      newtype Age = MkAge Int deriving Ex

  For the derived ``Ex`` instance, GHC would need to generate something like
  this: ::

      instance Ex Age where
        data D Age = ???

  But it is not clear what GHC would fill in for ``???``, as each data family
  instance must generate fresh data constructors.

If both of these conditions are met, GHC will generate this instance: ::

      instance C c_1 c_2 ... c_(m-1) <rep-type> =>
               C c_1 c_2 ... c_(m-1) (N n_1 n_2 ... n_q) where
        type T1 t1_1 t1_2 ... (N n_1 n_2 ... n_q) ... t1_n
           = T1 t1_1 t1_2 ... <rep-type>          ... t1_n
        ...
        type Tk tk_1 tk_2 ... (N n_1 n_2 ... n_q) ... tk_p
           = Tk tk_1 tk_2 ... <rep-type>          ... tk_p

Again, if ``C`` contains no class methods, the instance context will be
redundant, so GHC will instead generate
``instance C c_1 c_2 ... c_(m-1) (N n_1 n_2 ... n_q)``.

Beware that in some cases, you may need to enable the
:extension:`UndecidableInstances` extension in order to use this feature.
Here's a pathological case that illustrates why this might happen: ::

      class C a where
        type T a

      newtype Loop = MkLoop Loop
        deriving C

This will generate the derived instance: ::

      instance C Loop where
        type T Loop = T Loop

Here, it is evident that attempting to use the type ``T Loop`` will throw the
typechecker into an infinite loop, as its definition recurses endlessly. In
other cases, you might need to enable :extension:`UndecidableInstances` even
if the generated code won't put the typechecker into a loop. For example: ::

      instance C Int where
        type C Int = Int

      newtype MyInt = MyInt Int
        deriving C

This will generate the derived instance: ::

      instance C MyInt where
        type T MyInt = T Int

Although typechecking ``T MyInt`` will terminate, GHC's termination checker
isn't sophisticated enough to determine this, so you'll need to enable
:extension:`UndecidableInstances` in order to use this derived instance. If
you do go down this route, make sure you can convince yourself that all of
the type family instances you're deriving will eventually terminate if used!

Note that :extension:`DerivingVia` (see :ref:`deriving-via`) uses essentially
the same specification to derive instances of associated type families as well
(except that it uses the ``via`` type instead of the underlying ``rep-type``
of a newtype).

.. _derive-any-class:

Deriving any other class
------------------------

.. extension:: DeriveAnyClass
    :shortdesc: Enable deriving for any class.

    :since: 7.10.1

    Allow use of any typeclass in ``deriving`` clauses.

With :extension:`DeriveAnyClass` you can derive any other class. The compiler
will simply generate an instance declaration with no explicitly-defined
methods.
This is
mostly useful in classes whose `minimal set <#minimal-pragma>`__ is
empty, and especially when writing
`generic functions <#generic-programming>`__.

As an example, consider a simple pretty-printer class ``SPretty``, which outputs
pretty strings: ::

    {-# LANGUAGE DefaultSignatures, DeriveAnyClass #-}

    class SPretty a where
      sPpr :: a -> String
      default sPpr :: Show a => a -> String
      sPpr = show

If a user does not provide a manual implementation for ``sPpr``, then it will
default to ``show``. Now we can leverage the :extension:`DeriveAnyClass` extension to
easily implement a ``SPretty`` instance for a new data type: ::

    data Foo = Foo deriving (Show, SPretty)

The above code is equivalent to: ::

    data Foo = Foo deriving Show
    instance SPretty Foo

That is, an ``SPretty Foo`` instance will be created with empty implementations
for all methods. Since we are using :extension:`DefaultSignatures` in this example, a
default implementation of ``sPpr`` is filled in automatically.

Note the following details

- In case you try to derive some
  class on a newtype, and :extension:`GeneralizedNewtypeDeriving` is also on,
  :extension:`DeriveAnyClass` takes precedence.

- The instance context is determined by the type signatures of the derived
  class's methods. For instance, if the class is: ::

    class Foo a where
      bar :: a -> String
      default bar :: Show a => a -> String
      bar = show

      baz :: a -> a -> Bool
      default baz :: Ord a => a -> a -> Bool
      baz x y = compare x y == EQ

  And you attempt to derive it using :extension:`DeriveAnyClass`: ::

    instance Eq   a => Eq   (Option a) where ...
    instance Ord  a => Ord  (Option a) where ...
    instance Show a => Show (Option a) where ...

    data Option a = None | Some a deriving Foo

  Then the derived ``Foo`` instance will be: ::

    instance (Show a, Ord a) => Foo (Option a)

  Since the default type signatures for ``bar`` and ``baz`` require ``Show a``
  and ``Ord a`` constraints, respectively.

  Constraints on the non-default type signatures can play a role in inferring
  the instance context as well. For example, if you have this class: ::

    class HigherEq f where
      (==#) :: f a -> f a -> Bool
      default (==#) :: Eq (f a) => f a -> f a -> Bool
      x ==# y = (x == y)

  And you tried to derive an instance for it: ::

    instance Eq a => Eq (Option a) where ...
    data Option a = None | Some a deriving HigherEq

  Then it will fail with an error to the effect of: ::

    No instance for (Eq a)
        arising from the 'deriving' clause of a data type declaration

  That is because we require an ``Eq (Option a)`` instance from the default
  type signature for ``(==#)``, which in turn requires an ``Eq a`` instance,
  which we don't have in scope. But if you tweak the definition of
  ``HigherEq`` slightly: ::

    class HigherEq f where
      (==#) :: Eq a => f a -> f a -> Bool
      default (==#) :: Eq (f a) => f a -> f a -> Bool
      x ==# y = (x == y)

  Then it becomes possible to derive a ``HigherEq Option`` instance. Note that
  the only difference is that now the non-default type signature for ``(==#)``
  brings in an ``Eq a`` constraint. Constraints from non-default type
  signatures never appear in the derived instance context itself, but they can
  be used to discharge obligations that are demanded by the default type
  signatures. In the example above, the default type signature demanded an
  ``Eq a`` instance, and the non-default signature was able to satisfy that
  request, so the derived instance is simply: ::

    instance HigherEq Option

- :extension:`DeriveAnyClass` can be used with partially applied classes,
  such as ::

    data T a = MKT a deriving( D Int )

  which generates ::

    instance D Int a => D Int (T a) where {}

- :extension:`DeriveAnyClass` can be used to fill in default instances for
  associated type families: ::

    {-# LANGUAGE DeriveAnyClass, TypeFamilies #-}

    class Sizable a where
      type Size a
      type Size a = Int

    data Bar = Bar deriving Sizable

    doubleBarSize :: Size Bar -> Size Bar
    doubleBarSize s = 2*s

  The ``deriving( Sizable )`` is equivalent to saying ::

    instance Sizeable Bar where {}

  and then the normal rules for filling in associated types from the
  default will apply, making ``Size Bar`` equal to ``Int``.

.. _deriving-strategies:

Deriving strategies
-------------------

.. extension:: DerivingStrategies
    :shortdesc: Enables deriving strategies.

    :since: 8.2.1

    Allow multiple ``deriving``, each optionally qualified with a *strategy*.

In most scenarios, every ``deriving`` statement generates a typeclass instance
in an unambiguous fashion. There is a corner case, however, where
simultaneously enabling both the :extension:`GeneralizedNewtypeDeriving` and
:extension:`DeriveAnyClass` extensions can make deriving become ambiguous.
Consider the following example ::

    {-# LANGUAGE DeriveAnyClass, GeneralizedNewtypeDeriving #-}
    newtype Foo = MkFoo Bar deriving C

One could either pick the ``DeriveAnyClass`` approach to deriving ``C`` or the
``GeneralizedNewtypeDeriving`` approach to deriving ``C``, both of which would
be equally as valid. GHC defaults to favoring ``DeriveAnyClass`` in such a
dispute, but this is not a satisfying solution, since that leaves users unable
to use both language extensions in a single module.

To make this more robust, GHC has a notion of deriving strategies, which allow
the user to explicitly request which approach to use when deriving an instance.
To enable this feature, one must enable the :extension:`DerivingStrategies`
language extension. A deriving strategy can be specified in a deriving
clause ::

    newtype Foo = MkFoo Bar
      deriving newtype C

Or in a standalone deriving declaration ::

    deriving anyclass instance C Foo

:extension:`DerivingStrategies` also allows the use of multiple deriving
clauses per data declaration so that a user can derive some instance with
one deriving strategy and other instances with another deriving strategy.
For example ::

    newtype Baz = Baz Quux
      deriving          (Eq, Ord)
      deriving stock    (Read, Show)
      deriving newtype  (Num, Floating)
      deriving anyclass C

Currently, the deriving strategies are:

- ``stock``: Have GHC implement a "standard" instance for a data type,
  if possible (e.g., ``Eq``, ``Ord``, ``Generic``, ``Data``, ``Functor``, etc.)

- ``anyclass``: Use :extension:`DeriveAnyClass` (see :ref:`derive-any-class`)

- ``newtype``: Use :extension:`GeneralizedNewtypeDeriving`
               (see :ref:`newtype-deriving`)

- ``via``: Use :extension:`DerivingVia` (see :ref:`deriving-via`)

.. _default-deriving-strategy:

Default deriving strategy
~~~~~~~~~~~~~~~~~~~~~~~~~

If an explicit deriving strategy is not given, multiple strategies may apply.
In that case, GHC chooses the strategy as follows:

1. Stock type classes, i.e. those specified in the report and those enabled by
   `language extensions <#deriving-extra>`__, are derived using the ``stock``
   strategy, with the following exception:

   * For newtypes, ``Eq``, ``Ord``, ``Ix`` and ``Bounded`` are always derived
     using the ``newtype`` strategy, even without
     ``GeneralizedNewtypeDeriving`` enabled. (There should be no observable
     difference to instances derived using the stock strategy.)

   * Also for newtypes, ``Functor``, ``Foldable`` and ``Enum`` are derived
     using the ``newtype`` strategy if ``GeneralizedNewtypeDeriving`` is
     enabled and the derivation succeeds.

2. For other any type class:

   1. When ``DeriveAnyClass`` is enabled, use ``anyclass``.

   2. When ``GeneralizedNewtypeDeriving`` is enabled and we are deriving for a
      newtype, then use ``newytype``.

   If both rules apply to a deriving clause, then ``anyclass`` is used and the
   user is warned about the ambiguity. The warning can be avoided by explicitly
   stating the desired deriving strategy.

.. _deriving-via:

Deriving via
------------

.. extension:: DerivingVia
    :shortdesc: Enable deriving instances ``via`` types of the same runtime
        representation.
        Implies :extension:`DerivingStrategies`.

    :implies: :extension:`DerivingStrategies`

    :since: 8.6.1

This allows ``deriving`` a class instance for a type by specifying
another type of equal runtime representation (such that there exists a
``Coercible`` instance between the two: see :ref:`coercible`) that is
already an instance of the that class.

:extension:`DerivingVia` is indicated by the use of the ``via``
deriving strategy. ``via`` requires specifying another type (the ``via`` type)
to ``coerce`` through. For example, this code: ::

    {-# LANGUAGE DerivingVia #-}

    import Numeric

    newtype Hex a = Hex a

    instance (Integral a, Show a) => Show (Hex a) where
      show (Hex a) = "0x" ++ showHex a ""

    newtype Unicode = U Int
      deriving Show
        via (Hex Int)

    -- >>> euroSign
    -- 0x20ac
    euroSign :: Unicode
    euroSign = U 0x20ac

Generates the following instance ::

    instance Show Unicode where
      show :: Unicode -> String
      show = Data.Coerce.coerce
        @(Hex Int -> String)
        @(Unicode -> String)
        show

This extension generalizes :extension:`GeneralizedNewtypeDeriving`. To
derive ``Num Unicode`` with GND (``deriving newtype Num``) it must
reuse the ``Num Int`` instance. With ``DerivingVia``, we can explicitly
specify the representation type ``Int``: ::

    newtype Unicode = U Int
      deriving Num
        via Int

      deriving Show
        via (Hex Int)

    euroSign :: Unicode
    euroSign = 0x20ac

Code duplication is common in instance declarations. A familiar
pattern is lifting operations over an ``Applicative`` functor.
Instead of having catch-all instances for ``f a`` which overlap
with all other such instances, like so: ::

    instance (Applicative f, Semigroup a) => Semigroup (f a) ..
    instance (Applicative f, Monoid    a) => Monoid    (f a) ..

We can instead create a newtype ``App``
(where ``App f a`` and ``f a`` are represented the same in memory)
and use :extension:`DerivingVia` to explicitly enable uses of this
pattern: ::

    {-# LANGUAGE DerivingVia, DeriveFunctor, GeneralizedNewtypeDeriving #-}

    import Control.Applicative

    newtype App f a = App (f a) deriving newtype (Functor, Applicative)

    instance (Applicative f, Semigroup a) => Semigroup (App f a) where
      (<>) = liftA2 (<>)

    instance (Applicative f, Monoid a) => Monoid (App f a) where
      mempty = pure mempty

    data Pair a = MkPair a a
      deriving stock
        Functor

      deriving (Semigroup, Monoid)
        via (App Pair a)

    instance Applicative Pair where
      pure a = MkPair a a

      MkPair f g <*> MkPair a b = MkPair (f a) (g b)

Note that the ``via`` type does not have to be a ``newtype``.
The only restriction is that it is coercible with the
original data type. This means there can be arbitrary nesting of newtypes,
as in the following example: ::

    newtype Kleisli m a b = (a -> m b)
      deriving (Semigroup, Monoid)
        via (a -> App m b)

Here we make use of the ``Monoid ((->) a)`` instance.

When used in combination with :extension:`StandaloneDeriving` we swap the order
for the instance we base our derivation on and the instance we define e.g.: ::

  deriving via (a -> App m b) instance Monoid (Kleisli m a b)


.. _pattern-synonyms:

Pattern synonyms
================

.. extension:: PatternSynonyms
    :shortdesc: Enable pattern synonyms.

    :since: 7.8.1

    Allow the definition of pattern synonyms.

Pattern synonyms are enabled by the language extension :extension:`PatternSynonyms`, which is
required for defining them, but *not* for using them. More information and
examples of pattern synonyms can be found on the :ghc-wiki:`Wiki page <pattern-synonyms>`.

Pattern synonyms enable giving names to parametrized pattern schemes.
They can also be thought of as abstract constructors that don't have a
bearing on data representation. For example, in a programming language
implementation, we might represent types of the language as follows: ::

    data Type = App String [Type]

Here are some examples of using said representation. Consider a few
types of the ``Type`` universe encoded like this: ::

      App "->" [t1, t2]          -- t1 -> t2
      App "Int" []               -- Int
      App "Maybe" [App "Int" []] -- Maybe Int

This representation is very generic in that no types are given special
treatment. However, some functions might need to handle some known types
specially, for example the following two functions collect all argument
types of (nested) arrow types, and recognize the ``Int`` type,
respectively: ::

      collectArgs :: Type -> [Type]
      collectArgs (App "->" [t1, t2]) = t1 : collectArgs t2
      collectArgs _                   = []

      isInt :: Type -> Bool
      isInt (App "Int" []) = True
      isInt _              = False

Matching on ``App`` directly is both hard to read and error prone to
write. And the situation is even worse when the matching is nested: ::

      isIntEndo :: Type -> Bool
      isIntEndo (App "->" [App "Int" [], App "Int" []]) = True
      isIntEndo _                                       = False

Pattern synonyms permit abstracting from the representation to expose
matchers that behave in a constructor-like manner with respect to
pattern matching. We can create pattern synonyms for the known types we
care about, without committing the representation to them (note that
these don't have to be defined in the same module as the ``Type`` type): ::

      pattern Arrow t1 t2 = App "->"    [t1, t2]
      pattern Int         = App "Int"   []
      pattern Maybe t     = App "Maybe" [t]

Which enables us to rewrite our functions in a much cleaner style: ::

      collectArgs :: Type -> [Type]
      collectArgs (Arrow t1 t2) = t1 : collectArgs t2
      collectArgs _             = []

      isInt :: Type -> Bool
      isInt Int = True
      isInt _   = False

      isIntEndo :: Type -> Bool
      isIntEndo (Arrow Int Int) = True
      isIntEndo _               = False

In general there are three kinds of pattern synonyms. Unidirectional,
bidirectional and explicitly bidirectional. The examples given so far are
examples of bidirectional pattern synonyms. A bidirectional synonym
behaves the same as an ordinary data constructor. We can use it in a pattern
context to deconstruct values and in an expression context to construct values.
For example, we can construct the value `intEndo` using the pattern synonyms
`Arrow` and `Int` as defined previously. ::

      intEndo :: Type
      intEndo = Arrow Int Int

This example is equivalent to the much more complicated construction if we had
directly used the `Type` constructors. ::

      intEndo :: Type
      intEndo = App "->" [App "Int" [], App "Int" []]


Unidirectional synonyms can only be used in a pattern context and are
defined as follows:


::

      pattern Head x <- x:xs

In this case, ``Head`` ⟨x⟩ cannot be used in expressions, only patterns,
since it wouldn't specify a value for the ⟨xs⟩ on the right-hand side. However,
we can define an explicitly bidirectional pattern synonym by separately
specifying how to construct and deconstruct a type. The syntax for
doing this is as follows:

::

      pattern HeadC x <- x:xs where
        HeadC x = [x]

We can then use ``HeadC`` in both expression and pattern contexts. In a pattern
context it will match the head of any list with length at least one. In an
expression context it will construct a singleton list.

Explicitly bidirectional pattern synonyms offer greater flexibility than
implicitly bidirectional ones in terms of the syntax that is permitted. For
instance, the following is not a legal implicitly bidirectional pattern
synonym: ::

      pattern StrictJust a = Just !a

This is illegal because the use of :extension:`BangPatterns` on the right-hand
sides prevents it from being a well formed expression. However, constructing a
strict pattern synonym is quite possible with an explicitly bidirectional
pattern synonym: ::

      pattern StrictJust a <- Just !a where
        StrictJust !a = Just a

Constructing an explicitly bidirectional pattern synonym also:

- can create different data constructors from the underlying data type,
  not just the one appearing in the pattern match;

- can call any functions or conditional logic, especially validation,
  of course providing it constructs a result of the right type;

- can use guards on the lhs of the ``=``;

- can have multiple equations.

For example: ::

      data PosNeg = Pos Int | Neg Int
      pattern Smarter{ nonneg } <- Pos nonneg  where
        Smarter x = if x >= 0 then (Pos x) else (Neg x)

Or using guards: ::

      pattern Smarter{ nonneg } <- Pos nonneg  where
        Smarter x | x >= 0    = (Pos x)
                  | otherwise = (Neg x)

There is an extensive Haskell folk art of `smart constructors
<https://wiki.haskell.org/Smart_constructor>`_,
essentially functions that wrap validation around a constructor,
and avoid exposing its representation.
The downside is that the underlying constructor can't be used as a matcher.
Pattern synonyms can be used as genuinely smart constructors, for both validation and matching.

The table below summarises where each kind of pattern synonym can be used.

+---------------+----------------+---------------+---------------------------+
| Context       | Unidirectional | Bidirectional | Explicitly Bidirectional  |
+===============+================+===============+===========================+
| Pattern       | Yes            | Yes           | Yes                       |
+---------------+----------------+---------------+---------------------------+
| Expression    | No             | Yes (Inferred)| Yes (Explicit)            |
+---------------+----------------+---------------+---------------------------+

.. _record-patsyn:

Record Pattern Synonyms
-----------------------

It is also possible to define pattern synonyms which behave just like record
constructors. The syntax for doing this is as follows:

::

      pattern Point :: Int -> Int -> (Int, Int)
      pattern Point{x, y} = (x, y)

The idea is that we can then use ``Point`` just as if we had defined a new
datatype ``MyPoint`` with two fields ``x`` and ``y``.

::

    data MyPoint = Point { x :: Int, y :: Int }

Whilst a normal pattern synonym can be used in two ways, there are then seven
ways in which to use ``Point``. Precisely the ways in which a normal record
constructor can be used.

=======================================   ==================================
Usage                                     Example
=======================================   ==================================
As a constructor                          ``zero = Point 0 0``
As a constructor with record syntax       ``zero = Point { x = 0, y = 0}``
In a pattern context                      ``isZero (Point 0 0) = True``
In a pattern context with record syntax   ``isZero (Point { x = 0, y = 0 }``
In a pattern context with field puns      ``getX (Point {x}) = x``
In a record update                        ``(0, 0) { x = 1 } == (1,0)``
Using record selectors                    ``x (0,0) == 0``
=======================================   ==================================

For a unidirectional record pattern synonym we define record selectors but do
not allow record updates or construction.

The syntax and semantics of pattern synonyms are elaborated in the
following subsections.
There are also lots more details in the `paper
<https://www.microsoft.com/en-us/research/wp-content/uploads/2016/08/pattern-synonyms-Haskell16.pdf>`_.

See the :ghc-wiki:`Wiki page <pattern-synonyms>` for more
details.

Syntax and scoping of pattern synonyms
--------------------------------------

A pattern synonym declaration can be either unidirectional,
bidirectional or explicitly bidirectional.
The syntax for unidirectional pattern synonyms is: ::

      pattern pat_lhs <- pat

the syntax for bidirectional pattern synonyms is: ::

      pattern pat_lhs = pat

and the syntax for explicitly bidirectional pattern synonyms is: ::

      pattern pat_lhs <- pat where
        pat_lhs = expr                      -- lhs restricted, see below

We can define either prefix, infix or record pattern synonyms by modifying
the form of `pat_lhs`. The syntax for these is as follows:

======= ============================
Prefix  ``Name args``
------- ----------------------------
Infix   ``arg1 `Name` arg2``
        or ``arg1 op arg2``
------- ----------------------------
Record  ``Name{arg1,arg2,...,argn}``
======= ============================

The `pat_lhs` for explicitly bidirectional construction cannot use Record syntax.
(Because the rhs *expr* might be constructing different data constructors.)
It can use guards with multiple equations.

Pattern synonym declarations can only occur in the top level of a
module. In particular, they are not allowed as local definitions.

The variables in the left-hand side of the definition are bound by the
pattern on the right-hand side. For bidirectional pattern
synonyms, all the variables of the right-hand side must also occur on
the left-hand side; also, wildcard patterns and view patterns are not
allowed. For unidirectional and explicitly bidirectional pattern
synonyms, there is no restriction on the right-hand side pattern.

Pattern synonyms cannot be defined recursively.

:ref:`complete-pragma` can be specified in order to tell
the pattern match exhaustiveness checker that a set of pattern synonyms is
complete.

.. _patsyn-impexp:

Import and export of pattern synonyms
-------------------------------------

The name of the pattern synonym is in the same namespace as proper data
constructors. Like normal data constructors, pattern synonyms can be imported
and exported through association with a type constructor or independently.

To export them on their own, in an export or import specification, you must
prefix pattern names with the ``pattern`` keyword, e.g.: ::

      module Example (pattern Zero) where

      data MyNum = MkNum Int

      pattern Zero :: MyNum
      pattern Zero = MkNum 0

Without the ``pattern`` prefix, ``Zero`` would be interpreted as a
type constructor in the export list.

You may also use the ``pattern`` keyword in an import/export
specification to import or export an ordinary data constructor. For
example: ::

      import Data.Maybe( pattern Just )

would bring into scope the data constructor ``Just`` from the ``Maybe``
type, without also bringing the type constructor ``Maybe`` into scope.

To bundle a pattern synonym with a type constructor, we list the pattern
synonym in the export list of a module which exports the type constructor.
For example, to bundle ``Zero`` with ``MyNum`` we could write the following: ::

      module Example ( MyNum(Zero) ) where

If a module was then to import ``MyNum`` from ``Example``, it would also import
the pattern synonym ``Zero``.

It is also possible to use the special token ``..`` in an export list to mean
all currently bundled constructors. For example, we could write: ::

      module Example ( MyNum(.., Zero) ) where

in which case, ``Example`` would export the type constructor ``MyNum`` with
the data constructor ``MkNum`` and also the pattern synonym ``Zero``.

Bundled pattern synonyms are type checked to ensure that they are of the same
type as the type constructor which they are bundled with. A pattern synonym
``P`` can not be bundled with a type constructor ``T`` if ``P``\'s type is visibly
incompatible with ``T``.

A module which imports ``MyNum(..)`` from ``Example`` and then re-exports
``MyNum(..)`` will also export any pattern synonyms bundled with ``MyNum`` in
``Example``. A more complete specification can be found on the
:ghc-wiki:`wiki. <pattern-synonyms/associating-synonyms>`


.. _patsyn-typing:

Typing of pattern synonyms
--------------------------

Given a pattern synonym definition of the form ::

      pattern P var1 var2 ... varN <- pat

it is assigned a *pattern type* of the form ::

      pattern P :: CReq => CProv => t1 -> t2 -> ... -> tN -> t

where ⟨CReq⟩ and ⟨CProv⟩ are type contexts, and ⟨t1⟩, ⟨t2⟩, ..., ⟨tN⟩
and ⟨t⟩ are types. Notice the unusual form of the type, with two
contexts ⟨CReq⟩ and ⟨CProv⟩:

-  ⟨CReq⟩ are the constraints *required* to match the pattern.

-  ⟨CProv⟩ are the constraints *made available (provided)* by a
   successful pattern match.

For example, consider ::

    data T a where
      MkT :: (Show b) => a -> b -> T a

    f1 :: (Num a, Eq a) => T a -> String
    f1 (MkT 42 x) = show x

    pattern ExNumPat :: (Num a, Eq a) => (Show b) => b -> T a
    pattern ExNumPat x = MkT 42 x

    f2 :: (Eq a, Num a) => T a -> String
    f2 (ExNumPat x) = show x

Here ``f1`` does not use pattern synonyms. To match against the numeric
pattern ``42`` *requires* the caller to satisfy the constraints
``(Num a, Eq a)``, so they appear in ``f1``'s type. The call to ``show``
generates a ``(Show b)`` constraint, where ``b`` is an existentially
type variable bound by the pattern match on ``MkT``. But the same
pattern match also *provides* the constraint ``(Show b)`` (see ``MkT``'s
type), and so all is well.

Exactly the same reasoning applies to ``ExNumPat``: matching against
``ExNumPat`` *requires* the constraints ``(Num a, Eq a)``, and
*provides* the constraint ``(Show b)``.

Note also the following points

-  In the common case where ``CProv`` is empty, (i.e., ``()``), it can be
   omitted altogether in the above pattern type signature for ``P``.

-  However, if ``CProv`` is non-empty, while ``CReq`` is, the above pattern type
   signature for ``P`` must be specified as ::

     P :: () => CProv => t1 -> t2 -> .. -> tN -> t

-  The GHCi :ghci-cmd:`:info` command shows pattern types in this format.

-  You may specify an explicit *pattern signature*, as we did for
   ``ExNumPat`` above, to specify the type of a pattern, just as you can
   for a function. As usual, the type signature can be less polymorphic
   than the inferred type. For example ::

         -- Inferred type would be 'a -> [a]'
         pattern SinglePair :: (a, a) -> [(a, a)]
         pattern SinglePair x = [x]

   Just like signatures on value-level bindings, pattern synonym signatures can
   apply to more than one pattern. For instance, ::

         pattern Left', Right' :: a -> Either a a
         pattern Left' x  = Left x
         pattern Right' x = Right x

-  The rules for lexically-scoped type variables (see
   :ref:`scoped-type-variables`) apply to pattern-synonym signatures.
   As those rules specify, only the type variables from an explicit,
   syntactically-visible outer `forall` (the universals) scope over
   the definition of the pattern synonym; the existentials, bound by
   the inner forall, do not.  For example ::

         data T a where
            MkT :: Bool -> b -> (b->Int) -> a -> T a

         pattern P :: forall a. forall b. b -> (b->Int) -> a -> T a
         pattern P x y v <- MkT True x y (v::a)

   Here the universal type variable `a` scopes over the definition of `P`,
   but the existential `b` does not.  (c.f. discussion on #14998.)

-  For a bidirectional pattern synonym, a use of the pattern synonym as
   an expression has the type

   ::

         (CReq, CProv) => t1 -> t2 -> ... -> tN -> t

   So in the previous example, when used in an expression, ``ExNumPat``
   has type

   ::

         ExNumPat :: (Num a, Eq a, Show b) => b -> T t

   Notice that this is a tiny bit more restrictive than the expression
   ``MkT 42 x`` which would not require ``(Eq a)``.

-  Consider these two pattern synonyms: ::

       data S a where
          S1 :: Bool -> S Bool

       pattern P1 :: Bool -> Maybe Bool
       pattern P1 b = Just b

       pattern P2 :: () => (b ~ Bool) => Bool -> S b
       pattern P2 b = S1 b

       f :: Maybe a -> String
       f (P1 x) = "no no no"     -- Type-incorrect

       g :: S a -> String
       g (P2 b) = "yes yes yes"  -- Fine

   Pattern ``P1`` can only match against a value of type ``Maybe Bool``,
   so function ``f`` is rejected because the type signature is
   ``Maybe a``. (To see this, imagine expanding the pattern synonym.)

   On the other hand, function ``g`` works fine, because matching
   against ``P2`` (which wraps the GADT ``S``) provides the local
   equality ``(a~Bool)``. If you were to give an explicit pattern
   signature ``P2 :: Bool -> S Bool``, then ``P2`` would become less
   polymorphic, and would behave exactly like ``P1`` so that ``g`` would
   then be rejected.

   In short, if you want GADT-like behaviour for pattern synonyms, then
   (unlike concrete data constructors like ``S1``) you must write
   its type with explicit provided equalities. For a concrete data
   constructor like ``S1`` you can write its type signature as either
   ``S1 :: Bool -> S Bool`` or ``S1 :: (b~Bool) => Bool -> S b``; the
   two are equivalent. Not so for pattern synonyms: the two forms are
   different, in order to distinguish the two cases above. (See
   :ghc-ticket:`9953` for discussion of this choice.)

Matching of pattern synonyms
----------------------------

A pattern synonym occurrence in a pattern is evaluated by first matching
against the pattern synonym itself, and then on the argument patterns.

More precisely, the semantics of pattern matching is given in
`Section 3.17 of the Haskell 2010 report <https://www.haskell.org/onlinereport/haskell2010/haskellch3.html#x8-580003.17>`__.   To the informal semantics in Section 3.17.2 we add this extra rule:

* If the pattern is a constructor pattern ``(P p1 ... pn)``, where ``P`` is
  a pattern synonym defined by ``P x1 ... xn = p`` or ``P x1 ... xn <- p``, then:

  (a) Match the value ``v`` against ``p``. If this match fails or diverges,
      so does the whole (pattern synonym) match.   Otherwise the match
      against ``p`` must bind the variables ``x1 ... xn``; let them be bound to values ``v1 ... vn``.

  (b) Match ``v1`` against ``p1``, ``v2`` against ``p2`` and so on.
      If any of these matches fail or diverge, so does the whole match.

  (c) If all the matches against the ``pi`` succeed, the match succeeds,
      binding the variables bound by the ``pi`` . (The ``xi`` are not
      bound; they remain local to the pattern synonym declaration.)

For example, in the following program, ``f`` and ``f'`` are equivalent: ::

    pattern Pair x y <- [x, y]

    f (Pair True True) = True
    f _                = False

    f' [x, y] | True <- x, True <- y = True
    f' _                              = False

Note that the strictness of ``f`` differs from that of ``g`` defined
below:

.. code-block:: none

    g [True, True] = True
    g _            = False

    *Main> f (False:undefined)
    *** Exception: Prelude.undefined
    *Main> g (False:undefined)
    False

.. _type-class-extensions:

Class and instances declarations
================================

.. _multi-param-type-classes:

Class declarations
------------------

This section, and the next one, documents GHC's type-class extensions.
There's lots of background in the paper `Type classes: exploring the
design
space <http://research.microsoft.com/~simonpj/Papers/type-class-design-space/>`__
(Simon Peyton Jones, Mark Jones, Erik Meijer).

Multi-parameter type classes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: MultiParamTypeClasses
    :shortdesc: Enable multi parameter type classes.
         Implied by :extension:`FunctionalDependencies`.

    :implies: :extension:`ConstrainedClassMethods`
    :since: 6.8.1

    Allow the definition of typeclasses with more than one parameter.

Multi-parameter type classes are permitted, with extension
:extension:`MultiParamTypeClasses`. For example: ::

      class Collection c a where
          union :: c a -> c a -> c a
          ...etc.

.. _superclass-rules:

The superclasses of a class declaration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: FlexibleContexts
    :shortdesc: Enable flexible contexts.

    :since: 6.8.1

    Allow the use of complex constraints in class declaration contexts.

In Haskell 98 the context of a class declaration (which introduces
superclasses) must be simple; that is, each predicate must consist of a
class applied to type variables. The extension :extension:`FlexibleContexts`
(:ref:`flexible-contexts`) lifts this restriction, so that the only
restriction on the context in a class declaration is that the class
hierarchy must be acyclic. So these class declarations are OK: ::

      class Functor (m k) => FiniteMap m k where
        ...

      class (Monad m, Monad (t m)) => Transform t m where
        lift :: m a -> (t m) a

As in Haskell 98, the class hierarchy must be acyclic. However, the
definition of "acyclic" involves only the superclass relationships. For
example, this is okay: ::

      class C a where
        op :: D b => a -> b -> b

      class C a => D a where ...

Here, ``C`` is a superclass of ``D``, but it's OK for a class operation
``op`` of ``C`` to mention ``D``. (It would not be OK for ``D`` to be a
superclass of ``C``.)

With the extension that adds a `kind of
constraints <#constraint-kind>`__, you can write more exotic superclass
definitions. The superclass cycle check is even more liberal in these
case. For example, this is OK: ::

      class A cls c where
        meth :: cls c => c -> c

      class A B c => B c where

A superclass context for a class ``C`` is allowed if, after expanding
type synonyms to their right-hand-sides, and uses of classes (other than
``C``) to their superclasses, ``C`` does not occur syntactically in the
context.

.. _class-method-types:

Constrained class method types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: ConstrainedClassMethods
    :shortdesc: Enable constrained class methods.

    :since: 6.8.1

    Allows the definition of further constraints on individual class methods.

Haskell 98 prohibits class method types to mention constraints on the
class type variable, thus: ::

      class Seq s a where
        fromList :: [a] -> s a
        elem     :: Eq a => a -> s a -> Bool

The type of ``elem`` is illegal in Haskell 98, because it contains the
constraint ``Eq a``, which constrains only the class type variable (in
this case ``a``).
this case ``a``).  More precisely, a constraint in a class method signature is rejected if

- The constraint mentions at least one type variable.  So this is allowed: ::

     class C a where
       op1 :: HasCallStack => a -> a
       op2 :: (?x::Int) => Int -> a

- All of the type variables mentioned are bound by the class declaration, and none is locally quantified.  Examples: ::

     class C a where
       op3 :: Eq a => a -> a    -- Rejected: constrains class variable only
       op4 :: D b => a -> b     -- Accepted: constrains a locally-quantified variable `b`
       op5 :: D (a,b) => a -> b -- Accepted: constrains a locally-quantified variable `b`


GHC lifts this restriction with language extension
:extension:`ConstrainedClassMethods`. The restriction is a pretty stupid one in
the first place, so :extension:`ConstrainedClassMethods` is implied by
:extension:`MultiParamTypeClasses`.

.. _class-default-signatures:

Default method signatures
~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: DefaultSignatures
    :shortdesc: Enable default signatures.

    :since: 7.2.1

    Allows the definition of default method signatures in class definitions.

Haskell 98 allows you to define a default implementation when declaring
a class: ::

      class Enum a where
        enum :: [a]
        enum = []

The type of the ``enum`` method is ``[a]``, and this is also the type of
the default method. You can lift this restriction and give another type
to the default method using the extension :extension:`DefaultSignatures`. For
instance, if you have written a generic implementation of enumeration in
a class ``GEnum`` with method ``genum`` in terms of ``GHC.Generics``,
you can specify a default method that uses that generic implementation: ::

      class Enum a where
        enum :: [a]
        default enum :: (Generic a, GEnum (Rep a)) => [a]
        enum = map to genum

We reuse the keyword ``default`` to signal that a signature applies to
the default method only; when defining instances of the ``Enum`` class,
the original type ``[a]`` of ``enum`` still applies. When giving an
empty instance, however, the default implementation ``(map to genum)`` is
filled-in, and type-checked with the type
``(Generic a, GEnum (Rep a)) => [a]``.

The type signature for a default method of a type class must take on the same
form as the corresponding main method's type signature. Otherwise, the
typechecker will reject that class's definition. By "take on the same form", we
mean that the default type signature should differ from the main type signature
only in their contexts. Therefore, if you have a method ``bar``: ::

      class Foo a where
        bar :: forall b. C => a -> b -> b

Then a default method for ``bar`` must take on the form: ::

      default bar :: forall b. C' => a -> b -> b

``C`` is allowed to be different from ``C'``, but the right-hand sides of the
type signatures must coincide. We require this because when you declare an
empty instance for a class that uses :extension:`DefaultSignatures`, GHC
implicitly fills in the default implementation like this: ::

      instance Foo Int where
        bar = default_bar @Int

Where ``@Int`` utilizes visible type application
(:ref:`visible-type-application`) to instantiate the ``b`` in
``default bar :: forall b. C' => a -> b -> b``. In order for this type
application to work, the default type signature for ``bar`` must have the same
type variable order as the non-default signature! But there is no obligation
for ``C`` and ``C'`` to be the same (see, for instance, the ``Enum`` example
above, which relies on this).

To further explain this example, the right-hand side of the default
type signature for ``bar`` must be something that is alpha-equivalent to
``forall b. a -> b -> b`` (where ``a`` is bound by the class itself, and is
thus free in the methods' type signatures). So this would also be an acceptable
default type signature: ::

      default bar :: forall x. C' => a -> x -> x

But not this (since the free variable ``a`` is in the wrong place): ::

      default bar :: forall b. C' => b -> a -> b

Nor this, since we can't match the type variable ``b`` with the concrete type
``Int``: ::

      default bar :: C' => a -> Int -> Int

That last one deserves a special mention, however, since ``a -> Int -> Int`` is
a straightforward instantiation of ``forall b. a -> b -> b``. You can still
write such a default type signature, but you now must use type equalities to
do so: ::

      default bar :: forall b. (C', b ~ Int) => a -> b -> b

We use default signatures to simplify generic programming in GHC
(:ref:`generic-programming`).

.. _nullary-type-classes:

Nullary type classes
~~~~~~~~~~~~~~~~~~~~

.. extension:: NullaryTypeClasses
    :shortdesc: Deprecated, does nothing. nullary (no parameter) type
        classes are now enabled using :extension:`MultiParamTypeClasses`.

    :since: 7.8.1

    Allows the use definition of type classes with no parameters. This extension
    has been replaced by :extension:`MultiParamTypeClasses`.


Nullary (no parameter) type classes are enabled with
:extension:`MultiParamTypeClasses`; historically, they were enabled with the
(now deprecated) :extension:`NullaryTypeClasses`. Since there are no available
parameters, there can be at most one instance of a nullary class. A nullary type
class might be used to document some assumption in a type signature (such as
reliance on the Riemann hypothesis) or add some globally configurable settings
in a program. For example, ::

      class RiemannHypothesis where
        assumeRH :: a -> a

      -- Deterministic version of the Miller test
      -- correctness depends on the generalised Riemann hypothesis
      isPrime :: RiemannHypothesis => Integer -> Bool
      isPrime n = assumeRH (...)

The type signature of ``isPrime`` informs users that its correctness depends on
an unproven conjecture. If the function is used, the user has to acknowledge the
dependence with: ::

      instance RiemannHypothesis where
        assumeRH = id

.. _functional-dependencies:

Functional dependencies
-----------------------

.. extension:: FunctionalDependencies
    :shortdesc: Enable functional dependencies.
        Implies :extension:`MultiParamTypeClasses`.

    :implies: :extension:`MultiParamTypeClasses`
    :since: 6.8.1

    Allow use of functional dependencies in class declarations.

Functional dependencies are implemented as described by Mark Jones in
[Jones2000]_.

Functional dependencies are introduced by a vertical bar in the syntax
of a class declaration; e.g. ::

      class (Monad m) => MonadState s m | m -> s where ...

      class Foo a b c | a b -> c where ...

More documentation can be found in the `Haskell Wiki
<https://wiki.haskell.org/Functional_dependencies>`_.

.. [Jones2000]
    "`Type Classes with Functional
    Dependencies <https://web.cecs.pdx.edu/~mpj/pubs/fundeps.html>`__",
    Mark P. Jones, In *Proceedings of the 9th European Symposium on Programming*,
    ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782, .

Rules for functional dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In a class declaration, all of the class type variables must be
reachable (in the sense mentioned in :ref:`flexible-contexts`) from the
free variables of each method type. For example: ::

      class Coll s a where
        empty  :: s
        insert :: s -> a -> s

is not OK, because the type of ``empty`` doesn't mention ``a``.
Functional dependencies can make the type variable reachable: ::

      class Coll s a | s -> a where
        empty  :: s
        insert :: s -> a -> s

Alternatively ``Coll`` might be rewritten ::

      class Coll s a where
        empty  :: s a
        insert :: s a -> a -> s a

which makes the connection between the type of a collection of ``a``'s
(namely ``(s a)``) and the element type ``a``. Occasionally this really
doesn't work, in which case you can split the class like this: ::

      class CollE s where
        empty  :: s

      class CollE s => Coll s a where
        insert :: s -> a -> s

Background on functional dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following description of the motivation and use of functional
dependencies is taken from the Hugs user manual, reproduced here (with
minor changes) by kind permission of Mark Jones.

Consider the following class, intended as part of a library for
collection types: ::

       class Collects e ce where
           empty  :: ce
           insert :: e -> ce -> ce
           member :: e -> ce -> Bool

The type variable ``e`` used here represents the element type, while ``ce`` is
the type of the container itself. Within this framework, we might want to define
instances of this class for lists or characteristic functions (both of which can
be used to represent collections of any equality type), bit sets (which can be
used to represent collections of characters), or hash tables (which can be used
to represent any collection whose elements have a hash function). Omitting
standard implementation details, this would lead to the following declarations: ::

       instance Eq e => Collects e [e] where ...
       instance Eq e => Collects e (e -> Bool) where ...
       instance Collects Char BitSet where ...
       instance (Hashable e, Collects a ce)
                  => Collects e (Array Int ce) where ...

All this looks quite promising; we have a class and a range of
interesting implementations. Unfortunately, there are some serious
problems with the class declaration. First, the empty function has an
ambiguous type: ::

       empty :: Collects e ce => ce

By "ambiguous" we mean that there is a type variable ``e`` that appears on
the left of the ``=>`` symbol, but not on the right. The problem with
this is that, according to the theoretical foundations of Haskell
overloading, we cannot guarantee a well-defined semantics for any term
with an ambiguous type.

We can sidestep this specific problem by removing the empty member from
the class declaration. However, although the remaining members, insert
and member, do not have ambiguous types, we still run into problems when
we try to use them. For example, consider the following two functions: ::

       f x y = insert x . insert y
       g     = f True 'a'

for which GHC infers the following types: ::

       f :: (Collects a c, Collects b c) => a -> b -> c -> c
       g :: (Collects Bool c, Collects Char c) => c -> c

Notice that the type for ``f`` allows the two parameters ``x`` and ``y`` to be
assigned different types, even though it attempts to insert each of the
two values, one after the other, into the same collection. If we're
trying to model collections that contain only one type of value, then
this is clearly an inaccurate type. Worse still, the definition for g is
accepted, without causing a type error. As a result, the error in this
code will not be flagged at the point where it appears. Instead, it will
show up only when we try to use ``g``, which might even be in a different
module.

An attempt to use constructor classes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Faced with the problems described above, some Haskell programmers might
be tempted to use something like the following version of the class
declaration: ::

       class Collects e c where
          empty  :: c e
          insert :: e -> c e -> c e
          member :: e -> c e -> Bool

The key difference here is that we abstract over the type constructor ``c``
that is used to form the collection type ``c e``, and not over that
collection type itself, represented by ``ce`` in the original class
declaration. This avoids the immediate problems that we mentioned above:
empty has type ``Collects e c => c e``, which is not ambiguous.

The function ``f`` from the previous section has a more accurate type: ::

       f :: (Collects e c) => e -> e -> c e -> c e

The function ``g`` from the previous section is now rejected with a type
error as we would hope because the type of ``f`` does not allow the two
arguments to have different types. This, then, is an example of a
multiple parameter class that does actually work quite well in practice,
without ambiguity problems. There is, however, a catch. This version of
the ``Collects`` class is nowhere near as general as the original class
seemed to be: only one of the four instances for ``Collects`` given
above can be used with this version of Collects because only one of them—the
instance for lists—has a collection type that can be written in the form ``c
e``, for some type constructor ``c``, and element type ``e``.

Adding functional dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To get a more useful version of the ``Collects`` class, GHC provides a
mechanism that allows programmers to specify dependencies between the
parameters of a multiple parameter class (For readers with an interest
in theoretical foundations and previous work: The use of dependency
information can be seen both as a generalisation of the proposal for
"parametric type classes" that was put forward by Chen, Hudak, and
Odersky, or as a special case of Mark Jones's later framework for
"improvement" of qualified types. The underlying ideas are also
discussed in a more theoretical and abstract setting in a manuscript
[Jones1999]_, where they are identified as one point in a general design
space for systems of implicit parameterisation). To start with an
abstract example, consider a declaration such as: ::

       class C a b where ...

.. [Jones1999]
    "`Exploring the Design Space for Type-based Implicit Parameterization
    <https://web.cecs.pdx.edu/~mpj/pubs/fdtr.html>`__", Mark P. Jones, Oregon
    Graduate Institute of Science & Technology, Technical Report, July 1999.

which tells us simply that ``C`` can be thought of as a binary relation on
types (or type constructors, depending on the kinds of ``a`` and ``b``). Extra
clauses can be included in the definition of classes to add information
about dependencies between parameters, as in the following examples: ::

       class D a b | a -> b where ...
       class E a b | a -> b, b -> a where ...

The notation ``a -> b`` used here between the ``|`` and ``where`` symbols —
not to be confused with a function type — indicates that the ``a``
parameter uniquely determines the ``b`` parameter, and might be read as "``a``
determines ``b``." Thus ``D`` is not just a relation, but actually a (partial)
function. Similarly, from the two dependencies that are included in the
definition of ``E``, we can see that ``E`` represents a (partial) one-to-one
mapping between types.

More generally, dependencies take the form ``x1 ... xn -> y1 ... ym``,
where ``x1``, ..., ``xn``, and ``y1``, ..., ``yn`` are type variables with n>0 and m>=0,
meaning that the ``y`` parameters are uniquely determined by the ``x``
parameters. Spaces can be used as separators if more than one variable
appears on any single side of a dependency, as in ``t -> a b``. Note
that a class may be annotated with multiple dependencies using commas as
separators, as in the definition of ``E`` above. Some dependencies that we
can write in this notation are redundant, and will be rejected because
they don't serve any useful purpose, and may instead indicate an error
in the program. Examples of dependencies like this include ``a -> a``,
``a -> a a``, ``a ->``, etc. There can also be some redundancy if
multiple dependencies are given, as in ``a->b``, ``b->c``, ``a->c``, and
in which some subset implies the remaining dependencies. Examples like
this are not treated as errors. Note that dependencies appear only in
class declarations, and not in any other part of the language. In
particular, the syntax for instance declarations, class constraints, and
types is completely unchanged.

By including dependencies in a class declaration, we provide a mechanism
for the programmer to specify each multiple parameter class more
precisely. The compiler, on the other hand, is responsible for ensuring
that the set of instances that are in scope at any given point in the
program is consistent with any declared dependencies. For example, the
following pair of instance declarations cannot appear together in the
same scope because they violate the dependency for ``D``, even though either
one on its own would be acceptable: ::

       instance D Bool Int where ...
       instance D Bool Char where ...

Note also that the following declaration is not allowed, even by itself: ::

       instance D [a] b where ...

The problem here is that this instance would allow one particular choice
of ``[a]`` to be associated with more than one choice for ``b``, which
contradicts the dependency specified in the definition of ``D``. More
generally, this means that, in any instance of the form: ::

       instance D t s where ...

for some particular types ``t`` and ``s``, the only variables that can appear in
``s`` are the ones that appear in ``t``, and hence, if the type ``t`` is known,
then ``s`` will be uniquely determined.

The benefit of including dependency information is that it allows us to
define more general multiple parameter classes, without ambiguity
problems, and with the benefit of more accurate types. To illustrate
this, we return to the collection class example, and annotate the
original definition of ``Collects`` with a simple dependency: ::

       class Collects e ce | ce -> e where
          empty  :: ce
          insert :: e -> ce -> ce
          member :: e -> ce -> Bool

The dependency ``ce -> e`` here specifies that the type ``e`` of elements is
uniquely determined by the type of the collection ``ce``. Note that both
parameters of Collects are of kind ``Type``; there are no constructor classes
here. Note too that all of the instances of ``Collects`` that we gave earlier
can be used together with this new definition.

What about the ambiguity problems that we encountered with the original
definition? The empty function still has type ``Collects e ce => ce``, but
it is no longer necessary to regard that as an ambiguous type: Although
the variable ``e`` does not appear on the right of the ``=>`` symbol, the
dependency for class ``Collects`` tells us that it is uniquely determined by
``ce``, which does appear on the right of the ``=>`` symbol. Hence the context
in which empty is used can still give enough information to determine
types for both ``ce`` and ``e``, without ambiguity. More generally, we need only
regard a type as ambiguous if it contains a variable on the left of the
``=>`` that is not uniquely determined (either directly or indirectly) by
the variables on the right.

Dependencies also help to produce more accurate types for user defined
functions, and hence to provide earlier detection of errors, and less
cluttered types for programmers to work with. Recall the previous
definition for a function ``f``: ::

       f x y = insert x y = insert x . insert y

for which we originally obtained a type: ::

       f :: (Collects a c, Collects b c) => a -> b -> c -> c

Given the dependency information that we have for ``Collects``, however, we
can deduce that ``a`` and ``b`` must be equal because they both appear as the
second parameter in a ``Collects`` constraint with the same first parameter
``c``. Hence we can infer a shorter and more accurate type for ``f``: ::

       f :: (Collects a c) => a -> a -> c -> c

In a similar way, the earlier definition of ``g`` will now be flagged as a
type error.

Although we have given only a few examples here, it should be clear that
the addition of dependency information can help to make multiple
parameter classes more useful in practice, avoiding ambiguity problems,
and allowing more general sets of instance declarations.

.. _instance-decls:

Instance declarations
---------------------

An instance declaration has the form ::

      instance ( assertion1, ..., assertionn) => class type1 ... typem where ...

The part before the "``=>``" is the *context*, while the part after the
"``=>``" is the *head* of the instance declaration.

.. _instance-resolution:

Instance resolution
~~~~~~~~~~~~~~~~~~~

When GHC tries to resolve, say, the constraint ``C Int Bool``, it tries
to match every instance declaration against the constraint, by
instantiating the head of the instance declaration. Consider these
declarations: ::

      instance context1 => C Int a     where ...  -- (A)
      instance context2 => C a   Bool  where ...  -- (B)

GHC's default behaviour is that *exactly one instance must match the
constraint it is trying to resolve*. For example, the constraint
``C Int Bool`` matches instances (A) and (B), and hence would be
rejected; while ``C Int Char`` matches only (A) and hence (A) is chosen.

Notice that

-  When matching, GHC takes no account of the context of the instance
   declaration (``context1`` etc).

-  It is fine for there to be a *potential* of overlap (by including
   both declarations (A) and (B), say); an error is only reported if a
   particular constraint matches more than one.

See also :ref:`instance-overlap` for flags that loosen the instance
resolution rules.

.. _flexible-instance-head:

Relaxed rules for the instance head
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: TypeSynonymInstances
    :shortdesc: Enable type synonyms in instance heads.
      Implied by :extension:`FlexibleInstances`.

    :since: 6.8.1

    Allow definition of type class instances for type synonyms.

.. extension:: FlexibleInstances
    :shortdesc: Enable flexible instances.
        Implies :extension:`TypeSynonymInstances`.

    :implies: :extension:`TypeSynonymInstances`
    :since: 6.8.1

    Allow definition of type class instances with arbitrary nested types in the
    instance head.

In Haskell 98 the head of an instance declaration must be of the form
``C (T a1 ... an)``, where ``C`` is the class, ``T`` is a data type
constructor, and the ``a1 ... an`` are distinct type variables. In the
case of multi-parameter type classes, this rule applies to each
parameter of the instance head (Arguably it should be okay if just one
has this form and the others are type variables, but that's the rules at
the moment).

GHC relaxes this rule in two ways:

-  With the :extension:`TypeSynonymInstances` extension, instance heads may use type
   synonyms. As always, using a type synonym is just shorthand for
   writing the RHS of the type synonym definition. For example: ::

         type Point a = (a,a)
         instance C (Point a)   where ...

   is legal. The instance declaration is equivalent to ::

         instance C (a,a) where ...

   As always, type synonyms must be fully applied. You cannot, for
   example, write: ::

         instance Monad Point where ...

-  The :extension:`FlexibleInstances` extension allows the head of the instance
   declaration to mention arbitrary nested types. For example, this
   becomes a legal instance declaration ::

         instance C (Maybe Int) where ...

   See also the `rules on overlap <#instance-overlap>`__.

   The :extension:`FlexibleInstances` extension implies
   :extension:`TypeSynonymInstances`.

However, the instance declaration must still conform to the rules for
instance termination: see :ref:`instance-termination`.

.. _instance-rules:

Relaxed rules for instance contexts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In Haskell 98, the class constraints in the context of the instance
declaration must be of the form ``C a`` where ``a`` is a type variable
that occurs in the head.

The :extension:`FlexibleContexts` extension relaxes this rule, as well as relaxing
the corresponding rule for type signatures (see
:ref:`flexible-contexts`). Specifically, :extension:`FlexibleContexts`, allows
(well-kinded) class constraints of form ``(C t1 ... tn)`` in the context
of an instance declaration.

Notice that the extension does not affect equality constraints in an instance
context; they are permitted by :extension:`TypeFamilies` or :extension:`GADTs`.

However, the instance declaration must still conform to the rules for
instance termination: see :ref:`instance-termination`.

.. _instance-termination:

Instance termination rules
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: UndecidableInstances
    :shortdesc: Enable undecidable instances.

    :since: 6.8.1

    Permit definition of instances which may lead to type-checker non-termination.

Regardless of :extension:`FlexibleInstances` and :extension:`FlexibleContexts`,
instance declarations must conform to some rules that ensure that
instance resolution will terminate. The restrictions can be lifted with
:extension:`UndecidableInstances` (see :ref:`undecidable-instances`).

The rules are these:

1. The Paterson Conditions: for each class constraint ``(C t1 ... tn)``
   in the context

   1. No type variable has more occurrences in the constraint than in
      the head

   2. The constraint has fewer constructors and variables (taken
      together and counting repetitions) than the head

   3. The constraint mentions no type functions. A type function
      application can in principle expand to a type of arbitrary size,
      and so are rejected out of hand

2. The Coverage Condition. For each functional dependency,
   ⟨tvs⟩\ :sub:`left` ``->`` ⟨tvs⟩\ :sub:`right`, of the class, every
   type variable in S(⟨tvs⟩\ :sub:`right`) must appear in
   S(⟨tvs⟩\ :sub:`left`), where S is the substitution mapping each type
   variable in the class declaration to the corresponding type in the
   instance head.

These restrictions ensure that instance resolution terminates: each
reduction step makes the problem smaller by at least one constructor.
You can find lots of background material about the reason for these
restrictions in the paper `Understanding functional dependencies via
Constraint Handling
Rules <https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/jfp06.pdf>`__.

For example, these are okay:

::

      instance C Int [a]          -- Multiple parameters
      instance Eq (S [a])         -- Structured type in head

          -- Repeated type variable in head
      instance C4 a a => C4 [a] [a]
      instance Stateful (ST s) (MutVar s)

          -- Head can consist of type variables only
      instance C a
      instance (Eq a, Show b) => C2 a b

          -- Non-type variables in context
      instance Show (s a) => Show (Sized s a)
      instance C2 Int a => C3 Bool [a]
      instance C2 Int a => C3 [a] b

But these are not:

::

          -- Context assertion no smaller than head
      instance C a => C a where ...
          -- (C b b) has more occurrences of b than the head
      instance C b b => Foo [b] where ...

The same restrictions apply to instances generated by ``deriving``
clauses. Thus the following is accepted:

::

      data MinHeap h a = H a (h a)
        deriving (Show)

because the derived instance

::

      instance (Show a, Show (h a)) => Show (MinHeap h a)

conforms to the above rules.

A useful idiom permitted by the above rules is as follows. If one allows
overlapping instance declarations then it's quite convenient to have a
"default instance" declaration that applies if something more specific
does not:

::

      instance C a where
        op = ... -- Default

.. _undecidable-instances:

Undecidable instances
~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: -XUndecidableInstances

Sometimes even the termination rules of :ref:`instance-termination` are
too onerous. So GHC allows you to experiment with more liberal rules: if
you use the experimental extension :extension:`UndecidableInstances`, both the Paterson
Conditions and the Coverage
Condition (described in :ref:`instance-termination`) are lifted.
Termination is still ensured by having a fixed-depth recursion stack. If
you exceed the stack depth you get a sort of backtrace, and the
opportunity to increase the stack depth with
``-freduction-depth=⟨n⟩``. However, if you should exceed the default
reduction depth limit, it is probably best just to disable depth
checking, with ``-freduction-depth=0``. The exact depth your program
requires depends on minutiae of your code, and it may change between
minor GHC releases. The safest bet for released code -- if you're sure
that it should compile in finite time -- is just to disable the check.

For example, sometimes you might want to use the following to get the
effect of a "class synonym":

::

      class (C1 a, C2 a, C3 a) => C a where { }

      instance (C1 a, C2 a, C3 a) => C a where { }

This allows you to write shorter signatures:

::

      f :: C a => ...

instead of

::

      f :: (C1 a, C2 a, C3 a) => ...

The restrictions on functional dependencies
(:ref:`functional-dependencies`) are particularly troublesome. It is
tempting to introduce type variables in the context that do not appear
in the head, something that is excluded by the normal rules. For
example:

::

      class HasConverter a b | a -> b where
         convert :: a -> b

      data Foo a = MkFoo a

      instance (HasConverter a b,Show b) => Show (Foo a) where
         show (MkFoo value) = show (convert value)

This is dangerous territory, however. Here, for example, is a program
that would make the typechecker loop:

::

      class D a
      class F a b | a->b
      instance F [a] [[a]]
      instance (D c, F a c) => D [a]   -- 'c' is not mentioned in the head

Similarly, it can be tempting to lift the coverage condition:

::

      class Mul a b c | a b -> c where
        (.*.) :: a -> b -> c

      instance Mul Int Int Int where (.*.) = (*)
      instance Mul Int Float Float where x .*. y = fromIntegral x * y
      instance Mul a b c => Mul a [b] [c] where x .*. v = map (x.*.) v

The third instance declaration does not obey the coverage condition; and
indeed the (somewhat strange) definition:

::

      f = \ b x y -> if b then x .*. [y] else y

makes instance inference go into a loop, because it requires the
constraint ``(Mul a [b] b)``.

The :extension:`UndecidableInstances` extension is also used to lift some of the
restrictions imposed on type family instances. See
:ref:`type-family-decidability`.

.. _instance-overlap:

Overlapping instances
~~~~~~~~~~~~~~~~~~~~~

.. extension:: OverlappingInstances
    :shortdesc: Enable overlapping instances.

    Deprecated extension to weaken checks intended to ensure instance resolution
    termination.

.. extension:: IncoherentInstances
    :shortdesc: Enable incoherent instances.
        Implies :extension:`OverlappingInstances`.

    :since: 6.8.1

    Deprecated extension to weaken checks intended to ensure instance resolution
    termination.

In general, as discussed in :ref:`instance-resolution`, *GHC requires
that it be unambiguous which instance declaration should be used to
resolve a type-class constraint*. GHC also provides a way to loosen
the instance resolution, by allowing more than one instance to match,
*provided there is a most specific one*. Moreover, it can be loosened
further, by allowing more than one instance to match irrespective of
whether there is a most specific one. This section gives the details.

To control the choice of instance, it is possible to specify the overlap
behavior for individual instances with a pragma, written immediately
after the ``instance`` keyword. The pragma may be one of:
``{-# OVERLAPPING #-}``, ``{-# OVERLAPPABLE #-}``, ``{-# OVERLAPS #-}``,
or ``{-# INCOHERENT #-}``.

The matching behaviour is also influenced by two module-level language
extension flags: :extension:`OverlappingInstances` and
:extension:`IncoherentInstances`. These extensions are now
deprecated (since GHC 7.10) in favour of the fine-grained per-instance
pragmas.

A more precise specification is as follows. The willingness to be
overlapped or incoherent is a property of the *instance declaration*
itself, controlled as follows:

-  An instance is *incoherent* if: it has an ``INCOHERENT`` pragma; or
   if the instance has no pragma and it appears in a module compiled
   with :extension:`IncoherentInstances`.

-  An instance is *overlappable* if: it has an ``OVERLAPPABLE`` or
   ``OVERLAPS`` pragma; or if the instance has no pragma and it appears
   in a module compiled with :extension:`OverlappingInstances`; or if the
   instance is incoherent.

-  An instance is *overlapping* if: it has an ``OVERLAPPING`` or
   ``OVERLAPS`` pragma; or if the instance has no pragma and it appears
   in a module compiled with :extension:`OverlappingInstances`; or if the
   instance is incoherent.

Now suppose that, in some client module, we are searching for an
instance of the *target constraint* ``(C ty1 .. tyn)``. The search works
like this:

-  Find all instances :math:`I` that *match* the target constraint; that is, the
   target constraint is a substitution instance of :math:`I`. These instance
   declarations are the *candidates*.

-  If no candidates remain, the search failes

-  Eliminate any candidate :math:`IX` for which there is another candidate
   :math:`IY` such that both of the following hold:

   -  :math:`IY` is strictly more specific than :math:`IX`.  That
      is, :math:`IY` is a substitution instance of :math:`IX` but not vice versa.

   -  Either :math:`IX` is *overlappable*, or :math:`IY` is *overlapping*. (This
      "either/or" design, rather than a "both/and" design, allow a
      client to deliberately override an instance from a library,
      without requiring a change to the library.)

-  If all the remaining candidates are incoherent, the search suceeds, returning
   an arbitrary surviving candidate.

-  If more than one non-incoherent candidate remains, the search fails.

-  Otherwise there is exactly one non-incoherent candidate; call it the
   "prime candidate".

-  Now find all instances, or in-scope given constraints, that *unify* with
   the target constraint,
   but do not *match* it. Such non-candidate instances might match when
   the target constraint is further instantiated. If all of them are
   incoherent top-level instances, the search succeeds, returning the prime candidate.
   Otherwise the search fails.

Notice that these rules are not influenced by flag settings in the
client module, where the instances are *used*. These rules make it
possible for a library author to design a library that relies on
overlapping instances without the client having to know.

Errors are reported *lazily* (when attempting to solve a constraint),
rather than *eagerly* (when the instances themselves are defined).
Consider, for example ::

      instance C Int  b where ..
      instance C a Bool where ..

These potentially overlap, but GHC will not complain about the instance
declarations themselves, regardless of flag settings. If we later try to
solve the constraint ``(C Int Char)`` then only the first instance
matches, and all is well. Similarly with ``(C Bool Bool)``. But if we
try to solve ``(C Int Bool)``, both instances match and an error is
reported.

As a more substantial example of the rules in action, consider ::

      instance {-# OVERLAPPABLE #-} context1 => C Int b     where ...  -- (A)
      instance {-# OVERLAPPABLE #-} context2 => C a   Bool  where ...  -- (B)
      instance {-# OVERLAPPABLE #-} context3 => C a   [b]   where ...  -- (C)
      instance {-# OVERLAPPING  #-} context4 => C Int [Int] where ...  -- (D)

Now suppose that the type inference engine needs to solve the constraint
``C Int [Int]``. This constraint matches instances (A), (C) and (D), but
the last is more specific, and hence is chosen.

If (D) did not exist then (A) and (C) would still be matched, but
neither is most specific. In that case, the program would be rejected,
unless :extension:`IncoherentInstances` is enabled, in which case it would be
accepted and (A) or (C) would be chosen arbitrarily.

An instance declaration is *more specific* than another iff the head of
former is a substitution instance of the latter. For example (D) is
"more specific" than (C) because you can get from (C) to (D) by
substituting ``a := Int``.

The final bullet (about unifiying instances)
makes GHC conservative about committing to an
overlapping instance. For example: ::

      f :: [b] -> [b]
      f x = ...

Suppose that from the RHS of ``f`` we get the constraint ``C b [b]``.
But GHC does not commit to instance (C), because in a particular call of
``f``, ``b`` might be instantiated to ``Int``, in which case instance (D)
would be more specific still. So GHC rejects the program.

If, however, you enable the extension :extension:`IncoherentInstances` when compiling
the module that contains (D), GHC will instead pick (C), without
complaining about the problem of subsequent instantiations.

Notice that we gave a type signature to ``f``, so GHC had to *check*
that ``f`` has the specified type. Suppose instead we do not give a type
signature, asking GHC to *infer* it instead. In this case, GHC will
refrain from simplifying the constraint ``C Int [b]`` (for the same
reason as before) but, rather than rejecting the program, it will infer
the type ::

      f :: C b [b] => [b] -> [b]

That postpones the question of which instance to pick to the call site
for ``f`` by which time more is known about the type ``b``. You can
write this type signature yourself if you use the
:extension:`FlexibleContexts` extension.

Exactly the same situation can arise in instance declarations
themselves. Suppose we have ::

      class Foo a where
         f :: a -> a
      instance Foo [b] where
         f x = ...

and, as before, the constraint ``C Int [b]`` arises from ``f``'s right
hand side. GHC will reject the instance, complaining as before that it
does not know how to resolve the constraint ``C Int [b]``, because it
matches more than one instance declaration. The solution is to postpone
the choice by adding the constraint to the context of the instance
declaration, thus: ::

      instance C Int [b] => Foo [b] where
         f x = ...

(You need :extension:`FlexibleInstances` to do this.)

In the unification check in the final bullet, GHC also uses the
"in-scope given constraints".  Consider for example ::

   instance C a Int

   g :: forall b c. C b Int => blah
   g = ...needs (C c Int)...

Here GHC will not solve the constraint ``(C c Int)`` from the
top-level instance, because a particular call of ``g`` might
instantiate both ``b`` and ``c`` to the same type, which would
allow the constraint to be solved in a different way.  This latter
restriction is principally to make the constraint-solver complete.
(Interested folk can read ``Note [Instance and Given overlap]`` in ``TcInteract``.)
It is easy to avoid: in a type signature avoid a constraint that
matches a top-level instance.  The flag :ghc-flag:`-Wsimplifiable-class-constraints` warns about such signatures.

.. warning::
    Overlapping instances must be used with care. They can give
    rise to incoherence (i.e. different instance choices are made in
    different parts of the program) even without :extension:`IncoherentInstances`.
    Consider: ::

        {-# LANGUAGE OverlappingInstances #-}
        module Help where

            class MyShow a where
            myshow :: a -> String

            instance MyShow a => MyShow [a] where
            myshow xs = concatMap myshow xs

            showHelp :: MyShow a => [a] -> String
            showHelp xs = myshow xs

        {-# LANGUAGE FlexibleInstances, OverlappingInstances #-}
        module Main where
            import Help

            data T = MkT

            instance MyShow T where
            myshow x = "Used generic instance"

            instance MyShow [T] where
            myshow xs = "Used more specific instance"

            main = do { print (myshow [MkT]); print (showHelp [MkT]) }

    In function ``showHelp`` GHC sees no overlapping instances, and so uses
    the ``MyShow [a]`` instance without complaint. In the call to ``myshow``
    in ``main``, GHC resolves the ``MyShow [T]`` constraint using the
    overlapping instance declaration in module ``Main``. As a result, the
    program prints

    .. code-block:: none

        "Used more specific instance"
        "Used generic instance"

    (An alternative possible behaviour, not currently implemented, would be
    to reject module ``Help`` on the grounds that a later instance
    declaration might overlap the local one.)

.. _instance-sigs:

Instance signatures: type signatures in instance declarations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: InstanceSigs
    :shortdesc: Enable instance signatures.

    :since: 7.6.1

    Allow type signatures for members in instance definitions.

In Haskell, you can't write a type signature in an instance declaration,
but it is sometimes convenient to do so, and the language extension
:extension:`InstanceSigs` allows you to do so. For example: ::

      data T a = MkT a a
      instance Eq a => Eq (T a) where
        (==) :: T a -> T a -> Bool   -- The signature
        (==) (MkT x1 x2) (MkTy y1 y2) = x1==y1 && x2==y2

Some details

-  The type signature in the instance declaration must be more
   polymorphic than (or the same as) the one in the class declaration,
   instantiated with the instance type. For example, this is fine: ::

         instance Eq a => Eq (T a) where
            (==) :: forall b. b -> b -> Bool
            (==) x y = True

   Here the signature in the instance declaration is more polymorphic
   than that required by the instantiated class method.

-  The code for the method in the instance declaration is typechecked
   against the type signature supplied in the instance declaration, as
   you would expect. So if the instance signature is more polymorphic
   than required, the code must be too.

-  One stylistic reason for wanting to write a type signature is simple
   documentation. Another is that you may want to bring scoped type
   variables into scope. For example: ::

       class C a where
         foo :: b -> a -> (a, [b])

       instance C a => C (T a) where
         foo :: forall b. b -> T a -> (T a, [b])
         foo x (T y) = (T y, xs)
            where
              xs :: [b]
              xs = [x,x,x]

   Provided that you also specify :extension:`ScopedTypeVariables`
   (:ref:`scoped-type-variables`), the ``forall b`` scopes over the
   definition of ``foo``, and in particular over the type signature for
   ``xs``.

.. _overloaded-strings:

Overloaded string literals
--------------------------

.. extension:: OverloadedStrings
    :shortdesc: Enable overloaded string literals.

    :since: 6.8.1

    Enable overloaded string literals (e.g. string literals desugared via the
    ``IsString`` class).

GHC supports *overloaded string literals*. Normally a string literal has
type ``String``, but with overloaded string literals enabled (with
:extension:`OverloadedStrings`) a string literal has type
``(IsString a) => a``.

This means that the usual string syntax can be used, e.g., for
``ByteString``, ``Text``, and other variations of string like types.
String literals behave very much like integer literals, i.e., they can
be used in both expressions and patterns. If used in a pattern the
literal will be replaced by an equality test, in the same way as an
integer literal is.

The class ``IsString`` is defined as: ::

    class IsString a where
        fromString :: String -> a

The only predefined instance is the obvious one to make strings work as
usual: ::

    instance IsString [Char] where
        fromString cs = cs

The class ``IsString`` is not in scope by default. If you want to
mention it explicitly (for example, to give an instance declaration for
it), you can import it from module ``Data.String``.

Haskell's defaulting mechanism (`Haskell Report, Section
4.3.4 <http://www.haskell.org/onlinereport/decls.html#sect4.3.4>`__) is
extended to cover string literals, when :extension:`OverloadedStrings` is
specified. Specifically:

-  Each type in a ``default`` declaration must be an instance of ``Num``
   *or* of ``IsString``.

-  If no ``default`` declaration is given, then it is just as if the
   module contained the declaration
   ``default( Integer, Double, String)``.

-  The standard defaulting rule is extended thus: defaulting applies
   when all the unresolved constraints involve standard classes *or*
   ``IsString``; and at least one is a numeric class *or* ``IsString``.

So, for example, the expression ``length "foo"`` will give rise to an
ambiguous use of ``IsString a0`` which, because of the above rules, will
default to ``String``.

A small example:

::

    module Main where

    import Data.String( IsString(..) )

    newtype MyString = MyString String deriving (Eq, Show)
    instance IsString MyString where
        fromString = MyString

    greet :: MyString -> MyString
    greet "hello" = "world"
    greet other = other

    main = do
        print $ greet "hello"
        print $ greet "fool"

Note that deriving ``Eq`` is necessary for the pattern matching to work
since it gets translated into an equality comparison.

.. _overloaded-labels:

Overloaded labels
-----------------

.. extension:: OverloadedLabels
    :shortdesc: Enable overloaded labels.

    :since: 8.0.1

    Enable use of the ``#foo`` overloaded label syntax.

GHC supports *overloaded labels*, a form of identifier whose interpretation may
depend both on its type and on its literal text.  When the
:extension:`OverloadedLabels` extension is enabled, an overloaded label can be written
with a prefix hash, for example ``#foo``.  The type of this expression is
``IsLabel "foo" a => a``.

The class ``IsLabel`` is defined as:

::

    class IsLabel (x :: Symbol) a where
      fromLabel :: a

This is rather similar to the class ``IsString`` (see
:ref:`overloaded-strings`), but with an additional type parameter that makes the
text of the label available as a type-level string (see
:ref:`type-level-literals`).  Note that ``fromLabel`` had an extra ``Proxy# x``
argument in GHC 8.0, but this was removed in GHC 8.2 as a type application (see
:ref:`visible-type-application`) can be used instead.

There are no predefined instances of this class.  It is not in scope by default,
but can be brought into scope by importing
:base-ref:`GHC.OverloadedLabels.`.  Unlike
``IsString``, there are no special defaulting rules for ``IsLabel``.

During typechecking, GHC will replace an occurrence of an overloaded label like
``#foo`` with ``fromLabel @"foo"``.  This will have some type ``alpha`` and
require the solution of a class constraint ``IsLabel "foo" alpha``.

The intention is for ``IsLabel`` to be used to support overloaded record fields
and perhaps anonymous records.  Thus, it may be given instances for base
datatypes (in particular ``(->)``) in the future.

If :extension:`RebindableSyntax` is enabled, overloaded
labels will be desugared using whatever ``fromLabel`` function is in scope,
rather than always using ``GHC.OverloadedLabels.fromLabel``.

When writing an overloaded label, there must be no space between the hash sign
and the following identifier.  The :extension:`MagicHash` extension makes use
of postfix hash signs; if :extension:`OverloadedLabels` and
:extension:`MagicHash` are both enabled then ``x#y`` means ``x# y``, but if
only :extension:`OverloadedLabels` is enabled then it means ``x #y``.  The
:extension:`UnboxedTuples` extension makes ``(#`` a single lexeme, so when
:extension:`UnboxedTuples` is enabled you must write a space between an opening
parenthesis and an overloaded label.  To avoid confusion, you are strongly
encouraged to put a space before the hash when using
:extension:`OverloadedLabels`.

When using :extension:`OverloadedLabels` (or other extensions that make use of
hash signs) in a ``.hsc`` file (see :ref:`hsc2hs`), the hash signs must be
doubled (write ``##foo`` instead of ``#foo``) to avoid them being treated as
``hsc2hs`` directives.

Here is an extension of the record access example in :ref:`type-level-literals`
showing how an overloaded label can be used as a record selector:

::

    {-# LANGUAGE DataKinds, KindSignatures, MultiParamTypeClasses,
                 FunctionalDependencies, FlexibleInstances,
                 OverloadedLabels, ScopedTypeVariables #-}

    import GHC.OverloadedLabels (IsLabel(..))
    import GHC.TypeLits (Symbol)

    data Label (l :: Symbol) = Get

    class Has a l b | a l -> b where
      from :: a -> Label l -> b

    data Point = Point Int Int deriving Show

    instance Has Point "x" Int where from (Point x _) _ = x
    instance Has Point "y" Int where from (Point _ y) _ = y

    instance Has a l b => IsLabel l (a -> b) where
      fromLabel x = from x (Get :: Label l)

    example = #x (Point 1 2)


.. _overloaded-lists:

Overloaded lists
----------------

.. extension:: OverloadedLists
    :shortdesc: Enable overloaded lists.

    :since: 7.8.1

    Enable overloaded list syntax (e.g. desugaring of lists via the
    ``IsList`` class).

GHC supports *overloading of the list notation*. Let us recap the
notation for constructing lists. In Haskell, the list notation can be
used in the following seven ways:

::

    []          -- Empty list
    [x]         -- x : []
    [x,y,z]     -- x : y : z : []
    [x .. ]     -- enumFrom x
    [x,y ..]    -- enumFromThen x y
    [x .. y]    -- enumFromTo x y
    [x,y .. z]  -- enumFromThenTo x y z

When the ``OverloadedLists`` extension is turned on, the aforementioned
seven notations are desugared as follows:

::

    []          -- fromListN 0 []
    [x]         -- fromListN 1 (x : [])
    [x,y,z]     -- fromListN 3 (x : y : z : [])
    [x .. ]     -- fromList (enumFrom x)
    [x,y ..]    -- fromList (enumFromThen x y)
    [x .. y]    -- fromList (enumFromTo x y)
    [x,y .. z]  -- fromList (enumFromThenTo x y z)

This extension allows programmers to use the list notation for
construction of structures like: ``Set``, ``Map``, ``IntMap``,
``Vector``, ``Text`` and ``Array``. The following code listing gives a
few examples:

::

    ['0' .. '9']             :: Set Char
    [1 .. 10]                :: Vector Int
    [("default",0), (k1,v1)] :: Map String Int
    ['a' .. 'z']             :: Text

List patterns are also overloaded. When the ``OverloadedLists``
extension is turned on, these definitions are desugared as follows

::

    f [] = ...          -- f (toList -> []) = ...
    g [x,y,z] = ...     -- g (toList -> [x,y,z]) = ...

(Here we are using view-pattern syntax for the translation, see
:ref:`view-patterns`.)

The ``IsList`` class
~~~~~~~~~~~~~~~~~~~~

In the above desugarings, the functions ``toList``, ``fromList`` and
``fromListN`` are all methods of the ``IsList`` class, which is itself
exported from the ``GHC.Exts`` module. The type class is defined as
follows:

::

    class IsList l where
      type Item l

      fromList :: [Item l] -> l
      toList   :: l -> [Item l]

      fromListN :: Int -> [Item l] -> l
      fromListN _ = fromList

The ``IsList`` class and its methods are intended to be used in
conjunction with the ``OverloadedLists`` extension.

-  The type function ``Item`` returns the type of items of the structure
   ``l``.

-  The function ``fromList`` constructs the structure ``l`` from the
   given list of ``Item l``.

-  The function ``fromListN`` takes the input list's length as a hint.
   Its behaviour should be equivalent to ``fromList``. The hint can be
   used for more efficient construction of the structure ``l`` compared
   to ``fromList``. If the given hint is not equal to the input list's
   length the behaviour of ``fromListN`` is not specified.

-  The function ``toList`` should be the inverse of ``fromList``.

It is perfectly fine to declare new instances of ``IsList``, so that
list notation becomes useful for completely new data types. Here are
several example instances:

::

    instance IsList [a] where
      type Item [a] = a
      fromList = id
      toList = id

    instance (Ord a) => IsList (Set a) where
      type Item (Set a) = a
      fromList = Set.fromList
      toList = Set.toList

    instance (Ord k) => IsList (Map k v) where
      type Item (Map k v) = (k,v)
      fromList = Map.fromList
      toList = Map.toList

    instance IsList (IntMap v) where
      type Item (IntMap v) = (Int,v)
      fromList = IntMap.fromList
      toList = IntMap.toList

    instance IsList Text where
      type Item Text = Char
      fromList = Text.pack
      toList = Text.unpack

    instance IsList (Vector a) where
      type Item (Vector a) = a
      fromList  = Vector.fromList
      fromListN = Vector.fromListN
      toList = Vector.toList

Rebindable syntax
~~~~~~~~~~~~~~~~~

When desugaring list notation with :extension:`OverloadedLists` GHC uses the
``fromList`` (etc) methods from module ``GHC.Exts``. You do not need to
import ``GHC.Exts`` for this to happen.

However if you use :extension:`RebindableSyntax`, then GHC instead uses
whatever is in scope with the names of ``toList``, ``fromList`` and
``fromListN``. That is, these functions are rebindable; c.f.
:ref:`rebindable-syntax`.

Defaulting
~~~~~~~~~~

Currently, the ``IsList`` class is not accompanied with defaulting
rules. Although feasible, not much thought has gone into how to specify
the meaning of the default declarations like: ::

    default ([a])

Speculation about the future
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The current implementation of the ``OverloadedLists`` extension can be
improved by handling the lists that are only populated with literals in
a special way. More specifically, the compiler could allocate such lists
statically using a compact representation and allow ``IsList`` instances
to take advantage of the compact representation. Equipped with this
capability the ``OverloadedLists`` extension will be in a good position
to subsume the ``OverloadedStrings`` extension (currently, as a special
case, string literals benefit from statically allocated compact
representation).

Undecidable (or recursive) superclasses
---------------------------------------

.. extension:: UndecidableSuperClasses
    :shortdesc: Allow all superclass constraints, including those that may
        result in non-termination of the typechecker.

    :since: 8.0.1

    Allow all superclass constraints, including those that may result in
    non-termination of the typechecker.

The language extension :extension:`UndecidableSuperClasses` allows much more flexible
constraints in superclasses.

A class cannot generally have itself as a superclass. So this is illegal ::

    class C a => D a where ...
    class D a => C a where ...

GHC implements this test conservatively when type functions, or type variables,
are involved. For example ::

    type family F a :: Constraint
    class F a => C a where ...

GHC will complain about this, because you might later add ::

    type instance F Int = C Int

and now we'd be in a superclass loop.  Here's an example involving a type variable ::

   class f (C f) => C f
   class c       => Id c

If we expanded the superclasses of ``C Id`` we'd get first ``Id (C Id)`` and
thence ``C Id`` again.

But superclass constraints like these are sometimes useful, and the conservative
check is annoying where no actual recursion is involved.

Moreover genuninely-recursive superclasses are sometimes useful. Here's a real-life
example (#10318) ::

     class (Frac (Frac a) ~ Frac a,
            Fractional (Frac a),
            IntegralDomain (Frac a))
         => IntegralDomain a where
      type Frac a :: Type

Here the superclass cycle does terminate but it's not entirely straightforward
to see that it does.

With the language extension :extension:`UndecidableSuperClasses` GHC lifts all restrictions
on superclass constraints. If there really *is* a loop, GHC will only
expand it to finite depth.


.. _type-families:

Type families
=============

.. extension:: TypeFamilies
    :shortdesc: Enable type families.
        Implies :extension:`ExplicitNamespaces`, :extension:`KindSignatures`,
        and :extension:`MonoLocalBinds`.

    :implies: :extension:`MonoLocalBinds`, :extension:`KindSignatures`,
              :extension:`ExplicitNamespaces`
    :since: 6.8.1

    Allow use and definition of indexed type and data families.

Indexed type families form an extension to facilitate type-level
programming. Type families are a generalisation of associated data types
[AssocDataTypes2005]_ and associated type synonyms
[AssocTypeSyn2005]_ Type families themselves are described in
Schrijvers 2008 [TypeFamilies2008]_. Type families essentially provide
type-indexed data types and named functions on types, which are useful for
generic programming and highly parameterised library interfaces as well as
interfaces with enhanced static information, much like dependent types. They
might also be regarded as an alternative to functional dependencies, but provide
a more functional style of type-level programming than the relational style of
functional dependencies.

Indexed type families, or type families for short, are type constructors
that represent sets of types. Set members are denoted by supplying the
type family constructor with type parameters, which are called type
indices. The difference between vanilla parametrised type constructors
and family constructors is much like between parametrically polymorphic
functions and (ad-hoc polymorphic) methods of type classes. Parametric
polymorphic functions behave the same at all type instances, whereas
class methods can change their behaviour in dependence on the class type
parameters. Similarly, vanilla type constructors imply the same data
representation for all type instances, but family constructors can have
varying representation types for varying type indices.

Indexed type families come in three flavours: data families, open type
synonym families, and closed type synonym families. They are the indexed
family variants of algebraic data types and type synonyms, respectively.
The instances of data families can be data types and newtypes.

Type families are enabled by the language extension :extension:`TypeFamilies`. Additional
information on the use of type families in GHC is available on `the
Haskell wiki page on type
families <http://www.haskell.org/haskellwiki/GHC/Indexed_types>`__.

.. [AssocDataTypes2005]
    “`Associated Types with Class
    <http://www.cse.unsw.edu.au/~chak/papers/CKPM05.html>`__\ ”, M.
    Chakravarty, G. Keller, S. Peyton Jones,
    and S. Marlow. In Proceedings of “The 32nd Annual
    ACM SIGPLAN-SIGACT Symposium on Principles of
    Programming Languages (POPL'05)”, pages 1-13, ACM
    Press, 2005.

.. [AssocTypeSyn2005]
    “`Type Associated Type
    Synonyms <http://www.cse.unsw.edu.au/~chak/papers/CKP05.html>`__\ ”. M.
    Chakravarty, G. Keller, and S. Peyton Jones. In Proceedings of “The
    Tenth ACM SIGPLAN International Conference on Functional Programming”,
    ACM Press, pages 241-253, 2005.

.. [TypeFamilies2008]
    “\ `Type Checking with Open Type
    Functions <http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html>`__\ ”,
    T. Schrijvers, S. Peyton-Jones, M. Chakravarty, and M. Sulzmann, in
    Proceedings of “ICFP 2008: The 13th ACM SIGPLAN International Conference
    on Functional Programming”, ACM Press, pages 51-62, 2008.


.. _data-families:

Data families
-------------

Data families appear in two flavours: (1) they can be defined on the
toplevel or (2) they can appear inside type classes (in which case they
are known as associated types). The former is the more general variant,
as it lacks the requirement for the type-indexes to coincide with the
class parameters. However, the latter can lead to more clearly
structured code and compiler warnings if some type instances were -
possibly accidentally - omitted. In the following, we always discuss the
general toplevel form first and then cover the additional constraints
placed on associated types.

.. _data-family-declarations:

Data family declarations
~~~~~~~~~~~~~~~~~~~~~~~~

Indexed data families are introduced by a signature, such as ::

    data family GMap k :: Type -> Type

The special ``family`` distinguishes family from standard data
declarations. The result kind annotation is optional and, as usual,
defaults to ``Type`` if omitted. An example is ::

    data family Array e

Named arguments can also be given explicit kind signatures if needed.
Just as with :ref:`GADT declarations <gadt>` named arguments are
entirely optional, so that we can declare ``Array`` alternatively with ::

    data family Array :: Type -> Type

Unlike with ordinary data definitions, the result kind of a data family
does not need to be ``Type``. It can alternatively be:

* Of the form ``TYPE r`` for some ``r`` (see :ref:`runtime-rep`).
  For example: ::

    data family DF1 :: TYPE IntRep
    data family DF2 (r :: RuntimeRep)  :: TYPE r
    data family DF3 :: Type -> TYPE WordRep

* A bare kind variable (with :extension:`PolyKinds` enabled).
  For example: ::

    data family DF4 :: k
    data family DF5 (a :: k) :: k
    data family DF6 :: (k -> Type) -> k

Data instances' kinds must end in ``Type``, however. This restriction is
slightly relaxed when the :extension:`UnliftedNewtypes` extension is enabled,
as it permits a ``newtype instance``'s kind to end in ``TYPE r`` for some
``r``.

.. _data-instance-declarations:

Data instance declarations
~~~~~~~~~~~~~~~~~~~~~~~~~~

Instance declarations of data and newtype families are very similar to
standard data and newtype declarations. The only two differences are
that the keyword ``data`` or ``newtype`` is followed by ``instance`` and
that some or all of the type arguments can be non-variable types, but
may not contain forall types or type synonym families. However, data
families are generally allowed in type parameters, and type synonyms are
allowed as long as they are fully applied and expand to a type that is
itself admissible - exactly as this is required for occurrences of type
synonyms in class instance parameters. For example, the ``Either``
instance for ``GMap`` is ::

    data instance GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)

In this example, the declaration has only one variant. In general, it
can be any number.

When :extension:`ExplicitForAll` is enabled, type and kind variables used on
the left hand side can be explicitly bound. For example: ::

    data instance forall a (b :: Proxy a). F (Proxy b) = FProxy Bool

When an explicit ``forall`` is present, *all* type and kind variables mentioned
which are not already in scope must be bound by the ``forall``:

    data instance forall   (a :: k). F a = FOtherwise  -- rejected: k not in scope
    data instance forall k (a :: k). F a = FOtherwise  -- accepted

When the flag :ghc-flag:`-Wunused-type-patterns` is enabled, type
variables that are mentioned in the patterns on the left hand side, but not
used on the right hand side are reported. Variables that occur multiple times
on the left hand side are also considered used. To suppress the warnings,
unused variables should be either replaced or prefixed with underscores. Type
variables starting with an underscore (``_x``) are otherwise treated as
ordinary type variables.

This resembles the wildcards that can be used in
:ref:`partial-type-signatures`. However, there are some differences.
No error messages reporting the inferred types are generated, nor does
the extension :extension:`PartialTypeSignatures` have any effect.

A type or kind variable explicitly bound using :extension:`ExplicitForAll` but
not used on the left hand side will generate an error, not a warning.

Data and newtype instance declarations are only permitted when an
appropriate family declaration is in scope - just as a class instance
declaration requires the class declaration to be visible. Moreover, each
instance declaration has to conform to the kind determined by its family
declaration. This implies that the number of parameters of an instance
declaration matches the arity determined by the kind of the family.

A data family instance declaration can use the full expressiveness of
ordinary ``data`` or ``newtype`` declarations:

-  Although, a data family is *introduced* with the keyword "``data``",
   a data family *instance* can use either ``data`` or ``newtype``. For
   example: ::

       data family T a
       data    instance T Int  = T1 Int | T2 Bool
       newtype instance T Char = TC Bool

-  A ``data instance`` can use GADT syntax for the data constructors,
   and indeed can define a GADT. For example: ::

       data family G a b
       data instance G [a] b where
          G1 :: c -> G [Int] b
          G2 :: G [a] Bool

-  You can use a ``deriving`` clause on a ``data instance`` or
   ``newtype instance`` declaration.

Even if data families are defined as toplevel declarations, functions
that perform different computations for different family instances may
still need to be defined as methods of type classes. In particular, the
following is not possible: ::

    data family T a
    data instance T Int  = A
    data instance T Char = B
    foo :: T a -> Int
    foo A = 1
    foo B = 2

Instead, you would have to write ``foo`` as a class operation, thus: ::

    class Foo a where
      foo :: T a -> Int
    instance Foo Int where
      foo A = 1
    instance Foo Char where
      foo B = 2

Given the functionality provided by GADTs (Generalised Algebraic Data
Types), it might seem as if a definition, such as the above, should be
feasible. However, type families - in contrast to GADTs - are
*open;* i.e., new instances can always be added, possibly in other
modules. Supporting pattern matching across different data instances
would require a form of extensible case construct.

.. _data-family-overlap:

Overlap of data instances
~~~~~~~~~~~~~~~~~~~~~~~~~

The instance declarations of a data family used in a single program may
not overlap at all, independent of whether they are associated or not.
In contrast to type class instances, this is not only a matter of
consistency, but one of type safety.

.. _synonym-families:

Synonym families
----------------

Type families appear in three flavours: (1) they can be defined as open
families on the toplevel, (2) they can be defined as closed families on
the toplevel, or (3) they can appear inside type classes (in which case
they are known as associated type synonyms). Toplevel families are more
general, as they lack the requirement for the type-indexes to coincide
with the class parameters. However, associated type synonyms can lead to
more clearly structured code and compiler warnings if some type
instances were - possibly accidentally - omitted. In the following, we
always discuss the general toplevel forms first and then cover the
additional constraints placed on associated types. Note that closed
associated type synonyms do not exist.

.. _type-family-declarations:

Type family declarations
~~~~~~~~~~~~~~~~~~~~~~~~

Open indexed type families are introduced by a signature, such as ::

    type family Elem c :: Type

The special ``family`` distinguishes family from standard type
declarations. The result kind annotation is optional and, as usual,
defaults to ``Type`` if omitted. An example is ::

    type family Elem c

Parameters can also be given explicit kind signatures if needed. We call
the number of parameters in a type family declaration, the family's
arity, and all applications of a type family must be fully saturated
with respect to that arity. This requirement is unlike ordinary type synonyms
and it implies that the kind of a type family is not sufficient to
determine a family's arity, and hence in general, also insufficient to
determine whether a type family application is well formed. As an
example, consider the following declaration: ::

    type family F a b :: Type -> Type
      -- F's arity is 2,
      -- although its overall kind is Type -> Type -> Type -> Type

Given this declaration the following are examples of well-formed and
malformed types: ::

    F Char [Int]       -- OK!  Kind: Type -> Type
    F Char [Int] Bool  -- OK!  Kind: Type
    F IO Bool          -- WRONG: kind mismatch in the first argument
    F Bool             -- WRONG: unsaturated application

The result kind annotation is optional and defaults to ``Type`` (like
argument kinds) if omitted. Polykinded type families can be declared
using a parameter in the kind annotation: ::

    type family F a :: k

In this case the kind parameter ``k`` is actually an implicit parameter
of the type family.

.. _type-instance-declarations:

Type instance declarations
~~~~~~~~~~~~~~~~~~~~~~~~~~

Instance declarations of type families are very similar to standard type
synonym declarations. The only two differences are that the keyword
``type`` is followed by ``instance`` and that some or all of the type
arguments can be non-variable types, but may not contain forall types or
type synonym families. However, data families are generally allowed, and
type synonyms are allowed as long as they are fully applied and expand
to a type that is admissible - these are the exact same requirements as
for data instances. For example, the ``[e]`` instance for ``Elem`` is ::

    type instance Elem [e] = e

Type arguments can be replaced with underscores (``_``) if the names of
the arguments don't matter. This is the same as writing type variables
with unique names. Unused type arguments can be replaced or prefixed
with underscores to avoid warnings when the
:ghc-flag:`-Wunused-type-patterns` flag is enabled. The same rules apply
as for :ref:`data-instance-declarations`.

Also in the same way as :ref:`data-instance-declarations`, when
:extension:`ExplicitForAll` is enabled, type and kind variables can be
explicilty bound in a type instance declaration.

Type family instance declarations are only legitimate when an
appropriate family declaration is in scope - just like class instances
require the class declaration to be visible. Moreover, each instance
declaration has to conform to the kind determined by its family
declaration, and the number of type parameters in an instance
declaration must match the number of type parameters in the family
declaration. Finally, the right-hand side of a type instance must be a
monotype (i.e., it may not include foralls) and after the expansion of
all saturated vanilla type synonyms, no synonyms, except family synonyms
may remain.

.. _closed-type-families:

Closed type families
~~~~~~~~~~~~~~~~~~~~

A type family can also be declared with a ``where`` clause, defining the
full set of equations for that family. For example: ::

    type family F a where
      F Int  = Double
      F Bool = Char
      F a    = String

A closed type family's equations are tried in order, from top to bottom,
when simplifying a type family application. In this example, we declare
an instance for ``F`` such that ``F Int`` simplifies to ``Double``,
``F Bool`` simplifies to ``Char``, and for any other type ``a`` that is
known not to be ``Int`` or ``Bool``, ``F a`` simplifies to ``String``.
Note that GHC must be sure that ``a`` cannot unify with ``Int`` or
``Bool`` in that last case; if a programmer specifies just ``F a`` in
their code, GHC will not be able to simplify the type. After all, ``a``
might later be instantiated with ``Int``.

A closed type family's equations have the same restrictions and extensions as
the equations for open type family instances. For instance, when
:extension:`ExplicitForAll` is enabled, type or kind variables used on the
left hand side of an equation can be explicitly bound, such as in: ::

  type family R a where
    forall t a. R (t a) = [a]
    forall a.   R a     = a

A closed type family may be declared with no equations. Such closed type
families are opaque type-level definitions that will never reduce, are
not necessarily injective (unlike empty data types), and cannot be given
any instances. This is different from omitting the equations of a closed
type family in a ``hs-boot`` file, which uses the syntax ``where ..``,
as in that case there may or may not be equations given in the ``hs``
file.

.. _type-family-examples:

Type family examples
~~~~~~~~~~~~~~~~~~~~

Here are some examples of admissible and illegal type instances: ::

    type family F a :: Type
    type instance F [Int]   = Int   -- OK!
    type instance F String  = Char  -- OK!
    type instance F (F a)   = a     -- WRONG: type parameter mentions a type family
    type instance
      F (forall a. (a, b))  = b     -- WRONG: a forall type appears in a type parameter
    type instance
      F Float = forall a.a          -- WRONG: right-hand side may not be a forall type
    type family H a where          -- OK!
      H Int  = Int
      H Bool = Bool
      H a    = String
    type instance H Char = Char    -- WRONG: cannot have instances of closed family
    type family K a where          -- OK!

    type family G a b :: Type -> Type
    type instance G Int            = (,)     -- WRONG: must be two type parameters
    type instance G Int Char Float = Double  -- WRONG: must be two type parameters

.. _type-family-overlap:

Compatibility and apartness of type family equations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There must be some restrictions on the equations of type families, lest
we define an ambiguous rewrite system. So, equations of open type
families are restricted to be compatible. Two type patterns are
compatible if

1. all corresponding types and implicit kinds in the patterns are apart,
   or

2. the two patterns unify producing a substitution, and the right-hand
   sides are equal under that substitution.

Two types are considered apart if, for all possible substitutions, the
types cannot reduce to a common reduct.

The first clause of "compatible" is the more straightforward one. It
says that the patterns of two distinct type family instances cannot
overlap. For example, the following is disallowed: ::

    type instance F Int = Bool
    type instance F Int = Char

The second clause is a little more interesting. It says that two
overlapping type family instances are allowed if the right-hand sides
coincide in the region of overlap. Some examples help here: ::

    type instance F (a, Int) = [a]
    type instance F (Int, b) = [b]   -- overlap permitted

    type instance G (a, Int)  = [a]
    type instance G (Char, a) = [a]  -- ILLEGAL overlap, as [Char] /= [Int]

Note that this compatibility condition is independent of whether the
type family is associated or not, and it is not only a matter of
consistency, but one of type safety.

For a polykinded type family, the kinds are checked for apartness just
like types. For example, the following is accepted: ::

    type family J a :: k
    type instance J Int = Bool
    type instance J Int = Maybe

These instances are compatible because they differ in their implicit kind
parameter; the first uses ``Type`` while the second uses ``Type -> Type``.

The definition for "compatible" uses a notion of "apart", whose
definition in turn relies on type family reduction. This condition of
"apartness", as stated, is impossible to check, so we use this
conservative approximation: two types are considered to be apart when
the two types cannot be unified, even by a potentially infinite unifier.
Allowing the unifier to be infinite disallows the following pair of
instances: ::

    type instance H x   x = Int
    type instance H [x] x = Bool

The type patterns in this pair equal if ``x`` is replaced by an infinite
nesting of lists. Rejecting instances such as these is necessary for
type soundness.

Compatibility also affects closed type families. When simplifying an
application of a closed type family, GHC will select an equation only
when it is sure that no incompatible previous equation will ever apply.
Here are some examples: ::

    type family F a where
      F Int = Bool
      F a   = Char

    type family G a where
      G Int = Int
      G a   = a

In the definition for ``F``, the two equations are incompatible -- their
patterns are not apart, and yet their right-hand sides do not coincide.
Thus, before GHC selects the second equation, it must be sure that the
first can never apply. So, the type ``F a`` does not simplify; only a
type such as ``F Double`` will simplify to ``Char``. In ``G``, on the
other hand, the two equations are compatible. Thus, GHC can ignore the
first equation when looking at the second. So, ``G a`` will simplify to
``a``.

Incompatibilities between closed type family equations can be displayed
in :ghci-cmd:`:info` when :ghc-flag:`-fprint-axiom-incomps` is enabled.

However see :ref:`ghci-decls` for the overlap rules in GHCi.

.. _type-family-decidability:

Decidability of type synonym instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. extension:: UndecidableInstances
    :noindex:

    Relax restrictions on the decidability of type synonym family instances.

In order to guarantee that type inference in the presence of type
families decidable, we need to place a number of additional restrictions
on the formation of type instance declarations (c.f., Definition 5
(Relaxed Conditions) of “\ `Type Checking with Open Type
Functions <http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html>`__\ ”).
Instance declarations have the general form ::

    type instance F t1 .. tn = t

where we require that for every type family application ``(G s1 .. sm)``
in ``t``,

1. ``s1 .. sm`` do not contain any type family constructors,

2. the total number of symbols (data type constructors and type
   variables) in ``s1 .. sm`` is strictly smaller than in ``t1 .. tn``,
   and

3. for every type variable ``a``, ``a`` occurs in ``s1 .. sm`` at most
   as often as in ``t1 .. tn``.

These restrictions are easily verified and ensure termination of type
inference. However, they are not sufficient to guarantee completeness of
type inference in the presence of, so called, ''loopy equalities'', such
as ``a ~ [F a]``, where a recursive occurrence of a type variable is
underneath a family application and data constructor application - see
the above mentioned paper for details.

If the option :extension:`UndecidableInstances` is passed to the compiler, the
above restrictions are not enforced and it is on the programmer to ensure
termination of the normalisation of type families during type inference.

.. _type-wildcards-lhs:

Wildcards on the LHS of data and type family instances
------------------------------------------------------

When the name of a type argument of a data or type instance
declaration doesn't matter, it can be replaced with an underscore
(``_``). This is the same as writing a type variable with a unique name. ::

    data family F a b :: Type
    data instance F Int _ = Int
    -- Equivalent to  data instance F Int b = Int

    type family T a :: Type
    type instance T (a,_) = a
    -- Equivalent to  type instance T (a,b) = a

This use of underscore for wildcard in a type pattern is exactly like
pattern matching in the term language, but is rather different to the
use of a underscore in a partial type signature (see :ref:`type-wildcards`).

A type variable beginning with an underscore is not treated specially in a
type or data instance declaration.  For example: ::

   data instance F Bool _a = _a -> Int
   -- Equivalent to  data instance F Bool a = a -> Int

Contrast this with the special treatment of named wildcards in
type signatures (:ref:`named-wildcards`).


.. _assoc-decl:

Associated data and type families
---------------------------------

A data or type synonym family can be declared as part of a type class,
thus: ::

    class GMapKey k where
      data GMap k :: Type -> Type
      ...

    class Collects ce where
      type Elem ce :: Type
      ...

When doing so, we (optionally) may drop the "``family``" keyword.

The type parameters must all be type variables, of course, and some (but
not necessarily all) of then can be the class parameters. Each class
parameter may only be used at most once per associated type, but some
may be omitted and they may be in an order other than in the class head.
Hence, the following contrived example is admissible: ::

      class C a b c where
        type T c a x :: Type

Here ``c`` and ``a`` are class parameters, but the type is also indexed
on a third parameter ``x``.

.. _assoc-inst:

Associated instances
~~~~~~~~~~~~~~~~~~~~

When an associated data or type synonym family instance is declared
within a type class instance, we (optionally) may drop the ``instance``
keyword in the family instance: ::

    instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where
      data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
      ...

    instance Eq (Elem [e]) => Collects [e] where
      type Elem [e] = e
      ...

The data or type family instance for an associated type must follow
the rule that the type indexes corresponding to class parameters must have
precisely the same as type given in the instance head. For example: ::

    class Collects ce where
      type Elem ce :: Type

    instance Eq (Elem [e]) => Collects [e] where
      -- Choose one of the following alternatives:
      type Elem [e] = e       -- OK
      type Elem [x] = x       -- BAD; '[x]' is different to '[e]' from head
      type Elem x   = x       -- BAD; 'x' is different to '[e]'
      type Elem [Maybe x] = x -- BAD: '[Maybe x]' is different to '[e]'

Note the following points:

-  An instance for an associated family can only appear as part of an
   instance declarations of the class in which the family was declared,
   just as with the equations of the methods of a class.

-  The type variables on the right hand side of the type family equation
   must, as usual, be explicitly bound by the left hand side. This restriction
   is relaxed for *kind* variables, however, as the right hand side is allowed
   to mention kind variables that are implicitly bound. For example, these are
   legitimate: ::

    data family Nat :: k -> k -> Type
    -- k is implicitly bound by an invisible kind pattern
    newtype instance Nat :: (k -> Type) -> (k -> Type) -> Type where
      Nat :: (forall xx. f xx -> g xx) -> Nat f g

    class Funct f where
      type Codomain f :: Type
    instance Funct ('KProxy :: KProxy o) where
      -- o is implicitly bound by the kind signature
      -- of the LHS type pattern ('KProxy)
      type Codomain 'KProxy = NatTr (Proxy :: o -> Type)

-  The instance for an associated type can be omitted in class
   instances. In that case, unless there is a default instance (see
   :ref:`assoc-decl-defs`), the corresponding instance type is not
   inhabited; i.e., only diverging expressions, such as ``undefined``,
   can assume the type.

-  Although it is unusual, there (currently) can be *multiple* instances
   for an associated family in a single instance declaration. For
   example, this is legitimate: ::

       instance GMapKey Flob where
         data GMap Flob [v] = G1 v
         data GMap Flob Int = G2 Int
         ...

   Here we give two data instance declarations, one in which the last
   parameter is ``[v]``, and one for which it is ``Int``. Since you
   cannot give any *subsequent* instances for ``(GMap Flob ...)``, this
   facility is most useful when the free indexed parameter is of a kind
   with a finite number of alternatives (unlike ``Type``).

-  When :extension:`ExplicitForAll` is enabled, type and kind variables can be
   explicily bound in associated data or type family instances in the same way
   (and with the same restrictions) as :ref:`data-instance-declarations` or
   :ref:`type-instance-declarations`. For example, adapting the above, the
   following is accepted: ::

     instance Eq (Elem [e]) => Collects [e] where
       type forall e. Elem [e] = e

.. _assoc-decl-defs:

Associated type synonym defaults
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It is possible for the class defining the associated type to specify a
default for associated type instances. So for example, this is OK: ::

    class IsBoolMap v where
      type Key v
      type instance Key v = Int

      lookupKey :: Key v -> v -> Maybe Bool

    instance IsBoolMap [(Int, Bool)] where
      lookupKey = lookup

In an ``instance`` declaration for the class, if no explicit
``type instance`` declaration is given for the associated type, the
default declaration is used instead, just as with default class methods.

Note the following points:

-  The ``instance`` keyword is optional.

-  There can be at most one default declaration for an associated type
   synonym.

-  A default declaration is not permitted for an associated *data* type.

-  The default declaration must mention only type *variables* on the
   left hand side, and type variables may not be repeated on the left-hand
   side. The right hand side must mention only type
   variables that are explicitly bound on the left hand side. This restriction
   is relaxed for *kind* variables, however, as the right hand side is allowed
   to mention kind variables that are implicitly bound on the left hand side.

   Like with :ref:`assoc-inst`, it is possible to explicitly bind type and kind
   variables in default declarations with a ``forall`` by using the
   :extension:`ExplicitForAll` language extension.

-  Unlike the associated type family declaration itself, the type variables of
   the default instance are independent of those of the parent class.

Here are some examples:

::

      class C (a :: Type) where
        type F1 a :: Type
        type instance F1 a = [a]     -- OK
        type instance F1 a = a->a    -- BAD; only one default instance is allowed

        type F2 b a                  -- OK; note the family has more type
                                     --     variables than the class
        type instance F2 c d = c->d  -- OK; you don't have to use 'a' in the type instance

        type F3 a
        type F3 [b] = b              -- BAD; only type variables allowed on the
                                             LHS, and the argument to F3 is
                                             instantiated to [b], which is not
                                             a bare type variable

        type F4 x y
        type F4 x x = x              -- BAD; the type variable x is repeated on
                                             the LHS

        type F5 a
        type F5 b = a                -- BAD; 'a' is not in scope  in the RHS

        type F6 a :: [k]
        type F6 a = ('[] :: [x])     -- OK; the kind variable x is implicitly
                                            bound by an invisible kind pattern
                                            on the LHS

        type F7 a
        type F7 a =
          Proxy ('[] :: [x])         -- BAD; the kind variable x is not bound,
                                             even by an invisible kind pattern

        type F8 (x :: a) :: [a]
        type F8 x = ('[] :: [a])     -- OK; the kind variable a is implicitly
                                            bound by the kind signature of the
                                            LHS type pattern

        type F9 (a :: k)
        type F9 a = Maybe a          -- BAD; the kind variable k is
                                             instantiated to Type, which is not
                                             a bare kind variable

        type F10 (a :: j) (b :: k)
        type F10 (a :: z) (b :: z)
          = Proxy a                  -- BAD; the kind variable z is repeated,
                                     -- as both j and k are instantiated to z

        type F11 a b
        type forall a b. F11 a b = a -- OK; LHS type variables can be
                                        explicitly bound with 'forall'

        type F12 (a :: k)
        type F12 @k a = Proxy a      -- OK; visible kind application syntax is
                                            permitted in default declarations

.. _scoping-class-params:

Scoping of class parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The visibility of class parameters in the right-hand side of associated
family instances depends *solely* on the parameters of the family. As an
example, consider the simple class declaration ::

    class C a b where
      data T a

Only one of the two class parameters is a parameter to the data family.
Hence, the following instance declaration is invalid: ::

    instance C [c] d where
      data T [c] = MkT (c, d)    -- WRONG!!  'd' is not in scope

Here, the right-hand side of the data instance mentions the type
variable ``d`` that does not occur in its left-hand side. We cannot
admit such data instances as they would compromise type safety.

Bear in mind that it is also possible for the *right*-hand side of an
associated family instance to contain *kind* parameters (by using the
:extension:`PolyKinds` extension). For instance, this class and instance are
perfectly admissible: ::

    class C k where
      type T :: k

    instance C (Maybe a) where
      type T = (Nothing :: Maybe a)

Here, although the right-hand side ``(Nothing :: Maybe a)`` mentions a kind
variable ``a`` which does not occur on the left-hand side, this is acceptable,
because ``a`` is *implicitly* bound by ``T``'s kind pattern.

A kind variable can also be bound implicitly in a LHS type pattern, as in this
example: ::

    class C a where
      type T (x :: a) :: [a]

    instance C (Maybe a) where
      type T x = ('[] :: [Maybe a])

In ``('[] :: [Maybe a])``, the kind variable ``a`` is implicitly bound by the
kind signature of the LHS type pattern ``x``.

Instance contexts and associated type and data instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Associated type and data instance declarations do not inherit any
context specified on the enclosing instance. For type instance
declarations, it is unclear what the context would mean. For data
instance declarations, it is unlikely a user would want the context
repeated for every data constructor. The only place where the context
might likely be useful is in a ``deriving`` clause of an associated data
instance. However, even here, the role of the outer instance context is
murky. So, for clarity, we just stick to the rule above: the enclosing
instance context is ignored. If you need to use a non-trivial context on
a derived instance, use a :ghc-flag:`standalone deriving <-XStandaloneDeriving>`
clause (at the top level).

.. _data-family-import-export:

Import and export
-----------------

The rules for export lists (Haskell Report `Section
5.2 <http://www.haskell.org/onlinereport/modules.html#sect5.2>`__) needs
adjustment for type families:

-  The form ``T(..)``, where ``T`` is a data family, names the family
   ``T`` and all the in-scope constructors (whether in scope qualified
   or unqualified) that are data instances of ``T``.

-  The form ``T(.., ci, .., fj, ..)``, where ``T`` is a data family,
   names ``T`` and the specified constructors ``ci`` and fields ``fj``
   as usual. The constructors and field names must belong to some data
   instance of ``T``, but are not required to belong to the *same*
   instance.

-  The form ``C(..)``, where ``C`` is a class, names the class ``C`` and
   all its methods *and associated types*.

-  The form ``C(.., mi, .., type Tj, ..)``, where ``C`` is a class,
   names the class ``C``, and the specified methods ``mi`` and
   associated types ``Tj``. The types need a keyword "``type``" to
   distinguish them from data constructors.

-  Whenever there is no export list and a data instance is defined, the
   corresponding data family type constructor is exported along with
   the new data constructors, regardless of whether the data family
   is defined locally or in another module.

.. _data-family-impexp-examples:

Examples
~~~~~~~~

Recall our running ``GMapKey`` class example:

::

    class GMapKey k where
      data GMap k :: Type -> Type
      insert :: GMap k v -> k -> v -> GMap k v
      lookup :: GMap k v -> k -> Maybe v
      empty  :: GMap k v

    instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where
      data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
      ...method declarations...

Here are some export lists and their meaning:

-  ::

     module GMap( GMapKey )

   Exports just the class name.

-  ::

     module GMap( GMapKey(..) )

   Exports the class, the associated type ``GMap`` and the member functions
   ``empty``, ``lookup``, and ``insert``. The data constructors of ``GMap`` (in
   this case ``GMapEither``) are not exported.

-  ::

     module GMap( GMapKey( type GMap, empty, lookup, insert ) )

   Same as the previous item. Note the "``type``" keyword.

-  ::

     module GMap( GMapKey(..), GMap(..) )

   Same as previous item, but also exports all the data constructors for
   ``GMap``, namely
   ``GMapEither``.

-  ::

     module GMap ( GMapKey( empty, lookup, insert), GMap(..) )

   Same as previous item.

-  ::

     module GMap ( GMapKey, empty, lookup, insert, GMap(..) )

   Same as previous item.

Two things to watch out for:

-  You cannot write ``GMapKey(type GMap(..))`` — i.e., sub-component
   specifications cannot be nested. To specify ``GMap``\ 's data
   constructors, you have to list it separately.

-  Consider this example: ::

         module X where
           data family D

         module Y where
           import X
           data instance D Int = D1 | D2

   Module ``Y`` exports all the entities defined in ``Y``, namely the data
   constructors ``D1`` and ``D2``, and *implicitly* the data family ``D``,
   even though it's defined in ``X``.
   This means you can write ``import Y( D(D1,D2) )`` *without*
   giving an explicit export list like this: ::

            module Y( D(..) ) where ...
       or   module Y( module Y, D ) where ...

.. _data-family-impexp-instances:

Instances
~~~~~~~~~

Family instances are implicitly exported, just like class instances.
However, this applies only to the heads of instances, not to the data
constructors an instance defines.

.. _ty-fams-in-instances:

Type families and instance declarations
---------------------------------------

Type families require us to extend the rules for the form of instance
heads, which are given in :ref:`flexible-instance-head`. Specifically:

-  Data type families may appear in an instance head

-  Type synonym families may not appear (at all) in an instance head

The reason for the latter restriction is that there is no way to check
for instance matching. Consider

::

       type family F a
       type instance F Bool = Int

       class C a

       instance C Int
       instance C (F a)

Now a constraint ``(C (F Bool))`` would match both instances. The
situation is especially bad because the type instance for ``F Bool``
might be in another module, or even in a module that is not yet written.

However, type class instances of instances of data families can be
defined much like any other data type. For example, we can say

::

    data instance T Int = T1 Int | T2 Bool
    instance Eq (T Int) where
      (T1 i) == (T1 j) = i==j
      (T2 i) == (T2 j) = i==j
      _      == _      = False

Note that class instances are always for particular *instances* of a
data family and never for an entire family as a whole. This is for
essentially the same reasons that we cannot define a toplevel function
that performs pattern matching on the data constructors of *different*
instances of a single type family. It would require a form of extensible
case construct.

Data instance declarations can also have ``deriving`` clauses. For
example, we can write ::

    data GMap () v = GMapUnit (Maybe v)
                   deriving Show

which implicitly defines an instance of the form ::

    instance Show v => Show (GMap () v) where ...


.. _injective-ty-fams:

Injective type families
-----------------------

.. extension:: TypeFamilyDependencies
    :shortdesc: Enable injective type families.
        Implies :extension:`TypeFamilies`.

    :implies: :extension:`TypeFamilies`
    :since: 8.0.1

    Allow functional dependency annotations on type families. This allows one to
    define injective type families.

Starting with GHC 8.0 type families can be annotated with injectivity
information. This information is then used by GHC during type checking
to resolve type ambiguities in situations where a type variable appears
only under type family applications. Consider this contrived example: ::

    type family Id a
    type instance Id Int = Int
    type instance Id Bool = Bool

    id :: Id t -> Id t
    id x = x

Here the definition of ``id`` will be rejected because type variable ``t``
appears only under type family applications and is thus ambiguous.  But this
code will be accepted if we tell GHC that ``Id`` is injective, which means it
will be possible to infer ``t`` at call sites from the type of the argument: ::

    type family Id a = r | r -> a

Injective type families are enabled with ``-XTypeFamilyDependencies`` language
extension.  This extension implies ``-XTypeFamilies``.

For full details on injective type families refer to Haskell Symposium
2015 paper `Injective type families for
Haskell <http://ics.p.lodz.pl/~stolarek/_media/pl:research:stolarek_peyton-jones_eisenberg_injectivity_extended.pdf>`__.

.. _injective-ty-fams-syntax:

Syntax of injectivity annotation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Injectivity annotation is added after type family head and consists of
two parts:

-  a type variable that names the result of a type family. Syntax:
   ``= tyvar`` or ``= (tyvar :: kind)``. Type variable must be fresh.

-  an injectivity annotation of the form ``| A -> B``, where ``A`` is the
   result type variable (see previous bullet) and ``B`` is a list of
   argument type and kind variables in which type family is injective.
   It is possible to omit some variables if type family is not injective
   in them.

Examples: ::

    type family Id a = result | result -> a where
    type family F a b c = d | d -> a c b
    type family G (a :: k) b c = foo | foo -> k b where

For open and closed type families it is OK to name the result but skip
the injectivity annotation. This is not the case for associated type
synonyms, where the named result without injectivity annotation will be
interpreted as associated type synonym default.

.. _injective-ty-fams-typecheck:

Verifying injectivity annotation against type family equations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once the user declares type family to be injective GHC must verify that
this declaration is correct, ie. type family equations don't violate the
injectivity annotation. A general idea is that if at least one equation
(bullets (1), (2) and (3) below) or a pair of equations (bullets (4) and
(5) below) violates the injectivity annotation then a type family is not
injective in a way user claims and an error is reported. In the bullets
below *RHS* refers to the right-hand side of the type family equation
being checked for injectivity. *LHS* refers to the arguments of that
type family equation. Below are the rules followed when checking
injectivity of a type family:

1. If a RHS of a type family equation is a type family application GHC
   reports that the type family is not injective.

2. If a RHS of a type family equation is a bare type variable we require
   that all LHS variables (including implicit kind variables) are also
   bare. In other words, this has to be a sole equation of that type
   family and it has to cover all possible patterns. If the patterns are
   not covering GHC reports that the type family is not injective.

3. If a LHS type variable that is declared as injective is not mentioned
   on injective position
   in the RHS GHC reports that the type family is not injective.
   Injective position means either argument to a type constructor or
   injective argument to a type family.

4. *Open type families* Open type families are typechecked
   incrementally. This means that when a module is imported type family
   instances contained in that module are checked against instances
   present in already imported modules.

   A pair of an open type family equations is checked by attempting to
   unify their RHSs. If the RHSs don't unify this pair does not violate
   injectivity annotation. If unification succeeds with a substitution
   then LHSs of unified equations must be identical under that
   substitution. If they are not identical then GHC reports that the
   type family is not injective.

5. In a *closed type family* all equations are ordered and in one place.
   Equations are also checked pair-wise but this time an equation has to
   be paired with all the preceeding equations. Of course a
   single-equation closed type family is trivially injective (unless
   (1), (2) or (3) above holds).

   When checking a pair of closed type family equations GHC tried to
   unify their RHSs. If they don't unify this pair of equations does not
   violate injectivity annotation. If the RHSs can be unified under some
   substitution (possibly empty) then either the LHSs unify under the
   same substitution or the LHS of the latter equation is subsumed by
   earlier equations. If neither condition is met GHC reports that a
   type family is not injective.

Note that for the purpose of injectivity check in bullets (4) and (5)
GHC uses a special variant of unification algorithm that treats type
family applications as possibly unifying with anything.

.. _promotion:

Datatype promotion
==================

.. extension:: DataKinds
    :shortdesc: Enable datatype promotion.

    :since: 7.4.1

    Allow promotion of data types to kind level.

This section describes *data type promotion*, an extension to the kind
system that complements kind polymorphism. It is enabled by
:extension:`DataKinds`, and described in more detail in the paper `Giving
Haskell a Promotion <http://dreixel.net/research/pdf/ghp.pdf>`__, which
appeared at TLDI 2012.

Motivation
----------

Standard Haskell has a rich type language. Types classify terms and
serve to avoid many common programming mistakes. The kind language,
however, is relatively simple, distinguishing only regular types (kind
``Type``) and type constructors (e.g. kind ``Type -> Type -> Type``).
In particular when using advanced type
system features, such as type families (:ref:`type-families`) or GADTs
(:ref:`gadt`), this simple kind system is insufficient, and fails to
prevent simple errors. Consider the example of type-level natural
numbers, and length-indexed vectors: ::

    data Ze
    data Su n

    data Vec :: Type -> Type -> Type where
      Nil  :: Vec a Ze
      Cons :: a -> Vec a n -> Vec a (Su n)

The kind of ``Vec`` is ``Type -> Type -> Type``. This means that, e.g.,
``Vec Int Char`` is a well-kinded type, even though this is not what we
intend when defining length-indexed vectors.

With :extension:`DataKinds`, the example above can then be rewritten to: ::

    data Nat = Ze | Su Nat

    data Vec :: Type -> Nat -> Type where
      Nil  :: Vec a 'Ze
      Cons :: a -> Vec a n -> Vec a ('Su n)

With the improved kind of ``Vec``, things like ``Vec Int Char`` are now
ill-kinded, and GHC will report an error.

Overview
--------

With :extension:`DataKinds`, GHC automatically promotes every datatype
to be a kind and its (value) constructors to be type constructors. The
following types ::

    data Nat = Zero | Succ Nat

    data List a = Nil | Cons a (List a)

    data Pair a b = Pair a b

    data Sum a b = L a | R b

give rise to the following kinds and type constructors (where promoted
constructors are prefixed by a tick ``'``): ::

    Nat :: Type
    'Zero :: Nat
    'Succ :: Nat -> Nat

    List :: Type -> Type
    'Nil  :: forall k. List k
    'Cons :: forall k. k -> List k -> List k

    Pair  :: Type -> Type -> Type
    'Pair :: forall k1 k2. k1 -> k2 -> Pair k1 k2

    Sum :: Type -> Type -> Type
    'L :: k1 -> Sum k1 k2
    'R :: k2 -> Sum k1 k2

Virtually all data constructors, even those with rich kinds, can be promoted.
There are only a couple of exceptions to this rule:

-  Data family instance constructors cannot be promoted at the moment. GHC's
   type theory just isn’t up to the task of promoting data families, which
   requires full dependent types.

-  Data constructors with contexts that contain non-equality constraints cannot
   be promoted. For example: ::

     data Foo :: Type -> Type where
       MkFoo1 :: a ~ Int         => Foo a    -- promotable
       MkFoo2 :: a ~~ Int        => Foo a    -- promotable
       MkFoo3 :: Show a          => Foo a    -- not promotable

   ``MkFoo1`` and ``MkFoo2`` can be promoted, since their contexts
   only involve equality-oriented constraints. However, ``MkFoo3``'s context
   contains a non-equality constraint ``Show a``, and thus cannot be promoted.

.. _promotion-syntax:

Distinguishing between types and constructors
---------------------------------------------

In the examples above, all promoted constructors are prefixed with a single
quote mark ``'``. This mark tells GHC to look in the data constructor namespace
for a name, not the type (constructor) namespace. Consider ::

    data P = MkP    -- 1

    data Prom = P   -- 2

We can thus distinguish the type ``P`` (which has a constructor ``MkP``)
from the promoted data constructor ``'P`` (of kind ``Prom``).

As a convenience, GHC allows you to omit the quote mark when the name is
unambiguous. However, our experience has shown that the quote mark helps
to make code more readable and less error-prone. GHC thus supports
:ghc-flag:`-Wunticked-promoted-constructors` that will warn you if you
use a promoted data constructor without a preceding quote mark.

Just as in the case of Template Haskell (:ref:`th-syntax`), GHC gets
confused if you put a quote mark before a data constructor whose second
character is a quote mark. In this case, just put a space between the
promotion quote and the data constructor: ::

  data T = A'
  type S = 'A'   -- ERROR: looks like a character
  type R = ' A'  -- OK: promoted `A'`

.. _promoted-lists-and-tuples:

Promoted list and tuple types
-----------------------------

With :extension:`DataKinds`, Haskell's list and tuple types are natively
promoted to kinds, and enjoy the same convenient syntax at the type
level, albeit prefixed with a quote: ::

    data HList :: [Type] -> Type where
      HNil  :: HList '[]
      HCons :: a -> HList t -> HList (a ': t)

    data Tuple :: (Type,Type) -> Type where
      Tuple :: a -> b -> Tuple '(a,b)

    foo0 :: HList '[]
    foo0 = HNil

    foo1 :: HList '[Int]
    foo1 = HCons (3::Int) HNil

    foo2 :: HList [Int, Bool]
    foo2 = ...

For type-level lists of *two or more elements*, such as the signature of
``foo2`` above, the quote may be omitted because the meaning is unambiguous. But
for lists of one or zero elements (as in ``foo0`` and ``foo1``), the quote is
required, because the types ``[]`` and ``[Int]`` have existing meanings in
Haskell.

.. note::
    The declaration for ``HCons`` also requires :extension:`TypeOperators`
    because of infix type operator ``(':)``


.. _promotion-existentials:

Promoting existential data constructors
---------------------------------------

Note that we do promote existential data constructors that are otherwise
suitable. For example, consider the following: ::

    data Ex :: Type where
      MkEx :: forall a. a -> Ex

Both the type ``Ex`` and the data constructor ``MkEx`` get promoted,
with the polymorphic kind ``'MkEx :: forall k. k -> Ex``. Somewhat
surprisingly, you can write a type family to extract the member of a
type-level existential: ::

    type family UnEx (ex :: Ex) :: k
    type instance UnEx (MkEx x) = x

At first blush, ``UnEx`` seems poorly-kinded. The return kind ``k`` is
not mentioned in the arguments, and thus it would seem that an instance
would have to return a member of ``k`` *for any* ``k``. However, this is
not the case. The type family ``UnEx`` is a kind-indexed type family.
The return kind ``k`` is an implicit parameter to ``UnEx``. The
elaborated definitions are as follows (where implicit parameters are
denoted by braces): ::

    type family UnEx {k :: Type} (ex :: Ex) :: k
    type instance UnEx {k} (MkEx @k x) = x

Thus, the instance triggers only when the implicit parameter to ``UnEx``
matches the implicit parameter to ``MkEx``. Because ``k`` is actually a
parameter to ``UnEx``, the kind is not escaping the existential, and the
above code is valid.

See also :ghc-ticket:`7347`.

.. _type-in-type:
.. _kind-polymorphism:

Kind polymorphism
==================================

.. extension:: TypeInType
    :shortdesc: Deprecated. Enable kind polymorphism and datatype promotion.

    :implies: :extension:`PolyKinds`, :extension:`DataKinds`, :extension:`KindSignatures`
    :since: 8.0.1

    The extension :extension:`TypeInType` is now deprecated: its sole effect is
    to switch on :extension:`PolyKinds`
    (and hence :extension:`KindSignatures`) and :extension:`DataKinds`.

.. extension:: PolyKinds
    :shortdesc: Enable kind polymorphism.
        Implies :extension:`KindSignatures`.

    :implies: :extension:`KindSignatures`
    :since: 7.4.1

    Allow kind polymorphic types.

This section describes GHC's kind system, as it appears in version 8.0 and beyond.
The kind system as described here is always in effect, with or without extensions,
although it is a conservative extension beyond standard Haskell. The extensions
above simply enable syntax and tweak the inference algorithm to allow users to
take advantage of the extra expressiveness of GHC's kind system.

Overview of kind polymorphism
-----------------------------

Consider inferring the kind for ::

  data App f a = MkApp (f a)

In Haskell 98, the inferred kind for ``App`` is ``(Type -> Type) -> Type ->
Type``. But this is overly specific, because another suitable Haskell 98 kind
for ``App`` is ``((Type -> Type) -> Type) -> (Type -> Type) -> Type``, where the
kind assigned to ``a`` is ``Type -> Type``. Indeed, without kind signatures
(:extension:`KindSignatures`), it is necessary to use a dummy constructor to get
a Haskell compiler to infer the second kind. With kind polymorphism
(:extension:`PolyKinds`), GHC infers the kind ``forall k. (k -> Type) -> k ->
Type`` for ``App``, which is its most general kind.

Thus, the chief benefit of kind polymorphism is that we can now infer these
most general kinds and use ``App`` at a variety of kinds: ::

  App Maybe Int   -- `k` is instantiated to Type

  data T a = MkT (a Int)    -- `a` is inferred to have kind (Type -> Type)
  App T Maybe     -- `k` is instantiated to (Type -> Type)

Overview of Type-in-Type
------------------------

GHC 8 extends the idea of kind polymorphism by declaring that types and kinds
are indeed one and the same. Nothing within GHC distinguishes between types
and kinds. Another way of thinking about this is that the type ``Bool`` and
the "promoted kind" ``Bool`` are actually identical. (Note that term
``True`` and the type ``'True`` are still distinct, because the former can
be used in expressions and the latter in types.) This lack of distinction
between types and kinds is a hallmark of dependently typed languages.
Full dependently typed languages also remove the difference between expressions
and types, but doing that in GHC is a story for another day.

One simplification allowed by combining types and kinds is that the type of
``Type`` is just ``Type``. It is true that the ``Type :: Type`` axiom can lead
to non-termination, but this is not a problem in GHC, as we already have other
means of non-terminating programs in both types and expressions. This decision
(among many, many others) *does* mean that despite the expressiveness of GHC's
type system, a "proof" you write in Haskell is not an irrefutable mathematical
proof. GHC promises only partial correctness, that if your programs compile and
run to completion, their results indeed have the types assigned. It makes no
claim about programs that do not finish in a finite amount of time.

To learn more about this decision and the design of GHC under the hood
please see the `paper <http://www.seas.upenn.edu/~sweirich/papers/fckinds.pdf>`__
introducing this kind system to GHC/Haskell.

Principles of kind inference
----------------------------

Generally speaking, when :extension:`PolyKinds` is on, GHC tries to infer the
most general kind for a declaration.
In many cases (for example, in a datatype declaration)
the definition has a right-hand side to inform kind
inference. But that is not always the case. Consider ::

    type family F a

Type family declarations have no right-hand side, but GHC must still
infer a kind for ``F``. Since there are no constraints, it could infer
``F :: forall k1 k2. k1 -> k2``, but that seems *too* polymorphic. So
GHC defaults those entirely-unconstrained kind variables to ``Type`` and we
get ``F :: Type -> Type``. You can still declare ``F`` to be kind-polymorphic
using kind signatures: ::

    type family F1 a                -- F1 :: Type -> Type
    type family F2 (a :: k)         -- F2 :: forall k. k -> Type
    type family F3 a :: k           -- F3 :: forall k. Type -> k
    type family F4 (a :: k1) :: k2  -- F4 :: forall k1 k2. k1 -> k2

The general principle is this:

-  When there is a right-hand side, GHC infers the most polymorphic
   kind consistent with the right-hand side. Examples: ordinary data
   type and GADT declarations, class declarations. In the case of a
   class declaration the role of "right hand side" is played by the
   class method signatures.

-  When there is no right hand side, GHC defaults argument and result
   kinds to ``Type``, except when directed otherwise by a kind signature.
   Examples: data and open type family declarations.

This rule has occasionally-surprising consequences (see
:ghc-ticket:`10132`). ::

    class C a where    -- Class declarations are generalised
                       -- so C :: forall k. k -> Constraint
      data D1 a        -- No right hand side for these two family
      type F1 a        -- declarations, but the class forces (a :: k)
                       -- so   D1, F1 :: forall k. k -> Type

    data D2 a   -- No right-hand side so D2 :: Type -> Type
    type F2 a   -- No right-hand side so F2 :: Type -> Type

The kind-polymorphism from the class declaration makes ``D1``
kind-polymorphic, but not so ``D2``; and similarly ``F1``, ``F1``.

.. _inferring-variable-order:

Inferring the order of variables in a type/class declaration
------------------------------------------------------------

It is possible to get intricate dependencies among the type variables
introduced in a type or class declaration. Here is an example::

  data T a (b :: k) c = MkT (a c)

After analysing this declaration, GHC will discover that ``a`` and
``c`` can be kind-polymorphic, with ``a :: k2 -> Type`` and
``c :: k2``. We thus infer the following kind::

  T :: forall {k2 :: Type} (k :: Type). (k2 -> Type) -> k -> k2 -> Type

Note that ``k2`` is placed *before* ``k``, and that ``k`` is placed *before*
``a``. Also, note that ``k2`` is written here in braces. As explained with
:extension:`TypeApplications` (:ref:`inferred-vs-specified`),
type and kind variables that GHC generalises
over, but not written in the original program, are not available for visible
type application. (These are called *inferred* variables.)
Such variables are written in braces with
:ghc-flag:`-fprint-explicit-foralls` enabled.

The general principle is this:

  * Variables not available for type application come first.

  * Then come variables the user has written, implicitly brought into scope
    in a type variable's kind.

  * Lastly come the normal type variables of a declaration.

  * Variables not given an explicit ordering by the user are sorted according
    to ScopedSort (:ref:`ScopedSort`).

With the ``T`` example above, we could bind ``k`` *after* ``a``; doing so
would not violate dependency concerns. However, it would violate our general
principle, and so ``k`` comes first.

Sometimes, this ordering does not respect dependency. For example::

  data T2 k (a :: k) (c :: Proxy '[a, b])

It must be that ``a`` and ``b`` have the same kind. Note also that ``b``
is implicitly declared in ``c``\'s kind. Thus, according to our general
principle, ``b`` must come *before* ``k``. However, ``b`` *depends on*
``k``. We thus reject ``T2`` with a suitable error message.

In associated types, we order the type variables as if the type family was a
top-level declaration, ignoring the visibilities of the class's type variable
binders. Here is an example: ::

  class C (a :: k) b where
    type F (c :: j) (d :: Proxy m) a b

We infer these kinds::

  C :: forall {k1 :: Type} (k :: Type). k -> k1 -> Constraint
  F :: forall {k1 :: Type} {k2 :: Type} {k3 :: Type} j (m :: k1).
       j -> Proxy m -> k2 -> k3 -> Type

Note that the kind of ``a`` is specified in the kind of ``C`` but inferred in
the kind of ``F``.

The "general principle" described here is meant to make all this more
predictable for users. It would not be hard to extend GHC to relax
this principle. If you should want a change here, consider writing
a `proposal <https://github.com/ghc-proposals/ghc-proposals/>`_ to
do so.

.. index::
   single: CUSK
   single: complete user-supplied kind signature

.. _complete-kind-signatures:

Complete user-supplied kind signatures and polymorphic recursion
----------------------------------------------------------------

.. extension:: CUSKs
    :shortdesc: Enable detection of complete user-supplied kind signatures.

    :since: 8.10.1

Just as in type inference, kind inference for recursive types can only
use *monomorphic* recursion. Consider this (contrived) example: ::

    data T m a = MkT (m a) (T Maybe (m a))
    -- GHC infers kind  T :: (Type -> Type) -> Type -> Type

The recursive use of ``T`` forced the second argument to have kind
``Type``. However, just as in type inference, you can achieve polymorphic
recursion by giving a *complete user-supplied kind signature* (or CUSK)
for ``T``. A CUSK is present when all argument kinds and the result kind
are known, without any need for inference. For example: ::

    data T (m :: k -> Type) :: k -> Type where
      MkT :: m a -> T Maybe (m a) -> T m a

The complete user-supplied kind signature specifies the polymorphic kind
for ``T``, and this signature is used for all the calls to ``T``
including the recursive ones. In particular, the recursive use of ``T``
is at kind ``Type``.

What exactly is considered to be a "complete user-supplied kind
signature" for a type constructor? These are the forms:

-  For a datatype, every type variable must be annotated with a kind. In
   a GADT-style declaration, there may also be a kind signature (with a
   top-level ``::`` in the header), but the presence or absence of this
   annotation does not affect whether or not the declaration has a
   complete signature. ::

       data T1 :: (k -> Type) -> k -> Type       where ...
       -- Yes;  T1 :: forall k. (k->Type) -> k -> Type

       data T2 (a :: k -> Type) :: k -> Type     where ...
       -- Yes;  T2 :: forall k. (k->Type) -> k -> Type

       data T3 (a :: k -> Type) (b :: k) :: Type where ...
       -- Yes;  T3 :: forall k. (k->Type) -> k -> Type

       data T4 (a :: k -> Type) (b :: k)      where ...
       -- Yes;  T4 :: forall k. (k->Type) -> k -> Type

       data T5 a (b :: k) :: Type             where ...
       -- No;  kind is inferred

       data T6 a b                         where ...
       -- No;  kind is inferred

-  For a datatype with a top-level ``::``: all kind variables introduced after
   the ``::`` must be explicitly quantified. ::

     data T1 :: k -> Type            -- No CUSK: `k` is not explicitly quantified
     data T2 :: forall k. k -> Type  -- CUSK: `k` is bound explicitly
     data T3 :: forall (k :: Type). k -> Type   -- still a CUSK

-  For a newtype, the rules are the same as they are for a data type
   unless :extension:`UnliftedNewtypes` is enabled.
   With :extension:`UnliftedNewtypes`, the type constructor
   only has a CUSK if a kind signature is present. As with a datatype
   with a top-level ``::``, all kind variables must introduced after
   the ``::`` must be explicitly quantified ::

       {-# LANGUAGE UnliftedNewtypes #-}
       newtype N1 where                 -- No; missing kind signature
       newtype N2 :: TYPE 'IntRep where -- Yes; kind signature present
       newtype N3 (a :: Type) where     -- No; missing kind signature
       newtype N4 :: k -> Type where    -- No; `k` is not explicitly quantified
       newtype N5 :: forall (k :: Type). k -> Type where -- Yes; good signature

-  For a class, every type variable must be annotated with a kind.

-  For a type synonym, every type variable and the result type must all
   be annotated with kinds: ::

       type S1 (a :: k) = (a :: k)    -- Yes   S1 :: forall k. k -> k
       type S2 (a :: k) = a           -- No    kind is inferred
       type S3 (a :: k) = Proxy a     -- No    kind is inferred

   Note that in ``S2`` and ``S3``, the kind of the right-hand side is
   rather apparent, but it is still not considered to have a complete
   signature -- no inference can be done before detecting the signature.

-  An un-associated open type or data family declaration *always* has a CUSK;
   un-annotated type variables default to kind ``Type``: ::

       data family D1 a                  -- D1 :: Type -> Type
       data family D2 (a :: k)           -- D2 :: forall k. k -> Type
       data family D3 (a :: k) :: Type   -- D3 :: forall k. k -> Type
       type family S1 a :: k -> Type     -- S1 :: forall k. Type -> k -> Type

-  An associated type or data family declaration has a CUSK precisely if
   its enclosing class has a CUSK. ::

       class C a where                -- no CUSK
         type AT a b                  -- no CUSK, b is defaulted

       class D (a :: k) where         -- yes CUSK
         type AT2 a b                 -- yes CUSK, b is defaulted

-  A closed type family has a complete signature when all of its type
   variables are annotated and a return kind (with a top-level ``::``)
   is supplied.

It is possible to write a datatype that syntactically has a CUSK (according to
the rules above) but actually requires some inference. As a very contrived
example, consider ::

  data Proxy a           -- Proxy :: forall k. k -> Type
  data X (a :: Proxy k)

According to the rules above ``X`` has a CUSK. Yet, the kind of ``k`` is undetermined.
It is thus quantified over, giving ``X`` the kind ``forall k1 (k :: k1). Proxy k -> Type``.

The detection of CUSKs is enabled by the :extension:`CUSKs` flag, which is
switched on by default. When :extension:`CUSKs` is switched off, there is
currently no way to enable polymorphic recursion in types. In the future, the
notion of a CUSK will be replaced by top-level kind signatures
(`GHC Proposal #36 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0036-kind-signatures.rst>`__),
then, after a transition period, this extension will be turned off by default, and eventually removed.

Kind inference in closed type families
--------------------------------------

Although all open type families are considered to have a complete
user-supplied kind signature, we can relax this condition for closed
type families, where we have equations on which to perform kind
inference. GHC will infer kinds for the arguments and result types of a
closed type family.

GHC supports *kind-indexed* type families, where the family matches both
on the kind and type. GHC will *not* infer this behaviour without a
complete user-supplied kind signature, as doing so would sometimes infer
non-principal types. Indeed, we can see kind-indexing as a form
of polymorphic recursion, where a type is used at a kind other than
its most general in its own definition.

For example: ::

    type family F1 a where
      F1 True  = False
      F1 False = True
      F1 x     = x
    -- F1 fails to compile: kind-indexing is not inferred

    type family F2 (a :: k) where
      F2 True  = False
      F2 False = True
      F2 x     = x
    -- F2 fails to compile: no complete signature

    type family F3 (a :: k) :: k where
      F3 True  = False
      F3 False = True
      F3 x     = x
    -- OK

Kind inference in class instance declarations
---------------------------------------------

Consider the following example of a poly-kinded class and an instance
for it: ::

    class C a where
      type F a

    instance C b where
      type F b = b -> b

In the class declaration, nothing constrains the kind of the type ``a``,
so it becomes a poly-kinded type variable ``(a :: k)``. Yet, in the
instance declaration, the right-hand side of the associated type
instance ``b -> b`` says that ``b`` must be of kind ``Type``. GHC could
theoretically propagate this information back into the instance head,
and make that instance declaration apply only to type of kind ``Type``, as
opposed to types of any kind. However, GHC does *not* do this.

In short: GHC does *not* propagate kind information from the members of
a class instance declaration into the instance declaration head.

This lack of kind inference is simply an engineering problem within GHC,
but getting it to work would make a substantial change to the inference
infrastructure, and it's not clear the payoff is worth it. If you want
to restrict ``b``\ 's kind in the instance above, just use a kind
signature in the instance head.

Kind inference in type signatures
---------------------------------

When kind-checking a type, GHC considers only what is written in that
type when figuring out how to generalise the type's kind.

For example,
consider these definitions (with :extension:`ScopedTypeVariables`): ::

  data Proxy a    -- Proxy :: forall k. k -> Type
  p :: forall a. Proxy a
  p = Proxy :: Proxy (a :: Type)

GHC reports an error, saying that the kind of ``a`` should be a kind variable
``k``, not ``Type``. This is because, by looking at the type signature
``forall a. Proxy a``, GHC assumes ``a``'s kind should be generalised, not
restricted to be ``Type``. The function definition is then rejected for being
more specific than its type signature.

.. _explicit-kind-quantification:

Explicit kind quantification
----------------------------

Enabled by :extension:`PolyKinds`, GHC supports explicit kind quantification,
as in these examples: ::

  data Proxy :: forall k. k -> Type
  f :: (forall k (a :: k). Proxy a -> ()) -> Int

Note that the second example has a ``forall`` that binds both a kind ``k`` and
a type variable ``a`` of kind ``k``. In general, there is no limit to how
deeply nested this sort of dependency can work. However, the dependency must
be well-scoped: ``forall (a :: k) k. ...`` is an error.

Implicit quantification in type synonyms and type family instances
------------------------------------------------------------------

Consider the scoping rules for type synonyms and type family instances, such as
these::

   type          TS a (b :: k) = <rhs>
   type instance TF a (b :: k) = <rhs>

The basic principle is that all variables mentioned on the right hand side
``<rhs>`` must be bound on the left hand side::

  type TS a (b :: k) = (k, a, Proxy b)    -- accepted
  type TS a (b :: k) = (k, a, Proxy b, z) -- rejected: z not in scope

But there is one exception: free variables mentioned in the outermost kind
signature on the right hand side are quantified implicitly. Thus, in the
following example the variables ``a``, ``b``, and ``k`` are all in scope on the
right hand side of ``S``::

  type S a b = <rhs> :: k -> k

The reason for this exception is that there may be no other way to bind ``k``.
For example, suppose we wanted ``S`` to have the the following kind with an
*invisible* parameter ``k``::

  S :: forall k. Type -> Type -> k -> k

In this case, we could not simply bind ``k`` on the left-hand side, as ``k``
would become a *visible* parameter::

  type S k a b = <rhs> :: k -> k
  S :: forall k -> Type -> Type -> k -> k

Note that we only look at the *outermost* kind signature to decide which
variables to quantify implicitly. As a counter-example, consider ``M1``: ::

  type M1 = 'Just ('Nothing :: Maybe k)    -- rejected: k not in scope

Here, the kind signature is hidden inside ``'Just``, and there is no outermost
kind signature. We can fix this example by providing an outermost kind signature: ::

  type M2 = 'Just ('Nothing :: Maybe k) :: Maybe (Maybe k)

Here, ``k`` is brought into scope by ``:: Maybe (Maybe k)``.

A kind signature is considered to be outermost regardless of redundant
parentheses: ::

  type P =    'Nothing :: Maybe a    -- accepted
  type P = ((('Nothing :: Maybe a))) -- accepted

Closed type family instances are subject to the same rules: ::

  type family F where
    F = 'Nothing :: Maybe k            -- accepted

  type family F where
    F = 'Just ('Nothing :: Maybe k)    -- rejected: k not in scope

  type family F where
    F = 'Just ('Nothing :: Maybe k) :: Maybe (Maybe k)  -- accepted

  type family F :: Maybe (Maybe k) where
    F = 'Just ('Nothing :: Maybe k)    -- rejected: k not in scope

  type family F :: Maybe (Maybe k) where
    F @k = 'Just ('Nothing :: Maybe k) -- accepted

Kind variables can also be quantified in *visible* positions. Consider the
following two examples: ::

  data ProxyKInvis (a :: k)
  data ProxyKVis k (a :: k)

In the first example, the kind variable ``k`` is an *invisible* argument to
``ProxyKInvis``. In other words, a user does not need to instantiate ``k``
explicitly, as kind inference automatically determines what ``k`` should be.
For instance, in ``ProxyKInvis True``, ``k`` is inferred to be ``Bool``.
This is reflected in the kind of ``ProxyKInvis``: ::

  ProxyKInvis :: forall k. k -> Type

In the second example, ``k`` is a *visible* argument to ``ProxyKVis``. That is
to say, ``k`` is an argument that users must provide explicitly when applying
``ProxyKVis``. For example, ``ProxyKVis Bool True`` is a well formed type.

What is the kind of ``ProxyKVis``? One might say
``forall k. Type -> k -> Type``, but this isn't quite right, since this would
allow incorrect things like ``ProxyKVis Bool Int``, which should be rejected
due to the fact that ``Int`` is not of kind ``Bool``. The key observation is that
the kind of the second argument *depend* on the first argument. GHC indicates
this dependency in the syntax that it gives for the kind of ``ProxyKVis``: ::

  ProxyKVis :: forall k -> k -> Type

This kind is similar to the kind of ``ProxyKInvis``, but with a key difference:
the type variables quantified by the ``forall`` are followed by an arrow
(``->``), not a dot (``.``). This is a visible, dependent quantifier. It is
visible in that it the user must pass in a type for ``k`` explicitly, and it is
dependent in the sense that ``k`` appears later in the kind of ``ProxyKVis``.
As a counterpart, the ``k`` binder in ``forall k. k -> Type`` can be thought
of as an *invisible*, dependent quantifier.

GHC permits writing kinds with this syntax, provided that the
``ExplicitForAll`` and ``PolyKinds`` language extensions are enabled. Just
like the invisible ``forall``, one can put explicit kind signatures on visibly
bound kind variables, so the following is syntactically valid: ::

  ProxyKVis :: forall (k :: Type) -> k -> Type

Currently, the ability to write visible, dependent quantifiers is limited to
kinds. Consequently, visible dependent quantifiers are rejected in any context
that is unambiguously the type of a term. They are also rejected in the types
of data constructors.

Kind-indexed GADTs
------------------

Consider the type ::

  data G (a :: k) where
    GInt    :: G Int
    GMaybe  :: G Maybe

This datatype ``G`` is GADT-like in both its kind and its type. Suppose you
have ``g :: G a``, where ``a :: k``. Then pattern matching to discover that
``g`` is in fact ``GMaybe`` tells you both that ``k ~ (Type -> Type)`` and
``a ~ Maybe``. The definition for ``G`` requires that :extension:`PolyKinds`
be in effect, but pattern-matching on ``G`` requires no extension beyond
:extension:`GADTs`. That this works is actually a straightforward extension
of regular GADTs and a consequence of the fact that kinds and types are the
same.

Note that the datatype ``G`` is used at different kinds in its body, and
therefore that kind-indexed GADTs use a form of polymorphic recursion.
It is thus only possible to use this feature if you have provided a
complete user-supplied kind signature
for the datatype (:ref:`complete-kind-signatures`).

Higher-rank kinds
-----------------

In concert with :extension:`RankNTypes`, GHC supports higher-rank kinds.
Here is an example::

  -- Heterogeneous propositional equality
  data (a :: k1) :~~: (b :: k2) where
    HRefl :: a :~~: a

  class HTestEquality (t :: forall k. k -> Type) where
    hTestEquality :: forall k1 k2 (a :: k1) (b :: k2). t a -> t b -> Maybe (a :~~: b)

Note that ``hTestEquality`` takes two arguments where the type variable ``t`` is applied
to types of different kinds. That type variable must then be polykinded. Accordingly,
the kind of ``HTestEquality`` (the class) is ``(forall k. k -> Type) -> Constraint``,
a higher-rank kind.

A big difference with higher-rank kinds as compared with higher-rank types is that
``forall``\s in kinds *cannot* be moved. This is best illustrated by example.
Suppose we want to have an instance of ``HTestEquality`` for ``(:~~:)``. ::

  instance HTestEquality ((:~~:) a) where
    hTestEquality HRefl HRefl = Just HRefl

With the declaration of ``(:~~:)`` above, it gets kind ``forall k1 k2. k1 -> k2 -> Type``.
Thus, the type ``(:~~:) a`` has kind ``k2 -> Type`` for some ``k2``. GHC cannot
then *regeneralize* this kind to become ``forall k2. k2 -> Type`` as desired. Thus, the
instance is rejected as ill-kinded.

To allow for such an instance, we would have to define ``(:~~:)`` as follows::

  data (:~~:) :: forall k1. k1 -> forall k2. k2 -> Type where
    HRefl :: a :~~: a

In this redefinition, we give an explicit kind for ``(:~~:)``, deferring the choice
of ``k2`` until after the first argument (``a``) has been given. With this declaration
for ``(:~~:)``, the instance for ``HTestEquality`` is accepted.

Another difference between higher-rank kinds and types can be found in their
treatment of inferred and user-specified type variables. Consider the following
program: ::

  newtype Foo (f :: forall k. k -> Type) = MkFoo (f Int)
  data Proxy a = Proxy

  foo :: Foo Proxy
  foo = MkFoo Proxy

The kind of ``Foo``'s parameter is ``forall k. k -> Type``, but the kind of
``Proxy`` is ``forall {k}. k -> Type``, where ``{k}`` denotes that the kind
variable ``k`` is to be inferred, not specified by the user. (See
:ref:`visible-type-application` for more discussion on the inferred-specified
distinction). GHC does not consider ``forall k. k -> Type`` and
``forall {k}. k -> Type`` to be equal at the kind level, and thus rejects
``Foo Proxy`` as ill-kinded.

Constraints in kinds
--------------------

As kinds and types are the same, kinds can (with :extension:`TypeInType`)
contain type constraints. However, only equality constraints are supported.

Here is an example of a constrained kind: ::

  type family IsTypeLit a where
    IsTypeLit Nat    = 'True
    IsTypeLit Symbol = 'True
    IsTypeLit a      = 'False

  data T :: forall a. (IsTypeLit a ~ 'True) => a -> Type where
    MkNat    :: T 42
    MkSymbol :: T "Don't panic!"

The declarations above are accepted. However, if we add ``MkOther :: T Int``,
we get an error that the equality constraint is not satisfied; ``Int`` is
not a type literal. Note that explicitly quantifying with ``forall a`` is
necessary in order for ``T`` to typecheck
(see :ref:`complete-kind-signatures`).

The kind ``Type``
-----------------

.. extension:: StarIsType
    :shortdesc: Treat ``*`` as ``Data.Kind.Type``.

    :since: 8.6.1

    Treat the unqualified uses of the ``*`` type operator as nullary and desugar
    to ``Data.Kind.Type``.

The kind ``Type`` (imported from ``Data.Kind``) classifies ordinary types. With
:extension:`StarIsType` (currently enabled by default), ``*`` is desugared to
``Type``, but using this legacy syntax is not recommended due to conflicts with
:extension:`TypeOperators`. This also applies to ``★``, the Unicode variant of
``*``.

Inferring dependency in datatype declarations
---------------------------------------------

If a type variable ``a`` in a datatype, class, or type family declaration
depends on another such variable ``k`` in the same declaration, two properties
must hold:

-  ``a`` must appear after ``k`` in the declaration, and

-  ``k`` must appear explicitly in the kind of *some* type variable in that
   declaration.

The first bullet simply means that the dependency must be well-scoped. The
second bullet concerns GHC's ability to infer dependency. Inferring this
dependency is difficult, and GHC currently requires the dependency to be
made explicit, meaning that ``k`` must appear in the kind of a type variable,
making it obvious to GHC that dependency is intended. For example: ::

  data Proxy k (a :: k)            -- OK: dependency is "obvious"
  data Proxy2 k a = P (Proxy k a)  -- ERROR: dependency is unclear

In the second declaration, GHC cannot immediately tell that ``k`` should
be a dependent variable, and so the declaration is rejected.

It is conceivable that this restriction will be relaxed in the future,
but it is (at the time of writing) unclear if the difficulties around this
scenario are theoretical (inferring this dependency would mean our type
system does not have principal types) or merely practical (inferring this
dependency is hard, given GHC's implementation). So, GHC takes the easy
way out and requires a little help from the user.

Inferring dependency in user-written ``forall``\s
-------------------------------------------------

A programmer may use ``forall`` in a type to introduce new quantified type
variables. These variables may depend on each other, even in the same
``forall``. However, GHC requires that the dependency be inferrable from
the body of the ``forall``. Here are some examples::

  data Proxy k (a :: k) = MkProxy   -- just to use below

  f :: forall k a. Proxy k a        -- This is just fine. We see that (a :: k).
  f = undefined

  g :: Proxy k a -> ()              -- This is to use below.
  g = undefined

  data Sing a
  h :: forall k a. Sing k -> Sing a -> ()  -- No obvious relationship between k and a
  h _ _ = g (MkProxy :: Proxy k a)  -- This fails. We didn't know that a should have kind k.

Note that in the last example, it's impossible to learn that ``a`` depends on ``k`` in the
body of the ``forall`` (that is, the ``Sing k -> Sing a -> ()``). And so GHC rejects
the program.

Kind defaulting without :extension:`PolyKinds`
-----------------------------------------------

Without :extension:`PolyKinds`, GHC refuses to generalise over kind variables.
It thus defaults kind variables to ``Type`` when possible; when this is not
possible, an error is issued.

Here is an example of this in action: ::

  {-# LANGUAGE PolyKinds #-}
  import Data.Kind (Type)
  data Proxy a = P   -- inferred kind: Proxy :: k -> Type
  data Compose f g x = MkCompose (f (g x))
    -- inferred kind: Compose :: (b -> Type) -> (a -> b) -> a -> Type

  -- separate module having imported the first
  {-# LANGUAGE NoPolyKinds, DataKinds #-}
  z = Proxy :: Proxy 'MkCompose

In the last line, we use the promoted constructor ``'MkCompose``, which has
kind ::

  forall (a :: Type) (b :: Type) (f :: b -> Type) (g :: a -> b) (x :: a).
    f (g x) -> Compose f g x

Now we must infer a type for ``z``. To do so without generalising over kind
variables, we must default the kind variables of ``'MkCompose``. We can easily
default ``a`` and ``b`` to ``Type``, but ``f`` and ``g`` would be ill-kinded if
defaulted. The definition for ``z`` is thus an error.

Pretty-printing in the presence of kind polymorphism
----------------------------------------------------

With kind polymorphism, there is quite a bit going on behind the scenes that
may be invisible to a Haskell programmer. GHC supports several flags that
control how types are printed in error messages and at the GHCi prompt.
See the :ref:`discussion of type pretty-printing options <pretty-printing-types>`
for further details. If you are using kind polymorphism and are confused as to
why GHC is rejecting (or accepting) your program, we encourage you to turn on
these flags, especially :ghc-flag:`-fprint-explicit-kinds`.

.. index::
   single: TYPE
   single: levity polymorphism

.. _runtime-rep:

Levity polymorphism
===================

In order to allow full flexibility in how kinds are used, it is necessary
to use the kind system to differentiate between boxed, lifted types
(normal, everyday types like ``Int`` and ``[Bool]``) and unboxed, primitive
types (:ref:`primitives`) like ``Int#``. We thus have so-called levity
polymorphism.

Here are the key definitions, all available from ``GHC.Exts``: ::

  TYPE :: RuntimeRep -> Type   -- highly magical, built into GHC

  data RuntimeRep = LiftedRep     -- for things like `Int`
                  | UnliftedRep   -- for things like `Array#`
                  | IntRep        -- for `Int#`
                  | TupleRep [RuntimeRep]  -- unboxed tuples, indexed by the representations of the elements
                  | SumRep [RuntimeRep]    -- unboxed sums, indexed by the representations of the disjuncts
                  | ...

  type Type = TYPE LiftedRep    -- Type is just an ordinary type synonym

The idea is that we have a new fundamental type constant ``TYPE``, which
is parameterised by a ``RuntimeRep``. We thus get ``Int# :: TYPE 'IntRep``
and ``Bool :: TYPE 'LiftedRep``. Anything with a type of the form
``TYPE x`` can appear to either side of a function arrow ``->``. We can
thus say that ``->`` has type
``TYPE r1 -> TYPE r2 -> TYPE 'LiftedRep``. The result is always lifted
because all functions are lifted in GHC.

.. _levity-polymorphic-restrictions:

No levity-polymorphic variables or arguments
--------------------------------------------

If GHC didn't have to compile programs that run in the real world, that
would be the end of the story. But representation polymorphism can cause
quite a bit of trouble for GHC's code generator. Consider ::

  bad :: forall (r1 :: RuntimeRep) (r2 :: RuntimeRep)
                (a :: TYPE r1) (b :: TYPE r2).
         (a -> b) -> a -> b
  bad f x = f x

This seems like a generalisation of the standard ``$`` operator. If we
think about compiling this to runnable code, though, problems appear.
In particular, when we call ``bad``, we must somehow pass ``x`` into
``bad``. How wide (that is, how many bits) is ``x``? Is it a pointer?
What kind of register (floating-point or integral) should ``x`` go in?
It's all impossible to say, because ``x``'s type, ``a :: TYPE r1`` is
levity polymorphic. We thus forbid such constructions, via the
following straightforward rule:

    No variable may have a levity-polymorphic type.

This eliminates ``bad`` because the variable ``x`` would have a
representation-polymorphic type.

However, not all is lost. We can still do this: ::

  ($) :: forall r (a :: Type) (b :: TYPE r).
         (a -> b) -> a -> b
  f $ x = f x

Here, only ``b`` is levity polymorphic. There are no variables
with a levity-polymorphic type. And the code generator has no
trouble with this. Indeed, this is the true type of GHC's ``$`` operator,
slightly more general than the Haskell 98 version.

Because the code generator must store and move arguments as well
as variables, the logic above applies equally well to function arguments,
which may not be levity-polymorphic.


Levity-polymorphic bottoms
--------------------------

We can use levity polymorphism to good effect with ``error``
and ``undefined``, whose types are given here: ::

  undefined :: forall (r :: RuntimeRep) (a :: TYPE r).
               HasCallStack => a
  error :: forall (r :: RuntimeRep) (a :: TYPE r).
           HasCallStack => String -> a

These functions do not bind a levity-polymorphic variable, and
so are accepted. Their polymorphism allows users to use these to conveniently
stub out functions that return unboxed types.

Printing levity-polymorphic types
---------------------------------

.. ghc-flag:: -fprint-explicit-runtime-reps
    :shortdesc: Print ``RuntimeRep`` variables in types which are
        runtime-representation polymorphic.
    :type: dynamic
    :reverse: -fno-print-explicit-runtime-reps
    :category: verbosity

    Print ``RuntimeRep`` parameters as they appear; otherwise, they are
    defaulted to ``'LiftedRep``.

Most GHC users will not need to worry about levity polymorphism
or unboxed types. For these users, seeing the levity polymorphism
in the type of ``$`` is unhelpful. And thus, by default, it is suppressed,
by supposing all type variables of type ``RuntimeRep`` to be ``'LiftedRep``
when printing, and printing ``TYPE 'LiftedRep`` as ``Type`` (or ``*`` when
:extension:`StarIsType` is on).

Should you wish to see levity polymorphism in your types, enable
the flag :ghc-flag:`-fprint-explicit-runtime-reps`. For example,

    .. code-block:: none

        ghci> :t ($)
        ($) :: (a -> b) -> a -> b
        ghci> :set -fprint-explicit-runtime-reps
        ghci> :t ($)
        ($)
          :: forall (r :: GHC.Types.RuntimeRep) a (b :: TYPE r).
             (a -> b) -> a -> b

.. _type-level-literals:

Type-Level Literals
===================

GHC supports numeric and string literals at the type level, giving
convenient access to a large number of predefined type-level constants.
Numeric literals are of kind ``Nat``, while string literals are of kind
``Symbol``. This feature is enabled by the :extension:`DataKinds` language
extension.

The kinds of the literals and all other low-level operations for this
feature are defined in module ``GHC.TypeLits``. Note that the module
defines some type-level operators that clash with their value-level
counterparts (e.g. ``(+)``). Import and export declarations referring to
these operators require an explicit namespace annotation (see
:ref:`explicit-namespaces`).

Here is an example of using type-level numeric literals to provide a
safe interface to a low-level function: ::

    import GHC.TypeLits
    import Data.Word
    import Foreign

    newtype ArrPtr (n :: Nat) a = ArrPtr (Ptr a)

    clearPage :: ArrPtr 4096 Word8 -> IO ()
    clearPage (ArrPtr p) = ...

Here is an example of using type-level string literals to simulate
simple record operations: ::

    data Label (l :: Symbol) = Get

    class Has a l b | a l -> b where
      from :: a -> Label l -> b

    data Point = Point Int Int deriving Show

    instance Has Point "x" Int where from (Point x _) _ = x
    instance Has Point "y" Int where from (Point _ y) _ = y

    example = from (Point 1 2) (Get :: Label "x")


.. _typelit-runtime:

Runtime Values for Type-Level Literals
--------------------------------------

Sometimes it is useful to access the value-level literal associated with
a type-level literal. This is done with the functions ``natVal`` and
``symbolVal``. For example: ::

    GHC.TypeLits> natVal (Proxy :: Proxy 2)
    2

These functions are overloaded because they need to return a different
result, depending on the type at which they are instantiated. ::

    natVal :: KnownNat n => proxy n -> Integer

    -- instance KnownNat 0
    -- instance KnownNat 1
    -- instance KnownNat 2
    -- ...

GHC discharges the constraint as soon as it knows what concrete
type-level literal is being used in the program. Note that this works
only for *literals* and not arbitrary type expressions. For example, a
constraint of the form ``KnownNat (a + b)`` will *not* be simplified to
``(KnownNat a, KnownNat b)``; instead, GHC will keep the constraint as
is, until it can simplify ``a + b`` to a constant value.

It is also possible to convert a run-time integer or string value to the
corresponding type-level literal. Of course, the resulting type literal
will be unknown at compile-time, so it is hidden in an existential type.
The conversion may be performed using ``someNatVal`` for integers and
``someSymbolVal`` for strings: ::

    someNatVal :: Integer -> Maybe SomeNat
    SomeNat    :: KnownNat n => Proxy n -> SomeNat

The operations on strings are similar.

.. _typelit-tyfuns:

Computing With Type-Level Naturals
----------------------------------

GHC 7.8 can evaluate arithmetic expressions involving type-level natural
numbers. Such expressions may be constructed using the type-families
``(+), (*), (^)`` for addition, multiplication, and exponentiation.
Numbers may be compared using ``(<=?)``, which returns a promoted
boolean value, or ``(<=)``, which compares numbers as a constraint. For
example:

.. code-block:: none

    GHC.TypeLits> natVal (Proxy :: Proxy (2 + 3))
    5

At present, GHC is quite limited in its reasoning about arithmetic: it
will only evaluate the arithmetic type functions and compare the
results--- in the same way that it does for any other type function. In
particular, it does not know more general facts about arithmetic, such
as the commutativity and associativity of ``(+)``, for example.

However, it is possible to perform a bit of "backwards" evaluation. For
example, here is how we could get GHC to compute arbitrary logarithms at
the type level:

.. code-block:: none

    lg :: Proxy base -> Proxy (base ^ pow) -> Proxy pow
    lg _ _ = Proxy

    GHC.TypeLits> natVal (lg (Proxy :: Proxy 2) (Proxy :: Proxy 8))
    3

Equality constraints, Coercible, and the kind Constraint
========================================================

.. _equality-constraints:

Equality constraints
--------------------

A type context can include equality constraints of the form ``t1 ~ t2``,
which denote that the types ``t1`` and ``t2`` need to be the same. In
the presence of type families, whether two types are equal cannot
generally be decided locally. Hence, the contexts of function signatures
may include equality constraints, as in the following example: ::

    sumCollects :: (Collects c1, Collects c2, Elem c1 ~ Elem c2) => c1 -> c2 -> c2

where we require that the element type of ``c1`` and ``c2`` are the
same. In general, the types ``t1`` and ``t2`` of an equality constraint
may be arbitrary monotypes; i.e., they may not contain any quantifiers,
independent of whether higher-rank types are otherwise enabled.

Equality constraints can also appear in class and instance contexts. The
former enable a simple translation of programs using functional
dependencies into programs using family synonyms instead. The general
idea is to rewrite a class declaration of the form ::

    class C a b | a -> b

to ::

    class (F a ~ b) => C a b where
      type F a

That is, we represent every functional dependency (FD) ``a1 .. an -> b``
by an FD type family ``F a1 .. an`` and a superclass context equality
``F a1 .. an ~ b``, essentially giving a name to the functional
dependency. In class instances, we define the type instances of FD
families in accordance with the class head. Method signatures are not
affected by that process.

.. index::
   pair: Type equality constraints; kind heterogeneous

Heterogeneous equality
----------------------

GHC also supports *kind-heterogeneous* equality, which relates two types of
potentially different kinds. Heterogeneous equality is spelled ``~~``. Here
are the kinds of ``~`` and ``~~`` to better understand their difference: ::

  (~)  :: forall k. k -> k -> Constraint
  (~~) :: forall k1 k2. k1 -> k2 -> Constraint

Users will most likely want ``~``, but ``~~`` is available if GHC cannot know,
a priori, that the two types of interest have the same kind. Evidence that
``(a :: k1) ~~ (b :: k2)`` tells GHC both that ``k1`` and ``k2`` are the same
and that ``a`` and ``b`` are the same.

Because ``~`` is the more common equality relation, GHC prints out ``~~`` like
``~`` unless :ghc-flag:`-fprint-equality-relations` is set.

Unlifted heterogeneous equality
-------------------------------

Internal to GHC is yet a third equality relation ``(~#)``. It is heterogeneous
(like ``~~``) and is used only internally. It may appear in error messages
and other output only when :ghc-flag:`-fprint-equality-relations` is enabled.

.. _coercible:

The ``Coercible`` constraint
----------------------------

The constraint ``Coercible t1 t2`` is similar to ``t1 ~ t2``, but
denotes representational equality between ``t1`` and ``t2`` in the sense
of Roles (:ref:`roles`). It is exported by :base-ref:`Data.Coerce.`, which also
contains the documentation. More details and discussion can be found in the
paper
`"Safe Coercions" <https://www.microsoft.com/en-us/research/uploads/prod/2018/05/coercible-JFP.pdf>`__.

.. _constraint-kind:

The ``Constraint`` kind
-----------------------

.. extension:: ConstraintKinds
    :shortdesc: Enable a kind of constraints.

    :since: 7.4.1

    Allow types of kind ``Constraint`` to be used in contexts.

Normally, *constraints* (which appear in types to the left of the ``=>``
arrow) have a very restricted syntax. They can only be:

-  Class constraints, e.g. ``Show a``

-  :ghc-flag:`Implicit parameter <-XImplicitParams>` constraints, e.g.
   ``?x::Int`` (with the :extension:`ImplicitParams` extension)

-  :ref:`Equality constraints <equality-constraints>`, e.g. ``a ~ Int``
   (with the :extension:`TypeFamilies` or :extension:`GADTs` extensions)

With the :extension:`ConstraintKinds` extension, GHC becomes more liberal in what it
accepts as constraints in your program. To be precise, with this flag
any *type* of the new kind ``Constraint`` can be used as a constraint.
The following things have kind ``Constraint``:

-  Anything which is already valid as a constraint without the flag:
   saturated applications to type classes, implicit parameter and
   equality constraints.

- Tuples, all of whose component types have kind ``Constraint``. So for example
  the type ``(Show a, Ord a)`` is of kind ``Constraint``.

-  Anything whose form is not yet known, but the user has declared to
   have kind ``Constraint`` (for which they need to import it from
   ``Data.Kind``). So for example
   ``type Foo (f :: Type -> Constraint) = forall b. f b => b -> b``
   is allowed, as well as examples involving type families: ::

       type family Typ a b :: Constraint
       type instance Typ Int  b = Show b
       type instance Typ Bool b = Num b

       func :: Typ a b => a -> b -> b
       func = ...

Note that because constraints are just handled as types of a particular
kind, this extension allows type constraint synonyms: ::

    type Stringy a = (Read a, Show a)
    foo :: Stringy a => a -> (String, String -> a)
    foo x = (show x, read)

Presently, only standard constraints, tuples and type synonyms for those
two sorts of constraint are permitted in instance contexts and
superclasses (without extra flags). The reason is that permitting more
general constraints can cause type checking to loop, as it would with
these two programs:

::

    type family Clsish u a
    type instance Clsish () a = Cls a
    class Clsish () a => Cls a where

::

    class OkCls a where

    type family OkClsish u a
    type instance OkClsish () a = OkCls a
    instance OkClsish () a => OkCls a where

You may write programs that use exotic sorts of constraints in instance
contexts and superclasses, but to do so you must use
:extension:`UndecidableInstances` to signal that you don't mind if the type
checker fails to terminate.

.. _quantified-constraints:

Quantified constraints
======================

.. extension:: QuantifiedConstraints
    :shortdesc: Allow ``forall`` quantifiers in constraints.

    :since: 8.6.1

    Allow constraints to quantify over types.

The extension :extension:`QuantifiedConstraints` introduces **quantified constraints**,
which give a new level of expressiveness in constraints. For example, consider ::

 data Rose f a = Branch a (f (Rose f a))

 instance (Eq a, ???) => Eq (Rose f a)
   where
     (Branch x1 c1) == (Branch x2 c2)
        = x1==x1 && c1==c2

From the ``x1==x2`` we need ``Eq a``, which is fine.  From ``c1==c2`` we need ``Eq (f (Rose f a))`` which
is *not* fine in Haskell today; we have no way to solve such a constraint.

:extension:`QuantifiedConstraints` lets us write this ::

 instance (Eq a, forall b. (Eq b) => Eq (f b))
        => Eq (Rose f a)
   where
     (Branch x1 c1) == (Branch x2 c2)
        = x1==x1 && c1==c2

Here, the quantified constraint ``forall b. (Eq b) => Eq (f b)`` behaves
a bit like a local instance declaration, and makes the instance typeable.

The paper `Quantified class constraints <http://i.cs.hku.hk/~bruno//papers/hs2017.pdf>`_ (by Bottu, Karachalias, Schrijvers, Oliveira, Wadler, Haskell Symposium 2017) describes this feature in technical detail, with examples, and so is a primary reference source for this proposal.

Motivation
----------------
Introducing quantified constraints offers two main benefits:

- Firstly, they enable terminating resolution where this was not possible before.  Consider for instance the following instance declaration for the general rose datatype ::

   data Rose f x = Rose x (f (Rose f x))

   instance (Eq a, forall b. Eq b => Eq (f b)) => Eq (Rose f a) where
     (Rose x1 rs1) == (Rose x2 rs2) = x1 == x2 && rs1 == rs2

  This extension allows us to write constraints of the form ``forall b. Eq b =>
  Eq (f b)``, which is needed to solve the ``Eq (f (Rose f x))`` constraint
  arising from the second usage of the ``(==)`` method.

- Secondly, quantified constraints allow for more concise and precise specifications. As an example, consider the MTL type class for monad transformers::

   class Trans t where
     lift :: Monad m => m a -> (t m) a

  The developer knows that a monad transformer takes a monad ``m`` into a new monad ``t m``.
  But this property is not formally specified in the above declaration.
  This omission becomes an issue when defining monad transformer composition::

    newtype (t1 * t2) m a = C { runC :: t1 (t2 m) a }

    instance (Trans t1, Trans t2) => Trans (t1 * t2) where
      lift = C . lift . lift

  The goal here is to ``lift`` from monad ``m`` to ``t2 m`` and
  then ``lift`` this again into ``t1 (t2 m)``.
  However, this second ``lift`` can only be accepted when ``(t2 m)`` is a monad
  and there is no way of establishing that this fact universally holds.

  Quantified constraints enable this property to be made explicit in the ``Trans``
  class declaration::

    class (forall m. Monad m => Monad (t m)) => Trans t where
      lift :: Monad m => m a -> (t m) a

This idea is very old; see Seciton 7 of `Derivable type classes <https://www.microsoft.com/en-us/research/publication/derivable-type-classes/>`_.

Syntax changes
----------------

`Haskell 2010 <https://www.haskell.org/onlinereport/haskell2010/haskellch10.html#x17-18000010.5>`_ defines a ``context`` (the bit to the left of ``=>`` in a type) like this

.. code-block:: none

    context ::= class
            |   ( class1, ..., classn )

    class ::= qtycls tyvar
            |  qtycls (tyvar atype1 ... atypen)

We to extend ``class`` (warning: this is a rather confusingly named non-terminal symbol) with two extra forms, namely precisely what can appear in an instance declaration

.. code-block:: none

    class ::= ...
          | [context =>] qtycls inst
          | [context =>] tyvar inst

The definition of ``inst`` is unchanged from the Haskell Report (roughly, just a type).
The ``context =>`` part is optional.  That is the only syntactic change to the language.

Notes:

- Where GHC allows extensions instance declarations we allow exactly the same extensions to this new form of ``class``.  Specifically, with :extension:`ExplicitForAll` and :extension:`MultiParameterTypeClasses` the syntax becomes

  .. code-block:: none

    class ::= ...
           | [forall tyavrs .] [context =>] qtycls inst1 ... instn
           | [forall tyavrs .] [context =>] tyvar inst1 ... instn

  Note that an explicit ``forall`` is often absolutely essential. Consider the rose-tree example ::

    instance (Eq a, forall b. Eq b => Eq (f b)) => Eq (Rose f a) where ...

  Without the ``forall b``, the type variable ``b`` would be quantified over the whole instance declaration, which is not what is intended.

- One of these new quantified constraints can appear anywhere that any other constraint can, not just in instance declarations.  Notably, it can appear in a type signature for a value binding, data constructor, or expression.  For example ::

   f :: (Eq a, forall b. Eq b => Eq (f b)) => Rose f a -> Rose f a -> Bool
   f t1 t2 = not (t1 == t2)

- The form with a type variable at the head allows this::

   instance (forall xx. c (Free c xx)) => Monad (Free c) where
       Free f >>= g = f g

  See `Iceland Jack's summary <https://gitlab.haskell.org/ghc/ghc/issues/14733#note_148352>`_.  The key point is that the bit to the right of the ``=>`` may be headed by a type *variable* (``c`` in this case), rather than a class.  It should not be one of the forall'd variables, though.

  (NB: this goes beyond what is described in `the paper <http://i.cs.hku.hk/~bruno//papers/hs2017.pdf>`_, but does not seem to introduce any new technical difficulties.)


Typing changes
----------------

See `the paper <http://i.cs.hku.hk/~bruno//papers/hs2017.pdf>`_.

Superclasses
----------------

Suppose we have::

     f :: forall m. (forall a. Ord a => Ord (m a)) => m Int -> Bool
     f x = x == x

From the ``x==x`` we need an ``Eq (m Int)`` constraint, but the context only gives us a way to figure out ``Ord (m a)`` constraints.  But from the given constraint ``forall a. Ord a => Ord (m a)`` we derive a second given constraint ``forall a. Ord a => Eq (m a)``, and from that we can readily solve ``Eq (m Int)``.  This process is very similar to the way that superclasses already work: given an ``Ord a`` constraint we derive a second given ``Eq a`` constraint.

NB: This treatment of superclasses goes beyond `the paper <http://i.cs.hku.hk/~bruno//papers/hs2017.pdf>`_, but is specifically desired by users.

Overlap
-------------

Quantified constraints can potentially lead to overlapping local axioms.
Consider for instance the following example::

 class A a where {}
 class B a where {}
 class C a where {}
 class (A a => C a) => D a where {}
 class (B a => C a) => E a where {}

 class C a => F a where {}
 instance (B a, D a, E a) => F a where {}

When type checking the instance declaration for ``F a``,
we need to check that the superclass ``C`` of ``F`` holds.
We thus try to entail the constraint ``C a`` under the theory containing:

- The instance axioms : ``(B a, D a, E a) => F a``
- The local axioms from the instance context : ``B a``, ``D a`` and ``E a``
- The closure of the superclass relation over these local axioms : ``A a => C a`` and ``B a => C a``

However, the ``A a => C a`` and ``B a => C a`` axioms both match the wanted constraint ``C a``.
There are several possible approaches for handling these overlapping local axioms:

- **Pick first**.  We can simply select the **first matching axiom** we encounter.
  In the above example, this would be ``A a => C a``.
  We'd then need to entail ``A a``, for which we have no matching axioms available, causing the above program to be rejected.

  But suppose we made a slight adjustment to the order of the instance context, putting ``E a`` before ``D a``::

   instance (B a, E a, D a) => F a where {}

  The first matching axiom we encounter while entailing ``C a``, is ``B a => C a``.
  We have a local axiom ``B a`` available, so now the program is suddenly accepted.
  This behaviour, where the ordering of an instance context determines
  whether or not the program is accepted, seems rather confusing for the developer.

- **Reject if in doubt**.  An alternative approach would be to check for overlapping axioms,
  when solving a constraint.
  When multiple matching axioms are discovered, we **reject the program**.
  This approach is a bit conservative, in that it may reject working programs.
  But it seem much more transparent towards the developer, who
  can be presented with a clear message, explaining why the program is rejected.

- **Backtracking**.  Lastly, a simple form of **backtracking** could be introduced.
  We simply select the first matching axiom we encounter and when the entailment fails,
  we backtrack and look for other axioms that might match the wanted constraint.

  This seems the most intuitive and transparent approach towards the developer,
  who no longer needs to concern himself with the fact that his code might contain
  overlapping axioms or with the ordering of his instance contexts.  But backtracking
  would apply equally to ordinary instance selection (in the presence of overlapping
  instances), so it is a much more pervasive change, with substantial consequences
  for the type inference engine.

GHC adopts **Reject if in doubt** for now.  We can see how painful it
is in practice, and try something more ambitious if necessary.

Instance lookup
-------------------

In the light of the overlap decision, instance lookup works like this when
trying to solve a class constraint ``C t``

1. First see if there is a given un-quantified constraint ``C t``.  If so, use it to solve the constraint.

2. If not, look at all the available given quantified constraints; if exactly one one matches ``C t``, choose it; if more than one matches, report an error.

3. If no quantified constraints match, look up in the global instances, as described in :ref:`instance-resolution` and :ref:`instance-overlap`.

Termination
---------------

GHC uses the :ref:`Paterson Conditions <instance-termination>` to ensure
that instance resolution terminates. How are those rules modified for quantified
constraints? In two ways.

- Each quantified constraint, taken by itself, must satisfy the termination rules for an instance declaration.

- After "for each class constraint ``(C t1 ... tn)``", add "or each quantified constraint ``(forall as. context => C t1 .. tn)``"

Note that the second item only at the *head* of the quantified constraint, not its context.  Reason: the head is the new goal that has to be solved if we use the instance declaration.

Of course, ``UndecidableInstances`` lifts the Paterson Conditions, as now.

Coherence
-----------

Although quantified constraints are a little like local instance declarations, they differ
in one big way: the local instances are written by the compiler, not the user, and hence
cannot introduce incoherence.  Consider ::

  f :: (forall a. Eq a => Eq (f a)) => f b -> f Bool
  f x = ...rhs...

In ``...rhs...`` there is, in effect a local instance for ``Eq (f a)`` for any ``a``.  But
at a call site for ``f`` the compiler itself produces evidence to pass to ``f``. For example,
if we called ``f Nothing``, then ``f`` is ``Maybe`` and the compiler must prove (at the
call site) that ``forall a. Eq a => Eq (Maybe a)`` holds.  It can do this easily, by
appealing to the existing instance declaration for ``Eq (Maybe a)``.

In short, quantifed constraints do not introduce incoherence.


.. _extensions-to-type-signatures:

Extensions to type signatures
=============================

.. _explicit-foralls:

Explicit universal quantification (forall)
------------------------------------------

.. extension:: ExplicitForAll
    :shortdesc: Enable explicit universal quantification.
        Implied by :extension:`ScopedTypeVariables`, :extension:`LiberalTypeSynonyms`,
        :extension:`RankNTypes` and :extension:`ExistentialQuantification`.

    :since: 6.12.1

    Allow use of the ``forall`` keyword in places where universal quantification
    is implicit.

Haskell type signatures are implicitly quantified. When the language
option :extension:`ExplicitForAll` is used, the keyword ``forall`` allows us to
say exactly what this means. For example: ::

    g :: b -> b

means this: ::

    g :: forall b. (b -> b)

The two are treated identically, except that the latter may bring type variables
into scope (see :ref:`scoped-type-variables`).

This extension also enables explicit quantification of type and kind variables
in :ref:`data-instance-declarations`, :ref:`type-instance-declarations`,
:ref:`closed-type-families`, :ref:`assoc-inst`, and :ref:`rewrite-rules`.

Notes:

- As well in type signatures, you can also use an explicit ``forall``
  in an instance declaration: ::

      instance forall a. Eq a => Eq [a] where ...

- If the :ghc-flag:`-Wunused-foralls` flag is enabled, a warning will be emitted
  when you write a type variable in an explicit ``forall`` statement that is
  otherwise unused. For instance: ::

    g :: forall a b. (b -> b)

  would warn about the unused type variable `a`.

.. _flexible-contexts:

The context of a type signature
-------------------------------

The :extension:`FlexibleContexts` extension lifts the Haskell 98 restriction that
the type-class constraints in a type signature must have the form *(class
type-variable)* or *(class (type-variable type1 type2 ... typen))*. With
:extension:`FlexibleContexts` these type signatures are perfectly okay
::

      g :: Eq [a] => ...
      g :: Ord (T a ()) => ...

The flag :extension:`FlexibleContexts` also lifts the corresponding restriction
on class declarations (:ref:`superclass-rules`) and instance
declarations (:ref:`instance-rules`).

.. _ambiguity:

Ambiguous types and the ambiguity check
---------------------------------------

.. extension:: AllowAmbiguousTypes
    :shortdesc: Allow the user to write ambiguous types, and
        the type inference engine to infer them.

    :since: 7.8.1

    Allow type signatures which appear that they would result in
    an unusable binding.

Each user-written type signature is subjected to an *ambiguity check*.
The ambiguity check rejects functions that can never be called; for
example: ::

       f :: C a => Int

The idea is there can be no legal calls to ``f`` because every call will
give rise to an ambiguous constraint. Indeed, the *only* purpose of the
ambiguity check is to report functions that cannot possibly be called.
We could soundly omit the ambiguity check on type signatures entirely,
at the expense of delaying ambiguity errors to call sites. Indeed, the
language extension :extension:`AllowAmbiguousTypes` switches off the ambiguity
check.

Ambiguity can be subtle. Consider this example which uses functional
dependencies: ::

       class D a b | a -> b where ..
       h :: D Int b => Int

The ``Int`` may well fix ``b`` at the call site, so that signature
should not be rejected. Moreover, the dependencies might be hidden.
Consider ::

       class X a b where ...
       class D a b | a -> b where ...
       instance D a b => X [a] b where...
       h :: X a b => a -> a

Here ``h``\'s type looks ambiguous in ``b``, but here's a legal call: ::

       ...(h [True])...

That gives rise to a ``(X [Bool] beta)`` constraint, and using the
instance means we need ``(D Bool beta)`` and that fixes ``beta`` via
``D``\'s fundep!

Behind all these special cases there is a simple guiding principle.
Consider ::

      f :: type
      f = ...blah...

      g :: type
      g = f

You would think that the definition of ``g`` would surely typecheck!
After all ``f`` has exactly the same type, and ``g=f``. But in fact
``f``\'s type is instantiated and the instantiated constraints are solved
against the constraints bound by ``g``\ 's signature. So, in the case an
ambiguous type, solving will fail. For example, consider the earlier
definition ``f :: C a => Int``: ::

      f :: C a => Int
      f = ...blah...

      g :: C a => Int
      g = f

In ``g``\'s definition, we'll instantiate to ``(C alpha)`` and try to
deduce ``(C alpha)`` from ``(C a)``, and fail.

So in fact we use this as our *definition* of ambiguity: a type ``ty``
is ambiguous if and only if ``((undefined :: ty) :: ty)`` would fail to
typecheck. We use a very similar test for *inferred* types, to ensure
that they too are unambiguous.

*Switching off the ambiguity check.* Even if a function has an
ambiguous type according the "guiding principle", it is possible that
the function is callable. For example: ::

      class D a b where ...
      instance D Bool b where ...

      strange :: D a b => a -> a
      strange = ...blah...

      foo = strange True

Here ``strange``\'s type is ambiguous, but the call in ``foo`` is OK
because it gives rise to a constraint ``(D Bool beta)``, which is
soluble by the ``(D Bool b)`` instance.

Another way of getting rid of the ambiguity at the call site is to use
the :extension:`TypeApplications` extension to specify the types. For example: ::

      class D a b where
        h :: b
      instance D Int Int where ...

      main = print (h @Int @Int)

Here ``a`` is ambiguous in the definition of ``D`` but later specified
to be `Int` using type applications.

:extension:`AllowAmbiguousTypes` allows you to switch off the ambiguity check.
However, even with ambiguity checking switched off, GHC will complain about a
function that can *never* be called, such as this one: ::

      f :: (Int ~ Bool) => a -> a

Sometimes :extension:`AllowAmbiguousTypes` does not mix well with :extension:`RankNTypes`.
For example: ::

      foo :: forall r. (forall i. (KnownNat i) => r) -> r
      foo f = f @1

      boo :: forall j. (KnownNat j) => Int
      boo = ....

      h :: Int
      h = foo boo

This program will be rejected as ambiguous because GHC will not unify
the type variables `j` and `i`.

Unlike the previous examples, it is not currently possible
to resolve the ambiguity manually by using :extension:`TypeApplications`.


.. note::
    *A historical note.* GHC used to impose some more restrictive and less
    principled conditions on type signatures. For type
    ``forall tv1..tvn (c1, ...,cn) => type`` GHC used to require

     a. that each universally quantified type variable ``tvi`` must be "reachable"
        from ``type``, and

     b. that every constraint ``ci`` mentions at least one of the universally
        quantified type variables ``tvi``. These ad-hoc restrictions are
        completely subsumed by the new ambiguity check.

.. _kinding:

Explicitly-kinded quantification
--------------------------------

.. extension:: KindSignatures
    :shortdesc: Enable kind signatures.
        Implied by :extension:`TypeFamilies` and :extension:`PolyKinds`.

    :since: 6.8.1

    Allow explicit kind signatures on type variables.

Haskell infers the kind of each type variable. Sometimes it is nice to
be able to give the kind explicitly as (machine-checked) documentation,
just as it is nice to give a type signature for a function. On some
occasions, it is essential to do so. For example, in his paper
"Restricted Data Types in Haskell" (Haskell Workshop 1999) John Hughes
had to define the data type: ::

    data Set cxt a = Set [a]
                   | Unused (cxt a -> ())

The only use for the ``Unused`` constructor was to force the correct
kind for the type variable ``cxt``.

GHC now instead allows you to specify the kind of a type variable
directly, wherever a type variable is explicitly bound, with the extension
:extension:`KindSignatures`.

This extension enables kind signatures in the following places:

-  ``data`` declarations: ::

         data Set (cxt :: Type -> Type) a = Set [a]

-  ``type`` declarations: ::

         type T (f :: Type -> Type) = f Int

-  ``class`` declarations: ::

         class (Eq a) => C (f :: Type -> Type) a where ...

-  ``forall``\'s in type signatures: ::

         f :: forall (cxt :: Type -> Type). Set cxt Int

The parentheses are required.

As part of the same extension, you can put kind annotations in types as
well. Thus: ::

       f :: (Int :: Type) -> Int
       g :: forall a. a -> (a :: Type)

The syntax is

.. code-block:: none

       atype ::= '(' ctype '::' kind ')

The parentheses are required.

.. _universal-quantification:

.. _scoped-type-variables:

Lexically scoped type variables
===============================

.. extension:: ScopedTypeVariables
    :shortdesc: Enable lexically-scoped type variables.

    :implies: :extension:`ExplicitForAll`
    :since: 6.8.1

    Enable lexical scoping of type variables explicitly introduced with
    ``forall``.

.. tip::

    ``ScopedTypeVariables`` breaks GHC's usual rule that explicit ``forall`` is optional and doesn't affect semantics.
    For the :ref:`decl-type-sigs` (or :ref:`exp-type-sigs`) examples in this section,
    the explicit ``forall`` is required.
    (If omitted, usually the program will not compile; in a few cases it will compile but the functions get a different signature.)
    To trigger those forms of ``ScopedTypeVariables``, the ``forall`` must appear against the top-level signature (or outer expression)
    but *not* against nested signatures referring to the same type variables.

    Explicit ``forall`` is not always required -- see :ref:`pattern signature equivalent <pattern-equiv-form>` for the example in this section, or :ref:`pattern-type-sigs`.

GHC supports *lexically scoped type variables*, without which some type
signatures are simply impossible to write. For example: ::

    f :: forall a. [a] -> [a]
    f xs = ys ++ ys
         where
           ys :: [a]
           ys = reverse xs

The type signature for ``f`` brings the type variable ``a`` into scope,
because of the explicit ``forall`` (:ref:`decl-type-sigs`). The type
variables bound by a ``forall`` scope over the entire definition of the
accompanying value declaration. In this example, the type variable ``a``
scopes over the whole definition of ``f``, including over the type
signature for ``ys``. In Haskell 98 it is not possible to declare a type
for ``ys``; a major benefit of scoped type variables is that it becomes
possible to do so.

.. _pattern-equiv-form:

An equivalent form for that example, avoiding explicit ``forall`` uses :ref:`pattern-type-sigs`: ::

    f :: [a] -> [a]
    f (xs :: [aa]) = xs ++ ys
      where
        ys :: [aa]
        ys = reverse xs

Unlike the ``forall`` form, type variable ``a`` from ``f``'s signature is not scoped over ``f``'s equation(s).
Type variable ``aa`` bound by the pattern signature is scoped over the right-hand side of ``f``'s equation.
(Therefore there is no need to use a distinct type variable; using ``a`` would be equivalent.)


Overview
--------

The design follows the following principles

-  A scoped type variable stands for a type *variable*, and not for a
   *type*. (This is a change from GHC's earlier design.)

-  Furthermore, distinct lexical type variables stand for distinct type
   variables. This means that every programmer-written type signature
   (including one that contains free scoped type variables) denotes a
   *rigid* type; that is, the type is fully known to the type checker,
   and no inference is involved.

-  Lexical type variables may be alpha-renamed freely, without changing
   the program.

A *lexically scoped type variable* can be bound by:

-  A declaration type signature (:ref:`decl-type-sigs`)

-  An expression type signature (:ref:`exp-type-sigs`)

-  A pattern type signature (:ref:`pattern-type-sigs`)

-  Class and instance declarations (:ref:`cls-inst-scoped-tyvars`)

In Haskell, a programmer-written type signature is implicitly quantified
over its free type variables (`Section
4.1.2 <http://www.haskell.org/onlinereport/decls.html#sect4.1.2>`__ of
the Haskell Report). Lexically scoped type variables affect this
implicit quantification rules as follows: any type variable that is in
scope is *not* universally quantified. For example, if type variable
``a`` is in scope, then ::

      (e :: a -> a)     means     (e :: a -> a)
      (e :: b -> b)     means     (e :: forall b. b->b)
      (e :: a -> b)     means     (e :: forall b. a->b)

.. _decl-type-sigs:

Declaration type signatures
---------------------------

A declaration type signature that has *explicit* quantification (using
``forall``) brings into scope the explicitly-quantified type variables,
in the definition of the named function. For example: ::

      f :: forall a. [a] -> [a]
      f (x:xs) = xs ++ [ x :: a ]

The "``forall a``" brings "``a``" into scope in the definition of
"``f``".

This only happens if:

-  The quantification in ``f``\'s type signature is explicit. For
   example: ::

         g :: [a] -> [a]
         g (x:xs) = xs ++ [ x :: a ]

   This program will be rejected, because "``a``" does not scope over
   the definition of "``g``", so "``x::a``" means "``x::forall a. a``"
   by Haskell's usual implicit quantification rules.

-  The type variable is quantified by the single, syntactically visible,
   outermost ``forall`` of the type signature. For example, GHC will reject
   all of the following examples: ::

         f1 :: forall a. forall b. a -> [b] -> [b]
         f1 _ (x:xs) = xs ++ [ x :: b ]

         f2 :: forall a. a -> forall b. [b] -> [b]
         f2 _ (x:xs) = xs ++ [ x :: b ]

         type Foo = forall b. [b] -> [b]

         f3 :: Foo
         f3 (x:xs) = xs ++ [ x :: b ]

   In ``f1`` and ``f2``, the type variable ``b`` is not quantified by the
   outermost ``forall``, so it is not in scope over the bodies of the
   functions. Neither is ``b`` in scope over the body of ``f3``, as the
   ``forall`` is tucked underneath the ``Foo`` type synonym.

-  The signature gives a type for a function binding or a bare variable
   binding, not a pattern binding. For example: ::

         f1 :: forall a. [a] -> [a]
         f1 (x:xs) = xs ++ [ x :: a ]   -- OK

         f2 :: forall a. [a] -> [a]
         f2 = \(x:xs) -> xs ++ [ x :: a ]   -- OK

         f3 :: forall a. [a] -> [a]
         Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ])   -- Not OK!

   ``f1`` is a function binding, and ``f2`` binds a bare variable;
   in both cases the type signature brings ``a`` into scope.
   However the binding for ``f3`` is a pattern binding,
   and so ``f3`` is a fresh variable brought into scope by the pattern,
   not connected with top level ``f3``.
   Then type variable ``a`` is not in scope of the right-hand side of ``Just f3 = ...``.

.. _exp-type-sigs:

Expression type signatures
--------------------------

An expression type signature that has *explicit* quantification (using
``forall``) brings into scope the explicitly-quantified type variables,
in the annotated expression. For example: ::

    f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool )

Here, the type signature ``forall s. ST s Bool`` brings the type
variable ``s`` into scope, in the annotated expression
``(op >>= \(x :: STRef s Int) -> g x)``.

.. _pattern-type-sigs:

Pattern type signatures
-----------------------

A type signature may occur in any pattern; this is a *pattern type
signature*. For example: ::

    -- f and g assume that 'a' is already in scope
    f = \(x::Int, y::a) -> x

    g (x::a) = x

    h ((x,y) :: (Int,Bool)) = (y,x)

In the case where all the type variables in the pattern type signature
are already in scope (i.e. bound by the enclosing context), matters are
simple: the signature simply constrains the type of the pattern in the
obvious way.

Unlike expression and declaration type signatures, pattern type
signatures are not implicitly generalised. The pattern in a *pattern
binding* may only mention type variables that are already in scope. For
example: ::

    f :: forall a. [a] -> (Int, [a])
    f xs = (n, zs)
      where
        (ys::[a], n) = (reverse xs, length xs) -- OK
        (zs::[a])    = xs ++ ys                     -- OK

        Just (v::b)  = ...  -- Not OK; b is not in scope

Here, the pattern signatures for ``ys`` and ``zs`` are fine, but the one
for ``v`` is not because ``b`` is not in scope.

However, in all patterns *other* than pattern bindings, a pattern type
signature may mention a type variable that is not in scope; in this
case, *the signature brings that type variable into scope*. For example: ::

    -- same f and g as above, now assuming that 'a' is not already in scope
    f = \(x::Int, y::a) -> x           -- 'a' is in scope on RHS of ->

    g (x::a) = x :: a

    hh (Just (v :: b)) = v :: b

The pattern type signature makes the type variable available on the right-hand side of the equation.

Bringing type variables into scope is particularly important
for existential data constructors. For example: ::

    data T = forall a. MkT [a]

    k :: T -> T
    k (MkT [t::a]) =
        MkT t3
      where
        (t3::[a]) = [t,t,t]

Here, the pattern type signature ``[t::a]`` mentions a lexical type
variable that is not already in scope. Indeed, it *must not* already be in
scope, because it is bound by the pattern match.
The effect is to bring it into scope,
standing for the existentially-bound type variable.

It does seem odd that the existentially-bound type variable *must not*
be already in scope. Contrast that usually name-bindings merely shadow
(make a 'hole') in a same-named outer variable's scope.
But we must have *some* way to bring such type variables into scope,
else we could not name existentially-bound type variables
in subsequent type signatures.

Compare the two (identical) definitions for examples ``f``, ``g``;
they are both legal whether or not ``a`` is already in scope.
They differ in that *if* ``a`` is already in scope, the signature constrains
the pattern, rather than the pattern binding the variable.

.. _cls-inst-scoped-tyvars:

Class and instance declarations
-------------------------------

The type variables in the head of a ``class`` or ``instance``
declaration scope over the methods defined in the ``where`` part. You do
not even need an explicit ``forall`` (although you are allowed an explicit
``forall`` in an ``instance`` declaration; see :ref:`explicit-foralls`).
For example: ::

      class C a where
        op :: [a] -> a

        op xs = let ys::[a]
                    ys = reverse xs
                in
                head ys

      instance C b => C [b] where
        op xs = reverse (head (xs :: [[b]]))

Bindings and generalisation
===========================

.. _monomorphism:

Switching off the dreaded Monomorphism Restriction
--------------------------------------------------

.. extension:: NoMonomorphismRestriction
    :shortdesc: Disable the monomorphism restriction.

    :default: on
    :since: 6.8.1

    Prevents the compiler from applying the monomorphism restriction to
    bindings lacking explicit type signatures.

Haskell's monomorphism restriction (see `Section
4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__ of
the Haskell Report) can be completely switched off by
:extension:`NoMonomorphismRestriction`. Since GHC 7.8.1, the monomorphism
restriction is switched off by default in GHCi's interactive options
(see :ref:`ghci-interactive-options`).

.. _mono-local-binds:

Let-generalisation
------------------

.. extension:: MonoLocalBinds
    :shortdesc: Enable do not generalise local bindings.
        Implied by :extension:`TypeFamilies` and :extension:`GADTs`.

    :since: 6.12.1

    Infer less polymorphic types for local bindings by default.

An ML-style language usually generalises the type of any ``let``\-bound or
``where``\-bound variable, so that it is as polymorphic as possible. With the
extension :extension:`MonoLocalBinds` GHC implements a slightly more conservative
policy, using the following rules:

-  A variable is *closed* if and only if

   -  the variable is let-bound

   -  one of the following holds:

      -  the variable has an explicit type signature that has no free
         type variables, or

      -  its binding group is fully generalised (see next bullet)

-  A binding group is *fully generalised* if and only if

   -  each of its free variables is either imported or closed, and

   -  the binding is not affected by the monomorphism restriction
      (`Haskell Report, Section
      4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__)

For example, consider ::

    f x = x + 1
    g x = let h y = f y * 2
              k z = z+x
          in  h x + k x

Here ``f`` is generalised because it has no free variables; and its
binding group is unaffected by the monomorphism restriction; and hence
``f`` is closed. The same reasoning applies to ``g``, except that it has
one closed free variable, namely ``f``. Similarly ``h`` is closed, *even
though it is not bound at top level*, because its only free variable
``f`` is closed. But ``k`` is not closed, because it mentions ``x``
which is not closed (because it is not let-bound).

Notice that a top-level binding that is affected by the monomorphism
restriction is not closed, and hence may in turn prevent generalisation
of bindings that mention it.

The rationale for this more conservative strategy is given in `the
papers <https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/jfp-outsidein.pdf>`__
"Let should not be generalised" and "Modular type inference with local
assumptions", and a related `blog post
<https://www.haskell.org/ghc/blog/20100930-LetGeneralisationInGhc7.html>`__.

The extension :extension:`MonoLocalBinds` is implied by :extension:`TypeFamilies`
and :extension:`GADTs`. You can switch it off again with
:extension:`NoMonoLocalBinds <-XMonoLocalBinds>` but type inference becomes
less predictable if you do so. (Read the papers!)

.. _visible-type-application:

Visible type application
========================

.. extension:: TypeApplications
    :shortdesc: Enable type application syntax in terms and types.

    :since: 8.0.1

    Allow the use of type application syntax.

The :extension:`TypeApplications` extension allows you to use
*visible type application* in expressions. Here is an
example: ``show (read @Int "5")``. The ``@Int``
is the visible type application; it specifies the value of the type variable
in ``read``'s type.

A visible type application is preceded with an ``@``
sign. (To disambiguate the syntax, the ``@`` must be
preceded with a non-identifier letter, usually a space. For example,
``read@Int 5`` would not parse.) It can be used whenever
the full polymorphic type of the function is known. If the function
is an identifier (the common case), its type is considered known only when
the identifier has been given a type signature. If the identifier does
not have a type signature, visible type application cannot be used.

GHC also permits visible kind application, where users can declare the kind
arguments to be instantiated in kind-polymorphic cases. Its usage parallels
visible type application in the term level, as specified above.

.. _inferred-vs-specified:

Inferred vs. specified type variables
-------------------------------------

.. index::
   single: type variable; inferred vs. specified

GHC tracks a distinction between what we call *inferred* and *specified*
type variables. Only specified type variables are available for instantiation
with visible type application. An example illustrates this well::

  f :: (Eq b, Eq a) => a -> b -> Bool
  f x y = (x == x) && (y == y)

  g x y = (x == x) && (y == y)

The functions ``f`` and ``g`` have the same body, but only ``f`` is given
a type signature. When GHC is figuring out how to process a visible type application,
it must know what variable to instantiate. It thus must be able to provide
an ordering to the type variables in a function's type.

If the user has supplied a type signature, as in ``f``, then this is easy:
we just take the ordering from the type signature, going left to right and
using the first occurrence of a variable to choose its position within the
ordering. Thus, the variables in ``f`` will be ``b``, then ``a``.

In contrast, there is no reliable way to do this for ``g``; we will not know
whether ``Eq a`` or ``Eq b`` will be listed first in the constraint in ``g``\'s
type. In order to have visible type application be robust between releases of
GHC, we thus forbid its use with ``g``.

We say that the type variables in ``f`` are *specified*, while those in
``g`` are *inferred*. The general rule is this: if the user has written
a type variable in the source program, it is *specified*; if not, it is
*inferred*.

This rule applies in datatype declarations, too. For example, if we have
``data Proxy a = Proxy`` (and :extension:`PolyKinds` is enabled), then
``a`` will be assigned kind ``k``, where ``k`` is a fresh kind variable.
Because ``k`` was not written by the user, it will be unavailable for
type application in the type of the constructor ``Proxy``; only the ``a``
will be available.

When :ghc-flag:`-fprint-explicit-foralls` is enabled, inferred variables
are printed in braces. Thus, the type of the data constructor ``Proxy``
from the previous example would be ``forall {k} (a :: k). Proxy a``.
We can observe this behavior in a GHCi session: ::

  > :set -XTypeApplications -fprint-explicit-foralls
  > let myLength1 :: Foldable f => f a -> Int; myLength1 = length
  > :type +v myLength1
  myLength1 :: forall (f :: * -> *) a. Foldable f => f a -> Int
  > let myLength2 = length
  > :type +v myLength2
  myLength2 :: forall {a} {t :: * -> *}. Foldable t => t a -> Int
  > :type +v myLength2 @[]

  <interactive>:1:1: error:
      • Cannot apply expression of type ‘t0 a0 -> Int’
        to a visible type argument ‘[]’
      • In the expression: myLength2 @[]

Notice that since ``myLength1`` was defined with an explicit type signature,
:ghci-cmd:`:type +v` reports that all of its type variables are available
for type application. On the other hand, ``myLength2`` was not given a type
signature. As a result, all of its type variables are surrounded with braces,
and trying to use visible type application with ``myLength2`` fails.

Also note the use of :ghci-cmd:`:type +v` in the GHCi session above instead
of :ghci-cmd:`:type`. This is because :ghci-cmd:`:type` gives you the type
that would be inferred for a variable assigned to the expression provided
(that is, the type of ``x`` in ``let x = <expr>``). As we saw above with
``myLength2``, this type will have no variables available to visible type
application. On the other hand, :ghci-cmd:`:type +v` gives you the actual
type of the expression provided. To illustrate this: ::

  > :type myLength1
  myLength1 :: forall {a} {f :: * -> *}. Foldable f => f a -> Int
  > :type myLength2
  myLength2 :: forall {a} {t :: * -> *}. Foldable t => t a -> Int

Using :ghci-cmd:`:type` might lead one to conclude that none of the type
variables in ``myLength1``'s type signature are available for type
application. This isn't true, however! Be sure to use :ghci-cmd:`:type +v`
if you want the most accurate information with respect to visible type
application properties.

.. index::
   single: ScopedSort

.. _ScopedSort:

Ordering of specified variables
-------------------------------

In the simple case of the previous section, we can say that specified variables
appear in left-to-right order. However, not all cases are so simple. Here are
the rules in the subtler cases:

- If an identifier's type has a ``forall``, then the order of type variables
  as written in the ``forall`` is retained.

- If any of the variables depend on other variables (that is, if some
  of the variables are *kind* variables), the variables are reordered
  so that kind variables come before type variables, preserving the
  left-to-right order as much as possible. That is, GHC performs a
  stable topological sort on the variables. Example::

    h :: Proxy (a :: (j, k)) -> Proxy (b :: Proxy a) -> ()
      -- as if h :: forall j k a b. ...

  In this example, ``a`` depends on ``j`` and ``k``, and ``b`` depends on ``a``.
  Even though ``a`` appears lexically before ``j`` and ``k``, ``j`` and ``k``
  are quantified first, because ``a`` depends on ``j`` and ``k``. Note further
  that ``j`` and ``k`` are not reordered with respect to each other, even
  though doing so would not violate dependency conditions.

  A "stable topological sort" here, we mean that we perform this algorithm
  (which we call *ScopedSort*):

  * Work left-to-right through the input list of type variables, with a cursor.
  * If variable ``v`` at the cursor is depended on by any earlier variable ``w``,
    move ``v`` immediately before the leftmost such ``w``.

- Class methods' type arguments include the class type
  variables, followed by any variables an individual method is polymorphic
  in. So, ``class Monad m where return :: a -> m a`` means
  that ``return``'s type arguments are ``m, a``.

- With the :extension:`RankNTypes` extension
  (:ref:`universal-quantification`), it is possible to declare
  type arguments somewhere other than the beginning of a type. For example,
  we can have ``pair :: forall a. a -> forall b. b -> (a, b)``
  and then say ``pair @Bool True @Char`` which would have
  type ``Char -> (Bool, Char)``.

- Partial type signatures (:ref:`partial-type-signatures`)
  work nicely with visible type
  application. If you want to specify only the second type argument to
  ``wurble``, then you can say ``wurble @_ @Int``.
  The first argument is a wildcard, just like in a partial type signature.
  However, if used in a visible type application/visible kind application,
  it is *not* necessary to specify :extension:`PartialTypeSignatures` and your
  code will not generate a warning informing you of the omitted type.

The section in this manual on kind polymorphism describes how variables
in type and class declarations are ordered (:ref:`inferring-variable-order`).

.. _implicit-parameters:

Implicit parameters
===================

.. extension:: ImplicitParams
    :shortdesc: Enable Implicit Parameters.

    :since: 6.8.1

    Allow definition of functions expecting implicit parameters.

Implicit parameters are implemented as described in [Lewis2000]_ and enabled
with the option :extension:`ImplicitParams`. (Most of the following, still rather
incomplete, documentation is due to Jeff Lewis.)

.. [Lewis2000]
    "Implicit parameters: dynamic scoping with static types",
    J Lewis, MB Shields, E Meijer, J Launchbury,
    *27th ACM Symposium on Principles of Programming Languages (POPL'00)*,
    Boston, Jan 2000.

A variable is called *dynamically bound* when it is bound by the calling
context of a function and *statically bound* when bound by the callee's
context. In Haskell, all variables are statically bound. Dynamic binding
of variables is a notion that goes back to Lisp, but was later discarded
in more modern incarnations, such as Scheme. Dynamic binding can be very
confusing in an untyped language, and unfortunately, typed languages, in
particular Hindley-Milner typed languages like Haskell, only support
static scoping of variables.

However, by a simple extension to the type class system of Haskell, we
can support dynamic binding. Basically, we express the use of a
dynamically bound variable as a constraint on the type. These
constraints lead to types of the form ``(?x::t') => t``, which says
"this function uses a dynamically-bound variable ``?x`` of type ``t'``".
For example, the following expresses the type of a sort function,
implicitly parameterised by a comparison function named ``cmp``. ::

      sort :: (?cmp :: a -> a -> Bool) => [a] -> [a]

The dynamic binding constraints are just a new form of predicate in the
type class system.

An implicit parameter occurs in an expression using the special form
``?x``, where ``x`` is any valid identifier (e.g. ``ord ?x`` is a valid
expression). Use of this construct also introduces a new dynamic-binding
constraint in the type of the expression. For example, the following
definition shows how we can define an implicitly parameterised sort
function in terms of an explicitly parameterised ``sortBy`` function: ::

      sortBy :: (a -> a -> Bool) -> [a] -> [a]

      sort   :: (?cmp :: a -> a -> Bool) => [a] -> [a]
      sort    = sortBy ?cmp

Implicit-parameter type constraints
-----------------------------------

Dynamic binding constraints behave just like other type class
constraints in that they are automatically propagated. Thus, when a
function is used, its implicit parameters are inherited by the function
that called it. For example, our ``sort`` function might be used to pick
out the least value in a list: ::

      least   :: (?cmp :: a -> a -> Bool) => [a] -> a
      least xs = head (sort xs)

Without lifting a finger, the ``?cmp`` parameter is propagated to become
a parameter of ``least`` as well. With explicit parameters, the default
is that parameters must always be explicit propagated. With implicit
parameters, the default is to always propagate them.

An implicit-parameter type constraint differs from other type class
constraints in the following way: All uses of a particular implicit
parameter must have the same type. This means that the type of
``(?x, ?x)`` is ``(?x::a) => (a,a)``, and not
``(?x::a, ?x::b) => (a, b)``, as would be the case for type class
constraints.

You can't have an implicit parameter in the context of a class or
instance declaration. For example, both these declarations are illegal: ::

      class (?x::Int) => C a where ...
      instance (?x::a) => Foo [a] where ...

Reason: exactly which implicit parameter you pick up depends on exactly
where you invoke a function. But the "invocation" of instance
declarations is done behind the scenes by the compiler, so it's hard to
figure out exactly where it is done. Easiest thing is to outlaw the
offending types.

Implicit-parameter constraints do not cause ambiguity. For example,
consider: ::

       f :: (?x :: [a]) => Int -> Int
       f n = n + length ?x

       g :: (Read a, Show a) => String -> String
       g s = show (read s)

Here, ``g`` has an ambiguous type, and is rejected, but ``f`` is fine.
The binding for ``?x`` at ``f``\ 's call site is quite unambiguous, and
fixes the type ``a``.

Implicit-parameter bindings
---------------------------

An implicit parameter is *bound* using the standard ``let`` or ``where``
binding forms. For example, we define the ``min`` function by binding
``cmp``. ::

      min :: Ord a => [a] -> a
      min  = let ?cmp = (<=) in least

A group of implicit-parameter bindings may occur anywhere a normal group
of Haskell bindings can occur, except at top level. That is, they can
occur in a ``let`` (including in a list comprehension, or do-notation,
or pattern guards), or a ``where`` clause. Note the following points:

-  An implicit-parameter binding group must be a collection of simple
   bindings to implicit-style variables (no function-style bindings, and
   no type signatures); these bindings are neither polymorphic or
   recursive.

-  You may not mix implicit-parameter bindings with ordinary bindings in
   a single ``let`` expression; use two nested ``let``\ s instead. (In
   the case of ``where`` you are stuck, since you can't nest ``where``
   clauses.)

-  You may put multiple implicit-parameter bindings in a single binding
   group; but they are *not* treated as a mutually recursive group (as
   ordinary ``let`` bindings are). Instead they are treated as a
   non-recursive group, simultaneously binding all the implicit
   parameter. The bindings are not nested, and may be re-ordered without
   changing the meaning of the program. For example, consider: ::

         f t = let { ?x = t; ?y = ?x+(1::Int) } in ?x + ?y

   The use of ``?x`` in the binding for ``?y`` does not "see" the
   binding for ``?x``, so the type of ``f`` is ::

         f :: (?x::Int) => Int -> Int

Implicit parameters and polymorphic recursion
---------------------------------------------

Consider these two definitions: ::

      len1 :: [a] -> Int
      len1 xs = let ?acc = 0 in len_acc1 xs

      len_acc1 [] = ?acc
      len_acc1 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc1 xs

      ------------

      len2 :: [a] -> Int
      len2 xs = let ?acc = 0 in len_acc2 xs

      len_acc2 :: (?acc :: Int) => [a] -> Int
      len_acc2 [] = ?acc
      len_acc2 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc2 xs

The only difference between the two groups is that in the second group
``len_acc`` is given a type signature. In the former case, ``len_acc1``
is monomorphic in its own right-hand side, so the implicit parameter
``?acc`` is not passed to the recursive call. In the latter case,
because ``len_acc2`` has a type signature, the recursive call is made to
the *polymorphic* version, which takes ``?acc`` as an implicit
parameter. So we get the following results in GHCi:

.. code-block:: none

      Prog> len1 "hello"
      0
      Prog> len2 "hello"
      5

Adding a type signature dramatically changes the result! This is a
rather counter-intuitive phenomenon, worth watching out for.

Implicit parameters and monomorphism
------------------------------------

GHC applies the dreaded Monomorphism Restriction (section 4.5.5 of the
Haskell Report) to implicit parameters. For example, consider: ::

     f :: Int -> Int
     f v = let ?x = 0     in
           let y = ?x + v in
           let ?x = 5     in
           y

Since the binding for ``y`` falls under the Monomorphism Restriction it
is not generalised, so the type of ``y`` is simply ``Int``, not
``(?x::Int) => Int``. Hence, ``(f 9)`` returns result ``9``. If you add
a type signature for ``y``, then ``y`` will get type
``(?x::Int) => Int``, so the occurrence of ``y`` in the body of the
``let`` will see the inner binding of ``?x``, so ``(f 9)`` will return
``14``.

Arbitrary-rank polymorphism
===========================

.. extension:: RankNTypes
    :shortdesc: Enable rank-N types.
        Implied by :extension:`ImpredicativeTypes`.

    :implies: :extension:`ExplicitForAll`
    :since: 6.8.1

    Allow types of arbitrary rank.

.. extension:: Rank2Types
    :shortdesc: Enable rank-2 types.
        Synonym for :extension:`RankNTypes`.

    :since: 6.8.1

    A deprecated alias of :extension:`RankNTypes`.

GHC's type system supports *arbitrary-rank* explicit universal
quantification in types. For example, all the following types are legal: ::

        f1 :: forall a b. a -> b -> a
        g1 :: forall a b. (Ord a, Eq  b) => a -> b -> a

        f2 :: (forall a. a->a) -> Int -> Int
        g2 :: (forall a. Eq a => [a] -> a -> Bool) -> Int -> Int

        f3 :: ((forall a. a->a) -> Int) -> Bool -> Bool

        f4 :: Int -> (forall a. a -> a)

Here, ``f1`` and ``g1`` are rank-1 types, and can be written in standard
Haskell (e.g. ``f1 :: a->b->a``). The ``forall`` makes explicit the
universal quantification that is implicitly added by Haskell.

The functions ``f2`` and ``g2`` have rank-2 types; the ``forall`` is on
the left of a function arrow. As ``g2`` shows, the polymorphic type on
the left of the function arrow can be overloaded.

The function ``f3`` has a rank-3 type; it has rank-2 types on the left
of a function arrow.

The language option :extension:`RankNTypes` (which implies
:extension:`ExplicitForAll`) enables higher-rank
types. That is, you can nest ``forall``\ s arbitrarily deep in function
arrows. For example, a forall-type (also called a "type scheme"),
including a type-class context, is legal:

-  On the left or right (see ``f4``, for example) of a function arrow

-  As the argument of a constructor, or type of a field, in a data type
   declaration. For example, any of the ``f1, f2, f3, g1, g2`` above would
   be valid field type signatures.

-  As the type of an implicit parameter

-  In a pattern type signature (see :ref:`scoped-type-variables`)

The :extension:`RankNTypes` option is also required for any type with a
``forall`` or context to the right of an arrow (e.g.
``f :: Int -> forall a. a->a``, or ``g :: Int -> Ord a => a -> a``).
Such types are technically rank 1, but are clearly not Haskell-98, and
an extra extension did not seem worth the bother.

In particular, in ``data`` and ``newtype`` declarations the constructor
arguments may be polymorphic types of any rank; see examples in
:ref:`univ`. Note that the declared types are nevertheless always
monomorphic. This is important because by default GHC will not
instantiate type variables to a polymorphic type
(:ref:`impredicative-polymorphism`).

The obsolete language options :extension:`PolymorphicComponents` and
:extension:`Rank2Types` are synonyms for :extension:`RankNTypes`. They used to
specify finer distinctions that GHC no longer makes. (They should really elicit
a deprecation warning, but they don't, purely to avoid the need to library
authors to change their old flags specifications.)

.. _univ:

Examples
--------

These are examples of ``data`` and ``newtype`` declarations whose data
constructors have polymorphic argument types: ::

    data T a = T1 (forall b. b -> b -> b) a

    data MonadT m = MkMonad { return :: forall a. a -> m a,
                              bind   :: forall a b. m a -> (a -> m b) -> m b
                            }

    newtype Swizzle = MkSwizzle (forall a. Ord a => [a] -> [a])

The constructors have rank-2 types: ::

    T1 :: forall a. (forall b. b -> b -> b) -> a -> T a

    MkMonad :: forall m. (forall a. a -> m a)
                      -> (forall a b. m a -> (a -> m b) -> m b)
                      -> MonadT m

    MkSwizzle :: (forall a. Ord a => [a] -> [a]) -> Swizzle

In earlier versions of GHC, it was possible to omit the ``forall`` in
the type of the constructor if there was an explicit context. For
example: ::

    newtype Swizzle' = MkSwizzle' (Ord a => [a] -> [a])

Since GHC 8.0 declarations such as ``MkSwizzle'`` will cause an out-of-scope
error.

As for type signatures, implicit quantification happens for
non-overloaded types too. So if you write this: ::

      f :: (a -> a) -> a

it's just as if you had written this: ::

      f :: forall a. (a -> a) -> a

That is, since the type variable ``a`` isn't in scope, it's implicitly
universally quantified.

You construct values of types ``T1, MonadT, Swizzle`` by applying the
constructor to suitable values, just as usual. For example, ::

        a1 :: T Int
        a1 = T1 (\xy->x) 3

        a2, a3 :: Swizzle
        a2 = MkSwizzle sort
        a3 = MkSwizzle reverse

        a4 :: MonadT Maybe
        a4 = let r x = Just x
             b m k = case m of
                   Just y -> k y
                   Nothing -> Nothing
             in
             MkMonad r b

        mkTs :: (forall b. b -> b -> b) -> a -> [T a]
        mkTs f x y = [T1 f x, T1 f y]

The type of the argument can, as usual, be more general than the type
required, as ``(MkSwizzle reverse)`` shows. (``reverse`` does not need
the ``Ord`` constraint.)

When you use pattern matching, the bound variables may now have
polymorphic types. For example: ::

        f :: T a -> a -> (a, Char)
        f (T1 w k) x = (w k x, w 'c' 'd')

        g :: (Ord a, Ord b) => Swizzle -> [a] -> (a -> b) -> [b]
        g (MkSwizzle s) xs f = s (map f (s xs))

        h :: MonadT m -> [m a] -> m [a]
        h m [] = return m []
        h m (x:xs) = bind m x          $ \y ->
                     bind m (h m xs)   $ \ys ->
                     return m (y:ys)

In the function ``h`` we use the record selectors ``return`` and
``bind`` to extract the polymorphic bind and return functions from the
``MonadT`` data structure, rather than using pattern matching.


.. _higher-rank-type-inference:

Type inference
--------------

In general, type inference for arbitrary-rank types is undecidable. GHC
uses an algorithm proposed by Odersky and Laufer ("Putting type
annotations to work", POPL'96) to get a decidable algorithm by requiring
some help from the programmer. We do not yet have a formal specification
of "some help" but the rule is this:

    For a lambda-bound or case-bound variable, x, either the programmer
    provides an explicit polymorphic type for x, or GHC's type inference
    will assume that x's type has no foralls in it.

What does it mean to "provide" an explicit type for x? You can do that
by giving a type signature for x directly, using a pattern type
signature (:ref:`scoped-type-variables`), thus: ::

    \ f :: (forall a. a->a) -> (f True, f 'c')

Alternatively, you can give a type signature to the enclosing context,
which GHC can "push down" to find the type for the variable: ::

    (\ f -> (f True, f 'c')) :: (forall a. a->a) -> (Bool,Char)

Here the type signature on the expression can be pushed inwards to give
a type signature for f. Similarly, and more commonly, one can give a
type signature for the function itself: ::

    h :: (forall a. a->a) -> (Bool,Char)
    h f = (f True, f 'c')

You don't need to give a type signature if the lambda bound variable is
a constructor argument. Here is an example we saw earlier: ::

    f :: T a -> a -> (a, Char)
    f (T1 w k) x = (w k x, w 'c' 'd')

Here we do not need to give a type signature to ``w``, because it is an
argument of constructor ``T1`` and that tells GHC all it needs to know.


.. _implicit-quantification:

Implicit quantification
-----------------------

GHC performs implicit quantification as follows. At the outermost level
(only) of user-written types, if and only if there is no explicit
``forall``, GHC finds all the type variables mentioned in the type that
are not already in scope, and universally quantifies them. For example,
the following pairs are equivalent: ::

      f :: a -> a
      f :: forall a. a -> a

      g (x::a) = let
                    h :: a -> b -> b
                    h x y = y
                 in ...
      g (x::a) = let
                    h :: forall b. a -> b -> b
                    h x y = y
                 in ...

Notice that GHC always adds implicit quantifiers *at the outermost level*
of a user-written type; it
does *not* find the inner-most possible quantification
point. For example: ::

      f :: (a -> a) -> Int
               -- MEANS
      f :: forall a. (a -> a) -> Int
               -- NOT
      f :: (forall a. a -> a) -> Int


      g :: (Ord a => a -> a) -> Int
               -- MEANS
      g :: forall a. (Ord a => a -> a) -> Int
               -- NOT
      g :: (forall a. Ord a => a -> a) -> Int

If you want the latter type, you can write
your ``forall``\s explicitly. Indeed, doing so is strongly advised for
rank-2 types.

Sometimes there *is* no "outermost level", in which case no
implicit quantification happens: ::

      data PackMap a b s t = PackMap (Monad f => (a -> f b) -> s -> f t)

This is rejected because there is no "outermost level" for the types on the RHS
(it would obviously be terrible to add extra parameters to ``PackMap``),
so no implicit quantification happens, and the declaration is rejected
(with "``f`` is out of scope").  Solution: use an explicit ``forall``: ::

      data PackMap a b s t = PackMap (forall f. Monad f => (a -> f b) -> s -> f t)

.. _impredicative-polymorphism:

Impredicative polymorphism
==========================

.. extension:: ImpredicativeTypes
    :shortdesc: Enable impredicative types.
        Implies :extension:`RankNTypes`.

    :implies: :extension:`RankNTypes`
    :since: 6.10.1

    Allow impredicative polymorphic types.

In general, GHC will only instantiate a polymorphic function at a
monomorphic type (one with no foralls). For example, ::

    runST :: (forall s. ST s a) -> a
    id :: forall b. b -> b

    foo = id runST   -- Rejected

The definition of ``foo`` is rejected because one would have to
instantiate ``id``\'s type with ``b := (forall s. ST s a) -> a``, and
that is not allowed. Instantiating polymorphic type variables with
polymorphic types is called *impredicative polymorphism*.

GHC has extremely flaky support for *impredicative polymorphism*,
enabled with :extension:`ImpredicativeTypes`. If it worked, this would mean
that you *could* call a polymorphic function at a polymorphic type, and
parameterise data structures over polymorphic types. For example: ::

      f :: Maybe (forall a. [a] -> [a]) -> Maybe ([Int], [Char])
      f (Just g) = Just (g [3], g "hello")
      f Nothing  = Nothing

Notice here that the ``Maybe`` type is parameterised by the
*polymorphic* type ``(forall a. [a] -> [a])``. However *the extension
should be considered highly experimental, and certainly un-supported*.
You are welcome to try it, but please don't rely on it working
consistently, or working the same in subsequent releases. See
:ghc-wiki:`this wiki page <impredicative-polymorphism>` for more details.

If you want impredicative polymorphism, the main workaround is to use a
newtype wrapper. The ``id runST`` example can be written using this
workaround like this: ::

    runST :: (forall s. ST s a) -> a
    id :: forall b. b -> b

    newtype Wrap a = Wrap { unWrap :: (forall s. ST s a) -> a }

    foo :: (forall s. ST s a) -> a
    foo = unWrap (id (Wrap runST))
          -- Here id is called at monomorphic type (Wrap a)

.. _typed-holes:

Typed Holes
===========

Typed holes are a feature of GHC that allows special placeholders
written with a leading underscore (e.g., "``_``", "``_foo``",
"``_bar``"), to be used as expressions. During compilation these holes
will generate an error message that describes which type is expected at
the hole's location, information about the origin of any free type
variables, and a list of local bindings that might help fill the hole
and bindings in scope that fit the type of the hole that might help fill
the hole with actual code. Typed holes are always enabled in GHC.

The goal of typed holes is to help with writing Haskell code rather than
to change the type system. Typed holes can be used to obtain extra
information from the type checker, which might otherwise be hard to get.
Normally, using GHCi, users can inspect the (inferred) type signatures
of all top-level bindings. However, this method is less convenient with
terms that are not defined on top-level or inside complex expressions.
Holes allow the user to check the type of the term they are about to
write.

For example, compiling the following module with GHC: ::

    f :: a -> a
    f x = _

will fail with the following error: ::

    hole.hs:2:7:
        Found hole `_' with type: a
        Where: `a' is a rigid type variable bound by
                   the type signature for f :: a -> a at hole.hs:1:6
        In the expression: _
        In an equation for `f': f x = _
        Relevant bindings include
          x :: a (bound at hole.hs:2:3)
          f :: a -> a (bound at hole.hs:2:1)
        Valid hole fits include x :: a (bound at hole.hs:2:3)

Here are some more details:

-  A "``Found hole``" error usually terminates compilation, like any
   other type error. After all, you have omitted some code from your
   program. Nevertheless, you can run and test a piece of code
   containing holes, by using the :ghc-flag:`-fdefer-typed-holes` flag. This
   flag defers errors produced by typed holes until runtime, and
   converts them into compile-time warnings. These warnings can in turn
   be suppressed entirely by :ghc-flag:`-Wno-typed-holes <-Wtyped-holes>`.

   The same behaviour for "``Variable out of scope``" errors, it terminates
   compilation by default. You can defer such errors by using the
   :ghc-flag:`-fdefer-out-of-scope-variables` flag. This flag defers errors
   produced by out of scope variables until runtime, and
   converts them into compile-time warnings. These warnings can in turn
   be suppressed entirely by :ghc-flag:`-Wno-deferred-out-of-scope-variables
   <-Wdeferred-out-of-scope-variables>`.

   The result is that a hole or a variable will behave like ``undefined``, but with
   the added benefits that it shows a warning at compile time, and will
   show the same message if it gets evaluated at runtime. This behaviour
   follows that of the :ghc-flag:`-fdefer-type-errors` option, which implies
   :ghc-flag:`-fdefer-typed-holes` and :ghc-flag:`-fdefer-out-of-scope-variables`.
   See :ref:`defer-type-errors`.

-  All unbound identifiers are treated as typed holes, *whether or not
   they start with an underscore*. The only difference is in the error
   message: ::

       cons z = z : True : _x : y

   yields the errors

   .. code-block:: none

       Foo.hs:3:21: error:
          Found hole: _x :: Bool
          Or perhaps ‘_x’ is mis-spelled, or not in scope
          In the first argument of ‘(:)’, namely ‘_x’
          In the second argument of ‘(:)’, namely ‘_x : y’
          In the second argument of ‘(:)’, namely ‘True : _x : y’
          Relevant bindings include
            z :: Bool (bound at Foo.hs:3:6)
          cons :: Bool -> [Bool] (bound at Foo.hs:3:1)
          Valid hole fits include
            z :: Bool (bound at mpt.hs:2:6)
            otherwise :: Bool
              (imported from ‘Prelude’ at mpt.hs:1:8-10
              (and originally defined in ‘GHC.Base’))
            False :: Bool
              (imported from ‘Prelude’ at mpt.hs:1:8-10
              (and originally defined in ‘GHC.Types’))
            True :: Bool
              (imported from ‘Prelude’ at mpt.hs:1:8-10
              (and originally defined in ‘GHC.Types’))
            maxBound :: forall a. Bounded a => a
              with maxBound @Bool
              (imported from ‘Prelude’ at mpt.hs:1:8-10
              (and originally defined in ‘GHC.Enum’))
            minBound :: forall a. Bounded a => a
              with minBound @Bool
              (imported from ‘Prelude’ at mpt.hs:1:8-10
              (and originally defined in ‘GHC.Enum’))

       Foo.hs:3:26: error:
           Variable not in scope: y :: [Bool]

   More information is given for explicit holes (i.e. ones that start
   with an underscore), than for out-of-scope variables, because the
   latter are often unintended typos, so the extra information is
   distracting. If you want the detailed information, use a leading
   underscore to make explicit your intent to use a hole.

-  Unbound identifiers with the same name are never unified, even within
   the same function, but shown individually. For example: ::

       cons = _x : _x

   results in the following errors:

   .. code-block:: none

      unbound.hs:1:8:
          Found hole '_x' with type: a
          Where: `a' is a rigid type variable bound by
                     the inferred type of cons :: [a] at unbound.hs:1:1
          In the first argument of `(:)', namely `_x'
          In the expression: _x : _x
          In an equation for `cons': cons = _x : _x
          Relevant bindings include cons :: [a] (bound at unbound.hs:1:1)

      unbound.hs:1:13:
          Found hole: _x :: [a]
          Where: ‘a’ is a rigid type variable bound by
                  the inferred type of cons :: [a]
                  at unbound.hs:3:1-12
          Or perhaps ‘_x’ is mis-spelled, or not in scope
          In the second argument of ‘(:)’, namely ‘_x’
          In the expression: _x : _x
          In an equation for ‘cons’: cons = _x : _x
          Relevant bindings include cons :: [a] (bound at unbound.hs:3:1)
          Valid hole fits include
            cons :: forall a. [a]
              with cons @a
              (defined at mpt.hs:3:1)
            mempty :: forall a. Monoid a => a
              with mempty @[a]
              (imported from ‘Prelude’ at mpt.hs:1:8-10
              (and originally defined in ‘GHC.Base’))

   Notice the two different types reported for the two different
   occurrences of ``_x``.

-  No language extension is required to use typed holes. The lexeme
   "``_``" was previously illegal in Haskell, but now has a more
   informative error message. The lexeme "``_x``" is a perfectly legal
   variable, and its behaviour is unchanged when it is in scope. For
   example ::

       f _x = _x + 1

   does not elict any errors. Only a variable *that is not in scope*
   (whether or not it starts with an underscore) is treated as an error
   (which it always was), albeit now with a more informative error
   message.

-  Unbound data constructors used in expressions behave exactly as
   above. However, unbound data constructors used in *patterns* cannot
   be deferred, and instead bring compilation to a halt. (In
   implementation terms, they are reported by the renamer rather than
   the type checker.)

- The list of valid hole fits is found by checking which bindings in scope
  would fit into the hole. As an example, compiling the following module with
  GHC: ::

      import Data.List (inits)

      g :: [String]
      g = _ "hello, world"

  yields the errors:


  .. code-block:: none


    • Found hole: _ :: [Char] -> [String]
    • In the expression: _
      In the expression: _ "hello, world"
      In an equation for ‘g’: g = _ "hello, world"
    • Relevant bindings include g :: [String] (bound at mpt.hs:6:1)
      Valid hole fits include
        lines :: String -> [String]
          (imported from ‘Prelude’ at mpt.hs:3:8-9
           (and originally defined in ‘base-4.11.0.0:Data.OldList’))
        words :: String -> [String]
          (imported from ‘Prelude’ at mpt.hs:3:8-9
           (and originally defined in ‘base-4.11.0.0:Data.OldList’))
        inits :: forall a. [a] -> [[a]]
          with inits @Char
          (imported from ‘Data.List’ at mpt.hs:4:19-23
           (and originally defined in ‘base-4.11.0.0:Data.OldList’))
        repeat :: forall a. a -> [a]
          with repeat @String
          (imported from ‘Prelude’ at mpt.hs:3:8-9
           (and originally defined in ‘GHC.List’))
        fail :: forall (m :: * -> *). Monad m => forall a. String -> m a
          with fail @[] @String
          (imported from ‘Prelude’ at mpt.hs:3:8-9
           (and originally defined in ‘GHC.Base’))
        return :: forall (m :: * -> *). Monad m => forall a. a -> m a
          with return @[] @String
          (imported from ‘Prelude’ at mpt.hs:3:8-9
           (and originally defined in ‘GHC.Base’))
        pure :: forall (f :: * -> *). Applicative f => forall a. a -> f a
          with pure @[] @String
          (imported from ‘Prelude’ at mpt.hs:3:8-9
           (and originally defined in ‘GHC.Base’))
        read :: forall a. Read a => String -> a
          with read @[String]
          (imported from ‘Prelude’ at mpt.hs:3:8-9
           (and originally defined in ‘Text.Read’))
        mempty :: forall a. Monoid a => a
          with mempty @([Char] -> [String])
          (imported from ‘Prelude’ at mpt.hs:3:8-9
           (and originally defined in ‘GHC.Base’))

There are a few flags for controlling the amount of context information shown
for typed holes:

.. ghc-flag:: -fshow-hole-constraints
    :shortdesc: Show constraints when reporting typed holes.
    :type: dynamic
    :category: verbosity

    When reporting typed holes, also print constraints that are in scope.
    Example: ::

        f :: Eq a => a -> Bool
        f x = _

    results in the following message:

    .. code-block:: none

      show_constraints.hs:4:7: error:
          • Found hole: _ :: Bool
          • In the expression: _
            In an equation for ‘f’: f x = _
          • Relevant bindings include
              x :: a (bound at show_constraints.hs:4:3)
              f :: a -> Bool (bound at show_constraints.hs:4:1)
            Constraints include Eq a (from show_constraints.hs:3:1-22)
            Valid hole fits include
              otherwise :: Bool
              False :: Bool
              True :: Bool
              maxBound :: forall a. Bounded a => a
                with maxBound @Bool
              minBound :: forall a. Bounded a => a
                with minBound @Bool

.. _typed-hole-valid-hole-fits:

Valid Hole Fits
-------------------
GHC sometimes suggests valid hole fits for typed holes, which is
configurable by a few flags.

.. ghc-flag:: -fno-show-valid-hole-fits
    :shortdesc: Disables showing a list of valid hole fits for typed holes
        in type error messages.
    :type: dynamic
    :category: verbosity

    :default: off

    This flag can be toggled to turn off the display of valid hole fits
    entirely.

.. ghc-flag:: -fmax-valid-hole-fits=⟨n⟩
    :shortdesc: *default: 6.* Set the maximum number of valid hole fits for
        typed holes to display in type error messages.
    :type: dynamic
    :reverse: -fno-max-valid-hole-fits
    :category: verbosity

    :default: 6

    The list of valid hole fits is limited by displaying up to 6
    hole fits per hole. The number of hole fits shown can be set by this
    flag. Turning the limit off with :ghc-flag:`-fno-max-valid-hole-fits`
    displays all found hole fits.


.. ghc-flag:: -fshow-type-of-hole-fits
    :shortdesc: Toggles whether to show the type of the valid hole fits
       in the output.
    :type: dynamic
    :category: verbosity
    :reverse: -fno-type-of-hole-fits

    :default: on

    By default, the hole fits show the type of the hole fit.
    This can be turned off by the reverse of this flag.



.. ghc-flag:: -fshow-type-app-of-hole-fits
    :shortdesc: Toggles whether to show the type application of the valid
       hole fits in the output.
    :type: dynamic
    :category: verbosity
    :reverse: -fno-show-type-app-of-hole-fits

    :default: on

    By default, the hole fits show the type application needed to make
    this hole fit fit the type of the hole, e.g. for the hole
    ``(_ :: Int -> [Int])``, ``mempty`` is a hole fit with
    ``mempty @(Int -> [Int])``. This can be toggled off with
    the reverse of this flag.

.. ghc-flag:: -fshow-docs-of-hole-fits
    :shortdesc: Toggles whether to show the documentation of the valid
       hole fits in the output.
    :type: dynamic
    :category: verbosity
    :reverse: -fno-show-docs-of-hole-fits

    :default: off

    It can sometime be the case that the name and type of a valid hole
    fit is not enough to realize what the fit stands for. This flag
    adds the documentation of the fit to the message, if the
    documentation is available (and the module from which the function
    comes was compiled with the ``-haddock`` flag).

.. ghc-flag:: -fshow-type-app-vars-of-hole-fits
    :shortdesc: Toggles whether to show what type each quantified
       variable takes in a valid hole fit.
    :type: dynamic
    :category: verbosity
    :reverse: -fno-show-type-app-vars-of-hole-fits

    :default: on

    By default, the hole fits show the type application needed to make
    this hole fit fit the type of the hole, e.g. for the hole
    ``(_ :: Int -> [Int])``, ``mempty :: Monoid a => a`` is a hole fit
    with ``mempty @(Int -> [Int])``. This flag toggles whether to show
    ``a ~ (Int -> [Int])`` instead of ``mempty @(Int -> [Int])`` in the where
    clause of the valid hole fit message.

.. ghc-flag:: -fshow-provenance-of-hole-fits
    :shortdesc: Toggles whether to show the provenance of the valid hole fits
       in the output.
    :type: dynamic
    :category: verbosity
    :reverse: -fno-show-provenance-of-hole-fits

    :default: on

    By default, each hole fit shows the provenance information of its
    hole fit, i.e. where it was bound or defined, and what module
    it was originally defined in if it was imported. This can be toggled
    off using the reverse of this flag.


.. ghc-flag:: -funclutter-valid-hole-fits
    :shortdesc: Unclutter the list of valid hole fits by not showing
        provenance nor type applications of suggestions.
    :type: dynamic
    :category: verbosity

    :default: off

    This flag can be toggled to decrease the verbosity of the valid hole fit
    suggestions by not showing the provenance nor type application of the
    suggestions.



.. _typed-holes-refinement-hole-fits:

Refinement Hole Fits
~~~~~~~~~~~~~~~~~~~~~~~~

When the flag :ghc-flag:`-frefinement-level-hole-fits=⟨n⟩` is set to an
``n`` larger than ``0``, GHC will offer up a list of valid refinement
hole fits, which are valid hole fits that need up to ``n`` levels of
additional refinement to be complete, where each level represents an additional
hole in the hole fit that requires filling in.  As an example, consider the
hole in ::

  f :: [Integer] -> Integer
  f = _

When the refinement level is not set, it will only offer valid hole fits
suggestions: ::

  Valid hole fits include
    f :: [Integer] -> Integer
    head :: forall a. [a] -> a
      with head @Integer
    last :: forall a. [a] -> a
      with last @Integer
    maximum :: forall (t :: * -> *).
                Foldable t =>
                forall a. Ord a => t a -> a
      with maximum @[] @Integer
    minimum :: forall (t :: * -> *).
                Foldable t =>
                forall a. Ord a => t a -> a
      with minimum @[] @Integer
    product :: forall (t :: * -> *).
                Foldable t =>
                forall a. Num a => t a -> a
      with product @[] @Integer
    sum :: forall (t :: * -> *).
            Foldable t =>
            forall a. Num a => t a -> a
      with sum @[] @Integer

However, with :ghc-flag:`-frefinement-level-hole-fits=⟨n⟩` set to e.g. `1`,
it will additionally offer up a list of refinement hole fits, in this case: ::

  Valid refinement hole fits include
    foldl1 (_ :: Integer -> Integer -> Integer)
      with foldl1 @[] @Integer
      where foldl1 :: forall (t :: * -> *).
                      Foldable t =>
                      forall a. (a -> a -> a) -> t a -> a
    foldr1 (_ :: Integer -> Integer -> Integer)
      with foldr1 @[] @Integer
      where foldr1 :: forall (t :: * -> *).
                      Foldable t =>
                      forall a. (a -> a -> a) -> t a -> a
    const (_ :: Integer)
      with const @Integer @[Integer]
      where const :: forall a b. a -> b -> a
    ($) (_ :: [Integer] -> Integer)
      with ($) @'GHC.Types.LiftedRep @[Integer] @Integer
      where ($) :: forall a b. (a -> b) -> a -> b
    fail (_ :: String)
      with fail @((->) [Integer]) @Integer
      where fail :: forall (m :: * -> *).
                    Monad m =>
                    forall a. String -> m a
    return (_ :: Integer)
      with return @((->) [Integer]) @Integer
      where return :: forall (m :: * -> *). Monad m => forall a. a -> m a
    (Some refinement hole fits suppressed;
      use -fmax-refinement-hole-fits=N or -fno-max-refinement-hole-fits)

Which shows that the hole could be replaced with e.g. ``foldl1 _``. While not
fixing the hole, this can help users understand what options they have.

.. ghc-flag:: -frefinement-level-hole-fits=⟨n⟩
    :shortdesc: *default: off.* Sets the level of refinement of the
         refinement hole fits, where level ``n`` means that hole fits
         of up to ``n`` holes will be considered.
    :type: dynamic
    :reverse: -fno-refinement-level-hole-fits
    :category: verbosity

    :default: off

    The list of valid refinement hole fits is generated by considering
    hole fits with a varying amount of additional holes. The amount of
    holes in a refinement can be set by this flag. If the flag is set to 0
    or not set at all, no valid refinement hole fits will be suggested.

.. ghc-flag:: -fabstract-refinement-hole-fits
    :shortdesc: *default: off.* Toggles whether refinements where one or more
         of the holes are abstract are reported.
    :type: dynamic
    :reverse: -fno-abstract-refinement-hole-fits
    :category: verbosity

    :default: off

    Valid list of valid refinement hole fits can often grow large when
    the refinement level is ``>= 2``, with holes like ``head _ _`` or
    ``fst _ _``, which are valid refinements, but which are unlikely to be
    relevant since one or more of the holes are still completely open, in that
    neither the type nor kind of those holes are constrained by the proposed
    identifier at all. By default, such holes are not reported. By turning this
    flag on, such holes are included in the list of valid refinement hole fits.

.. ghc-flag:: -fmax-refinement-hole-fits=⟨n⟩
    :shortdesc: *default: 6.* Set the maximum number of refinement hole fits
         for typed holes to display in type error messages.
    :type: dynamic
    :reverse: -fno-max-refinement-hole-fits
    :category: verbosity

    :default: 6

    The list of valid refinement hole fits is limited by displaying up to 6
    hole fits per hole. The number of hole fits shown can be set by this
    flag. Turning the limit off with :ghc-flag:`-fno-max-refinement-hole-fits`
    displays all found hole fits.

.. ghc-flag:: -fshow-hole-matches-of-hole-fits
    :shortdesc: Toggles whether to show the type of the additional holes
       in refinement hole fits.
    :type: dynamic
    :category: verbosity
    :reverse: -fno-show-hole-matches-of-hole-fits

    :default: on

    The types of the additional holes in refinement hole fits are displayed
    in the output, e.g. ``foldl1 (_ :: a -> a -> a)`` is a refinement
    for the hole ``_ :: [a] -> a``. If this flag is toggled off, the output
    will display only ``foldl1 _``, which can be used as a direct replacement
    for the hole, without requiring ``-XScopedTypeVariables``.




Sorting Valid Hole Fits
~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are currently two ways to sort valid hole fits.
Sorting can be toggled with :ghc-flag:`-fsort-valid-hole-fits`

.. ghc-flag:: -fno-sort-valid-hole-fits
    :shortdesc: Disables the sorting of the list of valid hole fits for typed holes
        in type error messages.
    :type: dynamic
    :category: verbosity

    :default: off

    By default the valid hole fits are sorted to show the most relevant
    hole fits at the top of the list of valid hole fits. This can be
    toggled off with this flag.

.. ghc-flag:: -fsort-by-size-hole-fits
    :shortdesc: Sort valid hole fits by size.
    :type: dynamic
    :reverse: -fno-sort-by-size-hole-fits

    :default: on

    Sorts by how big the types the quantified type variables in the type of the
    function would have to be in order to match the type of the hole.


.. ghc-flag:: -fsort-by-subsumption-hole-fits
    :shortdesc: Sort valid hole fits by subsumption.
    :type: dynamic
    :reverse: -fno-sort-by-subsumption-hole-fits

    :default: off

    An alternative sort. Sorts by checking which hole fits subsume other
    hole fits, such that if hole fit a could be used as hole fits for
    hole fit b, then b appears before a in the output. It is more precise than
    the default sort, but also a lot slower, since a subsumption check has to be
    run for each pair of valid hole fits.

.. _partial-type-signatures:

Partial Type Signatures
=======================

.. extension:: PartialTypeSignatures
    :shortdesc: Enable partial type signatures.

    :since: 7.10.1

    Type checker will allow inferred types for holes.

A partial type signature is a type signature containing special
placeholders written with a leading underscore (e.g., "``_``",
"``_foo``", "``_bar``") called *wildcards*. Partial type signatures are
to type signatures what :ref:`typed-holes` are to expressions. During
compilation these wildcards or holes will generate an error message that
describes which type was inferred at the hole's location, and
information about the origin of any free type variables. GHC reports
such error messages by default.

Unlike :ref:`typed-holes`, which make the program incomplete and will
generate errors when they are evaluated, this needn't be the case for
holes in type signatures. The type checker is capable (in most cases) of
type-checking a binding with or without a type signature. A partial type
signature bridges the gap between the two extremes, the programmer can
choose which parts of a type to annotate and which to leave over to the
type-checker to infer.

By default, the type-checker will report an error message for each hole
in a partial type signature, informing the programmer of the inferred
type. When the :extension:`PartialTypeSignatures` extension is enabled, the
type-checker will accept the inferred type for each hole, generating
warnings instead of errors. Additionally, these warnings can be silenced
with the :ghc-flag:`-Wno-partial-type-signatures <-Wpartial-type-signatures>`
flag.

However, because GHC must *infer* the type when part of a type is left
out, it is unable to use polymorphic recursion. The same restriction
takes place when the type signature is omitted completely.

.. _pts-syntax:

Syntax
------

A (partial) type signature has the following form:
``forall a b .. . (C1, C2, ..) => tau``. It consists of three parts:

-  The type variables:
   ``a b ..``
-  The constraints:
   ``(C1, C2, ..)``
-  The (mono)type:
   ``tau``

We distinguish three kinds of wildcards.

.. _type-wildcards:

Type Wildcards
~~~~~~~~~~~~~~

Wildcards occurring within the monotype (tau) part of the type signature
are *type wildcards* ("type" is often omitted as this is the default
kind of wildcard). Type wildcards can be instantiated to any monotype
like ``Bool`` or ``Maybe [Bool]``, including functions and higher-kinded
types like ``(Int -> Bool)`` or ``Maybe``.

::

    not' :: Bool -> _
    not' x = not x
    -- Inferred: Bool -> Bool

    maybools :: _
    maybools = Just [True]
    -- Inferred: Maybe [Bool]

    just1 :: _ Int
    just1 = Just 1
    -- Inferred: Maybe Int

    filterInt :: _ -> _ -> [Int]
    filterInt = filter -- has type forall a. (a -> Bool) -> [a] -> [a]
    -- Inferred: (Int -> Bool) -> [Int] -> [Int]

For instance, the first wildcard in the type signature ``not'`` would
produce the following error message:

.. code-block:: none

    Test.hs:4:17: error:
        • Found type wildcard ‘_’ standing for ‘Bool’
          To use the inferred type, enable PartialTypeSignatures
        • In the type signature:
            not' :: Bool -> _
        • Relevant bindings include
            not' :: Bool -> Bool (bound at Test.hs:5:1)


When a wildcard is not instantiated to a monotype, it will be
generalised over, i.e. replaced by a fresh type variable, e.g.

::

    foo :: _ -> _
    foo x = x
    -- Inferred: forall t. t -> t

    filter' :: _
    filter' = filter -- has type forall a. (a -> Bool) -> [a] -> [a]
    -- Inferred: (a -> Bool) -> [a] -> [a]

.. _named-wildcards:

Named Wildcards
~~~~~~~~~~~~~~~

.. extension:: NamedWildCards
    :shortdesc: Enable named wildcards.

    :since: 7.10.1

    Allow naming of wildcards (e.g. ``_x``) in type signatures.

Type wildcards can also be named by giving the underscore an identifier
as suffix, i.e. ``_a``. These are called *named wildcards*. All
occurrences of the same named wildcard within one type signature will
unify to the same type. For example: ::

    f :: _x -> _x
    f ('c', y) = ('d', error "Urk")
    -- Inferred: forall t. (Char, t) -> (Char, t)

The named wildcard forces the argument and result types to be the same.
Lacking a signature, GHC would have inferred
``forall a b. (Char, a) -> (Char, b)``. A named wildcard can be
mentioned in constraints, provided it also occurs in the monotype part
of the type signature to make sure that it unifies with something: ::

    somethingShowable :: Show _x => _x -> _
    somethingShowable x = show x
    -- Inferred type: Show a => a -> String

    somethingShowable' :: Show _x => _x -> _
    somethingShowable' x = show (not x)
    -- Inferred type: Bool -> String

Besides an extra-constraints wildcard (see
:ref:`extra-constraints-wildcard`), only named wildcards can occur in
the constraints, e.g. the ``_x`` in ``Show _x``.

Named wildcards *should not be confused with type variables*. Even
though syntactically similar, named wildcards can unify with monotypes
as well as be generalised over (and behave as type variables).

In the first example above, ``_x`` is generalised over (and is
effectively replaced by a fresh type variable ``a``). In the second
example, ``_x`` is unified with the ``Bool`` type, and as ``Bool``
implements the ``Show`` type class, the constraint ``Show Bool`` can be
simplified away.

By default, GHC (as the Haskell 2010 standard prescribes) parses
identifiers starting with an underscore in a type as type variables. To
treat them as named wildcards, the :extension:`NamedWildCards` extension should be
enabled. The example below demonstrated the effect. ::

    foo :: _a -> _a
    foo _ = False

Compiling this program without enabling :extension:`NamedWildCards` produces
the following error message complaining about the type variable ``_a``
no matching the actual type ``Bool``.

.. code-block:: none

    Test.hs:5:9: error:
        • Couldn't match expected type ‘_a’ with actual type ‘Bool’
          ‘_a’ is a rigid type variable bound by
            the type signature for:
              foo :: forall _a. _a -> _a
            at Test.hs:4:8
        • In the expression: False
          In an equation for ‘foo’: foo _ = False
        • Relevant bindings include foo :: _a -> _a (bound at Test.hs:5:1)

Compiling this program with :extension:`NamedWildCards` (as well as
:extension:`PartialTypeSignatures`) enabled produces the following error
message reporting the inferred type of the named wildcard ``_a``.

.. code-block:: none

    Test.hs:4:8: warning: [-Wpartial-type-signatures]
        • Found type wildcard ‘_a’ standing for ‘Bool’
        • In the type signature:
            foo :: _a -> _a
        • Relevant bindings include
            foo :: Bool -> Bool (bound at Test.hs:5:1)


.. _extra-constraints-wildcard:

Extra-Constraints Wildcard
~~~~~~~~~~~~~~~~~~~~~~~~~~

The third kind of wildcard is the *extra-constraints wildcard*. The
presence of an extra-constraints wildcard indicates that an arbitrary
number of extra constraints may be inferred during type checking and
will be added to the type signature. In the example below, the
extra-constraints wildcard is used to infer three extra constraints.

::

    arbitCs :: _ => a -> String
    arbitCs x = show (succ x) ++ show (x == x)
    -- Inferred:
    --   forall a. (Enum a, Eq a, Show a) => a -> String
    -- Error:
    Test.hs:5:12: error:
        Found constraint wildcard ‘_’ standing for ‘(Show a, Eq a, Enum a)’
        To use the inferred type, enable PartialTypeSignatures
        In the type signature:
          arbitCs :: _ => a -> String

An extra-constraints wildcard shouldn't prevent the programmer from
already listing the constraints he knows or wants to annotate, e.g.

::

    -- Also a correct partial type signature:
    arbitCs' :: (Enum a, _) => a -> String
    arbitCs' x = arbitCs x
    -- Inferred:
    --   forall a. (Enum a, Show a, Eq a) => a -> String
    -- Error:
    Test.hs:9:22: error:
        Found constraint wildcard ‘_’ standing for ‘()’
        To use the inferred type, enable PartialTypeSignatures
        In the type signature:
          arbitCs' :: (Enum a, _) => a -> String

An extra-constraints wildcard can also lead to zero extra constraints to
be inferred, e.g.

::

    noCs :: _ => String
    noCs = "noCs"
    -- Inferred: String
    -- Error:
    Test.hs:13:9: error:
        Found constraint wildcard ‘_’ standing for ‘()’
        To use the inferred type, enable PartialTypeSignatures
        In the type signature:
          noCs :: _ => String

As a single extra-constraints wildcard is enough to infer any number of
constraints, only one is allowed in a type signature and it should come
last in the list of constraints.

Extra-constraints wildcards cannot be named.

.. _pts-where:

Where can they occur?
---------------------

Partial type signatures are allowed for bindings, pattern and expression
signatures, except that extra-constraints
wildcards are not supported in pattern or expression signatures.
In the following example a wildcard is used in each of the three possible contexts.
::

    {-# LANGUAGE ScopedTypeVariables #-}
    foo :: _
    foo (x :: _) = (x :: _)
    -- Inferred: forall w_. w_ -> w_

Anonymous and named wildcards *can* occur on the left hand side of a
type or data instance declaration;
see :ref:`type-wildcards-lhs`.

Anonymous wildcards are also allowed in visible type applications/ visible kind
applications (:ref:`visible-type-application`). If you want to specify only the
second type argument to ``wurble``, then you can say ``wurble @_ @Int`` where
the first argument is a wildcard.

Standalone ``deriving`` declarations permit the use of a single,
extra-constraints wildcard, like so: ::

   deriving instance _ => Eq (Foo a)

This denotes a derived ``Eq (Foo a)`` instance where the context is inferred,
in much the same way that ordinary ``deriving`` clauses do. Any other use of
wildcards in a standalone ``deriving`` declaration is prohibited.

In all other contexts, type wildcards are disallowed, and a named wildcard is treated
as an ordinary type variable.  For example: ::

   class C _ where ...          -- Illegal
   instance Eq (T _)            -- Illegal (currently; would actually make sense)
   instance Eq _a => Eq (T _a)  -- Perfectly fine, same as  Eq a => Eq (T a)

Partial type signatures can also be used in :ref:`template-haskell`
splices.

-  Declaration splices: partial type signature are fully supported.
   ::

       {-# LANGUAGE TemplateHaskell, NamedWildCards #-}
       $( [d| foo :: _ => _a -> _a -> _
              foo x y = x == y|] )

-  Expression splices: anonymous and named wildcards can be used in
   expression signatures. Extra-constraints wildcards are not supported,
   just like in regular expression signatures.
   ::

       {-# LANGUAGE TemplateHaskell, NamedWildCards #-}
       $( [e| foo = (Just True :: _m _) |] )

-  Typed expression splices: the same wildcards as in (untyped)
   expression splices are supported.

-  Pattern splices: anonymous and named wildcards can be used in pattern
   signatures. Note that :extension:`ScopedTypeVariables` has to be enabled
   to allow pattern signatures. Extra-constraints wildcards are not supported,
   just like in regular pattern signatures.
   ::

       {-# LANGUAGE TemplateHaskell, ScopedTypeVariables #-}
       foo $( [p| (x :: _) |] ) = x

-  Type splices: only anonymous wildcards are supported in type splices.
   Named and extra-constraints wildcards are not. ::

       {-# LANGUAGE TemplateHaskell #-}
       foo :: $( [t| _ |] ) -> a
       foo x = x

.. _custom-errors:

Custom compile-time errors
==========================

When designing embedded domain specific languages in Haskell, it is useful to
have something like ``error`` at the type level. In this way, the EDSL designer
may show a type error that is specific to the DSL, rather than the standard GHC
type error.

For example, consider a type class that is not intended to be used with
functions, but the user accidentally used it at a function type, perhaps
because they missed an argument to some function. Then, instead of getting the
standard GHC message about a missing instance, it would be nicer to emit a more
friendly message specific to the EDSL. Similarly, the reduction of a type-level
function may get stuck due to an error, at which point it would be nice to
report an EDSL specific error, rather than a generic error about an ambiguous
type.

To solve this, GHC provides a single type-level function, ::

    type family TypeError (msg :: ErrorMessage) :: k

along with a small type-level language (via :extension:`DataKinds`)
for constructing pretty-printed error messages, ::

    -- ErrorMessage is intended to be used as a kind
    data ErrorMessage =
          Text Symbol                        -- Show this text as is
        | forall t. ShowType t               -- Pretty print a type
        | ErrorMessage :<>: ErrorMessage     -- Put two chunks of error message next to each other
        | ErrorMessage :$$: ErrorMessage     -- Put two chunks of error message above each other

in the :base-ref:`GHC.TypeLits.` module.

For instance, we might use this interface to provide a more useful error
message for applications of ``show`` on unsaturated functions like this, ::

    {-# LANGUAGE DataKinds #-}
    {-# LANGUAGE TypeOperators #-}
    {-# LANGUAGE UndecidableInstances #-}

    import GHC.TypeLits

    instance TypeError (Text "Cannot 'Show' functions." :$$:
                        Text "Perhaps there is a missing argument?")
             => Show (a -> b) where
       showsPrec = error "unreachable"

    main = print negate

Which will produce the following compile-time error,

.. code-block:: none

    Test.hs:12:8: error:
        • Cannot 'Show' functions.
          Perhaps there is a missing argument?
        • In the expression: print negate
          In an equation for ‘main’: main = print negate


.. _defer-type-errors:

Deferring type errors to runtime
================================

While developing, sometimes it is desirable to allow compilation to
succeed even if there are type errors in the code. Consider the
following case: ::

    module Main where

    a :: Int
    a = 'a'

    main = print "b"

Even though ``a`` is ill-typed, it is not used in the end, so if all
that we're interested in is ``main`` it can be useful to be able to
ignore the problems in ``a``.

For more motivation and details please refer to the
:ghc-wiki:`Wiki <defer-errors-to-runtime>` page or the `original
paper <http://dreixel.net/research/pdf/epdtecp.pdf>`__.

Enabling deferring of type errors
---------------------------------

The flag :ghc-flag:`-fdefer-type-errors` controls whether type errors are
deferred to runtime. Type errors will still be emitted as warnings, but
will not prevent compilation. You can use :ghc-flag:`-Wno-type-errors
<-Wtype-errors>` to suppress these warnings.

This flag implies the :ghc-flag:`-fdefer-typed-holes` and
:ghc-flag:`-fdefer-out-of-scope-variables` flags, which enables this behaviour
for `typed holes <#typed-holes>`__ and variables. Should you so wish, it is
possible to enable :ghc-flag:`-fdefer-type-errors` without enabling
:ghc-flag:`-fdefer-typed-holes` or :ghc-flag:`-fdefer-out-of-scope-variables`,
by explicitly specifying :ghc-flag:`-fno-defer-typed-holes
<-fdefer-typed-holes>` or :ghc-flag:`-fno-defer-out-of-scope-variables
<-fdefer-out-of-scope-variables>` on the command-line after the
:ghc-flag:`-fdefer-type-errors` flag.

At runtime, whenever a term containing a type error would need to be
evaluated, the error is converted into a runtime exception of type
``TypeError``. Note that type errors are deferred as much as possible
during runtime, but invalid coercions are never performed, even when
they would ultimately result in a value of the correct type. For
example, given the following code: ::

    x :: Int
    x = 0

    y :: Char
    y = x

    z :: Int
    z = y

evaluating ``z`` will result in a runtime ``TypeError``.

Deferred type errors in GHCi
----------------------------

The flag :ghc-flag:`-fdefer-type-errors` works in GHCi as well, with one
exception: for "naked" expressions typed at the prompt, type errors
don't get delayed, so for example: ::

    Prelude> fst (True, 1 == 'a')

    <interactive>:2:12:
        No instance for (Num Char) arising from the literal `1'
        Possible fix: add an instance declaration for (Num Char)
        In the first argument of `(==)', namely `1'
        In the expression: 1 == 'a'
        In the first argument of `fst', namely `(True, 1 == 'a')'

Otherwise, in the common case of a simple type error such as typing
``reverse True`` at the prompt, you would get a warning and then an
immediately-following type error when the expression is evaluated.

This exception doesn't apply to statements, as the following example
demonstrates:

.. code-block:: none

    Prelude> let x = (True, 1 == 'a')

    <interactive>:3:16: Warning:
        No instance for (Num Char) arising from the literal `1'
        Possible fix: add an instance declaration for (Num Char)
        In the first argument of `(==)', namely `1'
        In the expression: 1 == 'a'
        In the expression: (True, 1 == 'a')
    Prelude> fst x
    True

Limitations of deferred type errors
-----------------------------------
The errors that can be deferred are:

- Out of scope term variables
- Equality constraints; e.g. `ord True` gives rise to an insoluble equality constraint `Char ~ Bool`, which can be deferred.
- Type-class and implicit-parameter constraints

All other type errors are reported immediately, and cannot be deferred; for
example, an ill-kinded type signature, an instance declaration that is
non-terminating or ill-formed, a type-family instance that does not
obey the declared injectivity constraints, etc etc.

In a few cases, even equality constraints cannot be deferred.  Specifically:

- Kind-equalities cannot be deferred, e.g. ::

    f :: Int Bool -> Char

  This type signature contains a kind error which cannot be deferred.

- Type equalities under a forall cannot be deferred (c.f. #14605).

.. _template-haskell:

Template Haskell
================

Template Haskell allows you to do compile-time meta-programming in
Haskell. The background to the main technical innovations is discussed
in "`Template Meta-programming for
Haskell <http://research.microsoft.com/~simonpj/papers/meta-haskell/>`__"
(Proc Haskell Workshop 2002).

The `Template Haskell <http://www.haskell.org/haskellwiki/Template_Haskell>`__
page on the GHC Wiki has a wealth of information. You may also consult the
:th-ref:`Haddock reference documentation <Language.Haskell.TH.>`.
Many changes to the original
design are described in `Notes on Template Haskell version
2 <https://www.haskell.org/ghc/docs/papers/th2.ps>`__.
Not all of these changes are in GHC, however.

The first example from that paper is set out below (:ref:`th-example`)
as a worked example to help get you started.

The documentation here describes the realisation of Template Haskell in
GHC. It is not detailed enough to understand Template Haskell; see the
`Wiki page <http://haskell.org/haskellwiki/Template_Haskell>`__.

.. _th-syntax:

Syntax
------

.. extension:: TemplateHaskell
    :shortdesc: Enable Template Haskell.

    :implies: :extension:`TemplateHaskellQuotes`
    :since: 6.0. Typed splices introduced in GHC 7.8.1.

    Enable Template Haskell's splice and quotation syntax.

.. extension:: TemplateHaskellQuotes
    :shortdesc: Enable quotation subset of
        :ref:`Template Haskell <template-haskell>`.

    :since: 8.0.1

    Enable only Template Haskell's quotation syntax.

Template Haskell has the following new syntactic constructions. You need to use
the extension :extension:`TemplateHaskell` to switch these syntactic extensions on.
Alternatively, the :extension:`TemplateHaskellQuotes` extension can be used to
enable the quotation subset of Template Haskell (i.e. without splice syntax).
The :extension:`TemplateHaskellQuotes` extension is considered safe under
:ref:`safe-haskell` while :extension:`TemplateHaskell` is not.

-  A splice is written ``$x``, where ``x`` is an identifier, or
   ``$(...)``, where the "..." is an arbitrary expression. There must be
   no space between the "$" and the identifier or parenthesis. This use
   of "$" overrides its meaning as an infix operator, just as "M.x"
   overrides the meaning of "." as an infix operator. If you want the
   infix operator, put spaces around it.

   A splice can occur in place of

   -  an expression; the spliced expression must have type ``Q Exp``

   -  a pattern; the spliced pattern must have type ``Q Pat``

   -  a type; the spliced expression must have type ``Q Type``

   -  a list of declarations at top level; the spliced expression must
      have type ``Q [Dec]``

   Inside a splice you can only call functions defined in imported
   modules, not functions defined elsewhere in the same module. Note
   that declaration splices are not allowed anywhere except at top level
   (outside any other declarations).

-  A expression quotation is written in Oxford brackets, thus:

   -  ``[| ... |]``, or ``[e| ... |]``, where the "..." is an
      expression; the quotation has type ``Q Exp``.

   -  ``[d| ... |]``, where the "..." is a list of top-level
      declarations; the quotation has type ``Q [Dec]``.

   -  ``[t| ... |]``, where the "..." is a type; the quotation has type
      ``Q Type``.

   -  ``[p| ... |]``, where the "..." is a pattern; the quotation has
      type ``Q Pat``.

   See :ref:`pts-where` for using partial type signatures in quotations.

-  A *typed* expression splice is written ``$$x``, where ``x`` is an
   identifier, or ``$$(...)``, where the "..." is an arbitrary
   expression.

   A typed expression splice can occur in place of an expression; the
   spliced expression must have type ``Q (TExp a)``

-  A *typed* expression quotation is written as ``[|| ... ||]``, or
   ``[e|| ... ||]``, where the "..." is an expression; if the "..."
   expression has type ``a``, then the quotation has type
   ``Q (TExp a)``.

   Values of type ``TExp a`` may be converted to values of type ``Exp``
   using the function ``unType :: TExp a -> Exp``.

-  A quasi-quotation can appear in a pattern, type, expression, or
   declaration context and is also written in Oxford brackets:

   -  ``[varid| ... |]``, where the "..." is an arbitrary string; a full
      description of the quasi-quotation facility is given in
      :ref:`th-quasiquotation`.

-  A name can be quoted with either one or two prefix single quotes:

   -  ``'f`` has type ``Name``, and names the function ``f``. Similarly
      ``'C`` has type ``Name`` and names the data constructor ``C``. In
      general ``'``\ ⟨thing⟩ interprets ⟨thing⟩ in an expression
      context.

      A name whose second character is a single quote (sadly) cannot be
      quoted in this way, because it will be parsed instead as a quoted
      character. For example, if the function is called ``f'7`` (which
      is a legal Haskell identifier), an attempt to quote it as ``'f'7``
      would be parsed as the character literal ``'f'`` followed by the
      numeric literal ``7``. There is no current escape mechanism in
      this (unusual) situation.

   -  ``''T`` has type ``Name``, and names the type constructor ``T``.
      That is, ``''``\ ⟨thing⟩ interprets ⟨thing⟩ in a type context.

   These ``Names`` can be used to construct Template Haskell
   expressions, patterns, declarations etc. They may also be given as an
   argument to the ``reify`` function.

-  It is possible for a splice to expand to an expression that contain
   names which are not in scope at the site of the splice. As an
   example, consider the following code: ::

       module Bar where

       import Language.Haskell.TH

       add1 :: Int -> Q Exp
       add1 x = [| x + 1 |]

   Now consider a splice using ``add1`` in a separate
   module: ::

       module Foo where

       import Bar

       two :: Int
       two = $(add1 1)

   Template Haskell cannot know what the argument to ``add1`` will be at the
   function's definition site, so a lifting mechanism is used to promote
   ``x`` into a value of type ``Q Exp``. This functionality is exposed to the
   user as the ``Lift`` typeclass in the ``Language.Haskell.TH.Syntax``
   module. If a type has a ``Lift`` instance, then any of its values can be
   lifted to a Template Haskell expression: ::

       class Lift t where
           lift :: t -> Q Exp

   In general, if GHC sees an expression within Oxford brackets (e.g., ``[|
   foo bar |]``, then GHC looks up each name within the brackets. If a name
   is global (e.g., suppose ``foo`` comes from an import or a top-level
   declaration), then the fully qualified name is used directly in the
   quotation. If the name is local (e.g., suppose ``bar`` is bound locally in
   the function definition ``mkFoo bar = [| foo bar |]``), then GHC uses
   ``lift`` on it (so GHC pretends ``[| foo bar |]`` actually contains ``[|
   foo $(lift bar) |]``). Local names, which are not in scope at splice
   locations, are actually evaluated when the quotation is processed.

   The ``template-haskell`` library provides ``Lift`` instances for many
   common data types. Furthermore, it is possible to derive ``Lift``
   instances automatically by using the :extension:`DeriveLift` language extension.
   See :ref:`deriving-lift` for more information.

-  You may omit the ``$(...)`` in a top-level declaration splice. Simply
   writing an expression (rather than a declaration) implies a splice.
   For example, you can write ::

       module Foo where
       import Bar

       f x = x

       $(deriveStuff 'f)   -- Uses the $(...) notation

       g y = y+1

       deriveStuff 'g      -- Omits the $(...)

       h z = z-1

   This abbreviation makes top-level declaration slices quieter and less
   intimidating.

-  Pattern splices introduce variable binders but scoping of variables in
   expressions inside the pattern's scope is only checked when a splice is
   run.  Note that pattern splices that occur outside of any quotation
   brackets are run at compile time.  Pattern splices occurring inside a
   quotation bracket are *not* run at compile time; they are run when the
   bracket is spliced in, sometime later.  For example, ::

       mkPat :: Q Pat
       mkPat = [p| (x, y) |]

       -- in another module:
       foo :: (Char, String) -> String
       foo $(mkPat) = x : z

       bar :: Q Exp
       bar = [| \ $(mkPat) -> x : w |]

   will fail with ``z`` being out of scope in the definition of ``foo`` but it
   will *not* fail with ``w`` being out of scope in the definition of ``bar``.
   That will only happen when ``bar`` is spliced.

-  A pattern quasiquoter *may* generate binders that scope over the
   right-hand side of a definition because these binders are in scope
   lexically. For example, given a quasiquoter ``haskell`` that parses
   Haskell, in the following code, the ``y`` in the right-hand side of
   ``f`` refers to the ``y`` bound by the ``haskell`` pattern
   quasiquoter, *not* the top-level ``y = 7``. ::

       y :: Int
       y = 7

       f :: Int -> Int -> Int
       f n = \ [haskell|y|] -> y+n

-  Top-level declaration splices break up a source file into
   *declaration groups*. A *declaration group* is the group of
   declarations created by a top-level declaration splice, plus those
   following it, down to but not including the next top-level
   declaration splice. N.B. only top-level splices delimit declaration
   groups, not expression splices. The first declaration group in a module
   includes all top-level definitions down to but not including the first
   top-level declaration splice.

   Each declaration group is mutually recursive only within the group.
   Declaration groups can refer to definitions within previous groups,
   but not later ones.

   Accordingly, the type environment seen by ``reify`` includes all the
   top-level declarations up to the end of the immediately preceding
   declaration group, but no more.

   Unlike normal declaration splices, declaration quasiquoters do not
   cause a break. These quasiquoters are expanded before the rest of the
   declaration group is processed, and the declarations they generate
   are merged into the surrounding declaration group. Consequently, the
   type environment seen by ``reify`` from a declaration quasiquoter
   will not include anything from the quasiquoter's declaration group.

   Concretely, consider the following code ::

       module M where

       import ...

       f x = x

       $(th1 4)

       h y = k y y $(blah1)

       [qq|blah|]

       k x y z = x + y + z

       $(th2 10)

       w z = $(blah2)

   In this example, a ``reify`` inside...

   1. The splice ``$(th1 ...)`` would see the definition of ``f`` - the
      splice is top-level and thus all definitions in the previous
      declaration group are visible (that is, all definitions in the module
      up-to, but not including, the splice itself).

   2. The splice ``$(blah1)`` cannot refer to the function ``w`` - ``w`` is
      part of a later declaration group, and thus invisible, similarly,
      ``$(blah1)`` cannot see the definition of ``h`` (since it is part of
      the same declaration group as ``$(blah1)``. However, the splice
      ``$(blah1)`` can see the definition of ``f`` (since it is in the
      immediately preceding declaration group).

   3. The splice ``$(th2 ...)`` would see the definition of ``f``, all the
      bindings created by ``$(th1 ...)``, the definition of ``h`` and all
      bindings created by ``[qq|blah|]`` (they are all in previous
      declaration groups).

   4. The body of ``h`` *can* refer to the function ``k`` appearing on the
      other side of the declaration quasiquoter, as quasiquoters do not
      cause a declaration group to be broken up.

   5. The ``qq`` quasiquoter would be able to see the definition of ``f``
      from the preceding declaration group, but not the definitions of
      ``h`` or ``k``, or any definitions from subsequent declaration
      groups.

   6. The splice ``$(blah2)`` would see the same definitions as the splice
      ``$(th2 ...)`` (but *not* any bindings it creates).

   Note that since an expression splice is unable to refer to declarations
   in the same declaration group, we can introduce a top-level (empty)
   splice to break up the declaration group ::

       module M where

       data D = C1 | C2

       f1 = $(th1 ...)

       $(return [])

       f2 = $(th2 ...)

   Here

   1. The splice ``$(th1 ...)`` *cannot* refer to ``D`` - it is in the same
      declaration group.
   2. The declaration group containing ``D`` is terminated by the empty
      top-level declaration splice ``$(return [])`` (recall, ``Q`` is a
      Monad, so we may simply ``return`` the empty list of declarations).
   3. Since the declaration group containing ``D`` is in the previous
      declaration group, the splice ``$(th2 ...)`` *can* refer to ``D``.

-  Expression quotations accept most Haskell language constructs.
   However, there are some GHC-specific extensions which expression
   quotations currently do not support, including

   -  Recursive ``do``-statements (see :ghc-ticket:`1262`)

   -  Type holes in typed splices (see :ghc-ticket:`10945` and
      :ghc-ticket:`10946`)

(Compared to the original paper, there are many differences of detail.
The syntax for a declaration splice uses "``$``" not "``splice``". The type of
the enclosed expression must be ``Q [Dec]``, not ``[Q Dec]``. Typed expression
splices and quotations are supported.)

.. _th-usage:

Using Template Haskell
----------------------

-  The data types and monadic constructor functions for Template Haskell
   are in the library ``Language.Haskell.TH.Syntax``.

-  You can only run a function at compile time if it is imported from
   another module. That is, you can't define a function in a module, and
   call it from within a splice in the same module. (It would make sense
   to do so, but it's hard to implement.)

-  You can only run a function at compile time if it is imported from
   another module *that is not part of a mutually-recursive group of
   modules that includes the module currently being compiled*.
   Furthermore, all of the modules of the mutually-recursive group must
   be reachable by non-SOURCE imports from the module where the splice
   is to be run.

   For example, when compiling module A, you can only run Template
   Haskell functions imported from B if B does not import A (directly or
   indirectly). The reason should be clear: to run B we must compile and
   run A, but we are currently type-checking A.

-  If you are building GHC from source, you need at least a stage-2
   bootstrap compiler to run Template Haskell splices and quasi-quotes.
   A stage-1 compiler will only accept regular quotes of Haskell.
   Reason: TH splices and quasi-quotes compile and run a program, and
   then looks at the result. So it's important that the program it
   compiles produces results whose representations are identical to
   those of the compiler itself.

Template Haskell works in any mode (:ghc-flag:`--make`,
:ghc-flag:`--interactive`, or file-at-a-time). There used to be a restriction to
the former two, but that restriction has been lifted.

.. _th-view-gen-code:

Viewing Template Haskell generated code
---------------------------------------

The flag :ghc-flag:`-ddump-splices` shows the expansion of all top-level
declaration splices, both typed and untyped, as they happen. As with all
dump flags, the default is for this output to be sent to stdout. For a
non-trivial program, you may be interested in combining this with the
:ghc-flag:`-ddump-to-file` flag (see :ref:`dumping-output`. For each file using
Template Haskell, this will show the output in a ``.dump-splices`` file.

The flag :ghc-flag:`-dth-dec-file` dumps the expansions of all top-level
TH declaration splices, both typed and untyped, in the file :file:`M.th.hs`
for each module `M` being compiled. Note that other types of
splices (expressions, types, and patterns) are not shown. Application
developers can check this into their repository so that they can grep for
identifiers that were defined in Template Haskell. This is similar to using
:ghc-flag:`-ddump-to-file` with :ghc-flag:`-ddump-splices` but it always
generates a file instead of being coupled to :ghc-flag:`-ddump-to-file`. The
format is also different: it does not show code from the original file, instead
it only shows generated code and has a comment for the splice location of the
original file.

Below is a sample output of :ghc-flag:`-ddump-splices` ::

    TH_pragma.hs:(6,4)-(8,26): Splicing declarations
      [d| foo :: Int -> Int
          foo x = x + 1 |]
    ======>
      foo :: Int -> Int
      foo x = (x + 1)

Below is the output of the same sample using :ghc-flag:`-dth-dec-file` ::

    -- TH_pragma.hs:(6,4)-(8,26): Splicing declarations
    foo :: Int -> Int
    foo x = (x + 1)

.. _th-example:

A Template Haskell Worked Example
---------------------------------

To help you get over the confidence barrier, try out this skeletal
worked example. First cut and paste the two modules below into :file:`Main.hs`
and :file:`Printf.hs`:

::


    {- Main.hs -}
    module Main where

    -- Import our template "pr"
    import Printf ( pr )

    -- The splice operator $ takes the Haskell source code
    -- generated at compile time by "pr" and splices it into
    -- the argument of "putStrLn".
    main = putStrLn ( $(pr "Hello") )


    {- Printf.hs -}
    module Printf where

    -- Skeletal printf from the paper.
    -- It needs to be in a separate module to the one where
    -- you intend to use it.

    -- Import some Template Haskell syntax
    import Language.Haskell.TH

    -- Describe a format string
    data Format = D | S | L String

    -- Parse a format string.  This is left largely to you
    -- as we are here interested in building our first ever
    -- Template Haskell program and not in building printf.
    parse :: String -> [Format]
    parse s   = [ L s ]

    -- Generate Haskell source code from a parsed representation
    -- of the format string.  This code will be spliced into
    -- the module which calls "pr", at compile time.
    gen :: [Format] -> Q Exp
    gen [D]   = [| \n -> show n |]
    gen [S]   = [| \s -> s |]
    gen [L s] = stringE s

    -- Here we generate the Haskell code for the splice
    -- from an input format string.
    pr :: String -> Q Exp
    pr s = gen (parse s)

Now run the compiler,

.. code-block:: none

    $ ghc --make -XTemplateHaskell main.hs -o main

Run :file:`main` and here is your output:

.. code-block:: none

    $ ./main
    Hello

.. _th-profiling:

Using Template Haskell with Profiling
-------------------------------------

.. index::
   single: profiling; with Template Haskell

Template Haskell relies on GHC's built-in bytecode compiler and
interpreter to run the splice expressions. The bytecode interpreter runs
the compiled expression on top of the same runtime on which GHC itself
is running; this means that the compiled code referred to by the
interpreted expression must be compatible with this runtime, and in
particular this means that object code that is compiled for profiling
*cannot* be loaded and used by a splice expression, because profiled
object code is only compatible with the profiling version of the
runtime.

This causes difficulties if you have a multi-module program containing
Template Haskell code and you need to compile it for profiling, because
GHC cannot load the profiled object code and use it when executing the
splices.

Fortunately GHC provides two workarounds.

The first option is to compile the program twice:

1. Compile the program or library first the normal way, without
   :ghc-flag:`-prof`.

2. Then compile it again with :ghc-flag:`-prof`, and additionally use ``-osuf
   p_o`` to name the object files differently (you can choose any suffix that
   isn't the normal object suffix here). GHC will automatically load the object
   files built in the first step when executing splice expressions. If you omit
   the :ghc-flag:`-osuf ⟨suffix⟩` flag when building with :ghc-flag:`-prof` and
   Template Haskell is used, GHC will emit an error message.

   .. index::
      single : -osuf; using with profiling

The second option is to add the flag :ghc-flag:`-fexternal-interpreter` (see
:ref:`external-interpreter`), which runs the interpreter in a separate
process, wherein it can load and run the profiled code directly.
There's no need to compile the code twice, just add
:ghc-flag:`-fexternal-interpreter` and it should just work.  (this option is
experimental in GHC 8.0.x, but it may become the default in future
releases).

.. _th-quasiquotation:

Template Haskell Quasi-quotation
--------------------------------

.. extension:: QuasiQuotes
    :shortdesc: Enable quasiquotation.

    :since: 6.10.1

    Enable Template Haskell Quasi-quotation syntax.

Quasi-quotation allows patterns and expressions to be written using
programmer-defined concrete syntax; the motivation behind the extension
and several examples are documented in "`Why It's Nice to be Quoted:
Quasiquoting for
Haskell <http://www.cs.tufts.edu/comp/150FP/archive/geoff-mainland/quasiquoting.pdf>`__"
(Proc Haskell Workshop 2007). The example below shows how to write a
quasiquoter for a simple expression language.

Here are the salient features

-  A quasi-quote has the form ``[quoter| string |]``.

   -  The ⟨quoter⟩ must be the name of an imported quoter, either
      qualified or unqualified; it cannot be an arbitrary expression.

   -  The ⟨quoter⟩ cannot be "``e``", "``t``", "``d``", or "``p``",
      since those overlap with Template Haskell quotations.

   -  There must be no spaces in the token ``[quoter|``.

   -  The quoted ⟨string⟩ can be arbitrary, and may contain newlines.

   -  The quoted ⟨string⟩ finishes at the first occurrence of the
      two-character sequence ``"|]"``. Absolutely no escaping is
      performed. If you want to embed that character sequence in the
      string, you must invent your own escape convention (such as, say,
      using the string ``"|~]"`` instead), and make your quoter function
      interpret ``"|~]"`` as ``"|]"``. One way to implement this is to
      compose your quoter with a pre-processing pass to perform your
      escape conversion. See the discussion in :ghc-ticket:`5348` for details.

-  A quasiquote may appear in place of

   -  An expression

   -  A pattern

   -  A type

   -  A top-level declaration

   (Only the first two are described in the paper.)

-  A quoter is a value of type
   ``Language.Haskell.TH.Quote.QuasiQuoter``, which is defined thus: ::

       data QuasiQuoter = QuasiQuoter { quoteExp  :: String -> Q Exp,
                                        quotePat  :: String -> Q Pat,
                                        quoteType :: String -> Q Type,
                                        quoteDec  :: String -> Q [Dec] }

   That is, a quoter is a tuple of four parsers, one for each of the
   contexts in which a quasi-quote can occur.

-  A quasi-quote is expanded by applying the appropriate parser to the
   string enclosed by the Oxford brackets. The context of the
   quasi-quote (expression, pattern, type, declaration) determines which
   of the parsers is called.

-  Unlike normal declaration splices of the form ``$(...)``, declaration
   quasi-quotes do not cause a declaration group break. See
   :ref:`th-syntax` for more information.

.. _quasi-quotes-list-comprehension-ambiguity:

.. warning::

    .. index::
        single: quasi-quotes; ambiguity with list comprehensions
        single: list comprehensions; ambiguity with quasi-quotes

    :extension:`QuasiQuotes` introduces an unfortunate ambiguity with list
    comprehension syntax. Consider the following, ::

        let x = [v| v <- [0..10]]

    Without :extension:`QuasiQuotes` this is parsed as a list comprehension.
    With :extension:`QuasiQuotes` this is parsed as a quasi-quote; however,
    this parse will fail due to the lack of a closing ``|]``. See
    :ghc-ticket:`11679`.

The example below shows quasi-quotation in action. The quoter ``expr``
is bound to a value of type ``QuasiQuoter`` defined in module ``Expr``.
The example makes use of an antiquoted variable ``n``, indicated by the
syntax ``'int:n`` (this syntax for anti-quotation was defined by the
parser's author, *not* by GHC). This binds ``n`` to the integer value
argument of the constructor ``IntExpr`` when pattern matching. Please
see the referenced paper for further details regarding anti-quotation as
well as the description of a technique that uses SYB to leverage a
single parser of type ``String -> a`` to generate both an expression
parser that returns a value of type ``Q Exp`` and a pattern parser that
returns a value of type ``Q Pat``.

Quasiquoters must obey the same stage restrictions as Template Haskell,
e.g., in the example, ``expr`` cannot be defined in ``Main.hs`` where it
is used, but must be imported.

::

    {- ------------- file Main.hs --------------- -}
    module Main where

    import Expr

    main :: IO ()
    main = do { print $ eval [expr|1 + 2|]
              ; case IntExpr 1 of
                  { [expr|'int:n|] -> print n
                  ;  _              -> return ()
                  }
              }


    {- ------------- file Expr.hs --------------- -}
    module Expr where

    import qualified Language.Haskell.TH as TH
    import Language.Haskell.TH.Quote

    data Expr  =  IntExpr Integer
               |  AntiIntExpr String
               |  BinopExpr BinOp Expr Expr
               |  AntiExpr String
        deriving(Show, Typeable, Data)

    data BinOp  =  AddOp
                |  SubOp
                |  MulOp
                |  DivOp
        deriving(Show, Typeable, Data)

    eval :: Expr -> Integer
    eval (IntExpr n)        = n
    eval (BinopExpr op x y) = (opToFun op) (eval x) (eval y)
      where
        opToFun AddOp = (+)
        opToFun SubOp = (-)
        opToFun MulOp = (*)
        opToFun DivOp = div

    expr = QuasiQuoter { quoteExp = parseExprExp, quotePat =  parseExprPat }

    -- Parse an Expr, returning its representation as
    -- either a Q Exp or a Q Pat. See the referenced paper
    -- for how to use SYB to do this by writing a single
    -- parser of type String -> Expr instead of two
    -- separate parsers.

    parseExprExp :: String -> Q Exp
    parseExprExp ...

    parseExprPat :: String -> Q Pat
    parseExprPat ...

Now run the compiler:

.. code-block:: none

    $ ghc --make -XQuasiQuotes Main.hs -o main

Run "main" and here is your output:

.. code-block:: none

    $ ./main
    3
    1

.. _arrow-notation:

Arrow notation
==============

.. extension:: Arrows
    :shortdesc: Enable arrow notation extension

    :since: 6.8.1

    Enable arrow notation.

Arrows are a generalisation of monads introduced by John Hughes. For
more details, see

-  “Generalising Monads to Arrows”, John Hughes, in Science of Computer
   Programming 37, pp. 67–111, May 2000. The paper that introduced arrows:
   a friendly introduction, motivated with programming examples.

-  “\ `A New Notation for
   Arrows <http://www.soi.city.ac.uk/~ross/papers/notation.html>`__\ ”,
   Ross Paterson, in ICFP, Sep 2001. Introduced the notation described
   here.

-  “\ `Arrows and
   Computation <http://www.soi.city.ac.uk/~ross/papers/fop.html>`__\ ”,
   Ross Paterson, in The Fun of Programming, Palgrave, 2003.

-  “\ `Programming with
   Arrows <http://www.cse.chalmers.se/~rjmh/afp-arrows.pdf>`__\ ”, John
   Hughes, in 5th International Summer School on Advanced Functional
   Programming, Lecture Notes in Computer Science vol. 3622, Springer,
   2004. This paper includes another introduction to the notation, with
   practical examples.

-  “\ `Type and Translation Rules for Arrow Notation in
   GHC <http://www.haskell.org/ghc/docs/papers/arrow-rules.pdf>`__\ ”,
   Ross Paterson and Simon Peyton Jones, September 16, 2004. A terse
   enumeration of the formal rules used (extracted from comments in the
   source code).

-  The arrows web page at
   ``http://www.haskell.org/arrows/`` <http://www.haskell.org/arrows/>`__.

With the :extension:`Arrows` extension, GHC supports the arrow notation described in
the second of these papers, translating it using combinators from the
:base-ref:`Control.Arrow.` module.
What follows is a brief introduction to the notation; it won't make much
sense unless you've read Hughes's paper.

The extension adds a new kind of expression for defining arrows:

.. code-block:: none

    exp10 ::= ...
           |  proc apat -> cmd

where ``proc`` is a new keyword. The variables of the pattern are bound
in the body of the ``proc``-expression, which is a new sort of thing
called a command. The syntax of commands is as follows:

.. code-block:: none

    cmd   ::= exp10 -<  exp
           |  exp10 -<< exp
           |  cmd0

with ⟨cmd⟩\ :sup:`0` up to ⟨cmd⟩\ :sup:`9` defined using infix operators
as for expressions, and

.. code-block:: none

    cmd10 ::= \ apat ... apat -> cmd
           |  let decls in cmd
           |  if exp then cmd else cmd
           |  case exp of { calts }
           |  do { cstmt ; ... cstmt ; cmd }
           |  fcmd

    fcmd  ::= fcmd aexp
           |  ( cmd )
           |  (| aexp cmd ... cmd |)

    cstmt ::= let decls
           |  pat <- cmd
           |  rec { cstmt ; ... cstmt [;] }
           |  cmd

where ⟨calts⟩ are like ⟨alts⟩ except that the bodies are commands
instead of expressions.

Commands produce values, but (like monadic computations) may yield more
than one value, or none, and may do other things as well. For the most
part, familiarity with monadic notation is a good guide to using
commands. However the values of expressions, even monadic ones, are
determined by the values of the variables they contain; this is not
necessarily the case for commands.

A simple example of the new notation is the expression ::

    proc x -> f -< x+1

We call this a procedure or arrow abstraction. As with a lambda
expression, the variable ``x`` is a new variable bound within the
``proc``-expression. It refers to the input to the arrow. In the above
example, ``-<`` is not an identifier but a new reserved symbol used for
building commands from an expression of arrow type and an expression to
be fed as input to that arrow. (The weird look will make more sense
later.) It may be read as analogue of application for arrows. The above
example is equivalent to the Haskell expression ::

    arr (\ x -> x+1) >>> f

That would make no sense if the expression to the left of ``-<``
involves the bound variable ``x``. More generally, the expression to the
left of ``-<`` may not involve any local variable, i.e. a variable bound
in the current arrow abstraction. For such a situation there is a
variant ``-<<``, as in ::

    proc x -> f x -<< x+1

which is equivalent to ::

    arr (\ x -> (f x, x+1)) >>> app

so in this case the arrow must belong to the ``ArrowApply`` class. Such
an arrow is equivalent to a monad, so if you're using this form you may
find a monadic formulation more convenient.

do-notation for commands
------------------------

Another form of command is a form of ``do``-notation. For example, you
can write ::

    proc x -> do
            y <- f -< x+1
            g -< 2*y
            let z = x+y
            t <- h -< x*z
            returnA -< t+z

You can read this much like ordinary ``do``-notation, but with commands
in place of monadic expressions. The first line sends the value of
``x+1`` as an input to the arrow ``f``, and matches its output against
``y``. In the next line, the output is discarded. The arrow ``returnA``
is defined in the :base-ref:`Control.Arrow.` module as ``arr id``. The above
example is treated as an abbreviation for ::

    arr (\ x -> (x, x)) >>>
            first (arr (\ x -> x+1) >>> f) >>>
            arr (\ (y, x) -> (y, (x, y))) >>>
            first (arr (\ y -> 2*y) >>> g) >>>
            arr snd >>>
            arr (\ (x, y) -> let z = x+y in ((x, z), z)) >>>
            first (arr (\ (x, z) -> x*z) >>> h) >>>
            arr (\ (t, z) -> t+z) >>>
            returnA

Note that variables not used later in the composition are projected out.
After simplification using rewrite rules (see :ref:`rewrite-rules`)
defined in the :base-ref:`Control.Arrow.` module, this reduces to ::

    arr (\ x -> (x+1, x)) >>>
            first f >>>
            arr (\ (y, x) -> (2*y, (x, y))) >>>
            first g >>>
            arr (\ (_, (x, y)) -> let z = x+y in (x*z, z)) >>>
            first h >>>
            arr (\ (t, z) -> t+z)

which is what you might have written by hand. With arrow notation, GHC
keeps track of all those tuples of variables for you.

Note that although the above translation suggests that ``let``-bound
variables like ``z`` must be monomorphic, the actual translation
produces Core, so polymorphic variables are allowed.

It's also possible to have mutually recursive bindings, using the new
``rec`` keyword, as in the following example: ::

    counter :: ArrowCircuit a => a Bool Int
    counter = proc reset -> do
            rec     output <- returnA -< if reset then 0 else next
                    next <- delay 0 -< output+1
            returnA -< output

The translation of such forms uses the ``loop`` combinator, so the arrow
concerned must belong to the ``ArrowLoop`` class.

Conditional commands
--------------------

In the previous example, we used a conditional expression to construct
the input for an arrow. Sometimes we want to conditionally execute
different commands, as in ::

    proc (x,y) ->
            if f x y
            then g -< x+1
            else h -< y+2

which is translated to ::

    arr (\ (x,y) -> if f x y then Left x else Right y) >>>
            (arr (\x -> x+1) >>> g) ||| (arr (\y -> y+2) >>> h)

Since the translation uses ``|||``, the arrow concerned must belong to
the ``ArrowChoice`` class.

There are also ``case`` commands, like ::

    case input of
        [] -> f -< ()
        [x] -> g -< x+1
        x1:x2:xs -> do
            y <- h -< (x1, x2)
            ys <- k -< xs
            returnA -< y:ys

The syntax is the same as for ``case`` expressions, except that the
bodies of the alternatives are commands rather than expressions. The
translation is similar to that of ``if`` commands.

Defining your own control structures
------------------------------------

As we're seen, arrow notation provides constructs, modelled on those for
expressions, for sequencing, value recursion and conditionals. But
suitable combinators, which you can define in ordinary Haskell, may also
be used to build new commands out of existing ones. The basic idea is
that a command defines an arrow from environments to values. These
environments assign values to the free local variables of the command.
Thus combinators that produce arrows from arrows may also be used to
build commands from commands. For example, the ``ArrowPlus`` class
includes a combinator ::

    ArrowPlus a => (<+>) :: a b c -> a b c -> a b c

so we can use it to build commands: ::

    expr' = proc x -> do
                    returnA -< x
            <+> do
                    symbol Plus -< ()
                    y <- term -< ()
                    expr' -< x + y
            <+> do
                    symbol Minus -< ()
                    y <- term -< ()
                    expr' -< x - y

(The ``do`` on the first line is needed to prevent the first ``<+> ...``
from being interpreted as part of the expression on the previous line.)
This is equivalent to ::

    expr' = (proc x -> returnA -< x)
            <+> (proc x -> do
                    symbol Plus -< ()
                    y <- term -< ()
                    expr' -< x + y)
            <+> (proc x -> do
                    symbol Minus -< ()
                    y <- term -< ()
                    expr' -< x - y)

We are actually using ``<+>`` here with the more specific type ::

    ArrowPlus a => (<+>) :: a (e,()) c -> a (e,()) c -> a (e,()) c

It is essential that this operator be polymorphic in ``e`` (representing
the environment input to the command and thence to its subcommands) and
satisfy the corresponding naturality property ::

    arr (first k) >>> (f <+> g) = (arr (first k) >>> f) <+> (arr (first k) >>> g)

at least for strict ``k``. (This should be automatic if you're not using
``seq``.) This ensures that environments seen by the subcommands are
environments of the whole command, and also allows the translation to
safely trim these environments. (The second component of the input pairs
can contain unnamed input values, as described in the next section.) The
operator must also not use any variable defined within the current arrow
abstraction.

We could define our own operator ::

    untilA :: ArrowChoice a => a (e,s) () -> a (e,s) Bool -> a (e,s) ()
    untilA body cond = proc x -> do
            b <- cond -< x
            if b then returnA -< ()
            else do
                    body -< x
                    untilA body cond -< x

and use it in the same way. Of course this infix syntax only makes sense
for binary operators; there is also a more general syntax involving
special brackets: ::

    proc x -> do
            y <- f -< x+1
            (|untilA (increment -< x+y) (within 0.5 -< x)|)

Primitive constructs
--------------------

Some operators will need to pass additional inputs to their subcommands.
For example, in an arrow type supporting exceptions, the operator that
attaches an exception handler will wish to pass the exception that
occurred to the handler. Such an operator might have a type ::

    handleA :: ... => a (e,s) c -> a (e,(Ex,s)) c -> a (e,s) c

where ``Ex`` is the type of exceptions handled. You could then use this
with arrow notation by writing a command ::

    body `handleA` \ ex -> handler

so that if an exception is raised in the command ``body``, the variable
``ex`` is bound to the value of the exception and the command
``handler``, which typically refers to ``ex``, is entered. Though the
syntax here looks like a functional lambda, we are talking about
commands, and something different is going on. The input to the arrow
represented by a command consists of values for the free local variables
in the command, plus a stack of anonymous values. In all the prior
examples, we made no assumptions about this stack. In the second
argument to ``handleA``, the value of the exception has been added to
the stack input to the handler. The command form of lambda merely gives
this value a name.

More concretely, the input to a command consists of a pair of an
environment and a stack. Each value on the stack is paired with the
remainder of the stack, with an empty stack being ``()``. So operators
like ``handleA`` that pass extra inputs to their subcommands can be
designed for use with the notation by placing the values on the stack
paired with the environment in this way. More precisely, the type of
each argument of the operator (and its result) should have the form ::

    a (e, (t1, ... (tn, ())...)) t

where ⟨e⟩ is a polymorphic variable (representing the environment) and
⟨ti⟩ are the types of the values on the stack, with ⟨t1⟩ being the
"top". The polymorphic variable ⟨e⟩ must not occur in ⟨a⟩, ⟨ti⟩ or ⟨t⟩.
However the arrows involved need not be the same. Here are some more
examples of suitable operators: ::

    bracketA :: ... => a (e,s) b -> a (e,(b,s)) c -> a (e,(c,s)) d -> a (e,s) d
    runReader :: ... => a (e,s) c -> a' (e,(State,s)) c
    runState :: ... => a (e,s) c -> a' (e,(State,s)) (c,State)

We can supply the extra input required by commands built with the last
two by applying them to ordinary expressions, as in ::

    proc x -> do
            s <- ...
            (|runReader (do { ... })|) s

which adds ``s`` to the stack of inputs to the command built using
``runReader``.

The command versions of lambda abstraction and application are analogous
to the expression versions. In particular, the beta and eta rules
describe equivalences of commands. These three features (operators,
lambda abstraction and application) are the core of the notation;
everything else can be built using them, though the results would be
somewhat clumsy. For example, we could simulate ``do``\-notation by
defining ::

    bind :: Arrow a => a (e,s) b -> a (e,(b,s)) c -> a (e,s) c
    u `bind` f = returnA &&& u >>> f

    bind_ :: Arrow a => a (e,s) b -> a (e,s) c -> a (e,s) c
    u `bind_` f = u `bind` (arr fst >>> f)

We could simulate ``if`` by defining ::

    cond :: ArrowChoice a => a (e,s) b -> a (e,s) b -> a (e,(Bool,s)) b
    cond f g = arr (\ (e,(b,s)) -> if b then Left (e,s) else Right (e,s)) >>> f ||| g

Differences with the paper
--------------------------

-  Instead of a single form of arrow application (arrow tail) with two
   translations, the implementation provides two forms ``-<``
   (first-order) and ``-<<`` (higher-order).

-  User-defined operators are flagged with banana brackets instead of a
   new ``form`` keyword.

-  In the paper and the previous implementation, values on the stack
   were paired to the right of the environment in a single argument, but
   now the environment and stack are separate arguments.

Portability
-----------

Although only GHC implements arrow notation directly, there is also a
preprocessor (available from the `arrows web
page <http://www.haskell.org/arrows/>`__) that translates arrow notation
into Haskell 98 for use with other Haskell systems. You would still want
to check arrow programs with GHC; tracing type errors in the
preprocessor output is not easy. Modules intended for both GHC and the
preprocessor must observe some additional restrictions:

-  The module must import :base-ref:`Control.Arrow.`.

-  The preprocessor cannot cope with other Haskell extensions. These
   would have to go in separate modules.

-  Because the preprocessor targets Haskell (rather than Core),
   ``let``\-bound variables are monomorphic.

.. _bang-patterns:

.. _strict-haskell:

Bang patterns and Strict Haskell
================================

.. index::
   single: strict haskell

.. index::
   single: Bang patterns

In high-performance Haskell code (e.g. numeric code) eliminating
thunks from an inner loop can be a huge win.
GHC supports three extensions to allow the programmer to specify
use of strict (call-by-value) evaluation rather than lazy (call-by-need)
evaluation.

- Bang patterns (:extension:`BangPatterns`) makes pattern matching and
  let bindings stricter.

- Strict data types (:extension:`StrictData`) makes constructor fields
  strict by default, on a per-module basis.

- Strict pattern (:extension:`Strict`) makes all patterns and let bindings
  strict by default, on a per-module basis.

The latter two extensions are simply a way to avoid littering high-performance
code with bang patterns, making it harder to read.

Bang patterns and strict matching do not affect the type system in any way.

.. _bang-patterns-informal:

Bang patterns
-------------

.. extension:: BangPatterns
    :shortdesc: Enable bang patterns.

    :since: 6.8.1

    Allow use of bang pattern syntax.

GHC supports an extension of pattern matching called *bang patterns*,
written ``!pat``. Bang patterns are under consideration for Haskell
Prime. The `Haskell prime feature
description <http://ghc.haskell.org/trac/haskell-prime/wiki/BangPatterns>`__
contains more discussion and examples than the material below.

The main idea is to add a single new production to the syntax of
patterns: ::

      pat ::= !pat

Matching an expression ``e`` against a pattern ``!p`` is done by first
evaluating ``e`` (to WHNF) and then matching the result against ``p``.
Example: ::

    f1 !x = True

This definition makes ``f1`` is strict in ``x``, whereas without the
bang it would be lazy. Bang patterns can be nested of course: ::

    f2 (!x, y) = [x,y]

Here, ``f2`` is strict in ``x`` but not in ``y``.

Note the following points:

- A bang only really has
  an effect if it precedes a variable or wild-card pattern: ::

    f3 !(x,y) = [x,y]
    f4 (x,y)  = [x,y]

  Here, ``f3`` and ``f4`` are identical; putting a bang before a pattern
  that forces evaluation anyway does nothing.

- A bang pattern is allowed in a let or where clause, and makes the binding
  strict.  For example: ::

    let !x = e in body
    let !(p,q) = e in body

  In both cases ``e`` is evaluated before starting to evaluate ``body``.

  However, *nested* bangs in a let/where pattern binding behave uniformly with all
  other forms of pattern matching. For example ::

    let (!x,[y]) = e in b

  is equivalent to this: ::

    let { t = case e of (x,[y]) -> x `seq` (x,y)
          x = fst t
          y = snd t }
    in b

  The binding is lazy, but when either ``x`` or ``y`` is evaluated by
  ``b`` the entire pattern is matched, including forcing the evaluation of
  ``x``.

  See :ref:`Semantics of let bindings with bang patterns <recursive-and-polymorphic-let-bindings>` for
  the detailed semantics.

- A pattern with a bang at the outermost level is not allowed at the top
  level of a module.

- Bang patterns work in ``case`` expressions too, of course: ::

    g5 x = let y = f x in body
    g6 x = case f x of { y -> body }
    g7 x = case f x of { !y -> body }

  The functions ``g5`` and ``g6`` mean exactly the same thing. But ``g7``
  evaluates ``(f x)``, binds ``y`` to the result, and then evaluates
  ``body``.

- There is one problem with syntactic ambiguity. Consider: ::

    f !x = 3

  Is this a definition of the infix function "``(!)``", or of the "``f``"
  with a bang pattern? GHC resolves this ambiguity in favour of the
  latter. If you want to define ``(!)`` with bang-patterns enabled, you
  have to do so using prefix notation: ::

    (!) f x = 3


.. _strict-data:

Strict-by-default data types
----------------------------

.. extension:: StrictData
    :shortdesc: Enable default strict datatype fields.

    :since: 8.0.1

    Make fields of data types defined in the current module strict by default.

Informally the ``StrictData`` language extension switches data type
declarations to be strict by default allowing fields to be lazy by
adding a ``~`` in front of the field.

When the user writes ::

          data T = C a
          data T' = C' ~a

we interpret it as if they had written ::

          data T = C !a
          data T' = C' a

The extension only affects definitions in this module.


.. _strict:

Strict-by-default pattern bindings
----------------------------------

.. extension:: Strict
    :shortdesc: Make bindings in the current module strict by default.

    :implies: :extension:`StrictData`
    :since: 8.0.1

    Make bindings in the current module strict by default.

Informally the ``Strict`` language extension switches functions, data
types, and bindings to be strict by default, allowing optional laziness
by adding ``~`` in front of a variable. This essentially reverses the
present situation where laziness is default and strictness can be
optionally had by adding ``!`` in front of a variable.

``Strict`` implies :ref:`StrictData <strict-data>`.

-  **Function definitions**

   When the user writes ::

       f x = ...

   we interpret it as if they had written ::

       f !x = ...

   Adding ``~`` in front of ``x`` gives the regular lazy behavior.

   Turning patterns into irrefutable ones requires ``~(~p)`` or ``(~ ~p)`` when ``Strict`` is enabled.



-  **Let/where bindings**

   When the user writes ::

     let x = ...
     let pat = ...

   we interpret it as if they had written ::

     let !x = ...
     let !pat = ...

   Adding ``~`` in front of ``x`` gives the regular lazy
   behavior.
   The general rule is that we add an implicit bang on the outermost pattern,
   unless disabled with ``~``.

-  **Pattern matching in case expressions, lambdas, do-notation, etc**

   The outermost pattern of all pattern matches gets an implicit bang,
   unless disabled with ``~``.
   This applies to case expressions, patterns in lambda, do-notation,
   list comprehension, and so on.
   For example ::

       case x of (a,b) -> rhs

   is interpreted as ::

       case x of !(a,b) -> rhs

   Since the semantics of pattern matching in case expressions is
   strict, this usually has no effect whatsoever. But it does make a
   difference in the degenerate case of variables and newtypes. So ::

       case x of y -> rhs

   is lazy in Haskell, but with ``Strict`` is interpreted as ::

       case x of !y -> rhs

   which evaluates ``x``. Similarly, if ``newtype Age = MkAge Int``, then ::

       case x of MkAge i -> rhs

   is lazy in Haskell; but with ``Strict`` the added bang makes it
   strict.

   Similarly ::

      \ x -> body
      do { x <- rhs; blah }
      [ e | x <- rhs; blah }

   all get implicit bangs on the ``x`` pattern.

-  **Nested patterns**

   Notice that we do *not* put bangs on nested patterns. For
   example ::

     let (p,q) = if flob then (undefined, undefined) else (True, False)
     in ...

   will behave like ::

     let !(p,q) = if flob then (undefined, undefined) else (True,False)
     in ...

   which will strictly evaluate the right hand side, and bind ``p``
   and ``q`` to the components of the pair. But the pair itself is
   lazy (unless we also compile the ``Prelude`` with ``Strict``; see
   :ref:`strict-modularity` below). So ``p`` and ``q`` may end up bound to
   undefined. See also :ref:`recursive-and-polymorphic-let-bindings` below.

-  **Top level bindings**

   are unaffected by ``Strict``. For example: ::

       x = factorial 20
       (y,z) = if x > 10 then True else False

   Here ``x`` and the pattern binding ``(y,z)`` remain lazy. Reason:
   there is no good moment to force them, until first use.

-  **Newtypes**

   There is no effect on newtypes, which simply rename existing types.
   For example: ::

       newtype T = C a
       f (C x)  = rhs1
       g !(C x) = rhs2

   In ordinary Haskell, ``f`` is lazy in its argument and hence in
   ``x``; and ``g`` is strict in its argument and hence also strict in
   ``x``. With ``Strict``, both become strict because ``f``'s argument
   gets an implicit bang.


.. _strict-modularity:

Modularity
----------

``Strict`` and ``StrictData`` only affects definitions in the module
they are used in. Functions and data types imported from other modules
are unaffected. For example, we won't evaluate the argument to
``Just`` before applying the constructor.  Similarly we won't evaluate
the first argument to ``Data.Map.findWithDefault`` before applying the
function.

This is crucial to preserve correctness. Entities defined in other
modules might rely on laziness for correctness (whether functional or
performance).

Tuples, lists, ``Maybe``, and all the other types from ``Prelude``
continue to have their existing, lazy, semantics.

.. _bang-patterns-sem:
.. _recursive-and-polymorphic-let-bindings:

Dynamic semantics of bang patterns
----------------------------------

The semantics of Haskell pattern matching is described in `Section
3.17.2 <http://www.haskell.org/onlinereport/exps.html#sect3.17.2>`__ of
the Haskell Report. To this description add one extra item 10, saying:

-  Matching the pattern ``!pat`` against a value ``v`` behaves as
   follows:

   -  if ``v`` is bottom, the match diverges

   -  otherwise, ``pat`` is matched against ``v``

Similarly, in Figure 4 of `Section
3.17.3 <http://www.haskell.org/onlinereport/exps.html#sect3.17.3>`__,
add a new case (t): ::

    case v of { !pat -> e; _ -> e' }
       = v `seq` case v of { pat -> e; _ -> e' }

That leaves let expressions, whose translation is given in `Section
3.12 <http://www.haskell.org/onlinereport/exps.html#sect3.12>`__ of the
Haskell Report.
Replace the "Translation" there with the following one.  Given
``let { bind1 ... bindn } in body``:

.. admonition:: FORCE

    Replace any binding ``!p = e`` with ``v = case e of p -> (x1, ..., xn); (x1, ..., xn) = v`` and replace
    ``body`` with ``v seq body``, where ``v`` is fresh. This translation works fine if
    ``p`` is already a variable ``x``, but can obviously be optimised by not
    introducing a fresh variable ``v``.

.. admonition:: SPLIT

    Replace any binding ``p = e``, where ``p`` is not a variable, with
    ``v = e; x1 = case v of p -> x1; ...; xn = case v of p -> xn``, where
    ``v`` is fresh and ``x1``.. ``xn`` are the bound variables of ``p``.
    Again if ``e`` is a variable, this can be optimised by not introducing a
    fresh variable.

The result will be a (possibly) recursive set of bindings, binding
only simple variables on the left hand side. (One could go one step
further, as in the Haskell Report and make the recursive bindings
non-recursive using ``fix``, but we do not do so in Core, and it only
obfuscates matters, so we do not do so here.)

The translation is carefully crafted to make bang patterns meaningful
for recursive and polymorphic bindings as well as straightforward
non-recursive bindings.

Here are some examples of how this translation works. The first
expression of each sequence is Haskell source; the subsequent ones are
Core.

Here is a simple non-recursive case: ::

    let x :: Int     -- Non-recursive
        !x = factorial y
    in body

    ===> (FORCE)
        let x = factorial y in x `seq` body

    ===> (inline seq)
        let x = factorial y in case x of x -> body

    ===> (inline x)
        case factorial y of x -> body

Same again, only with a pattern binding: ::

    let !(Just x, Left y) = e in body

    ===> (FORCE)
        let v = case e of (Just x, Left y) -> (x,y)
            (x,y) = v
        in v `seq` body

    ===> (SPLIT)
        let v = case e of (Just x, Left y) -> (x,y)
            x = case v of (x,y) -> x
            y = case v of (x,y) -> y
        in v `seq` body

    ===> (inline seq, float x,y bindings inwards)
        let v = case e of (Just x, Left y) -> (x,y)
        in case v of v -> let x = case v of (x,y) -> x
                              y = case v of (x,y) -> y
                          in body

    ===> (fluff up v's pattern; this is a standard Core optimisation)
        let v = case e of (Just x, Left y) -> (x,y)
        in case v of v@(p,q) -> let x = case v of (x,y) -> x
                                    y = case v of (x,y) -> y
                                in body

    ===> (case of known constructor)
        let v = case e of (Just x, Left y) -> (x,y)
        in case v of v@(p,q) -> let x = p
                                    y = q
                                in body

    ===> (inline x,y, v)
        case (case e of (Just x, Left y) -> (x,y) of
            (p,q) -> body[p/x, q/y]

    ===> (case of case)
        case e of (Just x, Left y) -> body[p/x, q/y]

The final form is just what we want: a simple case expression.

Here is a recursive case ::

    letrec xs :: [Int]  -- Recursive
            !xs = factorial y : xs
    in body

    ===> (FORCE)
        letrec xs = factorial y : xs in xs `seq` body

    ===> (inline seq)
        letrec xs = factorial y : xs in case xs of xs -> body

    ===> (eliminate case of value)
        letrec xs = factorial y : xs in body

and a polymorphic one: ::

    let f :: forall a. [a] -> [a]    -- Polymorphic
        !f = fst (reverse, True)
    in body

    ===> (FORCE)
        let f = /\a. fst (reverse a, True) in f `seq` body
    ===> (inline seq, inline f)
        case (/\a. fst (reverse a, True)) of f -> body

Notice that the ``seq`` is added only in the translation to Core
If we did it in Haskell source, thus ::

   let f = ... in f `seq` body

then ``f``\ 's polymorphic type would get instantiated, so the Core
translation would be ::

   let f = ... in f Any `seq` body


When overloading is involved, the results might be slightly counter
intuitive: ::

    let f :: forall a. Eq a => a -> [a] -> Bool    -- Overloaded
        !f = fst (member, True)
    in body

    ===> (FORCE)
        let f = /\a \(d::Eq a). fst (member, True) in f `seq` body

    ===> (inline seq, case of value)
        let f = /\a \(d::Eq a). fst (member, True) in body

Note that the bang has no effect at all in this case


.. _assertions:

Assertions
==========

.. index::
   single: Assertions

If you want to make use of assertions in your standard Haskell code, you
could define a function like the following: ::

    assert :: Bool -> a -> a
    assert False x = error "assertion failed!"
    assert _     x = x

which works, but gives you back a less than useful error message -- an
assertion failed, but which and where?

One way out is to define an extended ``assert`` function which also
takes a descriptive string to include in the error message and perhaps
combine this with the use of a pre-processor which inserts the source
location where ``assert`` was used.

GHC offers a helping hand here, doing all of this for you. For every use
of ``assert`` in the user's source: ::

    kelvinToC :: Double -> Double
    kelvinToC k = assert (k >= 0.0) (k-273.15)

GHC will rewrite this to also include the source location where the
assertion was made, ::

    assert pred val ==> assertError "Main.hs|15" pred val

The rewrite is only performed by the compiler when it spots applications
of ``Control.Exception.assert``, so you can still define and use your
own versions of ``assert``, should you so wish. If not, import
``Control.Exception`` to make use ``assert`` in your code.

.. index::
   pair: assertions; disabling

GHC ignores assertions when optimisation is turned on with the
:ghc-flag:`-O` flag. That is, expressions of the form ``assert pred e``
will be rewritten to ``e``. You can also disable assertions using the
:ghc-flag:`-fignore-asserts` option. The option
:ghc-flag:`-fno-ignore-asserts <-fignore-asserts>`
allows enabling assertions even when optimisation is turned on.

Assertion failures can be caught, see the documentation for the
:base-ref:`Control.Exception` library for the details.

.. _static-pointers:

Static pointers
===============

.. index::
   single: Static pointers

.. extension:: StaticPointers
    :shortdesc: Enable static pointers.

    :since: 7.10.1

    Allow use of static pointer syntax.

The language extension :extension:`StaticPointers` adds a new syntactic form
``static e``, which stands for a reference to the closed expression ⟨e⟩.
This reference is stable and portable, in the sense that it remains
valid across different processes on possibly different machines. Thus, a
process can create a reference and send it to another process that can
resolve it to ⟨e⟩.

With this extension turned on, ``static`` is no longer a valid
identifier.

Static pointers were first proposed in the paper `Towards Haskell in the
cloud <http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/remote.pdf>`__,
Jeff Epstein, Andrew P. Black and Simon Peyton-Jones, Proceedings of the
4th ACM Symposium on Haskell, pp. 118-129, ACM, 2011.

.. _using-static-pointers:

Using static pointers
---------------------

Each reference is given a key which can be used to locate it at runtime
with :base-ref:`GHC.StaticPtr.unsafeLookupStaticPtr`
which uses a global and immutable table called the Static Pointer Table.
The compiler includes entries in this table for all static forms found
in the linked modules. The value can be obtained from the reference via
:base-ref:`GHC.StaticPtr.deRefStaticPtr`.

The body ``e`` of a ``static e`` expression must be a closed expression. Where
we say an expression is *closed* when all of its free (type) variables are
closed. And a variable is *closed* if it is let-bound to a *closed* expression
and its type is *closed* as well. And a type is *closed* if it has no free
variables.

All of the following are permissible: ::

    inc :: Int -> Int
    inc x = x + 1

    ref1 = static 1
    ref2 = static inc
    ref3 = static (inc 1)
    ref4 = static ((\x -> x + 1) (1 :: Int))
    ref5 y = static (let x = 1 in x)
    ref6 y = let x = 1 in static x

While the following definitions are rejected: ::

    ref7 y = let x = y in static x    -- x is not closed
    ref8 y = static (let x = 1 in y)  -- y is not let-bound
    ref8 (y :: a) = let x = undefined :: a
                     in static x      -- x has a non-closed type

.. note::

    While modules loaded in GHCi with the :ghci-cmd:`:load` command may use
    :extension:`StaticPointers` and ``static`` expressions, statements
    entered on the REPL may not. This is a limitation of GHCi; see
    :ghc-ticket:`12356` for details.

.. note::

    The set of keys used for locating static pointers in the Static Pointer
    Table is not guaranteed to remain stable for different program binaries.
    Or in other words, only processes launched from the same program binary
    are guaranteed to use the same set of keys.

.. _typechecking-static-pointers:

Static semantics of static pointers
-----------------------------------

Informally, if we have a closed expression ::

    e :: forall a_1 ... a_n . t

the static form is of type ::

    static e :: (IsStatic p, Typeable a_1, ... , Typeable a_n) => p t


A static form determines a value of type ``StaticPtr t``, but just
like ``OverloadedLists`` and ``OverloadedStrings``, this literal
expression is overloaded to allow lifting a ``StaticPtr`` into another
type implicitly, via the ``IsStatic`` class: ::

    class IsStatic p where
        fromStaticPtr :: StaticPtr a -> p a

The only predefined instance is the obvious one that does nothing: ::

    instance IsStatic StaticPtr where
        fromStaticPtr sptr = sptr

See :base-ref:`GHC.StaticPtr.IsStatic`.

Furthermore, type ``t`` is constrained to have a ``Typeable`` instance.
The following are therefore illegal: ::

    static show                    -- No Typeable instance for (Show a => a -> String)
    static Control.Monad.ST.runST  -- No Typeable instance for ((forall s. ST s a) -> a)

That being said, with the appropriate use of wrapper datatypes, the
above limitations induce no loss of generality: ::

    {-# LANGUAGE ConstraintKinds           #-}
    {-# LANGUAGE ExistentialQuantification #-}
    {-# LANGUAGE Rank2Types                #-}
    {-# LANGUAGE StandaloneDeriving        #-}
    {-# LANGUAGE StaticPointers            #-}

    import Control.Monad.ST
    import Data.Typeable
    import GHC.StaticPtr

    data Dict c = c => Dict

    g1 :: Typeable a => StaticPtr (Dict (Show a) -> a -> String)
    g1 = static (\Dict -> show)

    data Rank2Wrapper f = R2W (forall s. f s)
      deriving Typeable
    newtype Flip f a s = Flip { unFlip :: f s a }
      deriving Typeable

    g2 :: Typeable a => StaticPtr (Rank2Wrapper (Flip ST a) -> a)
    g2 = static (\(R2W f) -> runST (unFlip f))

.. _pragmas:

Pragmas
=======

.. index::
   single: pragma

GHC supports several pragmas, or instructions to the compiler placed in
the source code. Pragmas don't normally affect the meaning of the
program, but they might affect the efficiency of the generated code.

Pragmas all take the form ``{-# word ... #-}`` where ⟨word⟩ indicates
the type of pragma, and is followed optionally by information specific
to that type of pragma. Case is ignored in ⟨word⟩. The various values
for ⟨word⟩ that GHC understands are described in the following sections;
any pragma encountered with an unrecognised ⟨word⟩ is ignored. The
layout rule applies in pragmas, so the closing ``#-}`` should start in a
column to the right of the opening ``{-#``.

Certain pragmas are *file-header pragmas*:

-  A file-header pragma must precede the ``module`` keyword in the file.

-  There can be as many file-header pragmas as you please, and they can
   be preceded or followed by comments.

-  File-header pragmas are read once only, before pre-processing the
   file (e.g. with cpp).

-  The file-header pragmas are: ``{-# LANGUAGE #-}``,
   ``{-# OPTIONS_GHC #-}``, and ``{-# INCLUDE #-}``.

.. _language-pragma:

``LANGUAGE`` pragma
-------------------

.. pragma:: LANGUAGE ⟨ext⟩, ⟨ext⟩, ...

    :where: file header

    Enable or disable a set of language extensions.

The ``LANGUAGE`` pragma allows language extensions to be enabled in a
portable way. It is the intention that all Haskell compilers support the
``LANGUAGE`` pragma with the same syntax, although not all extensions
are supported by all compilers, of course. The ``LANGUAGE`` pragma
should be used instead of ``OPTIONS_GHC``, if possible.

For example, to enable the FFI and preprocessing with CPP: ::

    {-# LANGUAGE ForeignFunctionInterface, CPP #-}

``LANGUAGE`` is a file-header pragma (see :ref:`pragmas`).

Every language extension can also be turned into a command-line flag by
prefixing it with "``-X``"; for example ``-XForeignFunctionInterface``.
(Similarly, all "``-X``" flags can be written as ``LANGUAGE`` pragmas.)

A list of all supported language extensions can be obtained by invoking
``ghc --supported-extensions`` (see :ghc-flag:`--supported-extensions`).

Any extension from the ``Extension`` type defined in
:cabal-ref:`Language.Haskell.Extension.` may be used. GHC will report an error
if any of the requested extensions are not supported.

.. _options-pragma:

``OPTIONS_GHC`` pragma
----------------------

.. pragma:: OPTIONS_GHC ⟨flags⟩

    :where: file header

The ``OPTIONS_GHC`` pragma is used to specify additional options that
are given to the compiler when compiling this source file. See
:ref:`source-file-options` for details.

Previous versions of GHC accepted ``OPTIONS`` rather than
``OPTIONS_GHC``, but that is now deprecated.

``OPTIONS_GHC`` is a file-header pragma (see :ref:`pragmas`).

.. _include-pragma:

``INCLUDE`` pragma
------------------

The ``INCLUDE`` used to be necessary for specifying header files to be
included when using the FFI and compiling via C. It is no longer
required for GHC, but is accepted (and ignored) for compatibility with
other compilers.

.. _warning-deprecated-pragma:

``WARNING`` and ``DEPRECATED`` pragmas
--------------------------------------

.. pragma:: WARNING

    :where: declaration

    The ``WARNING`` pragma allows you to attach an arbitrary warning to a
    particular function, class, or type.

.. pragma:: DEPRECATED

    :where: declaration

    A ``DEPRECATED`` pragma lets you specify that a particular function, class,
    or type is deprecated.

There are two ways of using these pragmas.

-  You can work on an entire module thus: ::

          module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
            ...

   Or: ::

          module Wibble {-# WARNING "This is an unstable interface." #-} where
            ...

   When you compile any module that import ``Wibble``, GHC will print
   the specified message.

-  You can attach a warning to a function, class, type, or data
   constructor, with the following top-level declarations: ::

          {-# DEPRECATED f, C, T "Don't use these" #-}
          {-# WARNING unsafePerformIO "This is unsafe; I hope you know what you're doing" #-}

   When you compile any module that imports and uses any of the
   specified entities, GHC will print the specified message.

   You can only attach to entities declared at top level in the module
   being compiled, and you can only use unqualified names in the list of
   entities. A capitalised name, such as ``T`` refers to *either* the
   type constructor ``T`` *or* the data constructor ``T``, or both if
   both are in scope. If both are in scope, there is currently no way to
   specify one without the other (c.f. fixities :ref:`infix-tycons`).

Also note that the argument to ``DEPRECATED`` and ``WARNING`` can also be a list
of strings, in which case the strings will be presented on separate lines in the
resulting warning message, ::

    {-# DEPRECATED foo, bar ["Don't use these", "Use gar instead"] #-}

Warnings and deprecations are not reported for (a) uses within the
defining module, (b) defining a method in a class instance, and (c) uses
in an export list. The latter reduces spurious complaints within a
library in which one module gathers together and re-exports the exports
of several others.

You can suppress the warnings with the flag
:ghc-flag:`-Wno-warnings-deprecations <-Wwarnings-deprecations>`.

.. _minimal-pragma:

``MINIMAL`` pragma
------------------

.. pragma:: MINIMAL ⟨name⟩ | ⟨name⟩ , ...

    :where: in class body

    Define the methods needed for a minimal complete instance of a class.

The ``MINIMAL`` pragma is used to specify the minimal complete definition of
a class, i.e. specify which methods must be implemented by all
instances. If an instance does not satisfy the minimal complete
definition, then a warning is generated. This can be useful when a class
has methods with circular defaults. For example ::

    class Eq a where
        (==) :: a -> a -> Bool
        (/=) :: a -> a -> Bool
        x == y = not (x /= y)
        x /= y = not (x == y)
        {-# MINIMAL (==) | (/=) #-}

Without the ``MINIMAL`` pragma no warning would be generated for an instance
that implements neither method.

The syntax for minimal complete definition is: ::

    mindef ::= name
            |  '(' mindef ')'
            |  mindef '|' mindef
            |  mindef ',' mindef

A vertical bar denotes disjunction, i.e. one of the two sides is
required. A comma denotes conjunction, i.e. both sides are required.
Conjunction binds stronger than disjunction.

If no ``MINIMAL`` pragma is given in the class declaration, it is just as if
a pragma ``{-# MINIMAL op1, op2, ..., opn #-}`` was given, where the
``opi`` are the methods that lack a default method in the class
declaration (c.f. :ghc-flag:`-Wmissing-methods`, :ref:`options-sanity`).

This warning can be turned off with the flag
:ghc-flag:`-Wno-missing-methods <-Wmissing-methods>`.

.. _inline-noinline-pragma:

``INLINE`` and ``NOINLINE`` pragmas
-----------------------------------

These pragmas control the inlining of function definitions.

.. _inline-pragma:

``INLINE`` pragma
~~~~~~~~~~~~~~~~~

.. pragma:: INLINE ⟨name⟩

    :where: top-level

    Force GHC to inline a value.

GHC (with :ghc-flag:`-O`, as always) tries to inline (or "unfold")
functions/values that are "small enough," thus avoiding the call
overhead and possibly exposing other more-wonderful optimisations. GHC
has a set of heuristics, tuned over a long period of time using many
benchmarks, that decide when it is beneficial to inline a function at
its call site. The heuristics are designed to inline functions when it
appears to be beneficial to do so, but without incurring excessive code
bloat. If a function looks too big, it won't be inlined, and functions
larger than a certain size will not even have their definition exported
in the interface file. Some of the thresholds that govern these
heuristic decisions can be changed using flags, see :ref:`options-f`.

Normally GHC will do a reasonable job of deciding by itself when it is a
good idea to inline a function. However, sometimes you might want to
override the default behaviour. For example, if you have a key function
that is important to inline because it leads to further optimisations,
but GHC judges it to be too big to inline.

The sledgehammer you can bring to bear is the ``INLINE`` pragma, used thusly: ::

    key_function :: Int -> String -> (Bool, Double)
    {-# INLINE key_function #-}

The major effect of an ``INLINE`` pragma is to declare a function's
"cost" to be very low. The normal unfolding machinery will then be very
keen to inline it. However, an ``INLINE`` pragma for a function "``f``"
has a number of other effects:

-  While GHC is keen to inline the function, it does not do so blindly.
   For example, if you write ::

       map key_function xs

   there really isn't any point in inlining ``key_function`` to get ::

       map (\x -> body) xs

   In general, GHC only inlines the function if there is some reason (no
   matter how slight) to suppose that it is useful to do so.

-  Moreover, GHC will only inline the function if it is *fully applied*,
   where "fully applied" means applied to as many arguments as appear
   (syntactically) on the LHS of the function definition. For example: ::

       comp1 :: (b -> c) -> (a -> b) -> a -> c
       {-# INLINE comp1 #-}
       comp1 f g = \x -> f (g x)

       comp2 :: (b -> c) -> (a -> b) -> a -> c
       {-# INLINE comp2 #-}
       comp2 f g x = f (g x)

   The two functions ``comp1`` and ``comp2`` have the same semantics,
   but ``comp1`` will be inlined when applied to *two* arguments, while
   ``comp2`` requires *three*. This might make a big difference if you
   say ::

       map (not `comp1` not) xs

   which will optimise better than the corresponding use of ``comp2``.

-  It is useful for GHC to optimise the definition of an INLINE function
   ``f`` just like any other non-``INLINE`` function, in case the
   non-inlined version of ``f`` is ultimately called. But we don't want
   to inline the *optimised* version of ``f``; a major reason for ``INLINE``
   pragmas is to expose functions in ``f``\'s RHS that have rewrite
   rules, and it's no good if those functions have been optimised away.

   So *GHC guarantees to inline precisely the code that you wrote*, no
   more and no less. It does this by capturing a copy of the definition
   of the function to use for inlining (we call this the "inline-RHS"),
   which it leaves untouched, while optimising the ordinarily RHS as
   usual. For externally-visible functions the inline-RHS (not the
   optimised RHS) is recorded in the interface file.

-  An ``INLINE`` function is not worker/wrappered by strictness analysis.
   It's going to be inlined wholesale instead.

GHC ensures that inlining cannot go on forever: every mutually-recursive
group is cut by one or more *loop breakers* that is never inlined (see
`Secrets of the GHC inliner, JFP 12(4) July
2002 <http://research.microsoft.com/%7Esimonpj/Papers/inlining/index.htm>`__).
GHC tries not to select a function with an ``INLINE`` pragma as a loop
breaker, but when there is no choice even an INLINE function can be
selected, in which case the ``INLINE`` pragma is ignored. For example, for a
self-recursive function, the loop breaker can only be the function
itself, so an ``INLINE`` pragma is always ignored.

Syntactically, an ``INLINE`` pragma for a function can be put anywhere
its type signature could be put.

``INLINE`` pragmas are a particularly good idea for the
``then``/``return`` (or ``bind``/``unit``) functions in a monad. For
example, in GHC's own ``UniqueSupply`` monad code, we have: ::

    {-# INLINE thenUs #-}
    {-# INLINE returnUs #-}

See also the ``NOINLINE`` (:ref:`noinline-pragma`) and ``INLINABLE``
(:ref:`inlinable-pragma`) pragmas.

.. _inlinable-pragma:

``INLINABLE`` pragma
~~~~~~~~~~~~~~~~~~~~

.. pragma:: INLINABLE ⟨name⟩

    :where: top-level

    Suggest that the compiler always consider inlining ``name``.

An ``{-# INLINABLE f #-}`` pragma on a function ``f`` has the following
behaviour:

-  While ``INLINE`` says "please inline me", the ``INLINABLE`` says
   "feel free to inline me; use your discretion". In other words the
   choice is left to GHC, which uses the same rules as for pragma-free
   functions. Unlike ``INLINE``, that decision is made at the *call
   site*, and will therefore be affected by the inlining threshold,
   optimisation level etc.

-  Like ``INLINE``, the ``INLINABLE`` pragma retains a copy of the
   original RHS for inlining purposes, and persists it in the interface
   file, regardless of the size of the RHS.

-  One way to use ``INLINABLE`` is in conjunction with the special
   function ``inline`` (:ref:`special-ids`). The call ``inline f`` tries
   very hard to inline ``f``. To make sure that ``f`` can be inlined, it
   is a good idea to mark the definition of ``f`` as ``INLINABLE``, so
   that GHC guarantees to expose an unfolding regardless of how big it
   is. Moreover, by annotating ``f`` as ``INLINABLE``, you ensure that
   ``f``\'s original RHS is inlined, rather than whatever random
   optimised version of ``f`` GHC's optimiser has produced.

-  The ``INLINABLE`` pragma also works with ``SPECIALISE``: if you mark
   function ``f`` as ``INLINABLE``, then you can subsequently
   ``SPECIALISE`` in another module (see :ref:`specialize-pragma`).

-  Unlike ``INLINE``, it is OK to use an ``INLINABLE`` pragma on a
   recursive function. The principal reason do to so to allow later use
   of ``SPECIALISE``

The alternative spelling ``INLINEABLE`` is also accepted by GHC.

.. _noinline-pragma:

``NOINLINE`` pragma
~~~~~~~~~~~~~~~~~~~

.. index::
   single: NOTINLINE

.. pragma:: NOINLINE ⟨name⟩

    :where: top-level

    Instructs the compiler not to inline a value.

The :pragma:`NOINLINE` pragma does exactly what you'd expect: it stops the
named function from being inlined by the compiler. You shouldn't ever
need to do this, unless you're very cautious about code size.

``NOTINLINE`` is a synonym for ``NOINLINE`` (``NOINLINE`` is specified
by Haskell 98 as the standard way to disable inlining, so it should be
used if you want your code to be portable).

.. _conlike-pragma:

``CONLIKE`` modifier
~~~~~~~~~~~~~~~~~~~~

.. pragma:: CONLIKE

    :where: modifies :pragma:`INLINE` or :pragma:`NOINLINE` pragma

    Instructs GHC to consider a value to be especially cheap to inline.

An :pragma:`INLINE` or :pragma:`NOINLINE` pragma may have a :pragma:`CONLIKE` modifier, which affects
matching in :pragma:`RULE`\s (only). See :ref:`conlike`.

.. _phase-control:

Phase control
~~~~~~~~~~~~~

Sometimes you want to control exactly when in GHC's pipeline the :pragma:`INLINE`
pragma is switched on. Inlining happens only during runs of the
*simplifier*. Each run of the simplifier has a different *phase number*;
the phase number decreases towards zero. If you use
:ghc-flag:`-dverbose-core2core` you will see the sequence of phase numbers for
successive runs of the simplifier. In an :pragma:`INLINE` pragma you can
optionally specify a phase number, thus:

-  "``INLINE[k] f``" means: do not inline ``f`` until phase ``k``, but
   from phase ``k`` onwards be very keen to inline it.

-  "``INLINE[~k] f``" means: be very keen to inline ``f`` until phase
   ``k``, but from phase ``k`` onwards do not inline it.

-  "``NOINLINE[k] f``" means: do not inline ``f`` until phase ``k``, but
   from phase ``k`` onwards be willing to inline it (as if there was no
   pragma).

-  "``NOINLINE[~k] f``" means: be willing to inline ``f`` until phase
   ``k``, but from phase ``k`` onwards do not inline it.

The same information is summarised here:

.. code-block:: none

                               -- Before phase 2     Phase 2 and later
      {-# INLINE   [2]  f #-}  --      No                 Yes
      {-# INLINE   [~2] f #-}  --      Yes                No
      {-# NOINLINE [2]  f #-}  --      No                 Maybe
      {-# NOINLINE [~2] f #-}  --      Maybe              No

      {-# INLINE   f #-}       --      Yes                Yes
      {-# NOINLINE f #-}       --      No                 No

By "Maybe" we mean that the usual heuristic inlining rules apply (if the
function body is small, or it is applied to interesting-looking
arguments etc). Another way to understand the semantics is this:

-  For both :pragma:`INLINE` and :pragma:`NOINLINE`, the phase number says when
   inlining is allowed at all.

-  The :pragma:`INLINE` pragma has the additional effect of making the function
   body look small, so that when inlining is allowed it is very likely
   to happen.

The same phase-numbering control is available for :pragma:`RULE`\s
(:ref:`rewrite-rules`).

.. _line-pragma:

``LINE`` pragma
---------------

.. pragma:: LINE ⟨lineno⟩ "⟨file⟩"

    :where: anywhere

    Generated by preprocessors to convey source line numbers of the original
    source.

This pragma is similar to C's ``#line`` pragma, and is mainly for use in
automatically generated Haskell code. It lets you specify the line
number and filename of the original code; for example

::

    {-# LINE 42 "Foo.vhs" #-}

if you'd generated the current file from something called ``Foo.vhs``
and this line corresponds to line 42 in the original. GHC will adjust
its error messages to refer to the line/file named in the ``LINE``
pragma.

``LINE`` pragmas generated from Template Haskell set the file and line
position for the duration of the splice and are limited to the splice.
Note that because Template Haskell splices abstract syntax, the file
positions are not automatically advanced.

.. _column-pragma:

``COLUMN`` pragma
-----------------

.. index::
   single: COLUMN; pragma
   single: pragma; COLUMN

This is the analogue of the ``LINE`` pragma and is likewise intended for
use in automatically generated Haskell code. It lets you specify the
column number of the original code; for example

::

    foo = do
      {-# COLUMN 42 #-}pure ()
      pure ()

This adjusts all column numbers immediately after the pragma to start
at 42.  The presence of this pragma only affects the quality of the
diagnostics and does not change the syntax of the code itself.

.. _rules:

``RULES`` pragma
----------------

The :pragma:`RULES` pragma lets you specify rewrite rules. It is described in
:ref:`rewrite-rules`.

.. _specialize-pragma:

``SPECIALIZE`` pragma
---------------------

.. index::
   single: SPECIALIZE pragma
   single: pragma, SPECIALIZE
   single: overloading, death to

.. pragma:: SPECIALIZE ⟨name⟩ :: ⟨type⟩

    Ask that GHC specialize a polymorphic value to a particular type.

(UK spelling also accepted.) For key overloaded functions, you can
create extra versions (NB: at the cost of larger code) specialised to particular
types. Thus, if you have an overloaded function:

::

      hammeredLookup :: Ord key => [(key, value)] -> key -> value

If it is heavily used on lists with ``Widget`` keys, you could
specialise it as follows:

::

      {-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}

-  A ``SPECIALIZE`` pragma for a function can be put anywhere its type
   signature could be put. Moreover, you can also ``SPECIALIZE`` an
   *imported* function provided it was given an ``INLINABLE`` pragma at
   its definition site (:ref:`inlinable-pragma`).

-  A ``SPECIALIZE`` has the effect of generating (a) a specialised
   version of the function and (b) a rewrite rule (see
   :ref:`rewrite-rules`) that rewrites a call to the un-specialised
   function into a call to the specialised one. Moreover, given a
   ``SPECIALIZE`` pragma for a function ``f``, GHC will automatically
   create specialisations for any type-class-overloaded functions called
   by ``f``, if they are in the same module as the ``SPECIALIZE``
   pragma, or if they are ``INLINABLE``; and so on, transitively.

-  You can add phase control (:ref:`phase-control`) to the RULE
   generated by a ``SPECIALIZE`` pragma, just as you can if you write a
   ``RULE`` directly. For example:

   ::

         {-# SPECIALIZE [0] hammeredLookup :: [(Widget, value)] -> Widget -> value #-}

   generates a specialisation rule that only fires in Phase 0 (the final
   phase). If you do not specify any phase control in the ``SPECIALIZE``
   pragma, the phase control is inherited from the inline pragma (if
   any) of the function. For example:

   ::

         foo :: Num a => a -> a
         foo = ...blah...
         {-# NOINLINE [0] foo #-}
         {-# SPECIALIZE foo :: Int -> Int #-}

   The ``NOINLINE`` pragma tells GHC not to inline ``foo`` until Phase
   0; and this property is inherited by the specialisation RULE, which
   will therefore only fire in Phase 0.

   The main reason for using phase control on specialisations is so that
   you can write optimisation RULES that fire early in the compilation
   pipeline, and only *then* specialise the calls to the function. If
   specialisation is done too early, the optimisation rules might fail
   to fire.

-  The type in a ``SPECIALIZE`` pragma can be any type that is less
   polymorphic than the type of the original function. In concrete
   terms, if the original function is ``f`` then the pragma

   ::

         {-# SPECIALIZE f :: <type> #-}

   is valid if and only if the definition

   ::

         f_spec :: <type>
         f_spec = f

   is valid. Here are some examples (where we only give the type
   signature for the original function, not its code):

   ::

         f :: Eq a => a -> b -> b
         {-# SPECIALISE f :: Int -> b -> b #-}

         g :: (Eq a, Ix b) => a -> b -> b
         {-# SPECIALISE g :: (Eq a) => a -> Int -> Int #-}

         h :: Eq a => a -> a -> a
         {-# SPECIALISE h :: (Eq a) => [a] -> [a] -> [a] #-}

   The last of these examples will generate a RULE with a
   somewhat-complex left-hand side (try it yourself), so it might not
   fire very well. If you use this kind of specialisation, let us know
   how well it works.

.. _specialize-inline:

``SPECIALIZE INLINE``
~~~~~~~~~~~~~~~~~~~~~

.. pragma:: SPECIALIZE INLINE ⟨name⟩ :: ⟨type⟩

    :where: top-level

A ``SPECIALIZE`` pragma can optionally be followed with a ``INLINE`` or
``NOINLINE`` pragma, optionally followed by a phase, as described in
:ref:`inline-noinline-pragma`. The ``INLINE`` pragma affects the
specialised version of the function (only), and applies even if the
function is recursive. The motivating example is this: ::

    -- A GADT for arrays with type-indexed representation
    data Arr e where
      ArrInt :: !Int -> ByteArray# -> Arr Int
      ArrPair :: !Int -> Arr e1 -> Arr e2 -> Arr (e1, e2)

    (!:) :: Arr e -> Int -> e
    {-# SPECIALISE INLINE (!:) :: Arr Int -> Int -> Int #-}
    {-# SPECIALISE INLINE (!:) :: Arr (a, b) -> Int -> (a, b) #-}
    (ArrInt _ ba)     !: (I# i) = I# (indexIntArray# ba i)
    (ArrPair _ a1 a2) !: i      = (a1 !: i, a2 !: i)

Here, ``(!:)`` is a recursive function that indexes arrays of type
``Arr e``. Consider a call to ``(!:)`` at type ``(Int,Int)``. The second
specialisation will fire, and the specialised function will be inlined.
It has two calls to ``(!:)``, both at type ``Int``. Both these calls
fire the first specialisation, whose body is also inlined. The result is
a type-based unrolling of the indexing function.

You can add explicit phase control (:ref:`phase-control`) to
``SPECIALISE INLINE`` pragma, just like on an :pragma:`INLINE` pragma; if you do
so, the same phase is used for the rewrite rule and the INLINE control of the
specialised function.

.. warning:: You can make GHC diverge by using ``SPECIALISE INLINE`` on an
             ordinarily-recursive function.

``SPECIALIZE`` for imported functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Generally, you can only give a :pragma:`SPECIALIZE` pragma for a function
defined in the same module. However if a function ``f`` is given an
:pragma:`INLINABLE` pragma at its definition site, then it can subsequently be
specialised by importing modules (see :ref:`inlinable-pragma`). For example ::

    module Map( lookup, blah blah ) where
      lookup :: Ord key => [(key,a)] -> key -> Maybe a
      lookup = ...
      {-# INLINABLE lookup #-}

    module Client where
      import Map( lookup )

      data T = T1 | T2 deriving( Eq, Ord )
      {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a

Here, ``lookup`` is declared :pragma:`INLINABLE`, but it cannot be specialised
for type ``T`` at its definition site, because that type does not exist
yet. Instead a client module can define ``T`` and then specialise
``lookup`` at that type.

Moreover, every module that imports ``Client`` (or imports a module that
imports ``Client``, transitively) will "see", and make use of, the
specialised version of ``lookup``. You don't need to put a
:pragma:`SPECIALIZE` pragma in every module.

Moreover you often don't even need the :pragma:`SPECIALIZE` pragma in the
first place. When compiling a module ``M``, GHC's optimiser (when given the
:ghc-flag:`-O` flag) automatically considers each top-level overloaded function declared
in ``M``, and specialises it for the different types at which it is called in
``M``. The optimiser *also* considers each *imported* :pragma:`INLINABLE`
overloaded function, and specialises it for the different types at which
it is called in ``M``. So in our example, it would be enough for ``lookup``
to be called at type ``T``:

::

    module Client where
      import Map( lookup )

      data T = T1 | T2 deriving( Eq, Ord )

      findT1 :: [(T,a)] -> Maybe a
      findT1 m = lookup m T1   -- A call of lookup at type T

However, sometimes there are no such calls, in which case the pragma can
be useful.

.. _specialize-instance-pragma:

``SPECIALIZE`` instance pragma
------------------------------

.. index::
   single: instance, specializing
   single: overloading, death to

.. pragma:: SPECIALIZE instance ⟨instance head⟩

   :where: instance body

Same idea, except for instance declarations. For example:

::

    instance (Eq a) => Eq (Foo a) where {
       {-# SPECIALIZE instance Eq (Foo [(Int, Bar)]) #-}
       ... usual stuff ...
     }

The pragma must occur inside the ``where`` part of the instance
declaration.

.. _unpack-pragma:

``UNPACK`` pragma
-----------------

.. pragma:: UNPACK

    :where: data constructor field

    Instructs the compiler to unpack the contents of a constructor field into
    the constructor itself.

The ``UNPACK`` indicates to the compiler that it should unpack the
contents of a constructor field into the constructor itself, removing a
level of indirection. For example: ::

    data T = T {-# UNPACK #-} !Float
               {-# UNPACK #-} !Float

will create a constructor ``T`` containing two unboxed floats. This may
not always be an optimisation: if the ``T`` constructor is scrutinised
and the floats passed to a non-strict function for example, they will
have to be reboxed (this is done automatically by the compiler).

Unpacking constructor fields should only be used in conjunction with
:ghc-flag:`-O` [1]_, in order to expose unfoldings to the compiler so the
reboxing can be removed as often as possible. For example: ::

    f :: T -> Float
    f (T f1 f2) = f1 + f2

The compiler will avoid reboxing ``f1`` and ``f2`` by inlining ``+`` on
floats, but only when :ghc-flag:`-O` is on.

Any single-constructor data is eligible for unpacking; for example ::

    data T = T {-# UNPACK #-} !(Int,Int)

will store the two ``Int``\ s directly in the ``T`` constructor, by
flattening the pair. Multi-level unpacking is also supported: ::

    data T = T {-# UNPACK #-} !S
    data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int

will store two unboxed ``Int#``\ s directly in the ``T`` constructor.
The unpacker can see through newtypes, too.

See also the :ghc-flag:`-funbox-strict-fields` flag, which essentially has the
effect of adding ``{-# UNPACK #-}`` to every strict constructor field.

.. [1]
   In fact, :pragma:`UNPACK` has no effect without :ghc-flag:`-O`, for technical
   reasons (see :ghc-ticket:`5252`).

.. _nounpack-pragma:

``NOUNPACK`` pragma
-------------------

.. pragma:: NOUNPACK

    :where: top-level

    Instructs the compiler not to unpack a constructor field.

The ``NOUNPACK`` pragma indicates to the compiler that it should not
unpack the contents of a constructor field. Example: ::

    data T = T {-# NOUNPACK #-} !(Int,Int)

Even with the flags :ghc-flag:`-funbox-strict-fields` and :ghc-flag:`-O`, the
field of the constructor ``T`` is not unpacked.

.. _source-pragma:

``SOURCE`` pragma
-----------------

.. pragma:: SOURCE

    :where: after ``import`` statement

    Import a module by ``hs-boot`` file to break a module loop.

The ``{-# SOURCE #-}`` pragma is used only in ``import`` declarations,
to break a module loop. It is described in detail in
:ref:`mutual-recursion`.

.. _complete-pragma:

``COMPLETE`` pragmas
--------------------

.. pragma:: COMPLETE

    :where: at top level

    Specify the set of constructors or pattern synonyms which constitute a total
    match.

The ``COMPLETE`` pragma is used to inform the pattern match checker that a
certain set of patterns is complete and that any function which matches
on all the specified patterns is total.

The most common usage of ``COMPLETE`` pragmas is with
:ref:`pattern-synonyms`.
On its own, the checker is very naive and assumes that any match involving
a pattern synonym will fail. As a result, any pattern match on a
pattern synonym is regarded as
incomplete unless the user adds a catch-all case.

For example, the data types ``2 * A`` and ``A + A`` are isomorphic but some
computations are more naturally expressed in terms of one or the other. To
get the best of both worlds, we can choose one as our implementation and then
provide a set of pattern synonyms so that users can use the other representation
if they desire. We can then specify a ``COMPLETE`` pragma in order to
inform the pattern match checker that a function which matches on both ``LeftChoice``
and ``RightChoice`` is total. ::

    data Choice a = Choice Bool a

    pattern LeftChoice :: a -> Choice a
    pattern LeftChoice a = Choice False a

    pattern RightChoice :: a -> Choice a
    pattern RightChoice a = Choice True a

    {-# COMPLETE LeftChoice, RightChoice #-}

    foo :: Choice Int -> Int
    foo (LeftChoice n) = n * 2
    foo (RightChoice n) = n - 2

``COMPLETE`` pragmas are only used by the pattern match checker. If a function
definition matches on all the constructors specified in the pragma then the
compiler will produce no warning.

``COMPLETE`` pragmas can contain any data constructors or pattern
synonyms which are in scope, but must mention at least one data
constructor or pattern synonym defined in the same module.
``COMPLETE`` pragmas may only appear at the top level of a module.
Once defined, they are automatically imported and exported from
modules. ``COMPLETE`` pragmas should be thought of as asserting a
universal truth about a set of patterns and as a result, should not be
used to silence context specific incomplete match warnings.

When specifying a ``COMPLETE`` pragma, the result types of all patterns must
be consistent with each other. This is a sanity check as it would be impossible
to match on all the patterns if the types were inconsistent.

The result type must also be unambiguous. Usually this can be inferred but
when all the pattern synonyms in a group are polymorphic in the constructor
the user must provide a type signature. ::

    class LL f where
      go :: f a -> ()

    instance LL [] where
      go _ = ()

    pattern T :: LL f => f a
    pattern T <- (go -> ())

    {-# COMPLETE T :: [] #-}

    -- No warning
    foo :: [a] -> Int
    foo T = 5

.. _overlap-pragma:

``OVERLAPPING``, ``OVERLAPPABLE``, ``OVERLAPS``, and ``INCOHERENT`` pragmas
---------------------------------------------------------------------------

.. index::
   single: OVERLAPPING
   single: pragma; OVERLAPPING
   single: OVERLAPPABLE
   single: pragma; OVERLAPPABLE
   single: OVERLAPS
   single: pragma; OVERLAPS
   single: INCOHERENT
   single: pragma; INCOHERENT

.. pragma:: OVERLAPPING
.. pragma:: OVERLAPPABLE
.. pragma:: OVERLAPS
.. pragma:: INCOHERENT

    :where: on instance head

The pragmas ``OVERLAPPING``, ``OVERLAPPABLE``, ``OVERLAPS``,
``INCOHERENT`` are used to specify the overlap behavior for individual
instances, as described in Section :ref:`instance-overlap`. The pragmas
are written immediately after the ``instance`` keyword, like this:

::

    instance {-# OVERLAPPING #-} C t where ...

.. _rewrite-rules:

Rewrite rules
=============

.. index::
   single: rewrite rules

.. pragma:: RULES "⟨name⟩" forall ⟨binder⟩ ... . ⟨expr⟩ = ⟨expr⟩ ...

    :where: top-level

    Define a rewrite rule to be used to optimize a source program.

The programmer can specify rewrite rules as part of the source program
(in a pragma). Here is an example: ::

      {-# RULES
            "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
        #-}

Use the debug flag :ghc-flag:`-ddump-simpl-stats` to see what rules fired. If
you need more information, then :ghc-flag:`-ddump-rule-firings` shows you each
individual rule firing and :ghc-flag:`-ddump-rule-rewrites` also shows what the
code looks like before and after the rewrite.

.. ghc-flag:: -fenable-rewrite-rules
    :shortdesc: Switch on all rewrite rules (including rules generated by
        automatic specialisation of overloaded functions). Implied by
        :ghc-flag:`-O`.
    :type: dynamic
    :reverse: -fno-enable-rewrite-rules
    :category: optimization

    Allow the compiler to apply rewrite rules to the source program.

Syntax
------

From a syntactic point of view:

-  There may be zero or more rules in a :pragma:`RULES` pragma, separated by
   semicolons (which may be generated by the layout rule).

-  The layout rule applies in a pragma. Currently no new indentation
   level is set, so if you put several rules in single ``RULES`` pragma and
   wish to use layout to separate them, you must lay out the starting in
   the same column as the enclosing definitions. ::

         {-# RULES
               "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
               "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys
           #-}

   Furthermore, the closing ``#-}`` should start in a column to the
   right of the opening ``{-#``.

-  Each rule has a name, enclosed in double quotes. The name itself has
   no significance at all. It is only used when reporting how many times
   the rule fired.

-  A rule may optionally have a phase-control number (see
   :ref:`phase-control`), immediately after the name of the rule. Thus: ::

         {-# RULES
               "map/map" [2]  forall f g xs. map f (map g xs) = map (f.g) xs
           #-}

   The ``[2]`` means that the rule is active in Phase 2 and subsequent
   phases. The inverse notation ``[~2]`` is also accepted, meaning that
   the rule is active up to, but not including, Phase 2.

   Rules support the special phase-control notation ``[~]``, which means
   the rule is never active. This feature supports plugins (see
   :ref:`compiler-plugins`), by making it possible to define a RULE that
   is never run by GHC, but is nevertheless parsed, typechecked etc, so
   that it is available to the plugin.

-  Each (term) variable mentioned in a rule must either be in scope (e.g.
   ``map``), or bound by the ``forall`` (e.g. ``f``, ``g``, ``xs``). The
   variables bound by the ``forall`` are called the *pattern* variables.
   They are separated by spaces, just like in a type ``forall``.

-  A pattern variable may optionally have a type signature. If the type
   of the pattern variable is polymorphic, it *must* have a type
   signature. For example, here is the ``foldr/build`` rule: ::

       "fold/build"  forall k z (g::forall b. (a->b->b) -> b -> b) .
                     foldr k z (build g) = g k z

   Since ``g`` has a polymorphic type, it must have a type signature.

-  If :extension:`ExplicitForAll` is enabled, type/kind variables can also be
   explicitly bound. For example: ::

       {-# RULES "id" forall a. forall (x :: a). id @a x = x #-}

   When a type-level explicit ``forall`` is present, each type/kind variable
   mentioned must now also be either in scope or bound by the ``forall``. In
   particular, unlike some other places in Haskell, this means free kind
   variables will not be implicitly bound. For example: ::

       "this_is_bad" forall (c :: k). forall (x :: Proxy c) ...
       "this_is_ok"  forall k (c :: k). forall (x :: Proxy c) ...

   When bound type/kind variables are needed, both foralls must always be
   included, though if no pattern variables are needed, the second can be left
   empty. For example: ::

       {-# RULES "map/id" forall a. forall. map (id @a) = id @[a] #-}

-  The left hand side of a rule must consist of a top-level variable
   applied to arbitrary expressions. For example, this is *not* OK: ::

       "wrong1"   forall e1 e2.  case True of { True -> e1; False -> e2 } = e1
       "wrong2"   forall f.      f True = True
       "wrong3"   forall x.      Just x = Nothing

   In ``"wrong1"``, the LHS is not an application; in ``"wrong2"``, the
   LHS has a pattern variable in the head. In ``"wrong3"``, the LHS consists
   of a *constructor*, rather than a *variable*, applied to an argument.

-  A rule does not need to be in the same module as (any of) the
   variables it mentions, though of course they need to be in scope.

-  All rules are implicitly exported from the module, and are therefore
   in force in any module that imports the module that defined the rule,
   directly or indirectly. (That is, if A imports B, which imports C,
   then C's rules are in force when compiling A.) The situation is very
   similar to that for instance declarations.

-  Inside a :pragma:`RULE` "``forall``" is treated as a keyword, regardless of any
   other flag settings. Furthermore, inside a RULE, the language
   extension :extension:`ScopedTypeVariables` is automatically enabled; see
   :ref:`scoped-type-variables`.

-  Like other pragmas, :pragma:`RULE` pragmas are always checked for scope errors,
   and are typechecked. Typechecking means that the LHS and RHS of a
   rule are typechecked, and must have the same type. However, rules are
   only *enabled* if the :ghc-flag:`-fenable-rewrite-rules` flag is on (see
   :ref:`rule-semantics`).

.. _rule-semantics:

Semantics
---------

From a semantic point of view:

-  Rules are enabled (that is, used during optimisation) by the
   :ghc-flag:`-fenable-rewrite-rules` flag. This flag is implied by
   :ghc-flag:`-O`, and may be switched off (as usual) by
   :ghc-flag:`-fno-enable-rewrite-rules <-fenable-rewrite-rules>`. (NB: enabling
   :ghc-flag:`-fenable-rewrite-rules` without :ghc-flag:`-O` may not do what you
   expect, though, because without :ghc-flag:`-O` GHC ignores all optimisation
   information in interface files; see :ghc-flag:`-fignore-interface-pragmas`).
   Note that :ghc-flag:`-fenable-rewrite-rules` is an
   *optimisation* flag, and has no effect on parsing or typechecking.

-  Rules are regarded as left-to-right rewrite rules. When GHC finds an
   expression that is a substitution instance of the LHS of a rule, it
   replaces the expression by the (appropriately-substituted) RHS. By "a
   substitution instance" we mean that the LHS can be made equal to the
   expression by substituting for the pattern variables.

-  GHC makes absolutely no attempt to verify that the LHS and RHS of a
   rule have the same meaning. That is undecidable in general, and
   infeasible in most interesting cases. The responsibility is entirely
   the programmer's!

-  GHC makes no attempt to make sure that the rules are confluent or
   terminating. For example: ::

         "loop"        forall x y.  f x y = f y x

   This rule will cause the compiler to go into an infinite loop.

-  If more than one rule matches a call, GHC will choose one arbitrarily
   to apply.

-  GHC currently uses a very simple, syntactic, matching algorithm for
   matching a rule LHS with an expression. It seeks a substitution which
   makes the LHS and expression syntactically equal modulo alpha
   conversion. The pattern (rule), but not the expression, is
   eta-expanded if necessary. (Eta-expanding the expression can lead to
   laziness bugs.) But not beta conversion (that's called higher-order
   matching).

   Matching is carried out on GHC's intermediate language, which
   includes type abstractions and applications. So a rule only matches
   if the types match too. See :ref:`rule-spec` below.

-  GHC keeps trying to apply the rules as it optimises the program. For
   example, consider: ::

         let s = map f
             t = map g
         in
         s (t xs)

   The expression ``s (t xs)`` does not match the rule ``"map/map"``,
   but GHC will substitute for ``s`` and ``t``, giving an expression
   which does match. If ``s`` or ``t`` was (a) used more than once, and
   (b) large or a redex, then it would not be substituted, and the rule
   would not fire.

.. _rules-inline:

How rules interact with ``INLINE``/``NOINLINE`` pragmas
-------------------------------------------------------

Ordinary inlining happens at the same time as rule rewriting, which may
lead to unexpected results. Consider this (artificial) example ::

    f x = x
    g y = f y
    h z = g True

    {-# RULES "f" f True = False #-}

Since ``f``\'s right-hand side is small, it is inlined into ``g``, to
give ::

    g y = y

Now ``g`` is inlined into ``h``, but ``f``\'s :pragma:`RULE` has no chance to
fire. If instead GHC had first inlined ``g`` into ``h`` then there would have
been a better chance that ``f``\'s :pragma:`RULE` might fire.

The way to get predictable behaviour is to use a :pragma:`NOINLINE` pragma, or an
INLINE[⟨phase⟩] pragma, on ``f``, to ensure that it is not inlined until
its RULEs have had a chance to fire. The warning flag
:ghc-flag:`-Winline-rule-shadowing` (see :ref:`options-sanity`) warns about
this situation.

.. _conlike:

How rules interact with ``CONLIKE`` pragmas
-------------------------------------------

GHC is very cautious about duplicating work. For example, consider ::

    f k z xs = let xs = build g
               in ...(foldr k z xs)...sum xs...
    {-# RULES "foldr/build" forall k z g. foldr k z (build g) = g k z #-}

Since ``xs`` is used twice, GHC does not fire the foldr/build rule.
Rightly so, because it might take a lot of work to compute ``xs``, which
would be duplicated if the rule fired.

Sometimes, however, this approach is over-cautious, and we *do* want the
rule to fire, even though doing so would duplicate redex. There is no
way that GHC can work out when this is a good idea, so we provide the
``CONLIKE`` pragma to declare it, thus: ::

    {-# INLINE CONLIKE [1] f #-}
    f x = blah

``CONLIKE`` is a modifier to an ``INLINE`` or ``NOINLINE`` pragma. It specifies that
an application of ``f`` to one argument (in general, the number of arguments
to the left of the ``=`` sign) should be considered cheap enough to
duplicate, if such a duplication would make rule fire. (The name
"CONLIKE" is short for "constructor-like", because constructors
certainly have such a property.) The :pragma:`CONLIKE` pragma is a modifier to
:pragma:`INLINE`/:pragma:`NOINLINE` because it really only makes sense to match
``f`` on the LHS of a rule if you are sure that ``f`` is not going to be inlined
before the rule has a chance to fire.

.. _rules-class-methods:

How rules interact with class methods
-------------------------------------

Giving a RULE for a class method is a bad idea: ::

    class C a where
      op :: a -> a -> a

    instance C Bool where
      op x y = ...rhs for op at Bool...

    {-# RULES "f" op True y = False #-}

In this example, ``op`` is not an ordinary top-level function; it is a
class method. GHC rapidly rewrites any occurrences of
``op``\-used-at-type-Bool to a specialised function, say ``opBool``,
where ::

    opBool :: Bool -> Bool -> Bool
    opBool x y = ..rhs for op at Bool...

So the RULE never has a chance to fire, for just the same reasons as in
:ref:`rules-inline`.

The solution is to define the instance-specific function yourself, with
a pragma to prevent it being inlined too early, and give a RULE for it: ::

    instance C Bool where
      op = opBool

    opBool :: Bool -> Bool -> Bool
    {-# NOINLINE [1] opBool #-}
    opBool x y = ..rhs for op at Bool...

    {-# RULES "f" opBool True y = False #-}

If you want a RULE that truly applies to the overloaded class method,
the only way to do it is like this: ::

    class C a where
      op_c :: a -> a -> a

    op :: C a => a -> a -> a
    {-# NOINLINE [1] op #-}
    op = op_c

    {-# RULES "reassociate" op (op x y) z = op x (op y z) #-}

Now the inlining of ``op`` is delayed until the rule has a chance to
fire. The down-side is that instance declarations must define ``op_c``,
but all other uses should go via ``op``.

List fusion
-----------

The RULES mechanism is used to implement fusion (deforestation) of
common list functions. If a "good consumer" consumes an intermediate
list constructed by a "good producer", the intermediate list should be
eliminated entirely.

The following are good producers:

-  List comprehensions

-  Enumerations of ``Int``, ``Integer`` and ``Char`` (e.g.
   ``['a'..'z']``).

-  Explicit lists (e.g. ``[True, False]``)

-  The cons constructor (e.g ``3:4:[]``)

-  ``++``

-  ``map``

-  ``take``, ``filter``

-  ``iterate``, ``repeat``

-  ``zip``, ``zipWith``

The following are good consumers:

-  List comprehensions

-  ``array`` (on its second argument)

-  ``++`` (on its first argument)

-  ``foldr``

-  ``map``

-  ``take``, ``filter``

-  ``concat``

-  ``unzip``, ``unzip2``, ``unzip3``, ``unzip4``

-  ``zip``, ``zipWith`` (but on one argument only; if both are good
   producers, ``zip`` will fuse with one but not the other)

-  ``partition``

-  ``head``

-  ``and``, ``or``, ``any``, ``all``

-  ``sequence_``

-  ``msum``

So, for example, the following should generate no intermediate lists: ::

    array (1,10) [(i,i*i) | i <- map (+ 1) [0..9]]

This list could readily be extended; if there are Prelude functions that
you use a lot which are not included, please tell us.

If you want to write your own good consumers or producers, look at the
Prelude definitions of the above functions to see how to do so.

.. _rule-spec:

Specialisation
--------------

Rewrite rules can be used to get the same effect as a feature present in
earlier versions of GHC. For example, suppose that: ::

    genericLookup :: Ord a => Table a b   -> a   -> b
    intLookup     ::          Table Int b -> Int -> b

where ``intLookup`` is an implementation of ``genericLookup`` that works
very fast for keys of type ``Int``. You might wish to tell GHC to use
``intLookup`` instead of ``genericLookup`` whenever the latter was
called with type ``Table Int b -> Int -> b``. It used to be possible to
write ::

    {-# SPECIALIZE genericLookup :: Table Int b -> Int -> b = intLookup #-}

This feature is no longer in GHC, but rewrite rules let you do the same
thing: ::

    {-# RULES "genericLookup/Int" genericLookup = intLookup #-}

This slightly odd-looking rule instructs GHC to replace
``genericLookup`` by ``intLookup`` *whenever the types match*. What is
more, this rule does not need to be in the same file as
``genericLookup``, unlike the ``SPECIALIZE`` pragmas which currently do
(so that they have an original definition available to specialise).

It is *Your Responsibility* to make sure that ``intLookup`` really
behaves as a specialised version of ``genericLookup``!!!

An example in which using ``RULES`` for specialisation will Win Big: ::

    toDouble :: Real a => a -> Double
    toDouble = fromRational . toRational

    {-# RULES "toDouble/Int" toDouble = i2d #-}
    i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly

The ``i2d`` function is virtually one machine instruction; the default
conversion—via an intermediate ``Rational``\-is obscenely expensive by
comparison.

.. _controlling-rules:

Controlling what's going on in rewrite rules
--------------------------------------------

-  Use :ghc-flag:`-ddump-rules` to see the rules that are defined *in this
   module*. This includes rules generated by the specialisation pass,
   but excludes rules imported from other modules.

-  Use :ghc-flag:`-ddump-simpl-stats` to see what rules are being fired. If you
   add :ghc-flag:`-dppr-debug` you get a more detailed listing.

-  Use :ghc-flag:`-ddump-rule-firings` or :ghc-flag:`-ddump-rule-rewrites` to see in
   great detail what rules are being fired. If you add :ghc-flag:`-dppr-debug`
   you get a still more detailed listing.

-  The definition of (say) ``build`` in ``GHC/Base.hs`` looks like
   this: ::

               build   :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
               {-# INLINE build #-}
               build g = g (:) []

   Notice the :pragma:`INLINE`! That prevents ``(:)`` from being inlined when
   compiling ``PrelBase``, so that an importing module will “see” the
   ``(:)``, and can match it on the LHS of a rule. ``INLINE`` prevents
   any inlining happening in the RHS of the ``INLINE`` thing. I regret
   the delicacy of this.

-  In ``libraries/base/GHC/Base.hs`` look at the rules for ``map`` to
   see how to write rules that will do fusion and yet give an efficient
   program even if fusion doesn't happen. More rules in
   ``GHC/List.hs``.

.. _special-ids:

Special built-in functions
==========================

GHC has a few built-in functions with special behaviour. In particular:

-  :base-ref:`GHC.Exts.inline` allows control over inlining on a per-call-site basis.

-  :base-ref:`GHC.Exts.lazy` restrains the strictness analyser.

-  :base-ref:`GHC.Exts.oneShot` gives a hint to the compiler about how often a
   function is being called.

.. _generic-classes:

Generic classes
===============

GHC used to have an implementation of generic classes as defined in the
paper "Derivable type classes", Ralf Hinze and Simon Peyton Jones,
Haskell Workshop, Montreal Sept 2000, pp. 94-105. These have been removed
and replaced by the more general `support for generic
programming <#generic-programming>`__.

.. _generic-programming:

Generic programming
===================

Using a combination of :extension:`DeriveGeneric`,
:extension:`DefaultSignatures`, and :extension:`DeriveAnyClass`, you can
easily do datatype-generic programming using the :base-ref:`GHC.Generics.`
framework. This section gives a very brief overview of how to do it.

Generic programming support in GHC allows defining classes with methods
that do not need a user specification when instantiating: the method
body is automatically derived by GHC. This is similar to what happens
for standard classes such as ``Read`` and ``Show``, for instance, but
now for user-defined classes.

Deriving representations
------------------------

The first thing we need is generic representations. The ``GHC.Generics``
module defines a couple of primitive types that are used to represent
Haskell datatypes: ::

    -- | Unit: used for constructors without arguments
    data U1 p = U1

    -- | Constants, additional parameters and recursion of kind Type
    newtype K1 i c p = K1 { unK1 :: c }

    -- | Meta-information (constructor names, etc.)
    newtype M1 i c f p = M1 { unM1 :: f p }

    -- | Sums: encode choice between constructors
    infixr 5 :+:
    data (:+:) f g p = L1 (f p) | R1 (g p)

    -- | Products: encode multiple arguments to constructors
    infixr 6 :*:
    data (:*:) f g p = f p :*: g p

The ``Generic`` and ``Generic1`` classes mediate between user-defined
datatypes and their internal representation as a sum-of-products: ::

    class Generic a where
      -- Encode the representation of a user datatype
      type Rep a :: Type -> Type
      -- Convert from the datatype to its representation
      from  :: a -> (Rep a) x
      -- Convert from the representation to the datatype
      to    :: (Rep a) x -> a

    class Generic1 (f :: k -> Type) where
      type Rep1 f :: k -> Type

      from1  :: f a -> Rep1 f a
      to1    :: Rep1 f a -> f a

``Generic1`` is used for functions that can only be defined over type
containers, such as ``map``. Note that ``Generic1`` ranges over types of kind
``Type -> Type`` by default, but if the :extension:`PolyKinds` extension is
enabled, then it can range of types of kind ``k -> Type``, for any kind ``k``.

.. extension:: DeriveGeneric
    :shortdesc: Enable deriving for the Generic class.

    :since: 7.2.1

    Allow automatic deriving of instances for the ``Generic`` typeclass.


Instances of these classes can be derived by GHC with the
:extension:`DeriveGeneric` extension, and are necessary to be able to define
generic instances automatically.

For example, a user-defined datatype of trees ::

    data UserTree a = Node a (UserTree a) (UserTree a) | Leaf

in a ``Main`` module in a package named ``foo`` will get the following
representation: ::

    instance Generic (UserTree a) where
      -- Representation type
      type Rep (UserTree a) =
        M1 D ('MetaData "UserTree" "Main" "package-name" 'False) (
              M1 C ('MetaCons "Node" 'PrefixI 'False) (
                    M1 S ('MetaSel 'Nothing
                                   'NoSourceUnpackedness
                                   'NoSourceStrictness
                                   'DecidedLazy)
                         (K1 R a)
                :*: M1 S ('MetaSel 'Nothing
                                   'NoSourceUnpackedness
                                   'NoSourceStrictness
                                   'DecidedLazy)
                         (K1 R (UserTree a))
                :*: M1 S ('MetaSel 'Nothing
                                   'NoSourceUnpackedness
                                   'NoSourceStrictness
                                   'DecidedLazy)
                         (K1 R (UserTree a)))
          :+: M1 C ('MetaCons "Leaf" 'PrefixI 'False) U1)

      -- Conversion functions
      from (Node x l r) = M1 (L1 (M1 (M1 (K1 x) :*: M1 (K1 l) :*: M1 (K1 r))))
      from Leaf         = M1 (R1 (M1 U1))
      to (M1 (L1 (M1 (M1 (K1 x) :*: M1 (K1 l) :*: M1 (K1 r))))) = Node x l r
      to (M1 (R1 (M1 U1)))                                      = Leaf

This representation is generated automatically if a ``deriving Generic``
clause is attached to the datatype. `Standalone
deriving <#stand-alone-deriving>`__ can also be used.

Writing generic functions
-------------------------

A generic function is defined by creating a class and giving instances
for each of the representation types of ``GHC.Generics``. As an example
we show generic serialization: ::

    data Bin = O | I

    class GSerialize f where
      gput :: f a -> [Bin]

    instance GSerialize U1 where
      gput U1 = []

    instance (GSerialize a, GSerialize b) => GSerialize (a :*: b) where
      gput (x :*: y) = gput x ++ gput y

    instance (GSerialize a, GSerialize b) => GSerialize (a :+: b) where
      gput (L1 x) = O : gput x
      gput (R1 x) = I : gput x

    instance (GSerialize a) => GSerialize (M1 i c a) where
      gput (M1 x) = gput x

    instance (Serialize a) => GSerialize (K1 i a) where
      gput (K1 x) = put x

A caveat: this encoding strategy may not be reliable across different versions
of GHC. When deriving a ``Generic`` instance is free to choose any nesting of
``:+:`` and ``:*:`` it chooses, so if GHC chooses ``(a :+: b) :+: c``, then the
encoding for ``a`` would be ``[O, O]``, ``b`` would be ``[O, I]``, and ``c``
would be ``[I]``. However, if GHC chooses ``a :+: (b :+: c)``, then the
encoding for ``a`` would be ``[O]``, ``b`` would be ``[I, O]``, and ``c`` would
be ``[I, I]``. (In practice, the current implementation tries to produce a
more-or-less balanced nesting of ``:+:`` and ``:*:`` so that the traversal of
the structure of the datatype from the root to a particular component can be
performed in logarithmic rather than linear time.)

Typically this ``GSerialize`` class will not be exported, as it only makes
sense to have instances for the representation types.

Unlifted representation types
-----------------------------

The data family ``URec`` is provided to enable generic programming over
datatypes with certain unlifted arguments. There are six instances corresponding
to common unlifted types: ::

    data family URec a p

    data instance URec (Ptr ()) p = UAddr   { uAddr#   :: Addr#   }
    data instance URec Char     p = UChar   { uChar#   :: Char#   }
    data instance URec Double   p = UDouble { uDouble# :: Double# }
    data instance URec Int      p = UInt    { uInt#    :: Int#    }
    data instance URec Float    p = UFloat  { uFloat#  :: Float#  }
    data instance URec Word     p = UWord   { uWord#   :: Word#   }

Six type synonyms are provided for convenience: ::

    type UAddr   = URec (Ptr ())
    type UChar   = URec Char
    type UDouble = URec Double
    type UFloat  = URec Float
    type UInt    = URec Int
    type UWord   = URec Word

As an example, this data declaration: ::

    data IntHash = IntHash Int#
      deriving Generic

results in the following ``Generic`` instance: ::

    instance 'Generic' IntHash where
      type 'Rep' IntHash =
        'D1' ('MetaData "IntHash" "Main" "package-name" 'False)
          ('C1' ('MetaCons "IntHash" 'PrefixI 'False)
            ('S1' ('MetaSel 'Nothing
                            'NoSourceUnpackedness
                            'NoSourceStrictness
                            'DecidedLazy)
                  'UInt'))

A user could provide, for example, a ``GSerialize UInt`` instance so that a
``Serialize IntHash`` instance could be easily defined in terms of
``GSerialize``.

Generic defaults
----------------

The only thing left to do now is to define a "front-end" class, which is
exposed to the user: ::

    class Serialize a where
      put :: a -> [Bin]

      default put :: (Generic a, GSerialize (Rep a)) => a -> [Bin]
      put = gput . from

Here we use a `default signature <#class-default-signatures>`__ to
specify that the user does not have to provide an implementation for
``put``, as long as there is a ``Generic`` instance for the type to
instantiate. For the ``UserTree`` type, for instance, the user can just
write: ::

    instance (Serialize a) => Serialize (UserTree a)

The default method for ``put`` is then used, corresponding to the
generic implementation of serialization. If you are using
:extension:`DeriveAnyClass`, the same instance is generated by simply attaching
a ``deriving Serialize`` clause to the ``UserTree`` datatype
declaration. For more examples of generic functions please refer to the
`generic-deriving <http://hackage.haskell.org/package/generic-deriving>`__
package on Hackage.

More information
----------------

For more details please refer to the `Haskell Wiki
page <http://www.haskell.org/haskellwiki/GHC.Generics>`__ or the
original paper [Generics2010]_.

.. [Generics2010] Jose Pedro Magalhaes, Atze Dijkstra, Johan Jeuring, and Andres Loeh.
   `A generic deriving mechanism for Haskell
   <http://dreixel.net/research/pdf/gdmh.pdf>`__. Proceedings of
   the third ACM Haskell symposium on Haskell (Haskell'2010), pp. 37-48,
   ACM, 2010.

.. _roles:

Roles
=====

.. index::
   single: roles

Using :extension:`GeneralizedNewtypeDeriving`
(:ref:`newtype-deriving`), a programmer can take existing
instances of classes and "lift" these into instances of that class for a
newtype. However, this is not always safe. For example, consider the
following:

::

      newtype Age = MkAge { unAge :: Int }

      type family Inspect x
      type instance Inspect Age = Int
      type instance Inspect Int = Bool

      class BadIdea a where
        bad :: a -> Inspect a

      instance BadIdea Int where
        bad = (> 0)

      deriving instance BadIdea Age    -- not allowed!

If the derived instance were allowed, what would the type of its method
``bad`` be? It would seem to be ``Age -> Inspect Age``, which is
equivalent to ``Age -> Int``, according to the type family ``Inspect``.
Yet, if we simply adapt the implementation from the instance for
``Int``, the implementation for ``bad`` produces a ``Bool``, and we have
trouble.

The way to identify such situations is to have *roles* assigned to type
variables of datatypes, classes, and type synonyms.

Roles as implemented in GHC are a from a simplified version of the work
described in `Generative type abstraction and type-level
computation <http://www.seas.upenn.edu/~sweirich/papers/popl163af-weirich.pdf>`__,
published at POPL 2011.

.. _nominal-representational-and-phantom:

Nominal, Representational, and Phantom
--------------------------------------

.. index::
   single: representational; role
   single: nominal; role
   single: phantom; role

The goal of the roles system is to track when two types have the same
underlying representation. In the example above, ``Age`` and ``Int``
have the same representation. But, the corresponding instances of
``BadIdea`` would *not* have the same representation, because the types
of the implementations of ``bad`` would be different.

Suppose we have two uses of a type constructor, each applied to the same
parameters except for one difference. (For example, ``T Age Bool c`` and
``T Int Bool c`` for some type ``T``.) The role of a type parameter says
what we need to know about the two differing type arguments in order to
know that the two outer types have the same representation (in the
example, what must be true about ``Age`` and ``Int`` in order to show
that ``T Age Bool c`` has the same representation as ``T Int Bool c``).

GHC supports three different roles for type parameters: nominal,
representational, and phantom. If a type parameter has a nominal role,
then the two types that differ must not actually differ at all: they
must be identical (after type family reduction). If a type parameter has
a representational role, then the two types must have the same
representation. (If ``T``\'s first parameter's role is representational,
then ``T Age Bool c`` and ``T Int Bool c`` would have the same
representation, because ``Age`` and ``Int`` have the same
representation.) If a type parameter has a phantom role, then we need no
further information.

Here are some examples: ::

      data Simple a = MkSimple a          -- a has role representational

      type family F
      type instance F Int = Bool
      type instance F Age = Char

      data Complex a = MkComplex (F a)    -- a has role nominal

      data Phant a = MkPhant Bool         -- a has role phantom

The type ``Simple`` has its parameter at role representational, which is
generally the most common case. ``Simple Age`` would have the same
representation as ``Simple Int``. The type ``Complex``, on the other
hand, has its parameter at role nominal, because ``Complex Age`` and
``Complex Int`` are *not* the same. Lastly, ``Phant Age`` and
``Phant Bool`` have the same representation, even though ``Age`` and
``Bool`` are unrelated.

.. _role-inference:

Role inference
--------------

What role should a given type parameter should have? GHC performs role
inference to determine the correct role for every parameter. It starts
with a few base facts: ``(->)`` has two representational parameters;
``(~)`` has two nominal parameters; all type families' parameters are
nominal; and all GADT-like parameters are nominal. Then, these facts are
propagated to all places where these types are used. The default role
for datatypes and synonyms is phantom; the default role for classes is
nominal. Thus, for datatypes and synonyms, any parameters unused in the
right-hand side (or used only in other types in phantom positions) will
be phantom. Whenever a parameter is used in a representational position
(that is, used as a type argument to a constructor whose corresponding
variable is at role representational), we raise its role from phantom to
representational. Similarly, when a parameter is used in a nominal
position, its role is upgraded to nominal. We never downgrade a role
from nominal to phantom or representational, or from representational to
phantom. In this way, we infer the most-general role for each parameter.

Classes have their roles default to nominal to promote coherence of
class instances. If a ``C Int`` were stored in a datatype, it would be
quite bad if that were somehow changed into a ``C Age`` somewhere,
especially if another ``C Age`` had been declared!

There is one particularly tricky case that should be explained: ::

      data Tricky a b = MkTricky (a b)

What should ``Tricky``'s roles be? At first blush, it would seem that
both ``a`` and ``b`` should be at role representational, since both are
used in the right-hand side and neither is involved in a type family.
However, this would be wrong, as the following example shows: ::

      data Nom a = MkNom (F a)   -- type family F from example above

Is ``Tricky Nom Age`` representationally equal to ``Tricky Nom Int``?
No! The former stores a ``Char`` and the latter stores a ``Bool``. The
solution to this is to require all parameters to type variables to have
role nominal. Thus, GHC would infer role representational for ``a`` but
role nominal for ``b``.

.. _role-annotations:

Role annotations
----------------

.. extension:: RoleAnnotations
    :shortdesc: Enable role annotations.

    :since: 7.8.1

    Allow role annotation syntax.

Sometimes the programmer wants to constrain the inference process. For
example, the base library contains the following definition: ::

      data Ptr a = Ptr Addr#

The idea is that ``a`` should really be a representational parameter,
but role inference assigns it to phantom. This makes some level of
sense: a pointer to an ``Int`` really is representationally the same as
a pointer to a ``Bool``. But, that's not at all how we want to use
``Ptr``\ s! So, we want to be able to say ::

      type role Ptr representational
      data Ptr a = Ptr Addr#

The ``type role`` (enabled with :extension:`RoleAnnotations`) declaration
forces the parameter ``a`` to be at role representational, not role
phantom. GHC then checks the user-supplied roles to make sure they don't
break any promises. It would be bad, for example, if the user could make
``BadIdea``\'s role be representational.

As another example, we can consider a type ``Set a`` that represents a
set of data, ordered according to ``a``\'s ``Ord`` instance. While it
would generally be type-safe to consider ``a`` to be at role
representational, it is possible that a ``newtype`` and its base type
have *different* orderings encoded in their respective ``Ord``
instances. This would lead to misbehavior at runtime. So, the author of
the ``Set`` datatype would like its parameter to be at role nominal.
This would be done with a declaration ::

      type role Set nominal

Role annotations can also be used should a programmer wish to write a
class with a representational (or phantom) role. However, as a class
with non-nominal roles can quickly lead to class instance incoherence,
it is necessary to also specify :extension:`IncoherentInstances` to allow
non-nominal roles for classes.

The other place where role annotations may be necessary are in
``hs-boot`` files (:ref:`mutual-recursion`), where the right-hand sides
of definitions can be omitted. As usual, the types/classes declared in
an ``hs-boot`` file must match up with the definitions in the ``hs``
file, including down to the roles. The default role for datatypes is
representational in ``hs-boot`` files, corresponding to the common use
case.

Role annotations are allowed on data, newtype, and class declarations. A
role annotation declaration starts with ``type role`` and is followed by
one role listing for each parameter of the type. (This parameter count
includes parameters implicitly specified by a kind signature in a
GADT-style data or newtype declaration.) Each role listing is a role
(``nominal``, ``representational``, or ``phantom``) or a ``_``. Using a
``_`` says that GHC should infer that role. The role annotation may go
anywhere in the same module as the datatype or class definition (much
like a value-level type signature). Here are some examples: ::

      type role T1 _ phantom
      data T1 a b = MkT1 a     -- b is not used; annotation is fine but unnecessary

      type role T2 _ phantom
      data T2 a b = MkT2 b     -- ERROR: b is used and cannot be phantom

      type role T3 _ nominal
      data T3 a b = MkT3 a     -- OK: nominal is higher than necessary, but safe

      type role T4 nominal
      data T4 a = MkT4 (a Int) -- OK, but nominal is higher than necessary

      type role C representational _   -- OK, with -XIncoherentInstances
      class C a b where ...    -- OK, b will get a nominal role

      type role X nominal
      type X a = ...           -- ERROR: role annotations not allowed for type synonyms

.. _hascallstack:

HasCallStack
============

``GHC.Stack.HasCallStack`` is a lightweight method of obtaining a
partial call-stack at any point in the program.

A function can request its call-site with the ``HasCallStack`` constraint
and access it as a Haskell value by using ``callStack``.

One can then use functions from ``GHC.Stack`` to inspect or pretty
print (as is done in ``f`` below) the call stack.

   f :: HasCallStack => IO ()
   f = putStrLn (prettyCallStack callStack)

   g :: HasCallStack => IO ()
   g = f

Evaluating ``f`` directly shows a call stack with a single entry,
while evaluating ``g``, which also requests its call-site, shows
two entries, one for each computation "annotated" with
``HasCallStack``.

.. code-block:: none

   ghci> f
   CallStack (from HasCallStack):
     f, called at <interactive>:19:1 in interactive:Ghci1
   ghci> g
   CallStack (from HasCallStack):
     f, called at <interactive>:17:5 in main:Main
     g, called at <interactive>:20:1 in interactive:Ghci2

The ``error`` function from the Prelude supports printing the call stack that
led to the error in addition to the usual error message:

.. code-block:: none

   ghci> error "bad"
   *** Exception: bad
   CallStack (from HasCallStack):
     error, called at <interactive>:25:1 in interactive:Ghci5

The call stack here consists of a single entry, pinpointing the source
of the call to ``error``. However, by annotating several computations
with ``HasCallStack``, figuring out the exact circumstances and sequences
of calls that lead to a call to ``error`` becomes a lot easier, as demonstrated
with the simple example below. ::

   f :: HasCallStack => IO ()
   f = error "bad bad bad"

   g :: HasCallStack => IO ()
   g = f

   h :: HasCallStack => IO ()
   h = g

.. code-block:: none

   ghci> h
   *** Exception: bad bad bad
   CallStack (from HasCallStack):
     error, called at call-stack.hs:4:5 in main:Main
     f, called at call-stack.hs:7:5 in main:Main
     g, called at call-stack.hs:10:5 in main:Main
     h, called at <interactive>:28:1 in interactive:Ghci1

The ``CallStack`` will only extend as far as the types allow it, for
example ::

   myHead :: HasCallStack => [a] -> a
   myHead []     = errorWithCallStack "empty"
   myHead (x:xs) = x

   bad :: Int
   bad = myHead []

.. code-block:: none

   ghci> bad
   *** Exception: empty
   CallStack (from HasCallStack):
     errorWithCallStack, called at Bad.hs:8:15 in main:Bad
     myHead, called at Bad.hs:12:7 in main:Bad

includes the call-site of ``errorWithCallStack`` in ``myHead``, and of
``myHead`` in ``bad``, but not the call-site of ``bad`` at the GHCi
prompt.

GHC solves ``HasCallStack`` constraints in two steps:

1. If there is a ``CallStack`` in scope -- i.e. the enclosing definition
   has a ``HasCallStack`` constraint -- GHC will push the new call-site
   onto the existing ``CallStack``.

2. Otherwise GHC will solve the ``HasCallStack`` constraint for the
   singleton ``CallStack`` containing just the current call-site.

Importantly, GHC will **never** infer a ``HasCallStack`` constraint,
you must request it explicitly.

``CallStack`` is kept abstract, but GHC provides a function ::

   getCallStack :: CallStack -> [(String, SrcLoc)]

to access the individual call-sites in the stack. The ``String`` is the
name of the function that was called, and the ``SrcLoc`` provides the
package, module, and file name, as well as the line and column numbers.

``GHC.Stack`` additionally exports a function ``withFrozenCallStack`` that
allows users to freeze the current ``CallStack``, preventing any future push
operations from having an effect. This can be used by library authors
to prevent ``CallStack``\s from exposing unnecessary implementation
details. Consider the ``myHead`` example above, the ``errorWithCallStack`` line in
the printed stack is not particularly enlightening, so we might choose
to suppress it by freezing the ``CallStack`` that we pass to ``errorWithCallStack``. ::

   myHead :: HasCallStack => [a] -> a
   myHead []     = withFrozenCallStack (errorWithCallStack "empty")
   myHead (x:xs) = x

.. code-block:: none

   ghci> myHead []
   *** Exception: empty
   CallStack (from HasCallStack):
     myHead, called at Bad.hs:12:7 in main:Bad

**NOTE**: The intrepid user may notice that ``HasCallStack`` is just an
alias for an implicit parameter ``?callStack :: CallStack``. This is an
implementation detail and **should not** be considered part of the
``CallStack`` API, we may decide to change the implementation in the
future.

Compared with other sources of stack traces
-------------------------------------------

``HasCallStack`` does not interact with the RTS and does not require
compilation with ``-prof``. On the other hand, as the ``CallStack`` is
built up explicitly via the ``HasCallStack`` constraints, it will
generally not contain as much information as the simulated call-stacks
maintained by the RTS.