File: optionparser.h

package info (click to toggle)
gyoto 1.3.1-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 8,588 kB
  • sloc: cpp: 33,490; sh: 18,775; xml: 2,633; python: 1,424; makefile: 681; ansic: 314
file content (2815 lines) | stat: -rw-r--r-- 101,043 bytes parent folder | download | duplicates (3)
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
/*
 * The Lean Mean C++ Option Parser
 *
 * Copyright (C) 2012 Matthias S. Benkmann
 *
 * The "Software" in the following 2 paragraphs refers to this file containing
 * the code to The Lean Mean C++ Option Parser.
 * The "Software" does NOT refer to any other files which you
 * may have received alongside this file (e.g. as part of a larger project that
 * incorporates The Lean Mean C++ Option Parser).
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software, to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to permit
 * persons to whom the Software is furnished to do so, subject to the following
 * conditions:
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/*
 * NOTE: It is recommended that you read the processed HTML doxygen documentation
 * rather than this source. If you don't know doxygen, it's like javadoc for C++.
 * If you don't want to install doxygen you can find a copy of the processed
 * documentation at
 *
 * http://optionparser.sourceforge.net/
 *
 */

/**
 * @file
 *
 * @brief This is the only file required to use The Lean Mean C++ Option Parser.
 *        Just \#include it and you're set.
 *
 * The Lean Mean C++ Option Parser handles the program's command line arguments 
 * (argc, argv).
 * It supports the short and long option formats of getopt(), getopt_long() 
 * and getopt_long_only() but has a more convenient interface.
 * The following features set it apart from other option parsers:
 *
 * @par Highlights:
 * <ul style="padding-left:1em;margin-left:0">
 * <li> It is a header-only library. Just <code>\#include "optionparser.h"</code> and you're set.
 * <li> It is freestanding. There are no dependencies whatsoever, not even the
 *      C or C++ standard library.
 * <li> It has a usage message formatter that supports column alignment and
 *      line wrapping. This aids localization because it adapts to
 *      translated strings that are shorter or longer (even if they contain
 *      Asian wide characters).
 * <li> Unlike getopt() and derivatives it doesn't force you to loop through
 *     options sequentially. Instead you can access options directly like this:
 *     <ul style="margin-top:.5em">
 *     <li> Test for presence of a switch in the argument vector:
 *      @code if ( options[QUIET] ) ... @endcode
 *     <li> Evaluate --enable-foo/--disable-foo pair where the last one used wins:
 *     @code if ( options[FOO].last()->type() == DISABLE ) ... @endcode
 *     <li> Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose):
 *     @code int verbosity = options[VERBOSE].count(); @endcode
 *     <li> Iterate over all --file=&lt;fname> arguments:
 *     @code for (Option* opt = options[FILE]; opt; opt = opt->next())
 *   fname = opt->arg; ... @endcode
 *     <li> If you really want to, you can still process all arguments in order:
 *     @code
 *   for (int i = 0; i < p.optionsCount(); ++i) {
 *     Option& opt = buffer[i];
 *     switch(opt.index()) {
 *       case HELP:    ...
 *       case VERBOSE: ...
 *       case FILE:    fname = opt.arg; ...
 *       case UNKNOWN: ...
 *     @endcode
 *     </ul>
 * </ul> @n
 * Despite these features the code size remains tiny. 
 * It is smaller than <a href="http://uclibc.org">uClibc</a>'s GNU getopt() and just a
 * couple 100 bytes larger than uClibc's SUSv3 getopt(). @n
 * (This does not include the usage formatter, of course. But you don't have to use that.)
 *
 * @par Download:
 * Tarball with examples and test programs:
 * <a style="font-size:larger;font-weight:bold" href="http://sourceforge.net/projects/optionparser/files/optionparser-1.3.tar.gz/download">optionparser-1.3.tar.gz</a> @n
 * Just the header (this is all you really need):
 * <a style="font-size:larger;font-weight:bold" href="http://optionparser.sourceforge.net/optionparser.h">optionparser.h</a>
 *
 * @par Changelog:
 * <b>Version 1.3:</b> Compatible with Microsoft Visual C++. @n
 * <b>Version 1.2:</b> Added @ref option::Option::namelen "Option::namelen" and removed the extraction
 *                     of short option characters into a special buffer. @n
 *                     Changed @ref option::Arg::Optional "Arg::Optional" to accept arguments if they are attached
 *                     rather than separate. This is what GNU getopt() does and how POSIX recommends
 *                     utilities should interpret their arguments.@n
 * <b>Version 1.1:</b> Optional mode with argument reordering as done by GNU getopt(), so that
 *                     options and non-options can be mixed. See
 *                     @ref option::Parser::parse() "Parser::parse()".
 *
 * @par Feedback:
 * Send questions, bug reports, feature requests etc. to: <tt><b>optionparser-feedback<span id="antispam">&nbsp;(a)&nbsp;</span>lists.sourceforge.net</b></tt>
 * @htmlonly <script type="text/javascript">document.getElementById("antispam").innerHTML="@"</script> @endhtmlonly
 *
 *
 * @par Example program:
 * (Note: @c option::* identifiers are links that take you to their documentation.)
 * @code
 * #include <iostream>
 * #include "optionparser.h"
 *
 * enum  optionIndex { UNKNOWN, HELP, PLUS };
 * const option::Descriptor usage[] =
 * {
 *  {UNKNOWN, 0,"" , ""    ,option::Arg::None, "USAGE: example [options]\n\n"
 *                                             "Options:" },
 *  {HELP,    0,"" , "help",option::Arg::None, "  --help  \tPrint usage and exit." },
 *  {PLUS,    0,"p", "plus",option::Arg::None, "  --plus, -p  \tIncrement count." },
 *  {UNKNOWN, 0,"" ,  ""   ,option::Arg::None, "\nExamples:\n"
 *                                             "  example --unknown -- --this_is_no_option\n"
 *                                             "  example -unk --plus -ppp file1 file2\n" },
 *  {0,0,0,0,0,0}
 * };
 *
 * int main(int argc, char* argv[])
 * {
 *   argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present
 *   option::Stats  stats(usage, argc, argv);
 *   option::Option options[stats.options_max], buffer[stats.buffer_max];
 *   option::Parser parse(usage, argc, argv, options, buffer);
 *
 *   if (parse.error())
 *     return 1;
 *
 *   if (options[HELP] || argc == 0) {
 *     option::printUsage(std::cout, usage);
 *     return 0;
 *   }
 *
 *   std::cout << "--plus count: " <<
 *     options[PLUS].count() << "\n";
 *
 *   for (option::Option* opt = options[UNKNOWN]; opt; opt = opt->next())
 *     std::cout << "Unknown option: " << opt->name << "\n";
 *
 *   for (int i = 0; i < parse.nonOptionsCount(); ++i)
 *     std::cout << "Non-option #" << i << ": " << parse.nonOption(i) << "\n";
 * }
 * @endcode
 *
 * @par Option syntax:
 * @li The Lean Mean C++ Option Parser follows POSIX <code>getopt()</code> conventions and supports
 *     GNU-style <code>getopt_long()</code> long options as well as Perl-style single-minus
 *     long options (<code>getopt_long_only()</code>).
 * @li short options have the format @c -X where @c X is any character that fits in a char.
 * @li short options can be grouped, i.e. <code>-X -Y</code> is equivalent to @c -XY.
 * @li a short option may take an argument either separate (<code>-X foo</code>) or
 *     attached (@c -Xfoo). You can make the parser accept the additional format @c -X=foo by
 *     registering @c X as a long option (in addition to being a short option) and
 *     enabling single-minus long options.
 * @li an argument-taking short option may be grouped if it is the last in the group, e.g.
 *     @c -ABCXfoo or <code> -ABCX foo </code> (@c foo is the argument to the @c -X option).
 * @li a lone minus character @c '-' is not treated as an option. It is customarily used where
 *     a file name is expected to refer to stdin or stdout.
 * @li long options have the format @c --option-name.
 * @li the option-name of a long option can be anything and include any characters.
 *     Even @c = characters will work, but don't do that.
 * @li [optional] long options may be abbreviated as long as the abbreviation is unambiguous.
 *     You can set a minimum length for abbreviations.
 * @li [optional] long options may begin with a single minus. The double minus form is always
 *     accepted, too.
 * @li a long option may take an argument either separate (<code> --option arg </code>) or
 *     attached (<code> --option=arg </code>). In the attached form the equals sign is mandatory.
 * @li an empty string can be passed as an attached long option argument: <code> --option-name= </code>.
 *     Note the distinction between an empty string as argument and no argument at all.
 * @li an empty string is permitted as separate argument to both long and short options.
 * @li Arguments to both short and long options may start with a @c '-' character. E.g.
 *     <code> -X-X </code>, <code>-X -X</code> or <code> --long-X=-X </code>. If @c -X
 *     and @c --long-X take an argument, that argument will be @c "-X" in all 3 cases.
 * @li If using the built-in @ref option::Arg::Optional "Arg::Optional", optional arguments must
 *     be attached.
 * @li the special option @c -- (i.e. without a name) terminates the list of
 *     options. Everything that follows is a non-option argument, even if it starts with
 *     a @c '-' character. The @c -- itself will not appear in the parse results.
 * @li the first argument that doesn't start with @c '-' or @c '--' and does not belong to
 *     a preceding argument-taking option, will terminate the option list and is the
 *     first non-option argument. All following command line arguments are treated as
 *     non-option arguments, even if they start with @c '-' . @n
 *     NOTE: This behaviour is mandated by POSIX, but GNU getopt() only honours this if it is
 *     explicitly requested (e.g. by setting POSIXLY_CORRECT). @n
 *     You can enable the GNU behaviour by passing @c true as first argument to
 *     e.g. @ref option::Parser::parse() "Parser::parse()".
 * @li Arguments that look like options (i.e. @c '-' followed by at least 1 character) but
 *     aren't, are NOT treated as non-option arguments. They are treated as unknown options and
 *     are collected into a list of unknown options for error reporting. @n
 *     This means that in order to pass a first non-option
 *     argument beginning with the minus character it is required to use the
 *     @c -- special option, e.g.
 *     @code
 *     program -x -- --strange-filename
 *     @endcode
 *     In this example, @c --strange-filename is a non-option argument. If the @c --
 *     were omitted, it would be treated as an unknown option. @n
 *     See @ref option::Descriptor::longopt for information on how to collect unknown options.
 *
 */

#ifndef OPTIONPARSER_H_
#define OPTIONPARSER_H_

/** @brief The namespace of The Lean Mean C++ Option Parser. */
namespace option
{

#ifdef _MSC_VER
#include <intrin.h>
#pragma intrinsic(_BitScanReverse)
struct MSC_Builtin_CLZ
{
  static int builtin_clz(unsigned x)
  {
    unsigned long index;
    _BitScanReverse(&index, x);
    return 32-index; // int is always 32bit on Windows, even for target x64
  }
};
#define __builtin_clz(x) MSC_Builtin_CLZ::builtin_clz(x)
#endif

class Option;

/**
 * @brief Possible results when checking if an argument is valid for a certain option.
 *
 * In the case that no argument is provided for an option that takes an
 * optional argument, return codes @c ARG_OK and @c ARG_IGNORE are equivalent.
 */
enum ArgStatus
{
  //! The option does not take an argument.
  ARG_NONE,
  //! The argument is acceptable for the option.
  ARG_OK,
  //! The argument is not acceptable but that's non-fatal because the option's argument is optional.
  ARG_IGNORE,
  //! The argument is not acceptable and that's fatal.
  ARG_ILLEGAL
};

/**
 * @brief Signature of functions that check if an argument is valid for a certain type of option.
 *
 * Every Option has such a function assigned in its Descriptor.
 * @code
 * Descriptor usage[] = { {UNKNOWN, 0, "", "", Arg::None, ""}, ... };
 * @endcode
 *
 * A CheckArg function has the following signature:
 * @code ArgStatus CheckArg(const Option& option, bool msg); @endcode
 *
 * It is used to check if a potential argument would be acceptable for the option.
 * It will even be called if there is no argument. In that case @c option.arg will be @c NULL.
 *
 * If @c msg is @c true and the function determines that an argument is not acceptable and
 * that this is a fatal error, it should output a message to the user before
 * returning @ref ARG_ILLEGAL. If @c msg is @c false the function should remain silent (or you
 * will get duplicate messages).
 *
 * See @ref ArgStatus for the meaning of the return values.
 *
 * While you can provide your own functions,
 * often the following pre-defined checks (which never return @ref ARG_ILLEGAL) will suffice:
 *
 * @li @c Arg::None @copybrief Arg::None
 * @li @c Arg::Optional @copybrief Arg::Optional
 *
 */
typedef ArgStatus (*CheckArg)(const Option& option, bool msg);

/**
 * @brief Describes an option, its help text (usage) and how it should be parsed.
 *
 * The main input when constructing an option::Parser is an array of Descriptors.

 * @par Example:
 * @code
 * enum OptionIndex {CREATE, ...};
 * enum OptionType {DISABLE, ENABLE, OTHER};
 *
 * const option::Descriptor usage[] = {
 *   { CREATE,                                            // index
 *     OTHER,                                             // type
 *     "c",                                               // shortopt
 *     "create",                                          // longopt
 *     Arg::None,                                         // check_arg
 *     "--create  Tells the program to create something." // help
 *   }
 *   , ...
 * };
 * @endcode
 */
struct Descriptor
{
  /**
   * @brief Index of this option's linked list in the array filled in by the parser.
   *
   * Command line options whose Descriptors have the same index will end up in the same
   * linked list in the order in which they appear on the command line. If you have
   * multiple long option aliases that refer to the same option, give their descriptors
   * the same @c index.
   *
   * If you have options that mean exactly opposite things
   * (e.g. @c --enable-foo and @c --disable-foo ), you should also give them the same
   * @c index, but distinguish them through different values for @ref type.
   * That way they end up in the same list and you can just take the last element of the
   * list and use its type. This way you get the usual behaviour where switches later
   * on the command line override earlier ones without having to code it manually.
   *
   * @par Tip:
   * Use an enum rather than plain ints for better readability, as shown in the example
   * at Descriptor.
   */
  const unsigned index;

  /**
   * @brief Used to distinguish between options with the same @ref index.
   * See @ref index for details.
   *
   * It is recommended that you use an enum rather than a plain int to make your
   * code more readable.
   */
  const int type;

  /**
   * @brief Each char in this string will be accepted as a short option character.
   *
   * The string must not include the minus character @c '-' or you'll get undefined
   * behaviour.
   *
   * If this Descriptor should not have short option characters, use the empty
   * string "". NULL is not permitted here!
   *
   * See @ref longopt for more information.
   */
  const char* const shortopt;

  /**
   * @brief The long option name (without the leading @c -- ).
   *
   * If this Descriptor should not have a long option name, use the empty
   * string "". NULL is not permitted here!
   *
   * While @ref shortopt allows multiple short option characters, each
   * Descriptor can have only a single long option name. If you have multiple
   * long option names referring to the same option use separate Descriptors
   * that have the same @ref index and @ref type. You may repeat
   * short option characters in such an alias Descriptor but there's no need to.
   *
   * @par Dummy Descriptors:
   * You can use dummy Descriptors with an
   * empty string for both @ref shortopt and @ref longopt to add text to
   * the usage that is not related to a specific option. See @ref help.
   * The first dummy Descriptor will be used for unknown options (see below).
   *
   * @par Unknown Option Descriptor:
   * The first dummy Descriptor in the list of Descriptors,
   * whose @ref shortopt and @ref longopt are both the empty string, will be used
   * as the Descriptor for unknown options. An unknown option is a string in
   * the argument vector that is not a lone minus @c '-' but starts with a minus
   * character and does not match any Descriptor's @ref shortopt or @ref longopt. @n
   * Note that the dummy descriptor's @ref check_arg function @e will be called and
   * its return value will be evaluated as usual. I.e. if it returns @ref ARG_ILLEGAL
   * the parsing will be aborted with <code>Parser::error()==true</code>. @n
   * if @c check_arg does not return @ref ARG_ILLEGAL the descriptor's
   * @ref index @e will be used to pick the linked list into which
   * to put the unknown option. @n
   * If there is no dummy descriptor, unknown options will be dropped silently.
   *
   */
  const char* const longopt;

  /**
   * @brief For each option that matches @ref shortopt or @ref longopt this function
   * will be called to check a potential argument to the option.
   *
   * This function will be called even if there is no potential argument. In that case
   * it will be passed @c NULL as @c arg parameter. Do not confuse this with the empty
   * string.
   *
   * See @ref CheckArg for more information.
   */
  const CheckArg check_arg;

  /**
   * @brief The usage text associated with the options in this Descriptor.
   *
   * You can use option::printUsage() to format your usage message based on
   * the @c help texts. You can use dummy Descriptors where
   * @ref shortopt and @ref longopt are both the empty string to add text to
   * the usage that is not related to a specific option.
   *
   * See option::printUsage() for special formatting characters you can use in
   * @c help to get a column layout.
   *
   * @attention
   * Must be UTF-8-encoded. If your compiler supports C++11 you can use the "u8"
   * prefix to make sure string literals are properly encoded.
   */
  const char* help;
};

/**
 * @brief A parsed option from the command line together with its argument if it has one.
 *
 * The Parser chains all parsed options with the same Descriptor::index together
 * to form a linked list. This allows you to easily implement all of the common ways
 * of handling repeated options and enable/disable pairs.
 *
 * @li Test for presence of a switch in the argument vector:
 *      @code if ( options[QUIET] ) ... @endcode
 * @li Evaluate --enable-foo/--disable-foo pair where the last one used wins:
 *     @code if ( options[FOO].last()->type() == DISABLE ) ... @endcode
 * @li Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose):
 *     @code int verbosity = options[VERBOSE].count(); @endcode
 * @li Iterate over all --file=&lt;fname> arguments:
 *     @code for (Option* opt = options[FILE]; opt; opt = opt->next())
 *   fname = opt->arg; ... @endcode
 */
class Option
{
  Option* next_;
  Option* prev_;
public:
  /**
   * @brief Pointer to this Option's Descriptor.
   *
   * Remember that the first dummy descriptor (see @ref Descriptor::longopt) is used
   * for unknown options.
   *
   * @attention
   * @c desc==NULL signals that this Option is unused. This is the default state of
   * elements in the result array. You don't need to test @c desc explicitly. You
   * can simply write something like this:
   * @code
   * if (options[CREATE])
   * {
   *   ...
   * }
   * @endcode
   * This works because of <code> operator const Option*() </code>.
   */
  const Descriptor* desc;

  /**
   * @brief The name of the option as used on the command line.
   *
   * The main purpose of this string is to be presented to the user in messages.
   *
   * In the case of a long option, this is the actual @c argv pointer, i.e. the first
   * character is a '-'. In the case of a short option this points to the option
   * character within the @c argv string.
   *
   * Note that in the case of a short option group or an attached option argument, this
   * string will contain additional characters following the actual name. Use @ref namelen
   * to filter out the actual option name only.
   *
   */
  const char* name;

  /**
   * @brief Pointer to this Option's argument (if any).
   *
   * NULL if this option has no argument. Do not confuse this with the empty string which
   * is a valid argument.
   */
  const char* arg;

  /**
   * @brief The length of the option @ref name.
   *
   * Because @ref name points into the actual @c argv string, the option name may be
   * followed by more characters (e.g. other short options in the same short option group).
   * This value is the number of bytes (not characters!) that are part of the actual name.
   *
   * For a short option, this length is always 1. For a long option this length is always
   * at least 2 if single minus long options are permitted and at least 3 if they are disabled.
   *
   * @note
   * In the pathological case of a minus within a short option group (e.g. @c -xf-z), this
   * length is incorrect, because this case will be misinterpreted as a long option and the
   * name will therefore extend to the string's 0-terminator or a following '=" character
   * if there is one. This is irrelevant for most uses of @ref name and @c namelen. If you
   * really need to distinguish the case of a long and a short option, compare @ref name to
   * the @c argv pointers. A long option's @c name is always identical to one of them,
   * whereas a short option's is never.
   */
  int namelen;

  /**
   * @brief Returns Descriptor::type of this Option's Descriptor, or 0 if this Option
   * is invalid (unused).
   *
   * Because this method (and last(), too) can be used even on unused Options with desc==0, you can (provided
   * you arrange your types properly) switch on type() without testing validity first.
   * @code
   * enum OptionType { UNUSED=0, DISABLED=0, ENABLED=1 };
   * enum OptionIndex { FOO };
   * const Descriptor usage[] = {
   *   { FOO, ENABLED,  "", "enable-foo",  Arg::None, 0 },
   *   { FOO, DISABLED, "", "disable-foo", Arg::None, 0 },
   *   { 0, 0, 0, 0, 0, 0 } };
   * ...
   * switch(options[FOO].last()->type()) // no validity check required!
   * {
   *   case ENABLED: ...
   *   case DISABLED: ...  // UNUSED==DISABLED !
   * }
   * @endcode
   */
  int type() const
  {
    return desc == 0 ? 0 : desc->type;
  }

  /**
   * @brief Returns Descriptor::index of this Option's Descriptor, or -1 if this Option
   * is invalid (unused).
   */
  int index() const
  {
    return desc == 0 ? -1 : desc->index;
  }

  /**
   * @brief Returns the number of times this Option (or others with the same Descriptor::index)
   * occurs in the argument vector.
   *
   * This corresponds to the number of elements in the linked list this Option is part of.
   * It doesn't matter on which element you call count(). The return value is always the same.
   *
   * Use this to implement cumulative options, such as -v, -vv, -vvv for
   * different verbosity levels.
   *
   * Returns 0 when called for an unused/invalid option.
   */
  int count()
  {
    int c = (desc == 0 ? 0 : 1);
    Option* p = first();
    while (!p->isLast())
    {
      ++c;
      p = p->next_;
    };
    return c;
  }

  /**
   * @brief Returns true iff this is the first element of the linked list.
   *
   * The first element in the linked list is the first option on the command line
   * that has the respective Descriptor::index value.
   *
   * Returns true for an unused/invalid option.
   */
  bool isFirst() const
  {
    return isTagged(prev_);
  }

  /**
   * @brief Returns true iff this is the last element of the linked list.
   *
   * The last element in the linked list is the last option on the command line
   * that has the respective Descriptor::index value.
   *
   * Returns true for an unused/invalid option.
   */
  bool isLast() const
  {
    return isTagged(next_);
  }

  /**
   * @brief Returns a pointer to the first element of the linked list.
   *
   * Use this when you want the first occurrence of an option on the command line to
   * take precedence. Note that this is not the way most programs handle options.
   * You should probably be using last() instead.
   *
   * @note
   * This method may be called on an unused/invalid option and will return a pointer to the
   * option itself.
   */
  Option* first()
  {
    Option* p = this;
    while (!p->isFirst())
      p = p->prev_;
    return p;
  }

  /**
   * @brief Returns a pointer to the last element of the linked list.
   *
   * Use this when you want the last occurrence of an option on the command line to
   * take precedence. This is the most common way of handling conflicting options.
   *
   * @note
   * This method may be called on an unused/invalid option and will return a pointer to the
   * option itself.
   *
   * @par Tip:
   * If you have options with opposite meanings (e.g. @c --enable-foo and @c --disable-foo), you
   * can assign them the same Descriptor::index to get them into the same list. Distinguish them by
   * Descriptor::type and all you have to do is check <code> last()->type() </code> to get
   * the state listed last on the command line.
   */
  Option* last()
  {
    return first()->prevwrap();
  }

  /**
   * @brief Returns a pointer to the previous element of the linked list or NULL if
   * called on first().
   *
   * If called on first() this method returns NULL. Otherwise it will return the
   * option with the same Descriptor::index that precedes this option on the command
   * line.
   */
  Option* prev()
  {
    return isFirst() ? 0 : prev_;
  }

  /**
   * @brief Returns a pointer to the previous element of the linked list with wrap-around from
   * first() to last().
   *
   * If called on first() this method returns last(). Otherwise it will return the
   * option with the same Descriptor::index that precedes this option on the command
   * line.
   */
  Option* prevwrap()
  {
    return untag(prev_);
  }

  /**
   * @brief Returns a pointer to the next element of the linked list or NULL if called
   * on last().
   *
   * If called on last() this method returns NULL. Otherwise it will return the
   * option with the same Descriptor::index that follows this option on the command
   * line.
   */
  Option* next()
  {
    return isLast() ? 0 : next_;
  }

  /**
   * @brief Returns a pointer to the next element of the linked list with wrap-around from
   * last() to first().
   *
   * If called on last() this method returns first(). Otherwise it will return the
   * option with the same Descriptor::index that follows this option on the command
   * line.
   */
  Option* nextwrap()
  {
    return untag(next_);
  }

  /**
   * @brief Makes @c new_last the new last() by chaining it into the list after last().
   *
   * It doesn't matter which element you call append() on. The new element will always
   * be appended to last().
   *
   * @attention
   * @c new_last must not yet be part of a list, or that list will become corrupted, because
   * this method does not unchain @c new_last from an existing list.
   */
  void append(Option* new_last)
  {
    Option* p = last();
    Option* f = first();
    p->next_ = new_last;
    new_last->prev_ = p;
    new_last->next_ = tag(f);
    f->prev_ = tag(new_last);
  }

  /**
   * @brief Casts from Option to const Option* but only if this Option is valid.
   *
   * If this Option is valid (i.e. @c desc!=NULL), returns this.
   * Otherwise returns NULL. This allows testing an Option directly
   * in an if-clause to see if it is used:
   * @code
   * if (options[CREATE])
   * {
   *   ...
   * }
   * @endcode
   * It also allows you to write loops like this:
   * @code for (Option* opt = options[FILE]; opt; opt = opt->next())
   *   fname = opt->arg; ... @endcode
   */
  operator const Option*() const
  {
    return desc ? this : 0;
  }

  /**
   * @brief Casts from Option to Option* but only if this Option is valid.
   *
   * If this Option is valid (i.e. @c desc!=NULL), returns this.
   * Otherwise returns NULL. This allows testing an Option directly
   * in an if-clause to see if it is used:
   * @code
   * if (options[CREATE])
   * {
   *   ...
   * }
   * @endcode
   * It also allows you to write loops like this:
   * @code for (Option* opt = options[FILE]; opt; opt = opt->next())
   *   fname = opt->arg; ... @endcode
   */
  operator Option*()
  {
    return desc ? this : 0;
  }

  /**
   * @brief Creates a new Option that is a one-element linked list and has NULL
   * @ref desc, @ref name, @ref arg and @ref namelen.
   */
  Option() :
      desc(0), name(0), arg(0), namelen(0)
  {
    prev_ = tag(this);
    next_ = tag(this);
  }

  /**
   * @brief Creates a new Option that is a one-element linked list and has the given
   * values for @ref desc, @ref name and @ref arg.
   *
   * If @c name_ points at a character other than '-' it will be assumed to refer to a
   * short option and @ref namelen will be set to 1. Otherwise the length will extend to
   * the first '=' character or the string's 0-terminator.
   */
  Option(const Descriptor* desc_, const char* name_, const char* arg_)
  {
    init(desc_, name_, arg_);
  }

  /**
   * @brief Makes @c *this a copy of @c orig except for the linked list pointers.
   *
   * After this operation @c *this will be a one-element linked list.
   */
  void operator=(const Option& orig)
  {
    init(orig.desc, orig.name, orig.arg);
  }

  /**
   * @brief Makes @c *this a copy of @c orig except for the linked list pointers.
   *
   * After this operation @c *this will be a one-element linked list.
   */
  Option(const Option& orig)
  {
    init(orig.desc, orig.name, orig.arg);
  }

private:
  /**
   * @internal
   * @brief Sets the fields of this Option to the given values (extracting @c name if necessary).
   *
   * If @c name_ points at a character other than '-' it will be assumed to refer to a
   * short option and @ref namelen will be set to 1. Otherwise the length will extend to
   * the first '=' character or the string's 0-terminator.
   */
  void init(const Descriptor* desc_, const char* name_, const char* arg_)
  {
    desc = desc_;
    name = name_;
    arg = arg_;
    prev_ = tag(this);
    next_ = tag(this);
    namelen = 0;
    if (name == 0)
      return;
    namelen = 1;
    if (name[0] != '-')
      return;
    while (name[namelen] != 0 && name[namelen] != '=')
      ++namelen;
  }

  static Option* tag(Option* ptr)
  {
    return (Option*) ((unsigned long long) ptr | 1);
  }

  static Option* untag(Option* ptr)
  {
    return (Option*) ((unsigned long long) ptr & ~1ull);
  }

  static bool isTagged(Option* ptr)
  {
    return ((unsigned long long) ptr & 1);
  }
};

/**
 * @brief Functions for checking the validity of option arguments.
 *
 * @copydetails CheckArg
 *
 * The following example code
 * can serve as starting place for writing your own more complex CheckArg functions:
 * @code
 * struct Arg: public option::Arg
 * {
 *   static void printError(const char* msg1, const option::Option& opt, const char* msg2)
 *   {
 *     fprintf(stderr, "ERROR: %s", msg1);
 *     fwrite(opt.name, opt.namelen, 1, stderr);
 *     fprintf(stderr, "%s", msg2);
 *   }
 *
 *   static option::ArgStatus Unknown(const option::Option& option, bool msg)
 *   {
 *     if (msg) printError("Unknown option '", option, "'\n");
 *     return option::ARG_ILLEGAL;
 *   }
 *
 *   static option::ArgStatus Required(const option::Option& option, bool msg)
 *   {
 *     if (option.arg != 0)
 *       return option::ARG_OK;
 *
 *     if (msg) printError("Option '", option, "' requires an argument\n");
 *     return option::ARG_ILLEGAL;
 *   }
 *
 *   static option::ArgStatus NonEmpty(const option::Option& option, bool msg)
 *   {
 *     if (option.arg != 0 && option.arg[0] != 0)
 *       return option::ARG_OK;
 *
 *     if (msg) printError("Option '", option, "' requires a non-empty argument\n");
 *     return option::ARG_ILLEGAL;
 *   }
 *
 *   static option::ArgStatus Numeric(const option::Option& option, bool msg)
 *   {
 *     char* endptr = 0;
 *     if (option.arg != 0 && strtol(option.arg, &endptr, 10)){};
 *     if (endptr != option.arg && *endptr == 0)
 *       return option::ARG_OK;
 *
 *     if (msg) printError("Option '", option, "' requires a numeric argument\n");
 *     return option::ARG_ILLEGAL;
 *   }
 * };
 * @endcode
 */
struct Arg
{
  //! @brief For options that don't take an argument: Returns ARG_NONE.
  static ArgStatus None(const Option&, bool)
  {
    return ARG_NONE;
  }

  //! @brief Returns ARG_OK if the argument is attached and ARG_IGNORE otherwise.
  static ArgStatus Optional(const Option& option, bool)
  {
    if (option.arg && option.name[option.namelen] != 0)
      return ARG_OK;
    else
      return ARG_IGNORE;
  }
};

/**
 * @brief Determines the minimum lengths of the buffer and options arrays used for Parser.
 *
 * Because Parser doesn't use dynamic memory its output arrays have to be pre-allocated.
 * If you don't want to use fixed size arrays (which may turn out too small, causing
 * command line arguments to be dropped), you can use Stats to determine the correct sizes.
 * Stats work cumulative. You can first pass in your default options and then the real
 * options and afterwards the counts will reflect the union.
 */
struct Stats
{
  /**
   * @brief Number of elements needed for a @c buffer[] array to be used for
   * @ref Parser::parse() "parsing" the same argument vectors that were fed
   * into this Stats object.
   *
   * @note
   * This number is always 1 greater than the actual number needed, to give
   * you a sentinel element.
   */
  unsigned buffer_max;

  /**
   * @brief Number of elements needed for an @c options[] array to be used for
   * @ref Parser::parse() "parsing" the same argument vectors that were fed
   * into this Stats object.
   *
   * @note
   * @li This number is always 1 greater than the actual number needed, to give
   * you a sentinel element.
   * @li This number depends only on the @c usage, not the argument vectors, because
   * the @c options array needs exactly one slot for each possible Descriptor::index.
   */
  unsigned options_max;

  /**
   * @brief Creates a Stats object with counts set to 1 (for the sentinel element).
   */
  Stats() :
      buffer_max(1), options_max(1) // 1 more than necessary as sentinel
  {
  }

  /**
   * @brief Creates a new Stats object and immediately updates it for the
   * given @c usage and argument vector. You may pass 0 for @c argc and/or @c argv,
   * if you just want to update @ref options_max.
   *
   * @note
   * The calls to Stats methods must match the later calls to Parser methods.
   * See Parser::parse() for the meaning of the arguments.
   */
  Stats(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, //
        bool single_minus_longopt = false) :
      buffer_max(1), options_max(1) // 1 more than necessary as sentinel
  {
    add(gnu, usage, argc, argv, min_abbr_len, single_minus_longopt);
  }

  //! @brief Stats(...) with non-const argv.
  Stats(bool gnu, const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, //
        bool single_minus_longopt = false) :
      buffer_max(1), options_max(1) // 1 more than necessary as sentinel
  {
    add(gnu, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt);
  }

  //! @brief POSIX Stats(...) (gnu==false).
  Stats(const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, //
        bool single_minus_longopt = false) :
      buffer_max(1), options_max(1) // 1 more than necessary as sentinel
  {
    add(false, usage, argc, argv, min_abbr_len, single_minus_longopt);
  }

  //! @brief POSIX Stats(...) (gnu==false) with non-const argv.
  Stats(const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, //
        bool single_minus_longopt = false) :
      buffer_max(1), options_max(1) // 1 more than necessary as sentinel
  {
    add(false, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt);
  }

  /**
   * @brief Updates this Stats object for the
   * given @c usage and argument vector. You may pass 0 for @c argc and/or @c argv,
   * if you just want to update @ref options_max.
   *
   * @note
   * The calls to Stats methods must match the later calls to Parser methods.
   * See Parser::parse() for the meaning of the arguments.
   */
  void add(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, //
           bool single_minus_longopt = false);

  //! @brief add() with non-const argv.
  void add(bool gnu, const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, //
           bool single_minus_longopt = false)
  {
    add(gnu, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt);
  }

  //! @brief POSIX add() (gnu==false).
  void add(const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, //
           bool single_minus_longopt = false)
  {
    add(false, usage, argc, argv, min_abbr_len, single_minus_longopt);
  }

  //! @brief POSIX add() (gnu==false) with non-const argv.
  void add(const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, //
           bool single_minus_longopt = false)
  {
    add(false, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt);
  }
private:
  class CountOptionsAction;
};

/**
 * @brief Checks argument vectors for validity and parses them into data
 * structures that are easier to work with.
 *
 * @par Example:
 * @code
 * int main(int argc, char* argv[])
 * {
 *   argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present
 *   option::Stats  stats(usage, argc, argv);
 *   option::Option options[stats.options_max], buffer[stats.buffer_max];
 *   option::Parser parse(usage, argc, argv, options, buffer);
 *
 *   if (parse.error())
 *     return 1;
 *
 *   if (options[HELP])
 *   ...
 * @endcode
 */
class Parser
{
  int op_count; //!< @internal @brief see optionsCount()
  int nonop_count; //!< @internal @brief see nonOptionsCount()
  const char** nonop_args; //!< @internal @brief see nonOptions()
  bool err; //!< @internal @brief see error()
public:

  /**
   * @brief Creates a new Parser.
   */
  Parser() :
      op_count(0), nonop_count(0), nonop_args(0), err(false)
  {
  }

  /**
   * @brief Creates a new Parser and immediately parses the given argument vector.
   * @copydetails parse()
   */
  Parser(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[],
         int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) :
      op_count(0), nonop_count(0), nonop_args(0), err(false)
  {
    parse(gnu, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
  }

  //! @brief Parser(...) with non-const argv.
  Parser(bool gnu, const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[],
         int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) :
      op_count(0), nonop_count(0), nonop_args(0), err(false)
  {
    parse(gnu, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
  }

  //! @brief POSIX Parser(...) (gnu==false).
  Parser(const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], int min_abbr_len = 0,
         bool single_minus_longopt = false, int bufmax = -1) :
      op_count(0), nonop_count(0), nonop_args(0), err(false)
  {
    parse(false, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
  }

  //! @brief POSIX Parser(...) (gnu==false) with non-const argv.
  Parser(const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], int min_abbr_len = 0,
         bool single_minus_longopt = false, int bufmax = -1) :
      op_count(0), nonop_count(0), nonop_args(0), err(false)
  {
    parse(false, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
  }

  /**
   * @brief Parses the given argument vector.
   *
   * @param gnu if true, parse() will not stop at the first non-option argument. Instead it will
   *            reorder arguments so that all non-options are at the end. This is the default behaviour
   *            of GNU getopt() but is not conforming to POSIX. @n
   *            Note, that once the argument vector has been reordered, the @c gnu flag will have
   *            no further effect on this argument vector. So it is enough to pass @c gnu==true when
   *            creating Stats.
   * @param usage Array of Descriptor objects that describe the options to support. The last entry
   *              of this array must have 0 in all fields.
   * @param argc The number of elements from @c argv that are to be parsed. If you pass -1, the number
   *             will be determined automatically. In that case the @c argv list must end with a NULL
   *             pointer.
   * @param argv The arguments to be parsed. If you pass -1 as @c argc the last pointer in the @c argv
   *             list must be NULL to mark the end.
   * @param options Each entry is the first element of a linked list of Options. Each new option
   *                that is parsed will be appended to the list specified by that Option's
   *                Descriptor::index. If an entry is not yet used (i.e. the Option is invalid),
   *                it will be replaced rather than appended to. @n
   *                The minimum length of this array is the greatest Descriptor::index value that
   *                occurs in @c usage @e PLUS ONE.
   * @param buffer Each argument that is successfully parsed (including unknown arguments, if they
   *        have a Descriptor whose CheckArg does not return @ref ARG_ILLEGAL) will be stored in this
   *        array. parse() scans the array for the first invalid entry and begins writing at that
   *        index. You can pass @c bufmax to limit the number of options stored.
   * @param min_abbr_len Passing a value <code> min_abbr_len > 0 </code> enables abbreviated long
   *               options. The parser will match a prefix of a long option as if it was
   *               the full long option (e.g. @c --foob=10 will be interpreted as if it was
   *               @c --foobar=10 ), as long as the prefix has at least @c min_abbr_len characters
   *               (not counting the @c -- ) and is unambiguous.
   *               @n Be careful if combining @c min_abbr_len=1 with @c single_minus_longopt=true
   *               because the ambiguity check does not consider short options and abbreviated
   *               single minus long options will take precedence over short options.
   * @param single_minus_longopt Passing @c true for this option allows long options to begin with
   *               a single minus. The double minus form will still be recognized. Note that
   *               single minus long options take precedence over short options and short option
   *               groups. E.g. @c -file would be interpreted as @c --file and not as
   *               <code> -f -i -l -e </code> (assuming a long option named @c "file" exists).
   * @param bufmax The greatest index in the @c buffer[] array that parse() will write to is
   *               @c bufmax-1. If there are more options, they will be processed (in particular
   *               their CheckArg will be called) but not stored. @n
   *               If you used Stats::buffer_max to dimension this array, you can pass
   *               -1 (or not pass @c bufmax at all) which tells parse() that the buffer is
   *               "large enough".
   * @attention
   * Remember that @c options and @c buffer store Option @e objects, not pointers. Therefore it
   * is not possible for the same object to be in both arrays. For those options that are found in
   * both @c buffer[] and @c options[] the respective objects are independent copies. And only the
   * objects in @c options[] are properly linked via Option::next() and Option::prev().
   * You can iterate over @c buffer[] to
   * process all options in the order they appear in the argument vector, but if you want access to
   * the other Options with the same Descriptor::index, then you @e must access the linked list via
   * @c options[]. You can get the linked list in options from a buffer object via something like
   * @c options[buffer[i].index()].
   */
  void parse(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[],
             int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1);

  //! @brief parse() with non-const argv.
  void parse(bool gnu, const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[],
             int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1)
  {
    parse(gnu, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
  }

  //! @brief POSIX parse() (gnu==false).
  void parse(const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[],
             int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1)
  {
    parse(false, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
  }

  //! @brief POSIX parse() (gnu==false) with non-const argv.
  void parse(const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], int min_abbr_len = 0,
             bool single_minus_longopt = false, int bufmax = -1)
  {
    parse(false, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
  }

  /**
   * @brief Returns the number of valid Option objects in @c buffer[].
   *
   * @note
   * @li The returned value always reflects the number of Options in the buffer[] array used for
   * the most recent call to parse().
   * @li The count (and the buffer[]) includes unknown options if they are collected
   * (see Descriptor::longopt).
   */
  int optionsCount()
  {
    return op_count;
  }

  /**
   * @brief Returns the number of non-option arguments that remained at the end of the
   * most recent parse() that actually encountered non-option arguments.
   *
   * @note
   * A parse() that does not encounter non-option arguments will leave this value
   * as well as nonOptions() undisturbed. This means you can feed the Parser a
   * default argument vector that contains non-option arguments (e.g. a default filename).
   * Then you feed it the actual arguments from the user. If the user has supplied at
   * least one non-option argument, all of the non-option arguments from the default
   * disappear and are replaced by the user's non-option arguments. However, if the
   * user does not supply any non-option arguments the defaults will still be in
   * effect.
   */
  int nonOptionsCount()
  {
    return nonop_count;
  }

  /**
   * @brief Returns a pointer to an array of non-option arguments (only valid
   * if <code>nonOptionsCount() >0 </code>).
   *
   * @note
   * @li parse() does not copy arguments, so this pointer points into the actual argument
   * vector as passed to parse().
   * @li As explained at nonOptionsCount() this pointer is only changed by parse() calls
   * that actually encounter non-option arguments. A parse() call that encounters only
   * options, will not change nonOptions().
   */
  const char** nonOptions()
  {
    return nonop_args;
  }

  /**
   * @brief Returns <b><code>nonOptions()[i]</code></b> (@e without checking if i is in range!).
   */
  const char* nonOption(int i)
  {
    return nonOptions()[i];
  }

  /**
   * @brief Returns @c true if an unrecoverable error occurred while parsing options.
   *
   * An illegal argument to an option (i.e. CheckArg returns @ref ARG_ILLEGAL) is an
   * unrecoverable error that aborts the parse. Unknown options are only an error if
   * their CheckArg function returns @ref ARG_ILLEGAL. Otherwise they are collected.
   * In that case if you want to exit the program if either an illegal argument
   * or an unknown option has been passed, use code like this
   *
   * @code
   * if (parser.error() || options[UNKNOWN])
   *   exit(1);
   * @endcode
   *
   */
  bool error()
  {
    return err;
  }

private:
  friend struct Stats;
  class StoreOptionAction;
  struct Action;

  /**
   * @internal
   * @brief This is the core function that does all the parsing.
   * @retval false iff an unrecoverable error occurred.
   */
  static bool workhorse(bool gnu, const Descriptor usage[], int numargs, const char** args, Action& action,
                        bool single_minus_longopt, bool print_errors, int min_abbr_len);

  /**
   * @internal
   * @brief Returns true iff @c st1 is a prefix of @c st2 and
   * in case @c st2 is longer than @c st1, then
   * the first additional character is '='.
   *
   * @par Examples:
   * @code
   * streq("foo", "foo=bar") == true
   * streq("foo", "foobar")  == false
   * streq("foo", "foo")     == true
   * streq("foo=bar", "foo") == false
   * @endcode
   */
  static bool streq(const char* st1, const char* st2)
  {
    while (*st1 != 0)
      if (*st1++ != *st2++)
        return false;
    return (*st2 == 0 || *st2 == '=');
  }

  /**
   * @internal
   * @brief Like streq() but handles abbreviations.
   *
   * Returns true iff @c st1 and @c st2 have a common
   * prefix with the following properties:
   * @li (if min > 0) its length is at least @c min characters or the same length as @c st1 (whichever is smaller).
   * @li (if min <= 0) its length is the same as that of @c st1
   * @li within @c st2 the character following the common prefix is either '=' or end-of-string.
   *
   * Examples:
   * @code
   * streqabbr("foo", "foo=bar",<anything>) == true
   * streqabbr("foo", "fo=bar" , 2) == true
   * streqabbr("foo", "fo"     , 2) == true
   * streqabbr("foo", "fo"     , 0) == false
   * streqabbr("foo", "f=bar"  , 2) == false
   * streqabbr("foo", "f"      , 2) == false
   * streqabbr("fo" , "foo=bar",<anything>)  == false
   * streqabbr("foo", "foobar" ,<anything>)  == false
   * streqabbr("foo", "fobar"  ,<anything>)  == false
   * streqabbr("foo", "foo"    ,<anything>)  == true
   * @endcode
   */
  static bool streqabbr(const char* st1, const char* st2, long long min)
  {
    const char* st1start = st1;
    while (*st1 != 0 && (*st1 == *st2))
    {
      ++st1;
      ++st2;
    }

    return (*st1 == 0 || (min > 0 && (st1 - st1start) >= min)) && (*st2 == 0 || *st2 == '=');
  }

  /**
   * @internal
   * @brief Returns true iff character @c ch is contained in the string @c st.
   *
   * Returns @c true for @c ch==0 .
   */
  static bool instr(char ch, const char* st)
  {
    while (*st != 0 && *st != ch)
      ++st;
    return *st == ch;
  }

  /**
   * @internal
   * @brief Rotates <code>args[-count],...,args[-1],args[0]</code> to become
   *        <code>args[0],args[-count],...,args[-1]</code>.
   */
  static void shift(const char** args, int count)
  {
    for (int i = 0; i > -count; --i)
    {
      const char* temp = args[i];
      args[i] = args[i - 1];
      args[i - 1] = temp;
    }
  }
};

/**
 * @internal
 * @brief Interface for actions Parser::workhorse() should perform for each Option it
 * parses.
 */
struct Parser::Action
{
  /**
   * @brief Called by Parser::workhorse() for each Option that has been successfully
   * parsed (including unknown
   * options if they have a Descriptor whose Descriptor::check_arg does not return
   * @ref ARG_ILLEGAL.
   *
   * Returns @c false iff a fatal error has occured and the parse should be aborted.
   */
  virtual bool perform(Option&)
  {
    return true;
  }

  /**
   * @brief Called by Parser::workhorse() after finishing the parse.
   * @param numargs the number of non-option arguments remaining
   * @param args pointer to the first remaining non-option argument (if numargs > 0).
   *
   * @return
   * @c false iff a fatal error has occurred.
   */
  virtual bool finished(int numargs, const char** args)
  {
    (void) numargs;
    (void) args;
    return true;
  }
};

/**
 * @internal
 * @brief An Action to pass to Parser::workhorse() that will increment a counter for
 * each parsed Option.
 */
class Stats::CountOptionsAction: public Parser::Action
{
  unsigned* buffer_max;
public:
  /**
   * Creates a new CountOptionsAction that will increase @c *buffer_max_ for each
   * parsed Option.
   */
  CountOptionsAction(unsigned* buffer_max_) :
      buffer_max(buffer_max_)
  {
  }

  bool perform(Option&)
  {
    if (*buffer_max == 0x7fffffff)
      return false; // overflow protection: don't accept number of options that doesn't fit signed int
    ++*buffer_max;
    return true;
  }
};

/**
 * @internal
 * @brief An Action to pass to Parser::workhorse() that will store each parsed Option in
 * appropriate arrays (see Parser::parse()).
 */
class Parser::StoreOptionAction: public Parser::Action
{
  Parser& parser;
  Option* options;
  Option* buffer;
  int bufmax; //! Number of slots in @c buffer. @c -1 means "large enough".
public:
  /**
   * @brief Creates a new StoreOption action.
   * @param parser_ the parser whose op_count should be updated.
   * @param options_ each Option @c o is chained into the linked list @c options_[o.desc->index]
   * @param buffer_ each Option is appended to this array as long as there's a free slot.
   * @param bufmax_ number of slots in @c buffer_. @c -1 means "large enough".
   */
  StoreOptionAction(Parser& parser_, Option options_[], Option buffer_[], int bufmax_) :
      parser(parser_), options(options_), buffer(buffer_), bufmax(bufmax_)
  {
    // find first empty slot in buffer (if any)
    int bufidx = 0;
    while ((bufmax < 0 || bufidx < bufmax) && buffer[bufidx])
      ++bufidx;

    // set parser's optionCount
    parser.op_count = bufidx;
  }

  bool perform(Option& option)
  {
    if (bufmax < 0 || parser.op_count < bufmax)
    {
      if (parser.op_count == 0x7fffffff)
        return false; // overflow protection: don't accept number of options that doesn't fit signed int

      buffer[parser.op_count] = option;
      int idx = buffer[parser.op_count].desc->index;
      if (options[idx])
        options[idx].append(buffer[parser.op_count]);
      else
        options[idx] = buffer[parser.op_count];
      ++parser.op_count;
    }
    return true; // NOTE: an option that is discarded because of a full buffer is not fatal
  }

  bool finished(int numargs, const char** args)
  {
    // only overwrite non-option argument list if there's at least 1
    // new non-option argument. Otherwise we keep the old list. This
    // makes it easy to use default non-option arguments.
    if (numargs > 0)
    {
      parser.nonop_count = numargs;
      parser.nonop_args = args;
    }

    return true;
  }
};

inline void Parser::parse(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[],
                          Option buffer[], int min_abbr_len, bool single_minus_longopt, int bufmax)
{
  StoreOptionAction action(*this, options, buffer, bufmax);
  err = !workhorse(gnu, usage, argc, argv, action, single_minus_longopt, true, min_abbr_len);
}

inline void Stats::add(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len,
                       bool single_minus_longopt)
{
  // determine size of options array. This is the greatest index used in the usage + 1
  int i = 0;
  while (usage[i].shortopt != 0)
  {
    if (usage[i].index + 1 >= options_max)
      options_max = (usage[i].index + 1) + 1; // 1 more than necessary as sentinel

    ++i;
  }

  CountOptionsAction action(&buffer_max);
  Parser::workhorse(gnu, usage, argc, argv, action, single_minus_longopt, false, min_abbr_len);
}

inline bool Parser::workhorse(bool gnu, const Descriptor usage[], int numargs, const char** args, Action& action,
                              bool single_minus_longopt, bool print_errors, int min_abbr_len)
{
  // protect against NULL pointer
  if (args == 0)
    numargs = 0;

  int nonops = 0;

  while (numargs != 0 && *args != 0)
  {
    const char* param = *args; // param can be --long-option, -srto or non-option argument

    // in POSIX mode the first non-option argument terminates the option list
    // a lone minus character is a non-option argument
    if (param[0] != '-' || param[1] == 0)
    {
      if (gnu)
      {
        ++nonops;
        ++args;
        if (numargs > 0)
          --numargs;
        continue;
      }
      else
        break;
    }

    // -- terminates the option list. The -- itself is skipped.
    if (param[1] == '-' && param[2] == 0)
    {
      shift(args, nonops);
      ++args;
      if (numargs > 0)
        --numargs;
      break;
    }

    bool handle_short_options;
    const char* longopt_name;
    if (param[1] == '-') // if --long-option
    {
      handle_short_options = false;
      longopt_name = param + 2;
    }
    else
    {
      handle_short_options = true;
      longopt_name = param + 1; //for testing a potential -long-option
    }

    bool try_single_minus_longopt = single_minus_longopt;
    bool have_more_args = (numargs > 1 || numargs < 0); // is referencing argv[1] valid?

    do // loop over short options in group, for long options the body is executed only once
    {
      int idx;

      const char* optarg;

      /******************** long option **********************/
      if (handle_short_options == false || try_single_minus_longopt)
      {
        idx = 0;
        while (usage[idx].longopt != 0 && !streq(usage[idx].longopt, longopt_name))
          ++idx;

        if (usage[idx].longopt == 0 && min_abbr_len > 0) // if we should try to match abbreviated long options
        {
          int i1 = 0;
          while (usage[i1].longopt != 0 && !streqabbr(usage[i1].longopt, longopt_name, min_abbr_len))
            ++i1;
          if (usage[i1].longopt != 0)
          { // now test if the match is unambiguous by checking for another match
            int i2 = i1 + 1;
            while (usage[i2].longopt != 0 && !streqabbr(usage[i2].longopt, longopt_name, min_abbr_len))
              ++i2;

            if (usage[i2].longopt == 0) // if there was no second match it's unambiguous, so accept i1 as idx
              idx = i1;
          }
        }

        // if we found something, disable handle_short_options (only relevant if single_minus_longopt)
        if (usage[idx].longopt != 0)
          handle_short_options = false;

        try_single_minus_longopt = false; // prevent looking for longopt in the middle of shortopt group

        optarg = longopt_name;
        while (*optarg != 0 && *optarg != '=')
          ++optarg;
        if (*optarg == '=') // attached argument
          ++optarg;
        else
          // possibly detached argument
          optarg = (have_more_args ? args[1] : 0);
      }

      /************************ short option ***********************************/
      if (handle_short_options)
      {
        if (*++param == 0) // point at the 1st/next option character
          break; // end of short option group

        idx = 0;
        while (usage[idx].shortopt != 0 && !instr(*param, usage[idx].shortopt))
          ++idx;

        if (param[1] == 0) // if the potential argument is separate
          optarg = (have_more_args ? args[1] : 0);
        else
          // if the potential argument is attached
          optarg = param + 1;
      }

      const Descriptor* descriptor = &usage[idx];

      if (descriptor->shortopt == 0) /**************  unknown option ********************/
      {
        // look for dummy entry (shortopt == "" and longopt == "") to use as Descriptor for unknown options
        idx = 0;
        while (usage[idx].shortopt != 0 && (usage[idx].shortopt[0] != 0 || usage[idx].longopt[0] != 0))
          ++idx;
        descriptor = (usage[idx].shortopt == 0 ? 0 : &usage[idx]);
      }

      if (descriptor != 0)
      {
        Option option(descriptor, param, optarg);
        switch (descriptor->check_arg(option, print_errors))
        {
          case ARG_ILLEGAL:
            return false; // fatal
          case ARG_OK:
            // skip one element of the argument vector, if it's a separated argument
            if (optarg != 0 && have_more_args && optarg == args[1])
            {
              shift(args, nonops);
              if (numargs > 0)
                --numargs;
              ++args;
            }

            // No further short options are possible after an argument
            handle_short_options = false;

            break;
          case ARG_IGNORE:
          case ARG_NONE:
            option.arg = 0;
            break;
        }

        if (!action.perform(option))
          return false;
      }

    } while (handle_short_options);

    shift(args, nonops);
    ++args;
    if (numargs > 0)
      --numargs;

  } // while

  if (numargs > 0 && *args == 0) // It's a bug in the caller if numargs is greater than the actual number
    numargs = 0; // of arguments, but as a service to the user we fix this if we spot it.

  if (numargs < 0) // if we don't know the number of remaining non-option arguments
  { // we need to count them
    numargs = 0;
    while (args[numargs] != 0)
      ++numargs;
  }

  return action.finished(numargs + nonops, args - nonops);
}

/**
 * @internal
 * @brief The implementation of option::printUsage().
 */
struct PrintUsageImplementation
{
  /**
   * @internal
   * @brief Interface for Functors that write (part of) a string somewhere.
   */
  struct IStringWriter
  {
    /**
     * @brief Writes the given number of chars beginning at the given pointer somewhere.
     */
    virtual void operator()(const char*, int)
    {
    }
  };

  /**
   * @internal
   * @brief Encapsulates a function with signature <code>func(string, size)</code> where
   * string can be initialized with a const char* and size with an int.
   */
  template<typename Function>
  struct FunctionWriter: public IStringWriter
  {
    Function* write;

    virtual void operator()(const char* str, int size)
    {
      (*write)(str, size);
    }

    FunctionWriter(Function* w) :
        write(w)
    {
    }
  };

  /**
   * @internal
   * @brief Encapsulates a reference to an object with a <code>write(string, size)</code>
   * method like that of @c std::ostream.
   */
  template<typename OStream>
  struct OStreamWriter: public IStringWriter
  {
    OStream& ostream;

    virtual void operator()(const char* str, int size)
    {
      ostream.write(str, size);
    }

    OStreamWriter(OStream& o) :
        ostream(o)
    {
    }
  };

  /**
   * @internal
   * @brief Like OStreamWriter but encapsulates a @c const reference, which is
   * typically a temporary object of a user class.
   */
  template<typename Temporary>
  struct TemporaryWriter: public IStringWriter
  {
    const Temporary& userstream;

    virtual void operator()(const char* str, int size)
    {
      userstream.write(str, size);
    }

    TemporaryWriter(const Temporary& u) :
        userstream(u)
    {
    }
  };

  /**
   * @internal
   * @brief Encapsulates a function with the signature <code>func(fd, string, size)</code> (the
   * signature of the @c write() system call)
   * where fd can be initialized from an int, string from a const char* and size from an int.
   */
  template<typename Syscall>
  struct SyscallWriter: public IStringWriter
  {
    Syscall* write;
    int fd;

    virtual void operator()(const char* str, int size)
    {
      (*write)(fd, str, size);
    }

    SyscallWriter(Syscall* w, int f) :
        write(w), fd(f)
    {
    }
  };

  /**
   * @internal
   * @brief Encapsulates a function with the same signature as @c std::fwrite().
   */
  template<typename Function, typename Stream>
  struct StreamWriter: public IStringWriter
  {
    Function* fwrite;
    Stream* stream;

    virtual void operator()(const char* str, int size)
    {
      (*fwrite)(str, size, 1, stream);
    }

    StreamWriter(Function* w, Stream* s) :
        fwrite(w), stream(s)
    {
    }
  };

  /**
   * @internal
   * @brief Sets <code> i1 = max(i1, i2) </code>
   */
  static void upmax(int& i1, int i2)
  {
    i1 = (i1 >= i2 ? i1 : i2);
  }

  /**
   * @internal
   * @brief Moves the "cursor" to column @c want_x assuming it is currently at column @c x
   * and sets @c x=want_x .
   * If <code> x > want_x </code>, a line break is output before indenting.
   *
   * @param write Spaces and possibly a line break are written via this functor to get
   *        the desired indentation @c want_x .
   * @param[in,out] x the current indentation. Set to @c want_x by this method.
   * @param want_x the desired indentation.
   */
  static void indent(IStringWriter& write, int& x, int want_x)
  {
    int indent = want_x - x;
    if (indent < 0)
    {
      write("\n", 1);
      indent = want_x;
    }

    if (indent > 0)
    {
      char space = ' ';
      for (int i = 0; i < indent; ++i)
        write(&space, 1);
      x = want_x;
    }
  }

  /**
   * @brief Returns true if ch is the unicode code point of a wide character.
   *
   * @note
   * The following character ranges are treated as wide
   * @code
   * 1100..115F
   * 2329..232A  (just 2 characters!)
   * 2E80..A4C6  except for 303F
   * A960..A97C
   * AC00..D7FB
   * F900..FAFF
   * FE10..FE6B
   * FF01..FF60
   * FFE0..FFE6
   * 1B000......
   * @endcode
   */
  static bool isWideChar(unsigned ch)
  {
    if (ch == 0x303F)
      return false;

    return ((0x1100 <= ch && ch <= 0x115F) || (0x2329 <= ch && ch <= 0x232A) || (0x2E80 <= ch && ch <= 0xA4C6)
        || (0xA960 <= ch && ch <= 0xA97C) || (0xAC00 <= ch && ch <= 0xD7FB) || (0xF900 <= ch && ch <= 0xFAFF)
        || (0xFE10 <= ch && ch <= 0xFE6B) || (0xFF01 <= ch && ch <= 0xFF60) || (0xFFE0 <= ch && ch <= 0xFFE6)
        || (0x1B000 <= ch));
  }

  /**
   * @internal
   * @brief Splits a @c Descriptor[] array into tables, rows, lines and columns and
   * iterates over these components.
   *
   * The top-level organizational unit is the @e table.
   * A table begins at a Descriptor with @c help!=NULL and extends up to
   * a Descriptor with @c help==NULL.
   *
   * A table consists of @e rows. Due to line-wrapping and explicit breaks
   * a row may take multiple lines on screen. Rows within the table are separated
   * by \\n. They never cross Descriptor boundaries. This means a row ends either
   * at \\n or the 0 at the end of the help string.
   *
   * A row consists of columns/cells. Columns/cells within a row are separated by \\t.
   * Line breaks within a cell are marked by \\v.
   *
   * Rows in the same table need not have the same number of columns/cells. The
   * extreme case are interjections, which are rows that contain neither \\t nor \\v.
   * These are NOT treated specially by LinePartIterator, but they are treated
   * specially by printUsage().
   *
   * LinePartIterator iterates through the usage at 3 levels: table, row and part.
   * Tables and rows are as described above. A @e part is a line within a cell.
   * LinePartIterator iterates through 1st parts of all cells, then through the 2nd
   * parts of all cells (if any),... @n
   * Example: The row <code> "1 \v 3 \t 2 \v 4" </code> has 2 cells/columns and 4 parts.
   * The parts will be returned in the order 1, 2, 3, 4.
   *
   * It is possible that some cells have fewer parts than others. In this case
   * LinePartIterator will "fill up" these cells with 0-length parts. IOW, LinePartIterator
   * always returns the same number of parts for each column. Note that this is different
   * from the way rows and columns are handled. LinePartIterator does @e not guarantee that
   * the same number of columns will be returned for each row.
   *
   */
  class LinePartIterator
  {
    const Descriptor* tablestart; //!< The 1st descriptor of the current table.
    const Descriptor* rowdesc; //!< The Descriptor that contains the current row.
    const char* rowstart; //!< Ptr to 1st character of current row within rowdesc->help.
    const char* ptr; //!< Ptr to current part within the current row.
    int col; //!< Index of current column.
    int len; //!< Length of the current part (that ptr points at) in BYTES
    int screenlen; //!< Length of the current part in screen columns (taking narrow/wide chars into account).
    int max_line_in_block; //!< Greatest index of a line within the block. This is the number of \\v within the cell with the most \\vs.
    int line_in_block; //!< Line index within the current cell of the current part.
    int target_line_in_block; //!< Line index of the parts we should return to the user on this iteration.
    bool hit_target_line; //!< Flag whether we encountered a part with line index target_line_in_block in the current cell.

    /** 
     * @brief Determines the byte and character lengths of the part at @ref ptr and 
     * stores them in @ref len and @ref screenlen respectively.
     */
    void update_length()
    {
      screenlen = 0;
      for (len = 0; ptr[len] != 0 && ptr[len] != '\v' && ptr[len] != '\t' && ptr[len] != '\n'; ++len)
      {
        ++screenlen;
        unsigned ch = (unsigned char) ptr[len];
        if (ch > 0xC1) // everything <= 0xC1 (yes, even 0xC1 itself) is not a valid UTF-8 start byte
        {
          // int __builtin_clz (unsigned int x)
          // Returns the number of leading 0-bits in x, starting at the most significant bit
          unsigned mask = (unsigned) -1 >> __builtin_clz(ch ^ 0xff);
          ch = ch & mask; // mask out length bits, we don't verify their correctness
          while (((unsigned char) ptr[len + 1] ^ 0x80) <= 0x3F) // while next byte is continuation byte
          {
            ch = (ch << 6) ^ (unsigned char) ptr[len + 1] ^ 0x80; // add continuation to char code
            ++len;
          }
          // ch is the decoded unicode code point
          if (ch >= 0x1100 && isWideChar(ch)) // the test for 0x1100 is here to avoid the function call in the Latin case
            ++screenlen;
        }
      }
    }

  public:
    //! @brief Creates an iterator for @c usage.
    LinePartIterator(const Descriptor usage[]) :
        tablestart(usage), rowdesc(0), rowstart(0), ptr(0), col(-1), len(0), max_line_in_block(0), line_in_block(0),
        target_line_in_block(0), hit_target_line(true)
    {
    }

    /**
     * @brief Moves iteration to the next table (if any). Has to be called once on a new
     * LinePartIterator to move to the 1st table.
     * @retval false if moving to next table failed because no further table exists.
     */
    bool nextTable()
    {
      // If this is NOT the first time nextTable() is called after the constructor,
      // then skip to the next table break (i.e. a Descriptor with help == 0)
      if (rowdesc != 0)
      {
        while (tablestart->help != 0 && tablestart->shortopt != 0)
          ++tablestart;
      }

      // Find the next table after the break (if any)
      while (tablestart->help == 0 && tablestart->shortopt != 0)
        ++tablestart;

      restartTable();
      return rowstart != 0;
    }

    /**
     * @brief Reset iteration to the beginning of the current table.
     */
    void restartTable()
    {
      rowdesc = tablestart;
      rowstart = tablestart->help;
      ptr = 0;
    }

    /**
     * @brief Moves iteration to the next row (if any). Has to be called once after each call to
     * @ref nextTable() to move to the 1st row of the table.
     * @retval false if moving to next row failed because no further row exists.
     */
    bool nextRow()
    {
      if (ptr == 0)
      {
        restartRow();
        return rowstart != 0;
      }

      while (*ptr != 0 && *ptr != '\n')
        ++ptr;

      if (*ptr == 0)
      {
        if ((rowdesc + 1)->help == 0) // table break
          return false;

        ++rowdesc;
        rowstart = rowdesc->help;
      }
      else // if (*ptr == '\n')
      {
        rowstart = ptr + 1;
      }

      restartRow();
      return true;
    }

    /**
     * @brief Reset iteration to the beginning of the current row.
     */
    void restartRow()
    {
      ptr = rowstart;
      col = -1;
      len = 0;
      screenlen = 0;
      max_line_in_block = 0;
      line_in_block = 0;
      target_line_in_block = 0;
      hit_target_line = true;
    }

    /**
     * @brief Moves iteration to the next part (if any). Has to be called once after each call to
     * @ref nextRow() to move to the 1st part of the row.
     * @retval false if moving to next part failed because no further part exists.
     *
     * See @ref LinePartIterator for details about the iteration.
     */
    bool next()
    {
      if (ptr == 0)
        return false;

      if (col == -1)
      {
        col = 0;
        update_length();
        return true;
      }

      ptr += len;
      while (true)
      {
        switch (*ptr)
        {
          case '\v':
            upmax(max_line_in_block, ++line_in_block);
            ++ptr;
            break;
          case '\t':
            if (!hit_target_line) // if previous column did not have the targetline
            { // then "insert" a 0-length part
              update_length();
              hit_target_line = true;
              return true;
            }

            hit_target_line = false;
            line_in_block = 0;
            ++col;
            ++ptr;
            break;
          case 0:
          case '\n':
            if (!hit_target_line) // if previous column did not have the targetline
            { // then "insert" a 0-length part
              update_length();
              hit_target_line = true;
              return true;
            }

            if (++target_line_in_block > max_line_in_block)
            {
              update_length();
              return false;
            }

            hit_target_line = false;
            line_in_block = 0;
            col = 0;
            ptr = rowstart;
            continue;
          default:
            ++ptr;
            continue;
        } // switch

        if (line_in_block == target_line_in_block)
        {
          update_length();
          hit_target_line = true;
          return true;
        }
      } // while
    }

    /**
     * @brief Returns the index (counting from 0) of the column in which
     * the part pointed to by @ref data() is located.
     */
    int column()
    {
      return col;
    }

    /**
     * @brief Returns the index (counting from 0) of the line within the current column
     * this part belongs to.
     */
    int line()
    {
      return target_line_in_block; // NOT line_in_block !!! It would be wrong if !hit_target_line
    }

    /**
     * @brief Returns the length of the part pointed to by @ref data() in raw chars (not UTF-8 characters).
     */
    int length()
    {
      return len;
    }

    /**
     * @brief Returns the width in screen columns of the part pointed to by @ref data().
     * Takes multi-byte UTF-8 sequences and wide characters into account.
     */
    int screenLength()
    {
      return screenlen;
    }

    /**
     * @brief Returns the current part of the iteration.
     */
    const char* data()
    {
      return ptr;
    }
  };

  /**
   * @internal
   * @brief Takes input and line wraps it, writing out one line at a time so that
   * it can be interleaved with output from other columns.
   *
   * The LineWrapper is used to handle the last column of each table as well as interjections.
   * The LineWrapper is called once for each line of output. If the data given to it fits
   * into the designated width of the last column it is simply written out. If there
   * is too much data, an appropriate split point is located and only the data up to this
   * split point is written out. The rest of the data is queued for the next line.
   * That way the last column can be line wrapped and interleaved with data from
   * other columns. The following example makes this clearer:
   * @code
   * Column 1,1    Column 2,1     This is a long text
   * Column 1,2    Column 2,2     that does not fit into
   *                              a single line.
   * @endcode
   *
   * The difficulty in producing this output is that the whole string
   * "This is a long text that does not fit into a single line" is the
   * 1st and only part of column 3. In order to produce the above
   * output the string must be output piecemeal, interleaved with
   * the data from the other columns.
   */
  class LineWrapper
  {
    static const int bufmask = 15; //!< Must be a power of 2 minus 1.
    /**
     * @brief Ring buffer for length component of pair (data, length).
     */
    int lenbuf[bufmask + 1];
    /**
     * @brief Ring buffer for data component of pair (data, length).
     */
    const char* datbuf[bufmask + 1];
    /**
     * @brief The indentation of the column to which the LineBuffer outputs. LineBuffer
     * assumes that the indentation has already been written when @ref process()
     * is called, so this value is only used when a buffer flush requires writing
     * additional lines of output.
     */
    int x;
    /**
     * @brief The width of the column to line wrap.
     */
    int width;
    int head; //!< @brief index for next write
    int tail; //!< @brief index for next read - 1 (i.e. increment tail BEFORE read)

    /**
     * @brief Multiple methods of LineWrapper may decide to flush part of the buffer to
     * free up space. The contract of process() says that only 1 line is output. So
     * this variable is used to track whether something has output a line. It is
     * reset at the beginning of process() and checked at the end to decide if
     * output has already occurred or is still needed.
     */
    bool wrote_something;

    bool buf_empty()
    {
      return ((tail + 1) & bufmask) == head;
    }

    bool buf_full()
    {
      return tail == head;
    }

    void buf_store(const char* data, int len)
    {
      lenbuf[head] = len;
      datbuf[head] = data;
      head = (head + 1) & bufmask;
    }

    //! @brief Call BEFORE reading ...buf[tail].
    void buf_next()
    {
      tail = (tail + 1) & bufmask;
    }

    /**
     * @brief Writes (data,len) into the ring buffer. If the buffer is full, a single line
     * is flushed out of the buffer into @c write.
     */
    void output(IStringWriter& write, const char* data, int len)
    {
      if (buf_full())
        write_one_line(write);

      buf_store(data, len);
    }

    /**
     * @brief Writes a single line of output from the buffer to @c write.
     */
    void write_one_line(IStringWriter& write)
    {
      if (wrote_something) // if we already wrote something, we need to start a new line
      {
        write("\n", 1);
        int _ = 0;
        indent(write, _, x);
      }

      if (!buf_empty())
      {
        buf_next();
        write(datbuf[tail], lenbuf[tail]);
      }

      wrote_something = true;
    }
  public:

    /**
     * @brief Writes out all remaining data from the LineWrapper using @c write.
     * Unlike @ref process() this method indents all lines including the first and
     * will output a \\n at the end (but only if something has been written).
     */
    void flush(IStringWriter& write)
    {
      if (buf_empty())
        return;
      int _ = 0;
      indent(write, _, x);
      wrote_something = false;
      while (!buf_empty())
        write_one_line(write);
      write("\n", 1);
    }

    /**
     * @brief Process, wrap and output the next piece of data.
     *
     * process() will output at least one line of output. This is not necessarily
     * the @c data passed in. It may be data queued from a prior call to process().
     * If the internal buffer is full, more than 1 line will be output.
     *
     * process() assumes that the a proper amount of indentation has already been
     * output. It won't write any further indentation before the 1st line. If
     * more than 1 line is written due to buffer constraints, the lines following
     * the first will be indented by this method, though.
     *
     * No \\n is written by this method after the last line that is written.
     *
     * @param write where to write the data.
     * @param data the new chunk of data to write.
     * @param len the length of the chunk of data to write.
     */
    void process(IStringWriter& write, const char* data, int len)
    {
      wrote_something = false;

      while (len > 0)
      {
        if (len <= width) // quick test that works because utf8width <= len (all wide chars have at least 2 bytes)
        {
          output(write, data, len);
          len = 0;
        }
        else // if (len > width)  it's possible (but not guaranteed) that utf8len > width
        {
          int utf8width = 0;
          int maxi = 0;
          while (maxi < len && utf8width < width)
          {
            int charbytes = 1;
            unsigned ch = (unsigned char) data[maxi];
            if (ch > 0xC1) // everything <= 0xC1 (yes, even 0xC1 itself) is not a valid UTF-8 start byte
            {
              // int __builtin_clz (unsigned int x)
              // Returns the number of leading 0-bits in x, starting at the most significant bit
              unsigned mask = (unsigned) -1 >> __builtin_clz(ch ^ 0xff);
              ch = ch & mask; // mask out length bits, we don't verify their correctness
              while ((maxi + charbytes < len) && //
                  (((unsigned char) data[maxi + charbytes] ^ 0x80) <= 0x3F)) // while next byte is continuation byte
              {
                ch = (ch << 6) ^ (unsigned char) data[maxi + charbytes] ^ 0x80; // add continuation to char code
                ++charbytes;
              }
              // ch is the decoded unicode code point
              if (ch >= 0x1100 && isWideChar(ch)) // the test for 0x1100 is here to avoid the function call in the Latin case
              {
                if (utf8width + 2 > width)
                  break;
                ++utf8width;
              }
            }
            ++utf8width;
            maxi += charbytes;
          }

          // data[maxi-1] is the last byte of the UTF-8 sequence of the last character that fits
          // onto the 1st line. If maxi == len, all characters fit on the line.

          if (maxi == len)
          {
            output(write, data, len);
            len = 0;
          }
          else // if (maxi < len)  at least 1 character (data[maxi] that is) doesn't fit on the line
          {
            int i;
            for (i = maxi; i >= 0; --i)
              if (data[i] == ' ')
                break;

            if (i >= 0)
            {
              output(write, data, i);
              data += i + 1;
              len -= i + 1;
            }
            else // did not find a space to split at => split before data[maxi]
            { // data[maxi] is always the beginning of a character, never a continuation byte
              output(write, data, maxi);
              data += maxi;
              len -= maxi;
            }
          }
        }
      }
      if (!wrote_something) // if we didn't already write something to make space in the buffer
        write_one_line(write); // write at most one line of actual output
    }

    /**
     * @brief Constructs a LineWrapper that wraps its output to fit into
     * screen columns @c x1 (incl.) to @c x2 (excl.).
     *
     * @c x1 gives the indentation LineWrapper uses if it needs to indent.
     */
    LineWrapper(int x1, int x2) :
        x(x1), width(x2 - x1), head(0), tail(bufmask)
    {
      if (width < 2) // because of wide characters we need at least width 2 or the code breaks
        width = 2;
    }
  };

  /**
   * @internal
   * @brief This is the implementation that is shared between all printUsage() templates.
   * Because all printUsage() templates share this implementation, there is no template bloat.
   */
  static void printUsage(IStringWriter& write, const Descriptor usage[], int width = 80, //
                         int last_column_min_percent = 50, int last_column_own_line_max_percent = 75)
  {
    if (width < 1) // protect against nonsense values
      width = 80;

    if (width > 10000) // protect against overflow in the following computation
      width = 10000;

    int last_column_min_width = ((width * last_column_min_percent) + 50) / 100;
    int last_column_own_line_max_width = ((width * last_column_own_line_max_percent) + 50) / 100;
    if (last_column_own_line_max_width == 0)
      last_column_own_line_max_width = 1;

    LinePartIterator part(usage);
    while (part.nextTable())
    {

      /***************** Determine column widths *******************************/

      const int maxcolumns = 8; // 8 columns are enough for everyone
      int col_width[maxcolumns];
      int lastcolumn;
      int leftwidth;
      int overlong_column_threshold = 10000;
      do
      {
        lastcolumn = 0;
        for (int i = 0; i < maxcolumns; ++i)
          col_width[i] = 0;

        part.restartTable();
        while (part.nextRow())
        {
          while (part.next())
          {
            if (part.column() < maxcolumns)
            {
              upmax(lastcolumn, part.column());
              if (part.screenLength() < overlong_column_threshold)
                // We don't let rows that don't use table separators (\t or \v) influence
                // the width of column 0. This allows the user to interject section headers
                // or explanatory paragraphs that do not participate in the table layout.
                if (part.column() > 0 || part.line() > 0 || part.data()[part.length()] == '\t'
                    || part.data()[part.length()] == '\v')
                  upmax(col_width[part.column()], part.screenLength());
            }
          }
        }

        /*
         * If the last column doesn't fit on the same
         * line as the other columns, we can fix that by starting it on its own line.
         * However we can't do this for any of the columns 0..lastcolumn-1.
         * If their sum exceeds the maximum width we try to fix this by iteratively
         * ignoring the widest line parts in the width determination until
         * we arrive at a series of column widths that fit into one line.
         * The result is a layout where everything is nicely formatted
         * except for a few overlong fragments.
         * */

        leftwidth = 0;
        overlong_column_threshold = 0;
        for (int i = 0; i < lastcolumn; ++i)
        {
          leftwidth += col_width[i];
          upmax(overlong_column_threshold, col_width[i]);
        }

      } while (leftwidth > width);

      /**************** Determine tab stops and last column handling **********************/

      int tabstop[maxcolumns];
      tabstop[0] = 0;
      for (int i = 1; i < maxcolumns; ++i)
        tabstop[i] = tabstop[i - 1] + col_width[i - 1];

      int rightwidth = width - tabstop[lastcolumn];
      bool print_last_column_on_own_line = false;
      if (rightwidth < last_column_min_width && rightwidth < col_width[lastcolumn])
      {
        print_last_column_on_own_line = true;
        rightwidth = last_column_own_line_max_width;
      }

      // If lastcolumn == 0 we must disable print_last_column_on_own_line because
      // otherwise 2 copies of the last (and only) column would be output.
      // Actually this is just defensive programming. It is currently not
      // possible that lastcolumn==0 and print_last_column_on_own_line==true
      // at the same time, because lastcolumn==0 => tabstop[lastcolumn] == 0 =>
      // rightwidth==width => rightwidth>=last_column_min_width  (unless someone passes
      // a bullshit value >100 for last_column_min_percent) => the above if condition
      // is false => print_last_column_on_own_line==false
      if (lastcolumn == 0)
        print_last_column_on_own_line = false;

      LineWrapper lastColumnLineWrapper(width - rightwidth, width);
      LineWrapper interjectionLineWrapper(0, width);

      part.restartTable();

      /***************** Print out all rows of the table *************************************/

      while (part.nextRow())
      {
        int x = -1;
        while (part.next())
        {
          if (part.column() > lastcolumn)
            continue; // drop excess columns (can happen if lastcolumn == maxcolumns-1)

          if (part.column() == 0)
          {
            if (x >= 0)
              write("\n", 1);
            x = 0;
          }

          indent(write, x, tabstop[part.column()]);

          if ((part.column() < lastcolumn)
              && (part.column() > 0 || part.line() > 0 || part.data()[part.length()] == '\t'
                  || part.data()[part.length()] == '\v'))
          {
            write(part.data(), part.length());
            x += part.screenLength();
          }
          else // either part.column() == lastcolumn or we are in the special case of
               // an interjection that doesn't contain \v or \t
          {
            // NOTE: This code block is not necessarily executed for
            // each line, because some rows may have fewer columns.

            LineWrapper& lineWrapper = (part.column() == 0) ? interjectionLineWrapper : lastColumnLineWrapper;

            if (!print_last_column_on_own_line)
              lineWrapper.process(write, part.data(), part.length());
          }
        } // while

        if (print_last_column_on_own_line)
        {
          part.restartRow();
          while (part.next())
          {
            if (part.column() == lastcolumn)
            {
              write("\n", 1);
              int _ = 0;
              indent(write, _, width - rightwidth);
              lastColumnLineWrapper.process(write, part.data(), part.length());
            }
          }
        }

        write("\n", 1);
        lastColumnLineWrapper.flush(write);
        interjectionLineWrapper.flush(write);
      }
    }
  }

}
;

/**
 * @brief Outputs a nicely formatted usage string with support for multi-column formatting
 * and line-wrapping.
 *
 * printUsage() takes the @c help texts of a Descriptor[] array and formats them into
 * a usage message, wrapping lines to achieve the desired output width.
 *
 * <b>Table formatting:</b>
 *
 * Aside from plain strings which are simply line-wrapped, the usage may contain tables. Tables
 * are used to align elements in the output.
 *
 * @code
 * // Without a table. The explanatory texts are not aligned.
 * -c, --create  |Creates something.
 * -k, --kill  |Destroys something.
 *
 * // With table formatting. The explanatory texts are aligned.
 * -c, --create  |Creates something.
 * -k, --kill    |Destroys something.
 * @endcode
 *
 * Table formatting removes the need to pad help texts manually with spaces to achieve
 * alignment. To create a table, simply insert \\t (tab) characters to separate the cells
 * within a row.
 *
 * @code
 * const option::Descriptor usage[] = {
 * {..., "-c, --create  \tCreates something." },
 * {..., "-k, --kill  \tDestroys something." }, ...
 * @endcode
 *
 * Note that you must include the minimum amount of space desired between cells yourself.
 * Table formatting will insert further spaces as needed to achieve alignment.
 *
 * You can insert line breaks within cells by using \\v (vertical tab).
 *
 * @code
 * const option::Descriptor usage[] = {
 * {..., "-c,\v--create  \tCreates\vsomething." },
 * {..., "-k,\v--kill  \tDestroys\vsomething." }, ...
 *
 * // results in
 *
 * -c,       Creates
 * --create  something.
 * -k,       Destroys
 * --kill    something.
 * @endcode
 *
 * You can mix lines that do not use \\t or \\v with those that do. The plain
 * lines will not mess up the table layout. Alignment of the table columns will
 * be maintained even across these interjections.
 *
 * @code
 * const option::Descriptor usage[] = {
 * {..., "-c, --create  \tCreates something." },
 * {..., "----------------------------------" },
 * {..., "-k, --kill  \tDestroys something." }, ...
 *
 * // results in
 *
 * -c, --create  Creates something.
 * ----------------------------------
 * -k, --kill    Destroys something.
 * @endcode
 *
 * You can have multiple tables within the same usage whose columns are
 * aligned independently. Simply insert a dummy Descriptor with @c help==0.
 *
 * @code
 * const option::Descriptor usage[] = {
 * {..., "Long options:" },
 * {..., "--very-long-option  \tDoes something long." },
 * {..., "--ultra-super-mega-long-option  \tTakes forever to complete." },
 * {..., 0 }, // ---------- table break -----------
 * {..., "Short options:" },
 * {..., "-s  \tShort." },
 * {..., "-q  \tQuick." }, ...
 *
 * // results in
 *
 * Long options:
 * --very-long-option              Does something long.
 * --ultra-super-mega-long-option  Takes forever to complete.
 * Short options:
 * -s  Short.
 * -q  Quick.
 *
 * // Without the table break it would be
 *
 * Long options:
 * --very-long-option              Does something long.
 * --ultra-super-mega-long-option  Takes forever to complete.
 * Short options:
 * -s                              Short.
 * -q                              Quick.
 * @endcode
 *
 * <b>Output methods:</b>
 *
 * Because TheLeanMeanC++Option parser is freestanding, you have to provide the means for
 * output in the first argument(s) to printUsage(). Because printUsage() is implemented as
 * a set of template functions, you have great flexibility in your choice of output
 * method. The following example demonstrates typical uses. Anything that's similar enough
 * will work.
 *
 * @code
 * #include <unistd.h>  // write()
 * #include <iostream>  // cout
 * #include <sstream>   // ostringstream
 * #include <cstdio>    // fwrite()
 * using namespace std;
 *
 * void my_write(const char* str, int size) {
 *   fwrite(str, size, 1, stdout);
 * }
 *
 * struct MyWriter {
 *   void write(const char* buf, size_t size) const {
 *      fwrite(str, size, 1, stdout);
 *   }
 * };
 *
 * struct MyWriteFunctor {
 *   void operator()(const char* buf, size_t size) {
 *      fwrite(str, size, 1, stdout);
 *   }
 * };
 * ...
 * printUsage(my_write, usage);    // custom write function
 * printUsage(MyWriter(), usage);  // temporary of a custom class
 * MyWriter writer;
 * printUsage(writer, usage);      // custom class object
 * MyWriteFunctor wfunctor;
 * printUsage(&wfunctor, usage);   // custom functor
 * printUsage(write, 1, usage);    // write() to file descriptor 1
 * printUsage(cout, usage);        // an ostream&
 * printUsage(fwrite, stdout, usage);  // fwrite() to stdout
 * ostringstream sstr;
 * printUsage(sstr, usage);        // an ostringstream&
 *
 * @endcode
 *
 * @par Notes:
 * @li the @c write() method of a class that is to be passed as a temporary
 *     as @c MyWriter() is in the example, must be a @c const method, because
 *     temporary objects are passed as const reference. This only applies to
 *     temporary objects that are created and destroyed in the same statement.
 *     If you create an object like @c writer in the example, this restriction
 *     does not apply.
 * @li a functor like @c MyWriteFunctor in the example must be passed as a pointer.
 *     This differs from the way functors are passed to e.g. the STL algorithms.
 * @li All printUsage() templates are tiny wrappers around a shared non-template implementation.
 *     So there's no penalty for using different versions in the same program.
 * @li printUsage() always interprets Descriptor::help as UTF-8 and always produces UTF-8-encoded
 *     output. If your system uses a different charset, you must do your own conversion. You
 *     may also need to change the font of the console to see non-ASCII characters properly.
 *     This is particularly true for Windows.
 * @li @b Security @b warning: Do not insert untrusted strings (such as user-supplied arguments)
 *     into the usage. printUsage() has no protection against malicious UTF-8 sequences.
 *
 * @param prn The output method to use. See the examples above.
 * @param usage the Descriptor[] array whose @c help texts will be formatted.
 * @param width the maximum number of characters per output line. Note that this number is
 *        in actual characters, not bytes. printUsage() supports UTF-8 in @c help and will
 *        count multi-byte UTF-8 sequences properly. Asian wide characters are counted
 *        as 2 characters.
 * @param last_column_min_percent (0-100) The minimum percentage of @c width that should be available
 *        for the last column (which typically contains the textual explanation of an option).
 *        If less space is available, the last column will be printed on its own line, indented
 *        according to @c last_column_own_line_max_percent.
 * @param last_column_own_line_max_percent (0-100) If the last column is printed on its own line due to
 *        less than @c last_column_min_percent of the width being available, then only
 *        @c last_column_own_line_max_percent of the extra line(s) will be used for the
 *        last column's text. This ensures an indentation. See example below.
 *
 * @code
 * // width=20, last_column_min_percent=50 (i.e. last col. min. width=10)
 * --3456789 1234567890
 *           1234567890
 *
 * // width=20, last_column_min_percent=75 (i.e. last col. min. width=15)
 * // last_column_own_line_max_percent=75
 * --3456789
 *      123456789012345
 *      67890
 *
 * // width=20, last_column_min_percent=75 (i.e. last col. min. width=15)
 * // last_column_own_line_max_percent=33 (i.e. max. 5)
 * --3456789
 *                12345
 *                67890
 *                12345
 *                67890
 * @endcode
 */
template<typename OStream>
void printUsage(OStream& prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50,
                int last_column_own_line_max_percent = 75)
{
  PrintUsageImplementation::OStreamWriter<OStream> write(prn);
  PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
}

template<typename Function>
void printUsage(Function* prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50,
                int last_column_own_line_max_percent = 75)
{
  PrintUsageImplementation::FunctionWriter<Function> write(prn);
  PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
}

template<typename Temporary>
void printUsage(const Temporary& prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50,
                int last_column_own_line_max_percent = 75)
{
  PrintUsageImplementation::TemporaryWriter<Temporary> write(prn);
  PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
}

template<typename Syscall>
void printUsage(Syscall* prn, int fd, const Descriptor usage[], int width = 80, int last_column_min_percent = 50,
                int last_column_own_line_max_percent = 75)
{
  PrintUsageImplementation::SyscallWriter<Syscall> write(prn, fd);
  PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
}

template<typename Function, typename Stream>
void printUsage(Function* prn, Stream* stream, const Descriptor usage[], int width = 80, int last_column_min_percent =
                    50,
                int last_column_own_line_max_percent = 75)
{
  PrintUsageImplementation::StreamWriter<Function, Stream> write(prn, stream);
  PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
}

}
// namespace option

#endif /* OPTIONPARSER_H_ */