1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
package Torello.HTML;

import java.util.*;
import java.util.regex.*;
import java.util.stream.*;

import java.util.function.Predicate;

import Torello.Java.StringParse;
import Torello.Java.StrCmpr;
import Torello.Java.StrFilter;

import Torello.HTML.parse.HTMLRegEx;
import Torello.HTML.NodeSearch.CSSStrException;
import Torello.HTML.NodeSearch.TextComparitor;

import Torello.Java.Shell.C;

/**
 * <CODE>TagNode - Documentation.</CODE><BR /><BR />
 * <EMBED CLASS="external-html" DATA-FILE-ID="TGND">
 * <EMBED CLASS="external-html" DATA-FILE-ID="HTMLNODESUB">
 * @see TextNode
 * @see CommentNode
 * @see HTMLNode
 */
public final class TagNode 
    extends HTMLNode 
    implements CharSequence, java.io.Serializable, Cloneable, Comparable<TagNode>
{
    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUID"> */
    public static final long serialVersionUID = 1;

    // ********************************************************************************************
    // NON-STATIC FIELDS
    // ********************************************************************************************

    /** <EMBED CLASS="external-html" DATA-FILE-ID="TGNDTOK"> */
    public final String tok;

    /** <EMBED CLASS="external-html" DATA-FILE-ID="TGNDCLOSE"> */
    public final boolean isClosing;

    // ********************************************************************************************
    // Constructors
    // ********************************************************************************************

    /**
     * Creates a {@code TagNode}, an inherited class of {@code 'HTMLNode'} that can be used as an 
     * element of an HTML {@code Vector}.
     *
     * <BR /><BR /><B>NOTE:</B> Attribute values are neither parsed, nor checked when this
     * constructor is used.  This constructor could allow malformed HTML to be passed to the
     * {@code public final String str} field!
     * 
     * <DIV CLASS="EXAMPLE">{@code
     * TagNode tn = new TagNode("<DIV CLASS='SUMMARY' onmouseover=\"alert('Hello!');\">");
     * System.out.println(tn.str);
     * 
     * // Prints to Terminal: <DIV CLASS='SUMMARY' onmouseover="alert('Hello!');">
     * }</DIV>
     *
     * @param s Any valid HTML tag, for instance: {@code <H1>, <A HREF="somoe url">,
     * 
     * <DIV ID="some id">} etc...
     * 
     * @throws MalformedTagNodeException If the passed {@code String} wasn't valid - meaning <I>it
     * did not match the regular-expression {@code parser}.</I> 
     * 
     * @throws HTMLTokException If the {@code String} found where the usual HTML token-element is
     * situated <I>is not a valid HTML element</I> then the {@code HTMLTokException} will be
     * thrown.
     * 
     * @see HTMLTags#getTag_MEM_HEAP_CHECKOUT_COPY(String)
     */
    public TagNode(String s)
    {
        super(s);

        // If the second character of the string is a forward-slash, this must be a closing-element
        // For Example: </SPAN>, </DIV>, </A>, etc...

        isClosing = s.charAt(1) == '/';

        // This is the Element & Attribute Matcher used by the RegEx Parser.  If this Matcher doesn't
        // find a match, the parameter 's' cannot be a valid HTML Element.  NOTE: The results of this
        // matcher are also used to retrieve attribute-values, but here below, its results are ignored.

        Matcher m = HTMLRegEx.P1.matcher(s);

        if (! m.find()) throw new MalformedTagNodeException(
            "The parser's regular-expression did not match the constructor-string.\n" +
            "The exact input-string was: [" + s + "]\n" +
            "NOTE:  The parameter-string is included as a field (ex.str) to this Exception.", s
        );

        String tokTEMP = m.group(1).toLowerCase();
            // MINOR/MAJOR IMPROVEMENT... REUSE THE "ALLOCATED STRING TOKEN" from the HTMLTag's class
            // THINK: Let the Garbage Collector take out as many duplicate-strings as is possible... 
            // AND SOONER.  DECEMBER 2019: "Optimization" or ... "Improvement"

        if ((m.start() != 0) || (m.end() != s.length()))
            throw new MalformedTagNodeException(
                "The parser's regular-expression did not match the entire-string-length of the " +
                "string-parameter to this constructor: m.start()=" + m.start() + ", m.end()=" + 
                m.end() + ".\nHowever, the length of the Input-Parameter String was=" + s.length() +
                "\nThe exact input-string was: [" + s + "]\nNOTE: The parameter-string is included " +
                "as a field (ex.str) to this Exception.", s
            );

        this.tok = HTMLTags.getTag_MEM_HEAP_CHECKOUT_COPY(tokTEMP);
            // Get a copy of the 'tok' string that was already allocated on the heap; (OPTIMIZATON)
            // NOTE: There are already myriad strings for the '.str' field.
            // ALSO: Don't pay much attention to this line if it doesn't make sense... it's not that
            // important.  If the HTML Token found was not a valid HTML5 token, this field will be null.

        // Now do the usual error check.
        if (this.tok == null) throw new HTMLTokException(
            "The HTML Tag / Token Element that is specified by the input string " +
            "[" + tokTEMP + "] is not a valid HTML Element Name.\n" +
            "The exact input-string was: [" + s + "]"
        );
    }

    // USED-INTERNALLY - bypasses all checks.  used when creating new HTML Element-Names
    // ONLY: class 'HTMLTags' via method 'addTag(...)' shall ever invoke this constructor.
    // NOTE: This only became necessary because of the MEM_COPY_HEAP optimization.  This
    //       optimization expects that there is already a TagNode with element 'tok' in
    //       the TreeSet, which is always OK - except for the method that CREATES NEW HTML
    //       TAGS... a.k.a. HTMLTags.addTag(String).
    TagNode(String token, TC openOrClosed)
    {
        super("<" + ((openOrClosed == TC.ClosingTags) ? "/" : "") + token + ">");

        // ONLY CHANGE CASE HERE, NOT IN PREVIOUS-LINE.  PAY ATTENTION.  
        this.tok = token.toLowerCase();

        this.isClosing = (openOrClosed == TC.ClosingTags) ? true : false;
    }

    /**
     * This will build a new {@code TagNode} that contains the inner tag values specified here.  It
     * is some-what checked for validity - though not all possible error cases are listed.  If a
     * major issue is discovered an exception is thrown.
     *
     * <BR /><BR /><B><SPAN STYLE='color: red;'>ATTRIBUTES:</SPAN></B> This constructor accepts
     * only <B STYLE="color: red;">key-value</B> attributes,  Boolean /
     * <B STYLE="color: red;">key-only</B> attributes are <B>NOT accepted</B> by this constructor.
     * 
     * <DIV CLASS="EXAMPLE">{@code
     * Properties attributes = new Properties();
     * attributes.put("CLASS", "SUMMARY");
     * attributes.put("onmouseover", "alert('Hello');");
     * 
     * TagNode tn = new TagNode("DIV", attributes, SD.DoubleQuotes, false);
     * 
     * System.out.println(tn);
     * // Prints To Terminal: <DIV CLASS="SUMMARY" onmouseover="alert('Hello');">
     * }</DIV>
     *
     * @param tok This may be any valid HTML Element name.  When this constructor is used,
     * {@code 'tok'} will always be rendered to <I>{@code ASCII} lower-case</I>.  If this
     * parameter does not contain a valid HTML element name, then an exception is thrown.
     * 
     * @param attributes This must be a table of HTML inner-tag
     * <B STYLE="color: red;">key-values</B> <B>(<I>a.k.a.</I></B> HTML Attributes) that are
     * acceptable for using with the HTML element that is being created.  Validity checking
     * <I><B>includes *only*</B></I> the following tests:
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> If any <B STYLE="color: red;">key</B> of {@code Properties} parameter {@code 'p'}
     *      contains characters outside of this ASCII-subset: {@code [A..Za..z0..9_-]}
     * </LI>
     * <LI> If any <B STYLE="color: red;">key</B> of parameter {@code 'p'} does not start with
     *      attributes a character from this subset: {@code [A..Za..z]}
     * </LI>
     * <LI> If any <B STYLE="color: red;">value</B> of {@code Properties} parameter {@code 'p'}
     *      has a "quote within quote" problem -  a {@code 'value'} that contains quotation marks
     *      that are the same as the quotation-parameter {@code SD quotes}
     * </LI>
     * </UL>
     *
     * <BR />If any of these requirements <B>fail</B>, the <B>exceptions</B> listed below
     * will throw.
     *
     * <BR /><BR /><B>NOTE:</B> When specifying a {@code java.util.Properties} parameter for which
     * <I>quotation-marks have already been added to the <B STYLE="color: red;">values</B></I>
     * inside the table, <I>parameter {@code SD quote} must be set to null</I>.  In such cases, if
     * {@code 'quote'} were not null, a second set of surrounding quotes would be appended each
     * attribute-<B STYLE="color: red;">value</B> in the output HTML-Element - and this would
     * likely force a {@code QuotesException} to throw, due to the <I>"quotes within quotes"</I>
     * issue.
     *
     * <BR /><BR /><B>NOTE:</B> The {@code 'attributes'} parameter may be null, and if so, it will
     * be ignored.  In this case, no <B STYLE="color: red;">key-value</B> attributes will be
     * incorporated into the {@code TagNode}.
     *
     * @param quotes This is either a single-quote {@code (')} or a double-quote {@code (")}.  The
     * {@code 'quotes'} parameter is an instance of the {@code Enumerated-Type: SD} from this
     * package.
     *
     * <BR /><BR /><B>NOTE ABOUT {@code 'SD'}:</B> This parameter (quotes) may be null.  If 'null'
     * is passed, then it should be expected that the contents of the {@code Properties p}
     * parameter contains <B STYLE="color: red;">values</B> that obey these rules:
     *
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> <B>Either:</B> The <B STYLE="color: red;">values</B> in {@code Properties}
     *      parameter {@code 'p'} <I>already have quotes surrounding their {@code String}
     *      contents.</I>
     * </LI>
     * <LI> <B>Or:</B> The <B STYLE="color: red;">values</B> in {@code 'p'} do not contain
     *      any white-space.  HTML rules state that in such cases, say quotes are actually
     *      optional.
     * </LI>
     * </UL>
     *
     * @param addEndingForwardSlash There are a few (very few) instances where an "ending
     * forward-slash" {@code ('/')} is expected at the end of the HTML-Tag.  If this is desired,
     * set this value to <B>true</B>.
     *
     * @throws InnerTagKeyException <EMBED CLASS="external-html" DATA-FILE-ID="ITKEYEXPROP">
     * 
     * @throws QuotesException If there are "quotes within quotes" problems, due to the
     * <B STYLE="color: red;">values</B> of the <B STYLE="color: red;">key-value</B> pairs inside
     * the input {@code Properties} hash-table, this exception will throw.  This also throws if the
     * the {@code 'quotes'} parameter is passed 'null', and any of the
     * property-<B STYLE="color: red;">values</B> in the table contain white-space.
     * 
     * @throws HTMLTokException if an invalid HTML 4 or 5 token is not present
     * <B>(check is {@code CASE_INSENSITIVE})</B>, this exception throws.
     * 
     * @see #tok
     * @see InnerTagKeyException#check(String, String)
     * @see QuotesException#check(String, SD, String)
     * @see #generateElementString(String, Properties, Iterable, SD, boolean)
     */
    public TagNode(String tok, Properties attributes, SD quotes, boolean addEndingForwardSlash) 
    { 
        this(generateElementString(
                tok, attributes, null /* keyOnlyAttributes */, quotes, addEndingForwardSlash
        ));
    }

    /**
     * This will build a new {@code TagNode} that contains the inner tag attributes specified here.
     * It is some-what checked for validity - though not all possible error cases are listed.  If a
     * major issue is discovered an exception is thrown.
     *
     * <DIV CLASS="EXAMPLE">{@code
     * Properties attributes = new Properties();
     * attributes.put("CLASS", "SUMMARY");
     * attributes.put("onmouseover", "alert('Hello');");
     *
     * Vector<String> booleanAttributes = new Vector<>();
     * booleanAttributes.add("HIDDEN");
     * 
     * TagNode tn = new TagNode("DIV", attributes, booleanAttributes, SD.DoubleQuotes, false);
     * 
     * System.out.println(tn);
     * // Prints To Terminal: <DIV CLASS="SUMMARY" onmouseover="alert('Hello');" HIDDEN>
     * }</DIV>
     * <BR /><BR /><B><SPAN STYLE='color: red;'>ATTRIBUTES:</SPAN></B> This constructor accepts
     * both <B STYLE="color: red;">key-value</B> attributes, and boolean /
     * <B STYLE="color: red;">key-only</B> attributes as input.  These two lists are passed through
     * two different input-parameters.
     *
     * @param tok This may be any valid HTML Element name.    Valid {@code String's} that this
     * parameter can accept include {@code 'div', 'img', 'span', 'a',} etc...  If this parameter
     * does not contain a valid HTML element name, then an exception is thrown.
     * 
     * @param attributes This must be a table of HTML inner-tag
     * <B STYLE="color: red;">key-values</B> <B>(<I>a.k.a.</I></B> HTML Attributes) that are
     * acceptable for using with the HTML element that is being created.  Validity checking
     * <I><B>includes *only*</B></I> the following tests:
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> If any <B STYLE="color: red;">key</B> of {@code 'Properties'} parameter
     *      {@code 'attributes'} contains characters outside of this ASCII-subset:
     *      {@code [A..Za..z0..9_-]}
     * </LI>
     * <LI> If any <B STYLE="color: red;">key</B> of {@code 'attributes'} does not start with a
     *      character from this subset: {@code [A..Za..z]}
     * </LI>
     * <LI> If any <B STYLE="color: red;">value</B> of {@code 'attributes'} has a "quote within
     *      quote" problem - a {@code 'value'} that contains quotation marks that are the same as
     *      the quotation parameter {@code SD quotes}
     * </LI>
     * </UL>
     * 
     * <BR />If any of these requirements <B>fail</B>, the <B>exceptions</B> listed below
     * will throw.
     *
     * <BR /><BR /><B>NOTE:</B> When specifying a {@code java.util.Properties} parameter for which
     * <I>quotation-marks have already been added to the <B STYLE="color: red;">values</B></I>
     * inside the table, <I>parameter {@code SD quote} must be set to null</I>.  In such cases, if
     * {@code 'quote'} were not null, a second set of surrounding quotes would be appended each
     * attribute-<B STYLE="color: red;">value</B> in the output HTML-Element - and this would
     * likely force a {@code QuotesException} to throw, due to the <I>"quotes within quotes"</I>
     * issue.
     *
     * <BR /><BR /><B>NOTE:</B> The {@code 'attributes'} parameter may be null, and if so, it will
     * be ignored.  In this case, no <B STYLE="color: red;">key-value</B> attributes will be
     * incorporated into the {@code TagNode}.
     *
     * @param keyOnlyAttributes This should be a valid list of "Attribute-Only" Inner-Tags.
     * Such attributes are often called "Boolean Attributes."  They are just a stand-alone
     * keywords, without any <B STYLE="color: red;">value</B> assignment.  The CSS keyword
     * {@code 'HIDDEN'} is a commonly used Boolean-Attribute.
     *
     * <BR /><BR /><B>NOTE:</B> This parameter may be null, and if so, no boolean-attributes will
     * be included in the HTML Element.
     *
     * @param quotes This is either a single-quote {@code (')} or a double-quote {@code (")}.  It
     * uses the {@code Enumerated Type: 'SD'} from this package.
     *
     * <BR /><BR /><B>NOTE ABOUT {@code 'SD'}:</B> This parameter (quotes) may be null.  If 'null'
     * is passed, then it should be expected that the contents of the {@code Properties p}
     * parameter contains <B STYLE="color: red;">values</B> that obey these rules:
     *
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> <B>Either:</B> The <B STYLE="color: red;">values</B> in {@code Properties}
     *      parameter {@code 'p'} <I>already have quotes surrounding their {@code String}
     *      contents.</I>
     * </LI>
     * <LI> <B>Or:</B> The <B STYLE="color: red;">values</B> in {@code 'p'} do not contain
     *      any white-space.  HTML rules state that in such cases, say quotes are actually
     *      optional.
     * </LI>
     * </UL>
     *
     * @param addEndingForwardSlash There are a few (very few) instances where an "ending
     * forward-slash" is expected at the end of the HTML -Tag.  If this is desired, set this value
     * to <B>TRUE</B>.
     * 
     * @throws InnerTagKeyException <EMBED CLASS="external-html" DATA-FILE-ID="ITKEYEXPROP">
     * 
     * @throws QuotesException <EMBED CLASS="external-html" DATA-FILE-ID="QEX">
     * 
     * @throws HTMLTokException if an invalid HTML 4 or 5 token is not present
     * <B>(check is {@code CASE_INSENSITIVE})</B>
     * 
     * @see InnerTagKeyException#check(String, String)
     * @see QuotesException#check(String, SD, String)
     * @see #generateElementString(String, Properties, Iterable, SD, boolean)
     */
    public TagNode(
        String tok, Properties attributes, Iterable<String> keyOnlyAttributes,
        SD quotes, boolean addEndingForwardSlash
    )
    {
        this(generateElementString(
            tok, attributes, keyOnlyAttributes, quotes, addEndingForwardSlash
        ));
    }

    /**
     * This builds an HTML Element as a {@code String.}  This {@code String} may be passed to the
     * standard HTML {@code TagNode} Constructor that accepts a {@code String} as input.
     * 
     * @param tok This is the HTML Element name.  Valid {@code String's} that this parameter can
     * accept include {@code 'div', 'img', 'span', 'a',} etc...  If this parameter does not contain
     * a valid HTML element name, then an exception is thrown.
     *
     * @param p This is a {@code java.util.Properties} table of HTML Attribute 
     * <B STYLE="color: red;">Key-Value</B> Pairs.
     * 
     * <BR /><BR /><B>NOTE:</B> This parameter may be null, and if so, no attribute-values will be
     * included in the {@code TagNode}.
     *
     * @param keyOnlyAttributes This is a list of keyword attributes that do not have 
     * <B STYLE="color: red;">value</B> assignments, and are to be inserted into the HTML Element.
     * This parameter could also be named 'Boolean Attributes.'
     * 
     * <BR /><BR /><B>NOTE:</B> This parameter may be null, and if so, no boolean-attributes will
     * be included in the {@code TagNode}.
     *
     * @param quotesChoice These quotes are used to encapsulate the
     * <B STYLE="color: red;">value</B> {@code String} of all key-value pairs when building the
     * HTML Element.  This parameter may be null, and if it is - then no quotes will be added to
     * the <B STYLE="color: red;">value</B> {@code String's} that are inserted
     * 
     * <BR /><BR /><B><SPAN STYLE='color: red;'>IMPORTANT:</B></SPAN> If different
     * quotes-selections are to be used for different attribute key-value pairs, then those quotes
     * should be provided <I><B>inside the {@code Properties}</I></B> data-structure - already
     * pre-wrapped. When individualized quotes are needed, this parameter should be passed null.
     *
     * @param addEndingForwardSlash When this receives <B>TRUE</B>, an ending {@code '/'} forward
     * slash is appended to the second-to-last character of the output {@code String.}
     *
     * @throws InnerTagKeyException <EMBED CLASS="external-html" DATA-FILE-ID="ITKEYEXPROP">
     * 
     * @throws QuotesException <EMBED CLASS="external-html" DATA-FILE-ID="QEX">
     * 
     * @throws HTMLTokException if an invalid HTML 4 or 5 token is not present
     * <B>{@code CASE_INSENSITIVE}</B>
     * 
     * @return This method returns an HTML Element, as a {@code String.}
     * 
     * @see HTMLTokException#check(String[])
     * @see InnerTagKeyException#check(String, String)
     * @see QuotesException#check(String, SD, String)
     */
    protected static String generateElementString(
        String tok, Properties p, Iterable<String> keyOnlyAttributes,
        SD quotesChoice, boolean addEndingForwardSlash
    )
    {
        String computedQuote = (quotesChoice == null) ? "" : ("" + quotesChoice.quote);
        HTMLTokException.check(tok);

        // The HTML Element is "built" using a StringBuilder
        StringBuilder sb = new StringBuilder();
        sb.append("<" + tok);

        // If there are any Inner-Tag Key-Value pairs, insert them first.
        if ((p != null) && (p.size() > 0))
            for (String key : p.stringPropertyNames())
            {
                String value = p.getProperty(key);

                InnerTagKeyException.check(key, value);

                QuotesException.check(
                    value, quotesChoice,
                    "parameter 'Properties' contains:\nkey:\t" + key + "\nvalue:\t" + value + "\n"
                );

                sb.append(" " + key + '=' + computedQuote + value + computedQuote);
            }

        // If there are any Key-Only Inner-Tags (Boolean Attributes), insert them next.
        if (keyOnlyAttributes != null)
            for (String keyOnlyAttribute : keyOnlyAttributes) 
            {
                InnerTagKeyException.check(keyOnlyAttribute);
                sb.append(" " + keyOnlyAttribute);
            }

        // Add a closing forward-slash
        sb.append(addEndingForwardSlash ? " />" : ">");

        // Build the String, using the StringBuilder, and return the newly-constructed HTML Element.
        return sb.toString();
    }

    // ********************************************************************************************
    // isTag
    // ********************************************************************************************

    /**
     * This method identifies that {@code 'this'} instance of {@code 'HTMLNode'} is, indeed, 
     * actually an instance of the (sub-class) {@code TagNode}.
     *
     * @return This method shall always return <B>TRUE</B>  It overrides the parent-class
     * {@code HTMLNode} method {@link #isTagNode()}, which always returns <B>FALSE</B>.
     */
    @Override
    public boolean isTagNode() { return true; }

    /**
     * Receives a list of html-elements which the {@code this.tok} field must match.  
     * This method returns <B>TRUE</B> if any match is found.
     * 
     * <BR /><BR /><IMG SRC='isTag.png' CLASS=JDIMG ALT='example'>
     * 
     * @param possibleTags This non-null list of potential HTML tags.
     * 
     * @return <B>TRUE</B> If {@code this.tok} matches at least one of these tags.
     * 
     * @see #tok
     */
    public boolean isTag(String... possibleTags)
    { 
        for (String htmlTag : possibleTags)
            if (htmlTag.equalsIgnoreCase(this.tok))
                return true;
        
        return false;
    }

    /**
     * Receives a list of html-elements which {@code this.tok} field <B>MAY NOT</B> match.
     * This method returns <B>FALSE</B> if any match is found.
     * 
     * @param possibleTags This must be a non-null list of potential HTML tags.
     * 
     * @return <B>FALSE</B> If {@code this.tok} matches any one of these tags, and <B>TRUE</B>
     * otherwise.
     * 
     * @see #tok
     * @see #isTag(String[])
     */
    public boolean isTagExcept(String... possibleTags)
    { 
        for (String htmlTag : possibleTags)
            if (htmlTag.equalsIgnoreCase(this.tok))
                return false;
        
        return true;
    }

    /**
     * Receives two "criteria-specifier" parameters.  This method shall return <B>TRUE</B> if:
     *
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI>Field {@code 'isClosing'} is equal-to / consistent-with {@code TC tagCriteria}</LI>
     * <LI>Field {@code 'tok'} is equal to at least one of the {@code 'possibleTags'}</LI>
     * </UL>
     * 
     * <BR /><BR /><IMG SRC='isTag2.png' CLASS=JDIMG ALT='example'>
     * 
     * @param tagCriteria This ought to be either {@code 'TC.OpeningTags'} or
     * {@code TC.ClosingTags'}.  This parameter specifies what {@code 'this'} instance of
     * {@code TagNode} is expected to contain, as {@code this.isClosing} field shall be compared
     * against it.
     * 
     * @param possibleTags This is presumed to be a non-zero-length, and non-null-valued list of
     * html tokens.
     * 
     * @return <B>TRUE</B> If {@code 'this'} matches the specified criteria, and <B>FALSE</B> 
     * otherwise.
     * 
     * @see TC
     * @see #isClosing
     * @see #tok
     */
    public boolean isTag(TC tagCriteria, String... possibleTags)
    {
        // Requested an "OpeningTag" but this is a "ClosingTag"
        if ((tagCriteria == TC.OpeningTags) && this.isClosing)
            return false;

        // Requested a "ClosingTag" but this is an "OpeningTag"
        if ((tagCriteria == TC.ClosingTags) && ! this.isClosing)
            return false;

        for (int i=0; i < possibleTags.length; i++)
            if (this.tok.equalsIgnoreCase(possibleTags[i]))
                return true;
                        // Found a TOKEN match, return TRUE immediately

        return false;   // None of the elements in 'possibleTags' equalled tn.tok
    }

    /**
     * Receives a {@code TagNode} and then two "criteria-specifier" parameters.  This method shall
     * return <B>FALSE</B> if:
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> Field {@code 'isClosing'} is <B><I>not</I></B> equal-to / 
     *      <B><I>not</I></B> consistent-with {@code TC tagCriteria}</LI>
     * <LI> Field {@code 'tok'} is <B><I>equal-to</I></B> any of the {@code 'possibleTags'}</LI>
     * </UL>
     *
     * @param tagCriteria tagCriteria This ought to be either {@code 'TC.OpeningTags'} or
     * {@code TC.ClosingTags'} This parameter specifies what {@code 'this'} instance of
     * {@code TagNode} is expected to contain, as {@code this.isClosing} field shall be compared
     * against it.
     * 
     * @param possibleTags This is presumed to be a non-zero-length, and non-null-valued list of
     * html tokens.
     * 
     * @return <B>TRUE</B> If this {@code TagNode 'n'} matches the specified criteria explained
     * above, and <B>FALSE</B> otherwise.
     * 
     * @see TC
     * @see #tok
     * @see #isClosing
     */
    public boolean isTagExcept(TC tagCriteria, String... possibleTags)
    {
        // Requested an "OpeningTag" but this is a "ClosingTag"
        if ((tagCriteria == TC.OpeningTags) && this.isClosing)
            return false;

        // Requested a "ClosingTag" but this is an "OpeningTag"
        if ((tagCriteria == TC.ClosingTags) && ! this.isClosing)
            return false;

        for (int i=0; i < possibleTags.length; i++)
            if (this.tok.equalsIgnoreCase(possibleTags[i]))
                return false;
                        // The Token of the input node was a match with one of the 'possibleTags'
                        // Since this is "Except" - we must return 'false'

        return true;    // None of the elements in 'possibleTags' equalled tn.tok
                        // since this is "Except" - return 'true'
    }


    // ********************************************************************************************
    // Main Method 'AV'
    // ********************************************************************************************

    /**
     * The letters: <B>{@code AV}</B> simply mean <B>"Attribute Value"</B>.  In this HTML scrape
     * &amp; search package, the words <I><B>attribute</B></I> and <I><B>inner-tag</B></I> are used
     * synonymously.
     * 
     * <BR /><BR />This will return the <B STYLE="color: red;">value</B> of any "Inner Tag" inside
     * the HTML {@code TagNode}.  An inner-tag is the choice of wording used in this scrape package
     * - partially for brevity since "tag" is usually interchangeable with "inner tag."  Often
     * HTML coders refer to this particular data as an <B>HTML Element Attribute</B> (or more
     * simply, just <B>"Attribute"</B>).
     * 
     * <BR /><BR /><IMG SRC="AV.png" CLASS=JDIMG ALT="example">
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDCSSAV">
     * 
     * @param innerTagAttribute  This may be any Java-{@code String}, but very common examples
     * of HTML attributes (and their <B STYLE="color: red;">values</B>) include:
     * 
     * <BR /><BR />
     * 
     * <TABLE CLASS="BRIEFSAMPLETABLE"><TBODY>
     * <TR> <TH>Attribute / Inner-Tag</TH>
     *      <TH>Commonly Found Attribute-Values</TH>
     * </TR>
     * <TR> <TD>HREF="..."</TD>
     *      <TD>where the attribute <B STYLE="color: red;">value</B> ("...") - is a URL</TD>
     * </TR>
     * <TR> <TD>SRC='...'</TD>
     *      <TD>and the attribute <B STYLE="color: red;">value</B> specified
     *          ('...') - is usually an Image-URL (like a "pic.jpg")</TD>
     * </TR>
     * <TR> <TD>ID=...</TD>
     *      <TD>where the attribute <B STYLE="color: red;">value</B> (...) -
     *          would be a "CSS Identifier Tag"</TD>
     * </TR>
     * <TR> <TD>CLASS='...'</TD>
     *      <TD>and the attribute <B STYLE="color: red;">value</B> ('...') -
     *          is the "CSS Class" to which the particular HTML element belongs</TD>
     * </TR>
     * <TR> <TD>OnClick="..."</TD>
     *      <TD>and the attribute <B STYLE="color: red;">value</B> ("...")
     *          - is often a function call to a Java-Script module, or actual Java-Script</TD>
     * </TR>
     * <TR> <TD>href="..."</TD>
     *      <TD><I>SAME AS ABOVE!</I> - Remember an "inner-tag" or
     *          "attribute" <B STYLE="color: red;">name</B> is <I>{@code CASE-INSENSITIVE}</I></TD>
     * </TR>
     * <TR> <TD>src='...'</TD>
     *      <TD><I>SAME AS ABOVE!</I> - Remember an "inner-tag" or "attribute"
     *      <B STYLE="color: red;">name</B> is <I>{@code CASE-INSENSITIVE}</I></TD>
     * </TR>
     * </TBODY></TABLE> 
     * 
     * @return The <B>"Attribute </B><B STYLE="color: red;">Value"</B>, which for the inner-tag
     * named by the input {@code String}-parameter.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">NOTE:</SPAN></B> If {@code 'this' TagNode} is a
     * closing-tag (specifically, if the {@code 'isClosing'} boolean-field is true), this method
     * will exit immediately, and return null.  Unlike the other Attribute-Modification Methods in
     * this class, no {@code ClosingTagNodeException} shall throw, but rather the method will exit
     * gracefully. This is because this method is a 'getter' only.  No invalid data will be
     * instantiated or saved - even if this method executes to completion.  Note, though, valid
     * HTML pages do not allow attributes inside of closing HTML Elements.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">ALSO:</SPAN></B> If the {@code 'str'}
     * {@code String}-field of {@code 'this' TagNode} has a length that isn't greater than the
     * following: {@code 3 + tok.length() + innerTagAttribute.trim().length())}, then in this case
     * this {@code AV} method will also return {@code null}.  The rational for returning null here
     * is that the {@code final String str} field simply does not have enough characters to contain
     * this inner-tag.
     *
     * @see #isClosing
     * @see #str
     * @see #tok
     * @see StringParse#ifQuotesStripQuotes(String)
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public String AV(String innerTagAttribute)
    {
        // All HTML element tags that start like: </DIV> with a front-slash.
        // They may not legally contain inner-tag attributes.

        if (this.isClosing) return null;    

        // All HTML element tags that contain only <TOK> (TOK <==> Element-Name) in their .str field...
        // Specifically: '<', TOKEN, '>',  (Where TOKEN is 'div', 'span', 'table', 'ul', etc...)
        // are TOO SHORT to have the attribute, so don't check... return null.

        if (this.str.length() < 
            (3 + this.tok.length() + (innerTagAttribute = innerTagAttribute.trim()).length()))
            return null;

        // Matches "Attribute / Inner-Tag Key-Value" Pairs.
        Matcher m = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // This loop iterates the KEY_VALUE PAIRS THAT HAVE BEEN FOUND.
        /// NOTE: The REGEX Matches on Key-Value Pairs.
        while (m.find())

            // m.group(2) is the "KEY" of the Attribute KEY-VALUE Pair
            // m.group(3) is the "VALUE" of the Attribute.
            if (m.group(2).equalsIgnoreCase(innerTagAttribute))
                return StringParse.ifQuotesStripQuotes(m.group(3));

        // This means the attribute name provided to parameter 'innerTagAttribute' was not found.
        return null;
    }

    /**
     * <SPAN STYLE="color: red;"><B>OPT: Optimized</B></SPAN>
     * 
     * <BR /><BR /> This is an "optimized" version of method {@link #AV(String)}.  This method does
     * the exact same thing as {@code AV(...)}, but leaves out parameter-checking and
     * error-checking. This is used internally (repeatedly) by the NodeSearch Package Search Loops.
     * 
     * @param innerTagAttribute This is the inner-tag / attribute <B STYLE="color: red;">name</B>
     * whose <B STYLE="color: red;">value</B> is hereby being requested.
     * 
     * @return {@code String}-<B STYLE="color: red;">value</B> of this inner-tag / attribute.
     * 
     * @see StringParse#ifQuotesStripQuotes(String)
     * @see #str
     * @see TagNode.AttrRegEx#KEY_VALUE_REGEX
     */
    public String AVOPT(String innerTagAttribute)
    {
        // COPIED DIRECTLY FROM class TagNode, leaves off initial tests.

        // Matches "Attribute / Inner-Tag Key-Value" Pairs.
        Matcher m = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // This loop iterates the KEY_VALUE PAIRS THAT HAVE BEEN FOUND.
        /// NOTE: The REGEX Matches on Key-Value Pairs.
        while (m.find())

            // m.group(2) is the "KEY" of the Attribute KEY-VALUE Pair
            // m.group(3) is the "VALUE" of the Attribute.
            if (m.group(2).equalsIgnoreCase(innerTagAttribute))
                return StringParse.ifQuotesStripQuotes(m.group(3));

        // This means the attribute name provided to parameter 'innerTagAttribute' was not found.
        return null;
    }

    // ********************************************************************************************
    // Attribute Modify-Value methods
    // ********************************************************************************************

    /**
     * This function will instantiate a new {@code TagNode} which contains this newly added 
     * <B STYLE="color: red;">attribute-value</B> pair. It uses the constructor listed above, and
     * furthermore does some error-handling checks.  It will throw an exception if the inner-tag /
     * value pairs do not pass inspection on quotes-error cases, or contain invalid characters.
     *
     * <BR /><BR /><IMG SRC="setAV.png" CLASS=JDIMG ALT="example">
     * 
     * @param attribute Any valid HTML attribute-<B STYLE="color: red;">name</B>.  This parameter
     * may not be null, or a {@code NullPointerException} will throw.
     *
     * <BR /><BR /><B>NOTE:</B> If the attribute that is specified is already contained within
     * this tag (where a {@code CASE-INSENSITIVE} comparison to the inner-tag's returned by
     * {@code public Properties allAV()} gets a match), then the original attribute is simply
     * over-written.  A Duplicate HTML-Element attribute <B><I>will not be added.</I></B>
     *
     * @param value Any valid attribute-<B STYLE="color: red;">value</B>.  This parameter may not
     * be null, or a {@code NullPointerException} will throw.
     *
     * @param quote This is either a single-quote, double-quote, or null. 
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> When parameter {@code 'quote'} is {@code SD.SingleQuotes}, a single-quote is
     *      prepended and appended to the beginning and ending (respectively) of the
     *      <B STYLE="color: red;"> {@code value}</B> parameter before inserting or replacing the
     *      inner-tag of this HTML ({@code TagNode}) Element.
     * </LI>
     * <LI> When parameter {@code 'quote'} is {@code SD.DoubleQuotes}, a double-quote is added
     *      to the beginning and ending of the <B STYLE="color: red;">{@code value}</B>-parameter
     *      before inserting (or re-inserting, if this attribute as already present).
     * </LI>
     * <LI> When {@code 'quote'} is null, there are two alternative results, depending on the
     *      {@code TagNode:}
     *      <BR /><BR /><OL CLASS="JDOL">
     *      <LI>If the {@code TagNode} already has an inner-tag <B STYLE="color: red;">name</B>
     *          that is equal ({@code CASE_INSENSITIVE}) to the <B STYLE="color: red;">
     *          {@code 'key'}</B> parameter, then the original {@code quote} found in
     *          {@code 'this'} Element is used.
     *      </LI>
     *      <LI>If a new attribute, not already found in {@code 'this' TagNode} is being 
     *          inserted, and parameter {@code 'quote'} is null, then no quotes will be used at all
     *          - which is a scenario sometimes found in HTML documents.  In this case, the
     *          <B STYLE="color: red;">key-value</B> inner-tag will simply contain the
     *          {@code String <HTML-ELEMENT ... key=value ...>} without any quotes present, at all.
     *      </LI>
     *      </OL>
     * </LI>
     * </UL>
     *
     * @throws InnerTagKeyException <EMBED CLASS="external-html" DATA-FILE-ID="ITKEYEX2">
     * 
     * @throws QuotesException <EMBED CLASS="external-html" DATA-FILE-ID="QEX">
     * 
     * @throws HTMLTokException If an invalid HTML 4 or 5 token is not present 
     * <B>{@code CASE_INSENSITIVE}</B>
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @return An HTML {@code TagNode} instance with updated attribute information.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</SPAN></B> Because <I>{@code TagNode's}
     * are immutable</I> (since they are just wrapped-java-{@code Strings}, which are also
     * immutable), it is important to remember that this method <I><B>does not change the
     * contents</B></I> of a {@code TagNode}, but rather <I><B>returns an entirely new
     * {@code TagNode}</I></B> instance as a result instead.
     *
     * @see ClosingTagNodeException#check(TagNode)
     * @see #generateElementString(String, Properties, Iterable, SD, boolean)
     * @see #setAV(Properties, SD)
     * @see #tok
     * @see #str
     * @see #isClosing
     */
    public TagNode setAV(String attribute, String value, SD quote)
    {
        ClosingTagNodeException.check(this);

        if (attribute == null) throw new NullPointerException(
            "You have passed 'null' to the 'attribute' (attribute-name) String-parameter, " +
            "but this is not allowed here."
        );

        if (value == null) throw new NullPointerException(
            "You have passed 'null' to the 'attribute' (attribute-value) String-parameter, " +
            "but this is not allowed here."
        );

        // Retrieve all "Key-Only" (Boolean) Attributes from 'this' (the original) TagNode
        // Use Java Streams to filter out any that match the newly-added attribute key-value pair.
        // SAVE: Save the updated / shortened list to a List<String>

        List<String> prunedOriginalKeyOnlyAttributes = allKeyOnlyAttributes(true)
            .filter((String originalKeyOnlyAttribute) -> 
                ! originalKeyOnlyAttribute.equalsIgnoreCase(attribute))
            .collect(Collectors.toList());

        // Retrieve all Inner-Tag Key-Value Pairs.  Preserve the Case of the Attributes.  Preserve
        // the Quotation-Marks.

        Properties  p                       = allAV(true, true);
        String      originalValueWithQuotes = null;
        String      computedQuote           = null;

        // NOTE, there should only be ONE instance of an attribute in an HTML element, but malformed
        // HTML happens all the time, so to keep this method safe, it checks (and removes) the entire
        // attribute-list for matches - not just the first found instance.

        for (String key : p.stringPropertyNames())
            if (key.equalsIgnoreCase(attribute))
            {
                Object temp = p.remove(key);
                if (temp instanceof String) originalValueWithQuotes = (String) temp;
            }

        // If the user does not wish to "change" the original quote choice, then find out what
        // the original-quote choice was...

        if (    (quote == null) 
            &&  (originalValueWithQuotes != null)
            &&  (originalValueWithQuotes.length() >= 2)
        )
        {
            char s = originalValueWithQuotes.charAt(0);
            char e = originalValueWithQuotes.charAt(originalValueWithQuotes.length() - 1);
            if ((s == e) && (s == '\''))        computedQuote = "" + SD.SingleQuotes.quote;
            else if ((s == e) && (s == '"'))    computedQuote = "" + SD.DoubleQuotes.quote;
            else                                computedQuote = "";
        }
        else if (quote == null)                 computedQuote = "";
        else                                    computedQuote = "" + quote.quote;

        p.put(attribute, computedQuote + value + computedQuote);

        return new TagNode(generateElementString(
            // Rather than using '.tok' here, preserve the case of the original HTML Element
            this.str.substring(1, 1 + tok.length()), p,
            prunedOriginalKeyOnlyAttributes, null /* SD */, this.str.endsWith("/>")
        ));
    }

    /**
     * This allows for inserting or updating multiple {@code TagNode} inner-tag
     * <B STYLE="color: red;">key-value</B> pairs with a single method invocation.
     * 
     * @param attributes These are the new attribute <B STYLE="color: red;">key-value</B> pairs to
     * be inserted.
     * 
     * @param defaultQuote This is the default quotation mark to use, if the {@code 'attribute'}
     * themselves do not already have quotations.
     *
     * <BR /><BR /><B><SPAN STYLE='color: red;'>IMPORTANT:</B></SPAN> If this value is used, then
     * none of the provided {@code Property}-<B STYLE="color: red;">values</B> of the input
     * {@code java.lang.Properties} instance should have quotes already.  Each of these 
     * new-<B STYLE="color: red;">values</B> will be wrapped in the quote that is provided as the
     * value to this parameter.
     *
     * <BR /><BR /><B><SPAN STYLE='color: red;'>HOWEVER:</B></SPAN> If this parameter is passed a
     * value of 'null', then no quotes will be added to the new <B STYLE="color: red;">keys</B> -
     * <I>unless the attribute being inserted is replacing a previous attribute that was already
     * present in the element.</I>  In this case, the original quotation shall be used.  If this
     * parameter receives 'null' and any of the new {@code Properties} were not already present in
     * the original ({@code 'this'}) element, then no quotation marks will be used, which may
     * throw a {@code QuotesException} if the attribute <B STYLE="color: red;">value</B> contains
     * any white-space.
     *
     * @throws InnerTagKeyException <EMBED CLASS="external-html" DATA-FILE-ID="ITKEYEXPROP">
     * 
     * @throws QuotesException if there are "quotes within quotes" problems, due to the
     * <B STYLE="color: red;">values</B> of the <B STYLE="color: red;">key-value</B> pairs.
     * 
     * @throws HTMLTokException if an invalid HTML 4 or 5 token is not present 
     * <B>({@code CASE_INSENSITIVE})</B>
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     *
     * @return An HTML {@code TagNode} instance with updated {@code TagNode} information.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</SPAN></B> Because 
     * <I>{@code TagNode's} are immutable</I> (since they are just wrapped-java-{@code String's},
     * which are also immutable), it is important to remember that this method <I><B>does not
     * change the contents</B></I> of a {@code TagNode}, but rather <I><B>returns an entirely
     * new {@code TagNode}</I></B> as a result instead.
     *
     * @see ClosingTagNodeException#check(TagNode)
     * @see #setAV(String, String, SD)
     * @see #allKeyOnlyAttributes(boolean)
     * @see #tok
     * @see #str
     * @see #isClosing
     */
    public TagNode setAV(Properties attributes, SD defaultQuote)
    {
        ClosingTagNodeException.check(this);

        // Check that this attributes has elements.
        if (attributes.size() == 0) throw new IllegalArgumentException(
            "You have passed an empty java.util.Properties instance to the " +
            "setAV(Properties, SD) method"
        );

        // Retrieve all Inner-Tag Key-Value Pairs.
        //      Preserve: the Case of the Attributes.
        //      Preserve: the Quotation-Marks.
        Properties originalAttributes = allAV(true, true);

        // Retrieve all "Key-Only" (Boolean) attributes from the new / update attribute-list
        Set<String> newAttributeKeys = attributes.stringPropertyNames();

        // Retrieve all "Key-Only" (Boolean) Attributes from 'this' (the original) TagNode
        // Use Java Streams to filter out all the ones that need to be clobbered by-virtue-of
        // the fact that they are present in the new / parameter-updated attribute key-value list.
        // SAVE: Save the updated / shortened list to a List<String>

        List<String> prunedOriginalKeyOnlyAttributes = allKeyOnlyAttributes(true)
            .filter((String originalKeyOnlyAttribute) ->
            {
                // Returns false when the original key-only attribute matches one of the
                // new attributes being inserted.  Notice that a case-insensitive comparison
                // must be performed - to preserve case.
                for (String newKey : newAttributeKeys) 
                    if (newKey.equalsIgnoreCase(originalKeyOnlyAttribute)) 
                        return false;

                return true;
            })
            .collect(Collectors.toList());

        // NOTE: There is no need to check the validity of the new attributes.  The TagNode
        //       constructor that is invoked on the last line of this method will do a 
        //       validity-check on the attribute key-names provided to the 'attributes' 
        //       java.util.Properties instance passed to to this method.

        for (String newKey : newAttributeKeys)
        {
            String      originalValueWithQuotes = null;
            String      computedQuote           = null;

            // NOTE, there should only be ONE instance of an attribute in an HTML element, but
            // malformed HTML happens all the time, so to keep this method safe, it checks (and
            // removes) the entire attribute-list for matches - not just the first found instance.

            for (String originalKey : originalAttributes.stringPropertyNames())
                if (originalKey.equalsIgnoreCase(newKey))
                {
                    // Remove the original key-value inner-tag pair.
                    Object temp = originalAttributes.remove(originalKey);
                    if (temp instanceof String) originalValueWithQuotes = (String) temp;
                }

            // If the user does not wish to "change" the original quote choice, then find out what
            // the original-quote choice was...

            if (    (defaultQuote == null) 
                &&  (originalValueWithQuotes != null)
                &&  (originalValueWithQuotes.length() >= 2)
            )
            {
                char s = originalValueWithQuotes.charAt(0);
                char e = originalValueWithQuotes.charAt(originalValueWithQuotes.length() - 1);
                if ((s == e) && (s == '\''))        computedQuote = "" + SD.SingleQuotes.quote;
                else if ((s == e) && (s == '"'))    computedQuote = "" + SD.DoubleQuotes.quote;
                else                                computedQuote = "";
            }
            else if (defaultQuote == null)          computedQuote = "";
            else                                    computedQuote = "" + defaultQuote.quote;

            // Insert the newly, updated key-value inner-tag pair.  This 'Properties' will be
            // used to construct a new TagNode.
            originalAttributes.put(newKey, computedQuote + attributes.get(newKey) + computedQuote);
        }

        return new TagNode(generateElementString(
            // Rather than using '.tok' here, preserve the case of the original HTML Element
            this.str.substring(1, 1 + tok.length()),
            originalAttributes, prunedOriginalKeyOnlyAttributes, null /* SD */,
            this.str.endsWith("/>")
        ));
    }


    /**
     * This will append a substring to the attribute <B STYLE="color: red;">value</B> of an HTML
     * {@code TagNode}.
     *
     * This method can be very useful, for instance when dealing with CSS tags that are inserted
     * inside the HTML node itself.  For instance, in order to add a {@code 'color: red;
     * background: white;'} portion to the CSS {@code 'style'} tag of an HTML
     * {@code <TABLE STYLE="...">} element, without clobbering the {@code style}-information that
     * is already inside the element, then this method will achieve such a result.
     *
     * @param attribute The <B STYLE="color: red;">name</B> of the attribute to which the 
     * <B STYLE="color: red;">value</B> must be appended.  This parameter may not be null, or a
     * {@code NullPointerException} will throw.
     *
     * @param appendStr The {@code String} to be appended to the
     * attribute-<B STYLE="color: red;">value</B>.
     * 
     * @param startOrEnd If this parameter is <B>TRUE</B> then the append-{@code String} will be
     * inserted at the beginning (before) whatever the current attribute-<B STYLE="color: red;">
     * value</B> is. If this parameter is <B>FALSE</B> then the append-{@code String} will be
     * inserted at the end (after) the current attribute-<B STYLE="color: red;">value</B>
     * {@code String}.
     *
     * <BR /><BR /><B>NOTE:</B> If tag element currently does not posses this attribute, then the
     * <B STYLE="color: red;">attribute/value</B> pair will be created and inserted with its
     * <B STYLE="color: red;">value</B> set to the value of {@code 'appendStr'.}
     *
     * @param quote This is the quote that will be used when defining the attribute's 
     * <B STYLE="color: red;">key-value</B> pair.  This parameter allows for {@code SD.Single,
     * SD.Double} or {@code 'null'.}  This parameter is provided to help ensure that improper
     * quotations do not occur when modifying  HTML pages.  If 'null' is passed to this parameter,
     * then the choice for quote will follow the rules found in method
     * {@link #setAV(String, String, SD)}.
     * 
     * @return Since all instances of {@code TagNode} are immutable, this method will not actually 
     * alter the {@code TagNode} element, but rather create a new object reference that contains
     * the updated attribute.
     *
     * @see #AV(String)
     * @see #setAV(String, String, SD)
     * @see ClosingTagNodeException#check(TagNode)
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @throws QuotesException The rules of the {@link #setAV(String, String, SD)} method for
     * quotation marks apply here as well.  See that method's requirements and definitions to
     * understand how this exception could possibly be thrown.
     */
    public TagNode appendToAV(String attribute, String appendStr, boolean startOrEnd, SD quote)
    {
        ClosingTagNodeException.check(this);

        if (attribute == null) throw new NullPointerException(
            "You have passed 'null' to the 'attribute' (attribute-name) String-parameter, " +
            "but this is not allowed here."
        );

        if (appendStr == null) throw new NullPointerException(
            "You have passed 'null' to the 'appendStr' (attribute-value-append-string) " +
            "String-parameter, but this is not allowed here."
        );

        String curVal = AV(attribute);
        if (curVal == null) curVal = "";

        // This decides whether to insert the "appendStr" before the current value-string,
        // or afterwards.  This is based on the passed boolean-parameter 'startOrEnd'
        curVal = startOrEnd ? (appendStr + curVal) : (curVal + appendStr);

        // Reuse the 'setAV(String, String, SD)' method already defined in this class.
        return setAV(attribute, curVal, quote);
    }   

    // ********************************************************************************************
    // Attribute Removal Operations
    // ********************************************************************************************

    /** Convenience Method.  Invokes {@link #removeAttributes(String[])} */
    public TagNode remove(String attributeName) { return removeAttributes(attributeName); }

    /**
     * This will remove all inner-tag's whose <B STYLE="color: red;">names</B> match (using
     * {@code CASE-INSENSITIVE} comparisons) the specified
     * attribute-<B STYLE="color: red;">names</B> in this input parameter list
     * {@code 'attributes'}.
     *
     * <BR /><BR /><B>NOTE:</B> This will remove all inner-tags that match the listed attributes 
     * provided.  This means removing <B>BOTH</B> {@code boolean}
     * <B STYLE="color: red;">'key-only'</B> attributes, <B>AND</B> any
     * <B STYLE="color: red;">key-value</B> inner-tags that have <B STYLE="color: red;">names</B>
     * which match the requested remove-list of names.
     *
     * @param attributes This is a list of attribute-<B STYLE="color: red;">names</B> (inner-tags)
     * to be removed from {@code 'this'} instance of {@code TagNode}.  Each {@code String} in this
     * var-args {@code String...} parameter will have {@code String.toLowerCase()} invoked before
     * performing these attribute-<B STYLE="color: red;">name</B> comparisons.
     * 
     * <BR /><BR /><B>NOTE:</B> If {@code 'this'} instance of {@code TagNode} node does not contain
     * any of these attributes, then nothing shall happen; however, a new {@code TagNode} instance
     * shall still be constructed and returned.
     *
     * @return An HTML {@code TagNode} instance with updated {@code TagNode} information.
     * 
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</SPAN></B> Because <I>{@code TagNode's}
     * are immutable</I> (since they are just wrapped-java-{@code String's}, which are also
     * immutable), it is important to remember that this method <I><B>does not change the
     * contents</B></I> of a {@code TagNode}, but rather <I><B>returns an entirely new
     * {@code TagNode}</I></B> as a result instead.
     *
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @see ClosingTagNodeException#check(TagNode)
     * @see #tok
     * @see #isClosing
     * @see #str
     * @see #TagNode(String)
     * @see #generateElementString(String, Properties, Iterable, SD, boolean)
     */
    public TagNode removeAttributes(String... attributes)
    {
        ClosingTagNodeException.check(this);

        // Retrieve all Inner-Tag Key-Value Pairs.  Preserve the Case of the Attributes.  Preserve
        // the Quotation-Marks.
        Properties originalAttributes = allAV(true, true);

        // Remove any attributes from the "Attributes Key-Value Properties Instance" which MATCH the
        // attribute names that have been EXPLICITLY REQUESTED FOR REMOVAL
        for (String key : originalAttributes.stringPropertyNames())
            for (String attribute : attributes)
                if (key.equalsIgnoreCase(attribute))
                    originalAttributes.remove(key);

        // Retrieve all "Boolean Attributes" (key-no-value).  Preserve the Case of these Attributes.
        // Retain only the attributes in the 'filteredKeyOnlyAttributes' String-Array which have
        // PASSED THE FILTER OPERATION.  The filter operation only returns TRUE if the 
        // requested-attribute-list does not contain a copy of the Key-Only-Attribute
        // NOTE: 'true' is passed as input to the 'allKeyOnlyAttributes(boolean)' method to request
        //       that CASE be PRESERVED.
        Iterable<String> prunedKeyOnlyAttributes = allKeyOnlyAttributes(true)
            .filter((String attribute) ->
            {
                // Returns false when the original key-only attribute matches one of the attributes
                // that was requested to to be removed.  Notice that a case-insensitive comparison 
                // must be performed.
                for (String removeAttributes : attributes)
                    if (removeAttributes.equalsIgnoreCase(attribute))
                        return false;

                return true;
            })
            .collect(Collectors.toList());

        return new TagNode(generateElementString(
            // Rather than using '.tok' here, preserve the case of the original HTML Element
            this.str.substring(1, 1 + tok.length()),
            originalAttributes, prunedKeyOnlyAttributes, /* SD */ null, 
            this.str.endsWith("/>")
        ));
    }

    /**
     * {@code TagNode's} are immutable.  And because of this, calling {@code removeAllAV()} is
     * actually the same as retrieving the standard, zero-attribute, pre-instantiated instance of
     * an HTML Element.  Pre-instantiated <B><I>factory-instances</I></B> of {@code class TagNode}
     * for every HTML-Element are stored by {@code class HTMLTags} inside a {@code Hashtable.}
     * They can be retrieved in multiple ways, two of which are found in methods in this class.
     *
     * <BR /><BR /><B>Point of Interest:</B> Calling these three different methods will all return
     * <I>identical</I> {@code Object} references:
     * 
     * <BR /><BR />
     * 
     * <UL CLASS="JDUL">
     * <LI>{@code TagNode v1 = myTagNode.removeAllAV(); } </LI>
     * <LI>{@code TagNode v2 = TagNode.getInstance(myTagToken, openOrClosed); } </LI>
     * <LI>{@code TagNode v3 = HTMLTag.hasTag(myTagToken, openOrClosed); } </LI>
     * <LI><SPAN STYLE="color: red;">{@code assert((v1 == v2) && (v2 == v3)); }</SPAN></LI>
     * </UL>
     * 
     * <BR /><BR /><IMG SRC='removeAllAV.png' CLASS=JDIMG ALT='example'>
     * 
     * @return An HTML {@code TagNode} instance with all inner attributes removed.
     *
     * <BR /><BR /><B>NOTE:</B> If this tag contains an "ending forward slash" that ending slash
     * will not be included in the output {@code TagNode.}
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</SPAN></B> Because <I>{@code TagNode's} 
     * are immutable</I> (since they are just wrapped-java-{@code String's}, which are also
     * immutable), it is important to remember that this method <I><B>does not change the
     * contents</B></I> of a {@code TagNode}, but rather <I><B>returns an entirely new
     * {@code TagNode}</I></B> as a result instead.
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @see ClosingTagNodeException#check(TagNode)
     * @see #getInstance(String, TC)
     * @see #str
     * @see #tok
     * @see TC#OpeningTags
     */
    public TagNode removeAllAV()
    {
        ClosingTagNodeException.check(this);

        // NOTE: We *CANNOT* use the 'tok' field to instantiate the TagNode here, because the 'tok'
        // String-field is *ALWAYS* guaranteed to be in a lower-case format.  The 'str'
        // String-field, however uses the original case that was found on the HTML Document by the
        // parser (or in the Constructor-Parameters that were passed to construct 'this' instance
        // of TagNode.

        return getInstance(this.str.substring(1, 1 + tok.length()), TC.OpeningTags);
    }

    // ********************************************************************************************
    // Retrieve all attributes
    // ********************************************************************************************

    /** Convenience Method.  Invokes {@link #allAV(boolean, boolean)}, attribute-<B STYLE="color: red;">names</B> will be in lower-case. */
    public Properties allAV() { return allAV(false, false); }

    /**
     * This will copy every attribute <B STYLE="color: red;">key-value</B> pair inside
     * {@code 'this'} HTML {@code TagNode} element into a {@code java.util.Properties} Hash-Table.
     *
     * <BR /><BR /><B>RETURN-VALUE NOTE:</B> This method shall not return any "Key-Only Attributes"
     * (a.k.a. "Boolean Attributes").  The most commonly used "Boolean Attribute" example is the
     * {@code 'HIDDEN'} key-word that is used to prevent the browser from displaying an HTML
     * Element. Inner-tags that represent attribute <B STYLE="color: red;">key-value</B> pairs are
     * the only attributes that may be included in the returned {@code 'Properties'} instance.
     *
     * <BR /><BR /><IMG SRC="allAV.png" CLASS=JDIMG ALT="example">
     * 
     * @param keepQuotes If this parameter is passed <B>TRUE</B>, then any surrounding quotation
     * marks will be included for each the <B STYLE="color: red;">values</B> of each attribute
     * key-value pair.
     *
     * @param preserveKeysCase If this parameter is passed <B>TRUE</B>, then the method
     * {@code String.toLowerCase()} will not be invoked on any of the
     * <B STYLE="color: red;">keys</B> (attribute-names) of each inner-tag key-value pair.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @return This returns a list of each and every attribute-<B STYLE="color: red;">name</B> -
     * <I>and the associate <B STYLE="color: red;">value</B> of the attribute</I> - found in
     * {@code 'this' TagNode}.  An instance of {@code class java.util.Properties} is used to store
     * the attribute <B STYLE="color: red;">key-value</B> pairs. 
     *
     * <BR /><BR /><B>NOTE:</B> This method will <B>NOT</B> return any boolean,
     * <B STYLE="color: red;">key-only</B> attributes present in {@code 'this' TagNode}.
     * 
     * <BR /><BR /><B>ALSO:</B> This method shall not return {@code 'null'}.  If there do not
     * exist any Attribute-Value Pairs, or if {@code 'this'} node is a closing-element, then
     * an empty {@code 'Properties'} instance shall be returned.
     * 
     * @see StringParse#ifQuotesStripQuotes(String)
     * @see AttrRegEx#KEY_VALUE_REGEX
     * @see #tok
     * @see #str
     */
    public Properties allAV(boolean keepQuotes, boolean preserveKeysCase)
    {
        Properties ret = new Properties();

        // NOTE:    OPTIMIZED, "closing-versions" of the TagNode, and TagNode's whose 'str' field is
        //          only longer than the token, itself, by 3 or less characters cannot have attributes.
        // CHARS:   '<', TOKEN, SPACE, '>'
        // RET:     In that case, just return an empty 'Properties' instance.
        if (isClosing || (str.length() <= (tok.length() + 3))) return ret;

        // This RegEx Matcher 'matches' against Attribute/InnerTag Key-Value Pairs.
        // m.group(1): UN-USED!  (Includes Key, Equals-Sign, and Value).  Leaves-off leading white-space.
        // m.group(2): returns the 'key' portion of the key-value pair, before an '=' (equals-sign).
        // m.group(3): returns the 'value' portion of the key-value pair, after an '='
        Matcher m = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // MORE-CODE, but MORE-EFFICIENT (slightly)  It looks neat to boot.
        if      (keepQuotes     && preserveKeysCase)    while (m.find()) ret.put(m.group(2), m.group(3));
        else if (!keepQuotes    && preserveKeysCase)    while (m.find()) ret.put(m.group(2), StringParse.ifQuotesStripQuotes(m.group(3)));
        else if (keepQuotes     && !preserveKeysCase)   while (m.find()) ret.put(m.group(2).toLowerCase(), m.group(3));
        else if (!keepQuotes    && !preserveKeysCase)   while (m.find()) ret.put(m.group(2).toLowerCase(), StringParse.ifQuotesStripQuotes(m.group(3)));

        return ret;
    }

    /**
     * Convenience Method.  Invokes {@link #allAN(boolean, boolean)}.
     * <BR /><BR />Attribute-<B STYLE="color: red;">names</B> will be in lower-case.
     */
    public Stream<String> allAN()
    { return allAN(false, false); }

    /**
     * This method will only return a list of attribute-<B STYLE="color: red;">names</B>.  The
     * attribute-<B STYLE="color: red">values</B> shall <B>NOT</B> be included in the result.  The
     * {@code String's} returned can have their "case-preserved" by passing <B>TRUE</B> to the
     * input boolean parameter {@code 'preserveCase'}.
     *
     * @param preserveKeysCase If this is parameter receives <B>TRUE</B> then the case of the
     * attribute-<B STYLE="color: red;">names</B> shall be preserved.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @param includeKeyOnlyAttributes When this parameter receives <B>TRUE</B>, then any
     * "Boolean Attributes" or "Key-Only, No-Value-Assignment" Inner-Tags will <B>ALSO</B> be
     * included in the {@code Stream<String>} returned by this method.
     *
     * @return an instance of {@code Stream<String>} containing all
     * attribute-<B STYLE="color: red;">names</B> identified in {@code 'this'} instance of
     * {@code TagNode}.  A {@code java.util.stream.Stream} is used because it's contents can easily
     * be converted to just about any data-type.  
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="STRMCNVT">
     *
     * <BR /><B>NOTE:</B> This method shall never return {@code 'null'} - even if there are no 
     * attribute <B STYLE="color: red;">key-value</B> pairs contained by {@code 'this' TagNode}.
     * If there are strictly zero attributes, an empty {@code Stream} shall be returned, instead.
     * 
     * @see #allKeyOnlyAttributes(boolean)
     * @see #allAN()
     */
    public Stream<String> allAN(boolean preserveKeysCase, boolean includeKeyOnlyAttributes)
    {
        // If there is NO ROOM in the "str" field for attributes, then there is now way attributes
        // could exist in this element.  Return "empty" immediately.
        // 
        // NOTE:    OPTIMIZED, "closing-versions" of the TagNode, and TagNode's whose 'str' field
        //          is only longer than the token, itself, by 3 or less characters cannot have
        //          attributes.
        // CHARS:   '<', TOKEN, SPACE, '>'
        // RET:     In that case, just return an empty Stream.
        if (isClosing || (str.length() <= (tok.length() + 3))) return Stream.empty();

        // Use Java Streams.  A String-Stream is easily converted to just about any data-type
        Stream.Builder<String> b = Stream.builder();

        // This RegEx Matcher 'matches' against Attribute/InnerTag Key-Value Pairs.
        // m.group(2): returns the 'key' portion of the key-value pair, before an '=' (equals-sign).
        Matcher m = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // Retrieve all of the keys of the attribute key-value pairs.
        while (m.find()) b.add(m.group(2));

        // This Stream contains only keys that were once key-value pairs, if there are "key-only" 
        // attributes, they have not been added yet.
        Stream<String> ret = b.build();

        // Convert these to lower-case, (if requested)
        if (! preserveKeysCase) ret = ret.map((String attribute) -> attribute.toLowerCase());

        // Now, add in all the "Key-Only" attributes (if there are any).  Note, "preserve-case"
        // and "to lower case" are handled, already, in method "allKeyOnlyAttributes(boolean)"
        if (includeKeyOnlyAttributes)
            return Stream.concat(ret, allKeyOnlyAttributes(preserveKeysCase));

        return ret;
    }

    // ********************************************************************************************
    // Key only attributes
    // ********************************************************************************************

    /**
     * This method returns a {@code Stream<String>} of all token-{@code String's} that are found 
     * between attribute key-value pairs in {@code 'this' TagNode} instance.  These 
     * attribute-<B STYLE="color: red;">names</B> may not have any
     * <B STYLE="color: red;">values</B> assignments, or they will be considered <B>INELLIGIBLE</B>
     * for being included in the return result set from this method.
     * 
     * <BR /><BR /><IMG SRC='allKeyOnlyAttributes.png' CLASS=JDIMG ALT='example'>
     *
     * @param preserveKeysCase If this parameter is passed <B>TRUE</B>, then the method 
     * {@code String.toLowerCase()} will not be invoked on any of the
     * <B STYLE="color: red;">keys</B> (attribute-<B STYLE="color: red;">names</B>) returned.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @return a java {@code Stream<String>} that contains any and all character text that resides
     * between attribute <B STYLE="color: red;">key-value</B> pairs that have matched.  Generally, 
     * in well formed HTML, this should correspond directly to what are normally called "Boolean 
     * Attributes."  Boolean attributes are just words inside of an HTML Element that describe the
     * contents of the HTML.  The primary issue about "Boolean Attributes" is that they do not need
     * <B STYLE="color: red;">values</B> - <I> they are strictly a <B STYLE="color: red;">key</B>,
     * alone.</I>
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="STRMCNVT">
     *
     * <BR /><B>NOTE:</B> This method shall never return 'null' - even if there are no attribute
     * <B STYLE="color: red;">key-value</B> pairs contained by the {@code TagNode}.  If there are 
     * strictly zero attributes, {@code Stream.empty()} shall be returned, instead.
     * 
     * @see #tok
     * @see #str
     */
    public Stream<String> allKeyOnlyAttributes(boolean preserveKeysCase)
    {
        // NOTE: OPTIMIZED, "closing-versions" of the TagNode, and TagNode's whose 'str'
        //       field is only longer than the token, itself, by 3 or less characters cannot have
        //       attributes.  In that case, just return an empty 'Stream' instance.
        int len = str.length();
        if (isClosing || (len <= (tok.length() + 3))) return Stream.empty();

        // Leaves off the opening 'token' and less-than '<' symbol  (leaves off, <DIV - for example)
        // Also leave off the "ending-forward-slash" (if there is one).
        String  s = str.substring(tok.length() + 1, len - ((str.charAt(len - 2) == '/') ? 2 : 1));

        // if all lower-case is requested, do that here.
        if (! preserveKeysCase) s = s.toLowerCase();

        // java.util.regex.Pattern.split(CharSequence) is sort of an "inverse reg-ex" in that it 
        // returns all of the text that was present BETWEEN the matches 
        // NOTE: This is the "opposite of the matches, themselves)" - a.k.a. all the stuff that was
        //       left-out.

        Stream.Builder<String> b = Stream.builder();
        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(s))      // 'split' => inverse-matches
            for (String keyWord : unMatchedStr.split("\\s+"))               // white-space split (connected chars)
                if ((keyWord = keyWord.trim()).length() > 0)                // Call String.trim() and String.length()
                    if (AttrRegEx.ATTRIBUTE_KEY_REGEX_PRED.test(keyWord))   // Check for valid Attribute-Name
                        b.add(keyWord);                                     // ... put it in the return stream.
                                                                            // NOTE: This has the potential to slightly
                                                                            //       change the original HTML... It will
                                                                            //       "leave out any guck" that was in the Element

        // Build the Stream<String>, and return;
        return b.build();
    }

    /**
     * Will identify if a "boolean attribute" - a.k.a. a token-<B STYLE="color: red;">name</B> that
     * exists BETWEEN inner-tag key-value pairs is present in the {@code TagNode}.  One of the
     * most common "Key-Word-Only Attributes" is the inner-tag {@code 'HIDDEN'}.  Hidden HTML
     * Elements have their CSS feature {@code style.display} set to {@code 'NONE'};
     * 
     * @param keyOnlyAttribute This may be the <B STYLE="color: red;">name</B> of any inner-tag.
     * 
     * <BR /><BR /><B>NOTE:</B> This parameter, is not checked for validity against the
     * attribute-<B STYLE='color: red;'>name</B> regular-expression.
     * 
     * @return Will return <B>TRUE</B> if the named {@code 'keyOnlyAttribute'} is present in the
     * HTML Element as a stand-alone attribute - <I>i.e., lacking a
     * <B STYLE="color: red;">value</B> assignment</I>  The comparison performed is
     * case-insensitive.
     * 
     * <BR /><BR />If {@code 'this'} instance of {@code TagNode} is a closing-version of the
     * element, this method shall return <B>FALSE</B> immediately, and exit.
     * 
     * @throws IllegalArgumentException If the input-parameter receives a {@code String} that
     * contains any white-space itself, an exception will throw.  The search-logic splits the
     * {@code String's} based on  white-space, so if a user passes a white-space containing
     * {@code String}, a match would simply never occur.
     * 
     * <BR /><BR /><B STYLE='color:red;'>IMPORTANT:</B> This method <I><B>does not</B></I> check
     * the validity of the {@code 'keyOnlyAttribute'} parameter against the
     * Attribute-<B STYLE='color:red;'>name</B> regular-expression, because this method uses the
     * {@code 'split(String)'} method of the Regular-Expression Matcher.  All this means, is that
     * this method may actually be used to check for any-text inside of an HTML Element - <I>so
     * long as that text does not contain white-space.</I>  This is not an encouraged use of this
     * method, but it will work.
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public boolean hasKeyOnlyAttribute(String keyOnlyAttribute)
    {
        // Closing TagNode's do not have attributes, return false immediately.
        if (this.isClosing) return false;

        // ONLY CHECKS FOR WHITE-SPACE, *NOT* VALIDITY...
        if (StringParse.hasWhiteSpace(keyOnlyAttribute)) throw new IllegalArgumentException(
            "The attribute you have passed [" + keyOnlyAttribute + "] has white-space, " +
            "This is not allowed here, because the search routine splits on whitespace, and " +
            "therefore a match would never be found."
        );

        // NOTE: TagNode's whose 'str' field is only longer than the token, itself, by 3 or less
        //       characters cannot have attributes.  In that case, just return false.
        int len = str.length();
        if (len <= (tok.length() + 3)) return false;

        // Leaves off the opening 'token' and less-than '<' symbol  (leaves off, <DIV - for example)
        // Also leave off the "ending-forward-slash" (if there is one).
        String s = str.substring(tok.length() + 1, len - ((str.charAt(len - 2) == '/') ? 2 : 1));

        // java.util.regex.Pattern.split(CharSequence) is sort of an "inverse reg-ex" in that it 
        // returns all of the text that was present BETWEEN the matches 

        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(s))  // 'split' => inverse-matches
            for (String keyWord : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyWord = keyWord.trim()).length() > 0)            // trim, check-length...
                    if (keyOnlyAttribute.equalsIgnoreCase(keyWord))
                        return true;

        // Was not found, return false;
        return false;
    }

    // ********************************************************************************************
    // testAV
    // ********************************************************************************************

    /**
     * Test the <B STYLE="color: red;">value</B> of the inner-tag named {@code 'attributeName'}
     * (if that attribute exists, and has a non-empty value) using a provided
     * {@code TextComparitor}
     * 
     * @param attributeName Any String will suffice - but only valid attribute
     * <B STYLE="color: red;">names</B> will match the internal regular-expression.
     * 
     * <BR /><BR /><B>NOTE:</B> The validity of this parameter <I><B>is not</I></B> checked with
     * the HTML attribute-<B STYLE="color: red;">name</B> Regular-Expression exception checker.
     * 
     * @param tc This may be any pre-instantiated or user created {@code TextComparitor}
     * 
     * @param compareStrs This should be a {@code String[] array} of comparison-strings to
     * work with parameter {@code 'tc'}.
     * 
     * @return Method will return <B>TRUE</B> if and only if:
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> {@code 'this'} instance of {@code TagNode} has an inner-tag named
     *      {@code 'attributeName'}.
     *      <BR /><BR />
     * </LI>
     * <LI> The results of applying the provided {@code TextComparitor} parameter {@code 'tc'}
     *      against the attribute-<B STYLE="color: red">value</B> and {@code comparStrs} array,
     *      returns <B>TRUE</B>.
     * </LI>
     * </UL>
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     * @see #str 
     * @see #isClosing
     * @see StringParse#ifQuotesStripQuotes(String)
     */
    public boolean testAV(String attributeName, TextComparitor tc, String... compareStrs)
    {
        // Closing TagNode's (</DIV>, </A>) cannot attributes, or attribute-values
        if (isClosing) return false;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have the attribute named by the input parameter
        if (this.str.length() < (this.tok.length() + attributeName.length() + 4)) return false;

        // This Reg-Ex will allow us to iterate through each attribute key-value pair
        // contained / 'inside' this instance of TagNode.
        Matcher m = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // Test each attribute key-value pair, and return the test results if an attribute
        // whose name matches 'attributeName' is found.
        while (m.find())
            if (m.group(2).equalsIgnoreCase(attributeName))
                return tc.test
                    (StringParse.ifQuotesStripQuotes(m.group(3)), compareStrs);

        // No attribute key-value pair was found whose 'key' matched input-parameter
        // 'attributeName'
        return false;
    }

    /**
     * Test the <B STYLE="color: red;">value</B> of the inner-tag named {@code 'attributeName'}
     * (if that attribute exists, and has a non-empty value) using a provided
     * {@code java.util.regex.Pattern}
     * 
     * <BR /><BR /><IMG SRC='testAV2.png' CLASS=JDIMG ALT='example'>
     * 
     * @param attributeName Any String will suffice - but only valid attribute
     * <B STYLE="color: red;">names</B> will match the internal regular-expression.
     * 
     * <BR /><BR /><B>NOTE:</B> The validity of this parameter <I><B>is not</I></B> checked with
     * the HTML attribute-<B STYLE="color: red;">name</B> Regular-Expression exception checker.
     * 
     * @param attributeValueTest This may be an regular-expression
     * 
     * @return Method will return <B>TRUE</B> if and only if:
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> {@code 'this'} instance of {@code TagNode} has an inner-tag named
     *      {@code 'attributeName'}.
     *      <BR /><BR />
     * </LI>
     * <LI> The results of invoking {@code attributeValueTest.matcher(...).find()} on the
     *      attribute-<B STYLE="color: red">value</B> returns <B>TRUE</B>.
     * </LI>
     * </UL>
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     * @see #str 
     * @see #isClosing
     * @see StringParse#ifQuotesStripQuotes(String)
     */
    public boolean testAV(String attributeName, Pattern attributeValueTest)
    {
        // Closing TagNode's (</DIV>, </A>) cannot attributes, or attribute-values
        if (isClosing) return false;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have the attribute named by the input parameter
        if (this.str.length() < (this.tok.length() + attributeName.length() + 4)) return false;

        // This Reg-Ex will allow us to iterate through each attribute key-value pair
        // contained / 'inside' this instance of TagNode.
        Matcher m = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // Test each attribute key-value pair, and return the test results if an attribute
        // whose name matches 'attributeName' is found.
        while (m.find())
            if (m.group(2).equalsIgnoreCase(attributeName))
                return attributeValueTest.matcher
                    (StringParse.ifQuotesStripQuotes(m.group(3))).find();

        // No attribute key-value pair was found whose 'key' matched input-parameter
        // 'attributeName'
        return false;
    }

    /**
     * Test the <B STYLE="color: red;">value</B> of the inner-tag named {@code 'attributeName'}
     * (if that attribute exists, and has a non-empty value) using a provided
     * {@code Predicate<String>}.
     * 
     * <BR /><BR /><IMG SRC='testAV1.png' CLASS=JDIMG ALT='example'>
     * 
     * @param attributeName Any String will suffice - but only valid attribute
     * <B STYLE="color: red;">names</B> will match the internal regular-expression.
     * 
     * <BR /><BR /><B>NOTE:</B> The validity of this parameter <I><B>is not</I></B> checked with
     * the HTML attribute-<B STYLE="color: red;">name</B> Regular-Expression exception checker.
     * 
     * @param attributeValueTest Any {@code java.util.function.Predicate<String>}
     * 
     * @return Method will return <B>TRUE</B> if and only if:
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     * <LI> {@code 'this'} instance of {@code TagNode} has an inner-tag named
     *      {@code 'attributeName'}.
     *      <BR /><BR />
     * </LI>
     * <LI> The results of the provided {@code String-Predicate}, when applied against the
     *      <B STYLE="color: red">value</B> of the requested attribute, returns <B>TRUE</B>.
     * </LI>
     * </UL>
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     * @see #str 
     * @see #isClosing
     * @see StringParse#ifQuotesStripQuotes(String)
     */
    public boolean testAV(String attributeName, Predicate<String> attributeValueTest)
    {
        // Closing TagNode's (</DIV>, </A>) cannot attributes, or attribute-values
        if (isClosing) return false;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have the attribute named by the input parameter
        if (this.str.length() < (this.tok.length() + attributeName.length() + 4)) return false;

        // This Reg-Ex will allow us to iterate through each attribute key-value pair
        // contained / 'inside' this instance of TagNode.
        Matcher m = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // Test each attribute key-value pair, and return the test results if an attribute
        // whose name matches 'attributeName' is found.
        while (m.find())
            if (m.group(2).equalsIgnoreCase(attributeName))
                return attributeValueTest.test
                    (StringParse.ifQuotesStripQuotes(m.group(3)));

        // No attribute key-value pair was found whose 'key' matched input-parameter
        // 'attributeName'
        return false;
    }


    // ********************************************************************************************
    // has-attribute boolean-logic methods
    // ********************************************************************************************

    /**
     * This method provides a quick way of testing if {@code 'this'} HTML {@code TagNode} contains
     * certain inner-tags with specified <B STYLE="color: red;">names</B>.
     * 
     * <BR /><BR />
     * This uses <B>{@code logical NAND}</B> meaning that {@code FALSE} shall be returned if any of
     * the inner tags provided in the {@code 'attributes'} parameter list are found in
     * {@code 'this'} instance of {@code TagNode}.
     * 
     * @param attributes This is a list of HTML Element Attribute-<B STYLE="color: red;">Names</B> 
     * or "Inner Tags" as they are called in this Search and Scrape Package.
     * 
     * @param checkAttributeStringsForErrors <EMBED CLASS="external-html" DATA-FILE-ID="TNHASBOOL">
     * 
     * @return <B>TRUE</B> if none of these  attributes-<B STYLE="color: red;">names</B> are
     * present, in {@code 'this'} instance and <B>FALSE</B> otherwise.
     * 
     * <BR /><BR /><B>NOTE:</B> If this method is passed a zero-length {@code String}-array to the
     * {@code 'attributes'} parameter, this method shall exit immediately and return <B>TRUE</B>.
     * 
     * @throws InnerTagKeyException If any of the {@code 'attributes'} are not valid HTML
     * attributes, <I><B>and</B></I> the user has passed <B>TRUE</B> to parameter
     * {@code checkAttributeStringsForErrors}.
     * 
     * @throws NullPointerException If any of the {@code 'attributes'} are null.
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @throws IllegalArgumentException If the {@code 'attributes'} parameter has length zero.
     * 
     * @see InnerTagKeyException#check(String[])
     * @see #AV(String)
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public boolean hasNAND(boolean checkAttributeStringsForErrors, String... attributes)
    {
        ClosingTagNodeException.check(this);

        // If no attributes are passed to 'attributes' parameter, throw exception.
        if (attributes.length == 0) throw new IllegalArgumentException
            ("Input variable-length String[] array parameter, 'attributes', has length zero.");

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have any attribute-value pairs.
        // 4 (characters) are: '<', '>', ' ' and 'X'
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X>
        //
        // This TagNode doesn't have any attributes in it.
        // There is no need to check anything, so return FALSE immediately ("NAND" succeeds)
        if (this.str.length() < (this.tok.length() + 4)) return true;

        if (checkAttributeStringsForErrors) InnerTagKeyException.check(attributes);

        // Get all inner-tag key-value pairs.  If even one of these is inside the 'attributes'
        // input-parameter string-array.  Then we must return false, since this is a NAND - or
        // 'NOT ANY' - operation.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        while (keyValueInnerTags.find())
        {
            String innerTagKey = keyValueInnerTags.group(2);                    // Retrieve the key of the key-value pair
            for (String attributeToNAND : attributes)                           // Iterate every element of the String[] 'attributes' parameter
                if (innerTagKey.equalsIgnoreCase(attributeToNAND))              // Does the input parameter String-array match with an inner-tag key?
                    return false;                                               // NAND: If there is a match, return FALSE immediately
        }

        // Also check the "Boolean Attributes" also known as the "Key-Word Only Attributes"
        // Use the "Inverse Reg-Ex Matcher" (which matches all the strings that are "between" the real matches)
        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(this.str))   // INVERSE-matches of the key-value Reg-Ex
            for (String keyOnlyInnerTag : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyOnlyInnerTag = keyOnlyInnerTag.trim()).length() > 0)    // Just-In-Case, usually not necessary
                    for (String attributeToNAND : attributes)                   // Iterate all the input-parameter String-array attributes
                        if (keyOnlyInnerTag.equalsIgnoreCase(attributeToNAND))  // If even one of them
                            return false;                                       // NAND: If there is a match, return FALSE immediately

        // If NIETHER the Key-Value attributes, NOR the Key-Only attributes had any matches with
        // the input String-Array parameter "attributes", then (and only then) should TRUE be returned.
        return true;
    }

    /**
     * This method provides a quick way of testing if {@code 'this'} HTML {@code TagNode} contains
     * certain inner-tags with specified <B STYLE="color: red;">names</B>.
     * 
     * <BR /><BR />
     * This uses <B>{@code logical XOR}</B> meaning that {@code TRUE} shall be returned if
     * <I>*precisely one*</I> of the inner tags provided in the {@code 'attributes'} parameter list
     * are found in {@code 'this'} instance of {@code TagNode}.
     * 
     * @param attributes This is a list of HTML Element Attribute-<B STYLE="color: red;">Names</B> 
     * or "Inner Tags" as they are called in this Search and Scrape Package.
     * 
     * @param checkAttributeStringsForErrors <EMBED CLASS="external-html" DATA-FILE-ID="TNHASBOOL">
     * 
     * @return <B>TRUE</B> if exactly one of these attributes-<B STYLE="color: red;">names</B> are
     * present in {@code 'this'} instance, and <B>FALSE</B> otherwise.
     * 
     * <BR /><BR /><B>NOTE:</B> If this method is passed a zero-length {@code String}-array to the
     * {@code 'attributes'} parameter, this method shall exit immediately and return <B>FALSE</B>.
     * 
     * @throws InnerTagKeyException If any of the {@code 'attributes'} are not valid HTML
     * attributes <I><B>and</B></I> the user has passed <B>TRUE</B> to parameter
     * {@code checkAttributeStringsForErrors}.
     * 
     * @throws NullPointerException If any of the {@code 'attributes'} are null.
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @throws IllegalArgumentException If the {@code 'attributes'} parameter has length zero.
     * 
     * @see InnerTagKeyException#check(String[])
     * @see #AV(String)
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public boolean hasXOR(boolean checkAttributeStringsForErrors, String... attributes)
    {
        ClosingTagNodeException.check(this);

        // If no attributes are passed to 'attributes' parameter, throw exception.
        if (attributes.length == 0) throw new IllegalArgumentException
            ("Input variable-length String[] array parameter, 'attributes', has length zero.");

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have any attribute-value pairs.
        // 4 (characters) are: '<', '>', ' ' and 'X'
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X>
        //
        // This TagNode doesn't have any attributes in it.
        // There is no need to check anything, so return FALSE immediately ("XOR" fails)
        if (this.str.length() < (this.tok.length() + 4)) return false;

        if (checkAttributeStringsForErrors) InnerTagKeyException.check(attributes);

        // Temporary variable.  This is required because this is an "XOR" comparison.
        boolean ret = false;

        // Get all inner-tag key-value pairs.  When one of the input-parameter string-array
        // inner-tags is found, we must take a note saying a match has been found.  If there is a
        // second-match, because this is XOR, we must return FALSE immediately.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        while (keyValueInnerTags.find())
        {
            String innerTagKey = keyValueInnerTags.group(2);                    // Retrieve the key of the key-value pair
            for (String attributeToXOR : attributes)                            // Iterate every element of the String[] 'attributes' parameter
                if (innerTagKey.equalsIgnoreCase(attributeToXOR))               // Does the input parameter String-array match with an inner-tag key?
                { if (ret) return false; else ret = true; }                     // XOR: If there is a second match must, return FALSE immediately
        }

        // Also check the "Boolean Attributes" also known as the "Key-Word Only Attributes"
        // Use the "Inverse Reg-Ex Matcher" (which matches all the strings that are "between" the
        // real matches)

        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(this.str))   // INVERSE-matches of the key-value Reg-Ex
            for (String keyOnlyInnerTag : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyOnlyInnerTag = keyOnlyInnerTag.trim()).length() > 0)    // Just-In-Case, usually not necessary
                    for (String attributeToXOR : attributes)                    // Iterate all the input-parameter String-array attributes
                        if (keyOnlyInnerTag.equalsIgnoreCase(attributeToXOR))   // Is there a match?
                        { if (ret) return false; else ret = true; }             // XOR: If there is a second match must, return FALSE immediately

        // This will be TRUE if there was PRECISELY one match.
        return ret;
    }

    /**
     * This method provides a quick way of testing if {@code 'this'} HTML {@code TagNode} contains
     * certain inner-tags with specified <B STYLE="color: red;">names</B>.
     * 
     * <BR /><BR />
     * This uses <B>{@code logical AND}</B> meaning that {@code TRUE} shall be returned <I>*if and 
     * only if*</I> all of the inner tags provided in the {@code 'attributes'} parameter list are
     * found in {@code 'this'} instance of {@code TagNode}.
     * 
     * <BR /><BR /><IMG SRC="hasAND.png" CLASS=JDIMG ALT="Example">
     * 
     * @param attributes This is a list of HTML Element Attribute-<B STYLE="color: red;">Names</B> 
     * or "Inner Tags" as they are called in this Search and Scrape Package.
     * 
     * @param checkAttributeStringsForErrors <EMBED CLASS="external-html" DATA-FILE-ID="TNHASBOOL">
     * 
     * @return <B>TRUE</B> if each and every one of these
     * attributes-<B STYLE="color: red;">names</B> are present in {@code 'this'} instance, and
     * <B>FALSE</B> otherwise.
     * 
     * <BR /><BR /><B>NOTE:</B> If this method is passed a zero-length {@code String}-array to the
     * {@code 'attributes'} parameter, this method shall exit immediately and return <B>FALSE</B>
     * 
     * @throws InnerTagKeyException If any of the {@code 'attributes'} are not valid HTML
     * attributes, <I><B>and</B></I> the user has passed <B>TRUE</B> to parameter
     * {@code checkAttributeStringsForErrors}.
     * 
     * @throws NullPointerException If any of the {@code 'attributes'} are null.
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @throws IllegalArgumentException If the {@code 'attributes'} parameter has length zero.
     * 
     * @see InnerTagKeyException#check(String[])
     * @see #AV(String)
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public boolean hasAND(boolean checkAttributeStringsForErrors, String... attributes)
    {
        ClosingTagNodeException.check(this);

        // If no attributes are passed to 'attributes' parameter, throw exception.
        if (attributes.length == 0) throw new IllegalArgumentException
            ("Input variable-length String[] array parameter, 'attributes', has length zero.");

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have any attribute-value pairs.
        // 4 (characters) are: '<', '>', ' ' and 'X'
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X>
        //
        // This TagNode doesn't have any attributes in it.
        // There is no need to check anything, so return FALSE immediately ("AND" fails)
        if (this.str.length() < (this.tok.length() + 4)) return false;

        if (checkAttributeStringsForErrors) InnerTagKeyException.check(attributes);

        // This is a temporary data-structure.  It will keep a list of the inner-tags from the
        // input-parameter string-array 'attributes' stored in lowe-case format.  These elements
        // will be slowly removed as they are found in the HTML Element.  Once the size() of this
        // TreeSet is zero, it would imply that ALL INNER-TAGS WERE FOUND, and then TRUE would be
        // returned.
        TreeSet<String> tlcAttributes = new TreeSet<>();

        for (String attribute : attributes) tlcAttributes.add(attribute.toLowerCase());

        // Get all inner-tag key-value pairs.  Every time the "attribute-name" matches one of the
        // elements in the temporary TreeSet data-structure, it means another one of the requested
        // attributes has been found.  When they are all found, we can return TRUE.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        String innerTagKey;
        while (keyValueInnerTags.find())
            if (tlcAttributes.contains(innerTagKey = keyValueInnerTags.group(2).toLowerCase()))
            {
                tlcAttributes.remove(innerTagKey);                              // Found another match with the input String[] parameter
                if (tlcAttributes.size() == 0) return true;                     // If all attributes have been found, return TRUE immediately
            }

        // Also check the "Boolean Attributes" also known as the "Key-Word Only Attrbutes"
        // Use the "Inverse Reg-Ex Matcher" (which matches all the strings that are "between" the
        // real matches)

        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(this.str))   // INVERSE-matches of the key-value Reg-Ex
            for (String keyOnlyInnerTag : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyOnlyInnerTag = keyOnlyInnerTag.trim()).length() > 0)    // Just-In-Case, usually not necessary
                    if (tlcAttributes.contains(keyOnlyInnerTag = keyOnlyInnerTag.toLowerCase()))
                    {
                        tlcAttributes.remove(keyOnlyInnerTag);                  // Found another match with the input String[] parameter
                        if (tlcAttributes.size() == 0) return true;             // If all attributes have been found, return TRUE immediately
                    }

        // Some of the input-parameter string-array 'attributes' were NOT FOUND (or else TRUE would
        // have already been returned).
        // Since this is an 'AND' return false.
        return false;
    }

    /**
     * This method provides a quick way of testing if {@code 'this'} HTML {@code TagNode} contains
     * certain inner-tags with specified <B STYLE="color: red;">names</B>.
     * 
     * <BR /><BR />
     * This uses {@code logical OR} meaning that {@code TRUE} shall be returned if any of the
     * inner tags provided in the {@code 'attributes'} parameter list are found in {@code 'this'}
     * instance of {@code TagNode}.
     * 
     * <BR /><BR /><IMG SRC="hasOR.png" CLASS=JDIMG ALT="Example">
     * 
     * @param attributes This is a list of HTML Element Attribute-<B STYLE="color: red;">Names</B> 
     * or "Inner Tags" as they are called in this Search and Scrape Package.
     * 
     * @param checkAttributeStringsForErrors <EMBED CLASS="external-html" DATA-FILE-ID="TNHASBOOL">
     * 
     * @return <B>TRUE</B> if at least one of these attribute-<B STYLE="color: red;">names</B> are
     * present in {@code 'this'} instance, and <B>FALSE</B> otherwise.
     * 
     * <BR /><BR /><B>NOTE:</B> If this method is passed a zero-length {@code String}-array to the
     * {@code 'attributes'} parameter, this method shall exit immediately and return <B>FALSE</B>.
     * 
     * @throws InnerTagKeyException If any of the {@code 'attributes'} are not valid HTML
     * attributes, <I><B>and</B></I> the user has passed <B>TRUE</B> to parameter
     * {@code checkAttributeStringsForErrors}.
     * 
     * @throws NullPointerException If any of the {@code 'attributes'} are null.
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @throws IllegalArgumentException If the {@code 'attributes'} parameter has length zero.
     * 
     * @see InnerTagKeyException#check(String[])
     * @see #AV(String)
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public boolean hasOR(boolean checkAttributeStringsForErrors, String... attributes)
    {
        ClosingTagNodeException.check(this);

        // If no attributes are passed to 'attributes' parameter, throw exception.
        if (attributes.length == 0) throw new IllegalArgumentException
            ("Input variable-length String[] array parameter, 'attributes', has length zero.");

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have any attribute-value pairs.
        // 4 (characters) are: '<', '>', ' ' and 'X'
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X>
        //
        // This TagNode doesn't have any attributes in it.
        // There is no need to check anything, so return FALSE immediately ("OR" fails)
        if (this.str.length() < (this.tok.length() + 4)) return false;

        if (checkAttributeStringsForErrors) InnerTagKeyException.check(attributes);

        // Get all inner-tag key-value pairs.  If even one of these is inside the 'attributes'
        // input-parameter string-array,  Then we must return true, since this is OR
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        while (keyValueInnerTags.find())
        {
            String innerTagKey = keyValueInnerTags.group(2);                    // Retrieve the key of the key-value pair
            for (String attributeToOR : attributes)                             // Iterate every element of the String[] 'attributes' parameter
                if (innerTagKey.equalsIgnoreCase(attributeToOR))                // Does the input parameter String-array match with an inner-tag key?
                    return true;                                                // OR: If there is any match, return TRUE immediately
        }

        // Also check the "Boolean Attributes" also known as the "Key-Word Only Attributes"
        // Use the "Inverse Reg-Ex Matcher" (which matches all the strings that are "between" the
        // real matches)

        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(this.str))   // INVERSE-matches of the key-value Reg-Ex
            for (String keyOnlyInnerTag : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyOnlyInnerTag = keyOnlyInnerTag.trim()).length() > 0)    // Just-In-Case, usually not necessary
                    for (String attributeToOR : attributes)                     // Iterate all the input-parameter String-array attributes
                        if (keyOnlyInnerTag.equalsIgnoreCase(attributeToOR))    // If even one of them
                            return true;                                        // NAND: If there is any match, return TRUE immediately

        // If NIETHER the Key-Value attributes, NOR the Key-Only attributes had any matches with
        // the input String-Array parameter "attributes", the OR-comparison has failed, and we
        // must return false.
        return false;
    }

    // ********************************************************************************************
    // has methods - extended, variable attribute-names
    // ********************************************************************************************

    /**
     * Will search this {@code TagNode} to determine if any inner-tag key-value pairs have a 
     * <B STYLE="color: red;">key</B> (attribute-<B STYLE="color: red;">name</B>)  that are
     * identical (using case-insensitive comparisons) to input-parameter
     * {@code String attributeName}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=TNHASNOTE>
     * 
     * <BR /><BR /><IMG SRC='has.png' CLASS=JDIMG ALT='example'>
     * 
     * @param attributeName A {@code String} parameter that may be the
     * <B STYLE="color: red;">name</B> of any attribute / inner-tag to be found inside
     * {@code 'this'} HTML Element.
     * 
     * <BR /><BR /><B>NOTE:</B> No validity checks are performed about this parameter.  If the 
     * {@code 'attributeName'} does not represent a valid attribute, it likely will
     * just fail to find a match - and the method will exit gracefully, returning <B>FALSE</B>.
     * 
     * @return Will return <B>TRUE</B> if there are any inner-tag's whose
     * <B STYLE="color: red;">name</B> equals parameter {@code 'attributeName'} using a
     * case-insensitive {@code String}-equality comparison (and <B>FALSE</B> otherwise).
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public boolean has(String attributeName)
    {
        // Closing HTML Elements may not have attribute-names or values.
        // Exit gracefully, and immediately.
        if (this.isClosing) return false;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have such an attribute-value pair.
        // 4 (characters) are: '<', '>', ' ' and 'X'
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X>
        if (this.str.length() < (this.tok.length() + 4)) return false;

        // Get all inner-tag key-value pairs.  If any are 'equal' to parameter attributeName,
        // return TRUE immediately.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // the matcher.group(2) has the key (not the value)
        while (keyValueInnerTags.find())
            if (attributeName.equalsIgnoreCase(keyValueInnerTags.group(2)))
                return true;

        // Also check the "Boolean Attributes" also known as the "Key-Word Only Attributes"
        // Use the "Inverse Reg-Ex Matcher" (which matches all the strings that are "between" the
        // real matches)

        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(this.str))   // INVERSE-matches of the key-value Reg-Ex
            for (String keyOnlyInnerTag : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyOnlyInnerTag = keyOnlyInnerTag.trim()).length() > 0)    // Just-In-Case, usually not necessary
                    if (attributeName.equalsIgnoreCase(keyOnlyInnerTag)) return true;

        // A match was not found in either the "key-value pairs", or the boolean "key-only list."
        return false;
    }

    /**
     * Will search this {@code TagNode} to determine if any inner-tag key-value pairs have a 
     * <B STYLE="color: red;">key</B> (attribute-<B STYLE="color: red;">name</B>) that is accepted
     * by the {@code Predicate<String>} parameter {@code 'attributeNameTest'}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=TNHASNOTE>
     * 
     * @param attributeNameTest A {@code String Predicate} parameter that is used to accept or
     * reject a match with the list of attribute <B STYLE="color: red;">keys</B> or
     * boolean-attribute <B STYLE="color: red;">keys</B> in {@code 'this'} HTML Element.
     * 
     * <BR /><BR /><B>NOTE:</B> The {@link StrFilter} in {@code package Torello.Java} is
     * capable of generating a rather wide range of test-{@code Predicate's} using
     * regular-expressions. This is one option to think about when using this method.
     * 
     * @return Will return <B>TRUE</B> if there are any inner-tag's whose
     * <B STYLE="color: red;">name</B> is accepted by the input-parameter {@code
     * Predicate 'attributeNameTest'} (and <B>FALSE</B> otherwise).
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     * @see StrFilter
     */
    public boolean has(Predicate<String> attributeNameTest)
    {
        // Closing HTML Elements may not have attribute-names or values.
        // Exit gracefully, and immediately.
        if (this.isClosing) return false;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have such an attribute-value pair.
        // 4 (characters) are: '<', '>', ' ' and 'X'
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X>
        if (this.str.length() < (this.tok.length() + 4)) return false;

        // Get all inner-tag key-value pairs.  If any of them match with the 'attributeNameTest'
        // Predicate, return TRUE immediately.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // the matcher.group(2) has the key (not the value)
        while (keyValueInnerTags.find())
            if (attributeNameTest.test(keyValueInnerTags.group(2)))
                return true;

        // Also check the "Boolean Attributes" also known as the "Key-Word Only Attributes"
        // Use the "Inverse Reg-Ex Matcher" (which matches all the strings that are "between" the
        // real matches)

        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(this.str))   // INVERSE-matches of the key-value Reg-Ex
            for (String keyOnlyInnerTag : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyOnlyInnerTag = keyOnlyInnerTag.trim()).length() > 0)    // Just-In-Case, usually not necessary
                    if (attributeNameTest.test(keyOnlyInnerTag))
                        return true;

        // A match was not found in either the "key-value pairs", or the boolean "key-only list."
        return false;
    }

    /**
     * Will search this {@code TagNode} to determine if any inner-tag key-value pairs have a 
     * <B STYLE="color: red;">key</B> (attribute-<B STYLE="color: red;">name</B>) that are accepted
     * by the Java Regular-Expression parameter {@code 'attributeNameTest'}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=TNHASNOTE>
     * 
     * @param attributeNameTest A {@code java.util.regex.Pattern} regular-expression  that is used
     * to accept or reject a match with the list of attribute <B STYLE="color: red;">keys</B> or 
     * boolean-attribute <B STYLE="color: red;">keys</B> in {@code 'this'} HTML Element 
     * 
     * @return Will return <B>TRUE</B> if there are any inner-tag's whose
     * <B STYLE="color: red;">name</B> is accepted by the input-parameter regular-expression
     * {@code 'attributeNameTest'} (and <B>FALSE</B> otherwise).
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public boolean has(Pattern attributeNameTest)
    {
        // Closing HTML Elements may not have attribute-names or values.
        // Exit gracefully, and immediately.
        if (this.isClosing) return false;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have such an attribute-value pair.
        // 4 (characters) are: '<', '>', ' ' and 'X'
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X>
        if (this.str.length() < (this.tok.length() + 4)) return false;

        // Get all inner-tag key-value pairs.  If any of them match with the 'attributeNameTest'
        // Regular-Expression, return TRUE immediately.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // the matcher.group(2) has the key (not the value)
        while (keyValueInnerTags.find())
            if (attributeNameTest.matcher(keyValueInnerTags.group(2)).find())
                return true;

        // Also check the "Boolean Attributes" also known as the "Key-Word Only Attributes"
        // Use the "Inverse Reg-Ex Matcher" (which matches all the strings that are "between" the
        // real matches)

        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(this.str))   // INVERSE-matches of the key-value Reg-Ex
            for (String keyOnlyInnerTag : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyOnlyInnerTag = keyOnlyInnerTag.trim()).length() > 0)    // Just-In-Case, usually not necessary
                    if (attributeNameTest.matcher(keyOnlyInnerTag).find())
                        return true;

        // A match was not found in either the "key-value pairs", or the boolean "key-only list."
        return false;
    }

    /**
     * Will search this {@code TagNode} to determine if any inner-tag key-value pairs have a 
     * <B STYLE="color: red;">key</B> (attribute-<B STYLE="color: red;">name</B>) that are accepted
     * by the {@code TextComparitor} &amp; Compare-{@code String's} parameters.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=TNHASNOTE>
     * 
     * @param tc An instance of {@code TextComparitor} that is used (in conjunction with the
     * {@code 'compareStrs'}) to accept or reject a match with the list of attribute
     * <B STYLE="color: red;">keys</B> or boolean-attribute <B STYLE="color: red;">keys</B> in
     * {@code 'this'} HTML Element 
     * 
     * @param compareStrs This is the list of comparison-{@code String's} with which the named
     * {@code TextComparitor} performs the tests against an input 'test-{@code String}.'  For more
     * information, please review the list of {@code TextComparitor} static-instances defined in
     * that class.
     * 
     * @return Will return <B>TRUE</B> if there are any inner-tag's whose
     * <B STYLE="color: red;">name</B> is accepted by the input-parameter {@code TextComparitor}
     * (and <B>FALSE</B> otherwise).
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     * @see TextComparitor
     */
    public boolean has(TextComparitor tc, String... compareStrs)
    {
        // Closing HTML Elements may not have attribute-names or values.
        // Exit gracefully, and immediately.
        if (this.isClosing) return false;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have such an attribute-value pair.
        // 4 (characters) are: '<', '>', ' ' and 'X'
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X>
        if (this.str.length() < (this.tok.length() + 4)) return false;

        // Get all inner-tag key-value pairs.  If any of them match with the TextComparitor & compareStrs,
        // return TRUE immediately.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // the matcher.group(2) has the key (not the value)
        while (keyValueInnerTags.find())
            if (tc.test(keyValueInnerTags.group(2), compareStrs))
                return true;

        // Also check the "Boolean Attributes" also known as the "Key-Word Only Attributes"
        // Use the "Inverse Reg-Ex Matcher" (which matches all the strings that are "between" the
        // real matches)

        for (String unMatchedStr : AttrRegEx.KEY_VALUE_REGEX.split(this.str))   // INVERSE-matches of the key-value Reg-Ex
            for (String keyOnlyInnerTag : unMatchedStr.split("\\s+"))           // white-space split (connected chars)
                if ((keyOnlyInnerTag = keyOnlyInnerTag.trim()).length() > 0)    // Just-In-Case, usually not necessary
                    if (tc.test(keyOnlyInnerTag, compareStrs))
                        return true;

        // A match was not found in either the "key-value pairs", or the boolean "key-only list."
        return false;
    }

    // ********************************************************************************************
    // hasValue(...) methods
    // ********************************************************************************************

    /**
     * Will search this {@code TagNode} to determine if any inner-tag key-value pairs have a 
     * an attribute-<B STYLE="color: red;">value</B> that is identical (using case-insensitive
     * comparisons) to input-parameter {@code String attributeName}.
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID=TNHASVAL1>
     * 
     * @param attributeValue A {@code String} parameter that may be the
     * <B STYLE="color: red;">value</B> of any attribute / inner-tag to be found inside
     * {@code 'this'} HTML Element.
     * 
     * <BR /><BR /><B>NOTE:</B> This parameter is not checked for validity.  If this {@code String}
     * is not a valid HTML Attribute-<B STYLE="color:red;">Name</B>, likely it will not match the
     * regular-expression matcher.  In such cases, the method returns null.
     *
     * @param retainQuotes The parameter is required to inform the program whether or not the
     * quotation marks should be included along with the returned <B STYLE="color: red;">value</B>
     * inside the {@code Map.Entry}.  This can sometimes be useful, for example, when complicated
     * script-containing {@code TagNode's} are involved.
     *
     * @param preserveKeysCase When this parameter is <B>TRUE</B>, the program will not invoke
     * {@code String.toLowerCase()} on the {@code Map.Entry's} <B STYLE="color: red;">key</B>.  If
     * <B>FALSE</B>, then the returned {@code Map.Entry} will have a
     * <B STYLE="color: red;">key</B> (attribute-<B STYLE="color: red;">name</B>) that is strictly
     * in lower-case format. 
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @return Returns a {@code Map.Entry<String, String>} <B STYLE="color: red;">Key-Value</B>
     * Pair - <B><I>if and only if</I></B> there are any inner-tag's whose
     * <B STYLE="color: red;">value</B> is equal to input-parameter {@code 'attributeValue'} using a
     * case-insensitive {@code String}-equality comparison.
     * 
     * <BR /><BR />If no such match is found, this method will return {@code 'null'}
     *
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public Map.Entry<String, String> hasValue
        (String attributeValue, boolean retainQuotes, boolean preserveKeysCase)
    {
        // Closing HTML Elements may not have attribute-names or values.
        // Exit gracefully, and immediately.
        if (this.isClosing) return null;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have such an attribute-value pair.
        // 5 (characters) are: '<', '>', ' ', 'X' and '=' 
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X=>
        if (this.str.length() < (this.tok.length() + 5)) return null;

        // Get all inner-tag key-value pairs.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        while (keyValueInnerTags.find())
        {
            // Matcher.group(3) has the key's value, of the inner-tag key-value pair
            // (matcher.group(2) has the key's name)
            String foundAttributeValue = keyValueInnerTags.group(3);

            // The comparison must be performed on the version of the value that DOES NOT HAVE the
            // surrounding quotation-marks
            String foundAttributeValueNoQuotes = StringParse.ifQuotesStripQuotes(foundAttributeValue);

            // Perform the comparison, making sure to ignore case when comparing.
            if (attributeValue.equalsIgnoreCase(foundAttributeValueNoQuotes))

                // matcher.group(2) has the key's name, not the value.  This is returned via the
                // Map.Entry key
                return retainQuotes
                    ? new AbstractMap.SimpleImmutableEntry<String, String>(preserveKeysCase
                            ? keyValueInnerTags.group(2)
                            : keyValueInnerTags.group(2).toLowerCase(),
                        foundAttributeValue)
                    : new AbstractMap.SimpleImmutableEntry<String, String>(preserveKeysCase
                            ? keyValueInnerTags.group(2)
                            : keyValueInnerTags.group(2).toLowerCase(),
                        foundAttributeValueNoQuotes);
        }

        // No match was identified, return null.
        return null;
    }

    /**
     * Will search this {@code TagNode} to determine if any inner-tag key-value pairs have a 
     * an attribute-<B STYLE="color: red;">value</B> that is accepted by the
     * {@code String-Predicate} parameter {@code 'attributeValueTest'}.
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID=TNHASVAL1>
     *
     * @param attributeValueTest A {@code String-Predicate} parameter that is used to accept or
     * reject a match with the list of all attribute <B STYLE="color: red;">values</B> in
     * {@code 'this'} HTML Element
     *
     * <BR /><BR /><B>NOTE:</B> The {@link StrFilter} in {@code package Torello.Java} is capable
     * of generating a rather wide range of test-{@code Predicate's} using regular-expressions.  
     * This is one option to think about when using this method.
     *
     * @param retainQuotes The parameter is required to inform the program whether or not the
     * quotation marks should be included along with the returned <B STYLE="color: red;">value</B>
     * inside the {@code Map.Entry}.  This can sometimes be useful, for example, when complicated
     * script-containing {@code TagNode's} are involved.
     *
     * @param preserveKeysCase When this parameter is <B>TRUE</B>, the program will not invoke
     * {@code String.toLowerCase()} on the {@code Map.Entry's} <B STYLE="color: red;">key</B>.  If
     * <B>FALSE</B>, then the returned {@code Map.Entry} will have a <B STYLE="color: red;">key</B>
     * (attribute-<B STYLE="color: red;">name</B>)  that is strictly in lower-case format.
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @return Returns a {@code Map.Entry<String, String>} <B STYLE="color: red;">Key-Value</B>
     * Pair - <B><I>if and only if</I></B> there are any inner-tag's whose
     * <B STYLE="color: red;">value</B> is accepted by the input-parameter {@code Predicate}-test
     * {@code 'attributeNameTest'}.
     * 
     * <BR /><BR />If no such match is found, this method will return {@code 'null'}
     *
     * @see AttrRegEx#KEY_VALUE_REGEX
     * @see StrFilter
     */
    public Map.Entry<String, String> hasValue
        (Predicate<String> attributeValueTest, boolean retainQuotes, boolean preserveKeysCase)
    {
        // Closing HTML Elements may not have attribute-names or values.
        // Exit gracefully, and immediately.
        if (this.isClosing) return null;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have such an attribute-value pair.
        // 5 (characters) are: '<', '>', ' ', 'X' and '=' 
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X=>
        if (this.str.length() < (this.tok.length() + 5)) return null;

        // Get all inner-tag key-value pairs.  If any are 'equal' to parameter attributeName,
        // return TRUE immediately.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        while (keyValueInnerTags.find())
        {
            // Matcher.group(3) has the key's value, of the inner-tag key-value pair
            // (matcher.group(2) has the key's name)
            String foundAttributeValue = keyValueInnerTags.group(3);

            // The comparison must be performed on the version of the value that DOES NOT HAVE the
            // surrounding quotation-marks
            String foundAttributeValueNoQuotes = StringParse.ifQuotesStripQuotes(foundAttributeValue);

            // Matcher.group(3) has the key-value, make sure to remove quotation marks (if present) before comparing.
            if (attributeValueTest.test(foundAttributeValueNoQuotes))

                // matcher.group(2) has the key's name, not the value.  This is returned via the
                // Map.Entry key
                return retainQuotes
                    ? new AbstractMap.SimpleImmutableEntry<String, String>(preserveKeysCase
                            ? keyValueInnerTags.group(2)
                            : keyValueInnerTags.group(2).toLowerCase(),
                        foundAttributeValue)
                    : new AbstractMap.SimpleImmutableEntry<String, String>(preserveKeysCase
                            ? keyValueInnerTags.group(2)
                            : keyValueInnerTags.group(2).toLowerCase(),
                        foundAttributeValueNoQuotes);
        }

        // No match was identified, return null.
        return null;
    }

    /**
     * Will search this {@code TagNode} to determine if any inner-tag
     * <B STYLE="color: red;">key-value</B> pairs have an
     * attribute-<B STYLE="color: red;">value</B> that is accepted by the Java Regular-Expression
     * parameter {@code 'attributeValueTest'}.
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID=TNHASVAL1>
     *
     * @param attributeValueTest A {@code java.util.regex.Pattern} parameter that is used to accept
     * or reject a match with the list of all attribute <B STYLE="color: red;">values</B> in 
     * {@code 'this'} HTML Element
     *
     * @param retainQuotes The parameter is required to inform the program whether or not the
     * quotation marks should be included along with the returned <B STYLE="color: red;">value</B>
     * inside the {@code Map.Entry}.  This can sometimes be useful, for example, when complicated
     * script-containing {@code TagNode's} are involved.
     *
     * @param preserveKeysCase When this parameter is <B>TRUE</B>, the program will not invoke
     * {@code String.toLowerCase()} on the {@code Map.Entry's} <B STYLE="color: red;">key</B>.
     * If <B>FALSE</B>, then the returned {@code Map.Entry} will have a
     * <B STYLE="color: red;">key</B> (attribute-<B STYLE="color: red;">name</B>) that is strictly
     * in lower-case format. 
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @returnReturns a {@code Map.Entry<String, String>} <B STYLE="color: red;">Key-Value</B>
     * Pair - <B><I>if and only if</I></B> there are any inner-tag's whose
     * <B STYLE="color: red;">value</B> is accepted by the input-parameter regular-expression
     * {@code 'attributeValueTest'}.
     * 
     * <BR /><BR />If no such match is found, this method will return {@code 'null'}
     *
     * @see AttrRegEx#KEY_VALUE_REGEX
     */
    public Map.Entry<String, String> hasValue
        (Pattern attributeValueTest, boolean retainQuotes, boolean preserveKeysCase)
    {
        // Closing HTML Elements may not have attribute-names or values.
        // Exit gracefully, and immediately.
        if (this.isClosing) return null;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have such an attribute-value pair.
        // 5 (characters) are: '<', '>', ' ', 'X' and '=' 
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X=>
        if (this.str.length() < (this.tok.length() + 5)) return null;

        // Get all inner-tag key-value pairs.  If any are 'equal' to parameter attributeName, return
        // TRUE immediately.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        while (keyValueInnerTags.find())
        {
            // Matcher.group(3) has the key's value, of the inner-tag key-value pair
            // (matcher.group(2) has the key's name)
            String foundAttributeValue = keyValueInnerTags.group(3);

            // The comparison must be performed on the version of the value that DOES NOT HAVE the
            // surrounding quotation-marks
            String foundAttributeValueNoQuotes = StringParse.ifQuotesStripQuotes(foundAttributeValue);

            // Matcher.group(3) has the key-value, make sure to remove quotation marks (if present)
            // before comparing.
            if (attributeValueTest.matcher(foundAttributeValueNoQuotes).find())

                // matcher.group(2) has the key's name, not the value.  This is returned via the 
                // Map.Entry key
                return retainQuotes
                    ? new AbstractMap.SimpleImmutableEntry<String, String>(preserveKeysCase
                            ? keyValueInnerTags.group(2)
                            : keyValueInnerTags.group(2).toLowerCase(),
                        foundAttributeValue)
                    : new AbstractMap.SimpleImmutableEntry<String, String>(preserveKeysCase
                            ? keyValueInnerTags.group(2)
                            : keyValueInnerTags.group(2).toLowerCase(),
                        foundAttributeValueNoQuotes);
        }

        // No match was identified, return null.
        return null;
    }

    /**
     * Will search this {@code TagNode} to determine if any inner-tag
     * <B STYLE="color: red;">key-value</B> pairs have a an
     * attribute-<B STYLE="color: red;">value</B> that is accepted by the {@code TextComparitor}
     * &amp; Compare-{@code String's} parameters.
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID=TNHASVAL1>
     *
     * @param tc An instance of {@code TextComparitor} that is used (in conjunction with the
     * {@code 'compareStrs'}) to accept or reject a match with the list of
     * attribute-<B STYLE="color: red">values</B> in {@code 'this'} HTML Element 
     *
     * @param compareStrs These are the standard compare-{@code String's} to be used as reference
     * with the {@code TextComparitor} provided.
     *
     * @param retainQuotes The parameter is required to inform the program whether or not the
     * quotation marks should be included along with the returned <B STYLE="color: red;">value</B>
     * inside the {@code Map.Entry}.  This can sometimes be useful, for example, when complicated
     * script-containing {@code TagNode's} are involved.
     *
     * @param preserveKeysCase When this parameter is <B>TRUE</B>, the program will not invoke
     * {@code String.toLowerCase()} on the {@code Map.Entry's} <B STYLE="color: red;">key</B>.
     * If <B>FALSE</B>, then the returned {@code Map.Entry} will have a
     * <B STYLE="color: red;">key</B> (attribute-<B STYLE="color: red;">name</B>)  that is strictly
     * in lower-case format. 
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @return Returns a {@code Map.Entry<String, String>} <B STYLE="color: red;">Key-Value</B>
     * Pair - <B><I>if and only if</I></B> there are any inner-tag's whose
     * <B STYLE="color: red;">value</B> is accepted by the input-parameter {@code TextComparitor}.
     * 
     * <BR /><BR />If no such match is found, this method will return {@code 'null'}
     * 
     * @see AttrRegEx#KEY_VALUE_REGEX
     * @see TextComparitor
     */
    public Map.Entry<String, String> hasValue
        (boolean retainQuotes, boolean preserveKeysCase, TextComparitor tc, String... compareStrs)
    {
        // Closing HTML Elements may not have attribute-names or values.
        // Exit gracefully, and immediately.
        if (this.isClosing) return null;

        // OPTIMIZATION: TagNode's whose String-length is less than this computed length 
        // are simply too short to have such an attribute-value pair.
        // 5 (characters) are: '<', '>', ' ', 'X' and '=' 
        // SHORTEST POSSIBLE SUCH-ELEMENT: <DIV X=>
        if (this.str.length() < (this.tok.length() + 5)) return null;

        // Get all inner-tag key-value pairs.  If any are 'equal' to parameter attributeName, 
        // return TRUE immediately.
        Matcher keyValueInnerTags = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        while (keyValueInnerTags.find())
        {
            // Matcher.group(3) has the key's value, of the inner-tag key-value pair
            // (matcher.group(2) has the key's name)
            String foundAttributeValue = keyValueInnerTags.group(3);

            // The comparison must be performed on the version of the value that DOES NOT HAVE the
            // surrounding quotation-marks
            String foundAttributeValueNoQuotes = StringParse.ifQuotesStripQuotes(foundAttributeValue);

            // Matcher.group(3) has the key-value, make sure to remove quotation marks (if present)
            // before comparing.
            if (tc.test(foundAttributeValueNoQuotes, compareStrs))

                // matcher.group(2) has the key's name, not the value.  This is returned via the
                // Map.Entry key
                return retainQuotes
                    ? new AbstractMap.SimpleImmutableEntry<String, String>(preserveKeysCase
                            ? keyValueInnerTags.group(2)
                            : keyValueInnerTags.group(2).toLowerCase(),
                        foundAttributeValue)
                    : new AbstractMap.SimpleImmutableEntry<String, String>(preserveKeysCase
                            ? keyValueInnerTags.group(2)
                            : keyValueInnerTags.group(2).toLowerCase(),
                        foundAttributeValueNoQuotes);
        }

        // No match was identified, return null.
        return null;
    }

    // ********************************************************************************************
    // getInstance()
    // ********************************************************************************************

    /**
     * This is an "identical" method to the one found in {@code class HTMLTags}, specifically: 
     * {@code public static TagNode hasTag(String tag, TC openOrClosed) { ... } }, except that this
     * method will do some parameter error-checking, and throw exceptions if possible, rather than
     * simply returning null.
     *
     * <BR /><BR /><B>NOTE:</B> All three classes which inherit {@code class HTMLNode} - including 
     * classes {@code TagNode, TextNode} and {@code CommentNode} are immutable.  The instances
     * <B><I>cannot be changed</I></B>.  In order to update, tweak, or modify an HTML page, you
     * must instantiate or retrieve another instance of {@code HTMLNode}, and replace the position
     * in the containing-{@code Vector} with a new node.  This method, {@code 'getInstance(...)'}
     * interacts with the {@code class HTMLTags} to retrieve one of the pre-instantiated
     * {@code TC.OpeningTags} or {@code TC.ClosingTags TagNode's}.  It is possible to 're-use' the
     * same instance of a {@code TagNode} in different pages and different {@code Vector's} <I>in
     * the same way that Java {@code String's} can be re-used</I>, exactly because they are
     * immutable.
     *
     * <BR /><BR />If a {@code TagNode} instance is used in different pages, the in-ability to
     * change a {@code TagNode's} contents is what allows multiple, different pages to use them in
     * multiple {@code Vector's} without worrying about their contents becoming affected by
     * concurrency issues. {@code class HTMLTags} maintains 4 complete lists of
     * already-instantiated {@code TagNode's} (upper-case, lower-case, opening-tag, closing-tag) in
     * a {@code java.util.TreeMap<String, TagNode>} since usually a very high percentage of HTML
     * Element's are elements with no attribute information at all.
     *
     * <BR /><BR /><B>ALSO:</B> It should be obvious to the reader, by now, that keeping
     * 'pre-instantiated' {@code TagNode} elements that <B>do contain attributes</B> would be
     * orders of magnitude more costly (and difficult}.  This practice is not performed by the
     * Java-HTML library.
     *
     * <BR /><BR /><B>SIMILARLY:</B> All pre-instantiated HTML {@code TagNode's} have <B>ZERO</B>
     * attributes or "inner-tags" inside. To generate a {@code TagNode} with attributes, use the
     * {@code class TagNode} constructor.   Make sure not to leave out the rest of the inner-tags
     * from the element-body {@code String}.
     *
     * @param tok Any valid HTML tag.
     * 
     * @param openOrClosed If {@code TC.OpeningTags} is passed, then an "open" version of the HTML
     * tag will be returned,
     * <BR />If {@code TC.ClosingTags}  is passed, then a closing version will be returned.
     * <BR />If {@code TC.Both} is accidentally passed - an {@code IllegalArgumentException} is
     * thrown.
     * 
     * @throws IllegalArgumentException If parameter {@code TC openOrClose} is {@code null} or
     * {@code TC.Both}
     * 
     * @throws HTMLTokException If the parameter {@code String tok} is not a valid HTML-tag
     * 
     * @throws SingletonException If the token requested is a {@code singleton} (self-closing) tag,
     * but the Tag-Criteria {@code 'TC'} parameter is requesting a closing-version of the tag.
     * 
     * @see HTMLTags#hasTag(String, TC)
     * @see HTMLTags#isSingleton(String)
     */
    public static TagNode getInstance(String tok, TC openOrClosed)
    {
        if (openOrClosed == null)
            throw new NullPointerException("The value of openOrClosed cannot be null.");

        if (openOrClosed == TC.Both)
            throw new IllegalArgumentException("The value of openOrClosed cannot be TC.Both.");

        if (HTMLTags.isSingleton(tok) && (openOrClosed == TC.ClosingTags))
            throw new SingletonException(
                    "The value of openOrClosed is TC.ClosingTags, but unfortunately you have asked " +
                    "for a [" + tok + "] HTML element, which is a singleton element, and therefore " +
                    "cannot have a closing-tag instance."
                );

        TagNode ret = HTMLTags.hasTag(tok, openOrClosed);
        if (ret == null)
            throw new HTMLTokException("The HTML-Tag provided isn't valid!\ntok: " + tok + "\nTC: " + openOrClosed);
        return ret;
    }

    // ********************************************************************************************
    // Methods for "CSS Classes"
    // ********************************************************************************************

    /** Convenience Method.  Invokes {@link #cssClasses()}.  Catches-Exception. */
    public Stream<String> cssClassesNOCSE()
    { try { return cssClasses(); } catch (CSSStrException e) { return Stream.empty(); } }

    /**
     * Method {@code cssClasses} is to be used as a tool for splitting the results of invoking
     * method {@code TagNode.AV("class")} into {@code String's} - <I>separating it by
     * white-space.</I> The code here is a rather 'naïve' attempt to retrieve CSS {@code classes},
     * because it follows the <B><I>95% percent rule:</B></I> 95% of the time there should be no
     * problems!  More advanced HTML Generator Tools have taken advantage of HTML's 'flexibility'
     * and have created CSS {@code classes} that my contain anything from parenthesis {@code '('}
     * and {@code ')'}, to semi-colons {@code ';'}, to many other formats that proprietary
     * web-developers so choose.  And rather than attempting to <B>'predict'</B> all future changes
     * to CSS {@code Class}-Names, this method is intended to help developers retrieve basic (READ:
     * 'non-preprocessor') CSS {@code class}-information.  This is the nature of changing
     * web-internet tools.
     *
     * <BR /><BR />  Primarily, recognizing that dynamically, script and pre-processor generated
     * {@code class} information, <I><B>cannot be known, without having script-processing
     * performed</I></B>.  This package is designed for parsing, searching, and updating HTML
     * Pages, but it does not execute script (at least not now).  Therefore, rather than returning
     * possibly fallacious results - an exception throws when non-standard HTML CSS Classes are
     * used, instead. This does not mean that the CSS {@code String} 'attribute-value' cannot be
     * retrieved, but rather just that the method {@code TagNode.getAV("class")} should
     * <I><B>always</I></B> work and be used instead.
     * 
     * <BR /><BR />If a return value is provided it is guaranteed to be correct (unless of course
     * script on the page would further change or modify the {@code class}).  This HTML
     * Parse-and-Search Package is highly flexible when it comes to attribute-values, in that an
     * attribute is never checked for 'validity.'
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDCSSCL">
     *
     * @return The {@code String}-Value of the Attribute-<B STYLE="color: red;">Name</B>
     * {@code 'class'} where that {@code String} has been 'split' - using {String.split(...)} and a
     * Match-White-Space Regular-Expression.  This is a method that will work just fine, unless
     * proprietary non-standard HTML 5 CSS {@code Class}-Names have been used.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="STRMCNVT">
     *
     * <BR /><B>NOTE:</B> This method shall never return 'null' - even if there are no attribute
     * <B STYLE="color: red;">key-value</B> pairs contained by the {@code TagNode}.  If there are 
     * strictly zero {@code classes}, {@code Stream.empty()} shall be returned, instead.
     *
     * @throws CSSStrException <B><SPAN STYLE="color: red;">IMPORTANT:</B></SPAN> This exception
     * will throw if <I><B>*any*</I></B> of the identified sub-{@code String's} of the CSS 
     * {@code 'class'} attributes contain non-standard characters, or do not meet the requirements
     * of a standard CSS {@code class} name.  The Regular-Expression describing a properly-formed
     * CSS Name can be viewed on the internet, or in {@code class CSSStrException} field 
     * {@code 'VALID_CSS_CLASS_OR_NAME_TOKEN'}.  This is an unchecked-{@code RuntimeException}, so
     * beware before using this method on pages generated by different, proprietary Web-Design
     * Tools.
     *
     * <BR /><BR /><B>NOTE:</B> To avoid an exception throw and retrieve the CSS {@code 'class'} 
     * attribute, regardless of whether it is standard CSS, use one of the following alternatives:
     *
     * <BR /><BR /><OL CLASS="JDOL">
     * <LI> {@code TagNode.AV("class")} This will return the raw-contents of the
     *      {@code 'class'} inner-tag inside {@code 'this'} HTML Element
     * </LI>
     * <LI> {@code TagNode.cssClassesNOCSE(true)} This invocation will retrieve the contents of
     *      a CSS {@code 'class'} inner-tag, but if there are non-standard CSS {@code class} names,
     *      or invalid CSS {@code class} names, this method will exit gracefully, and just return
     *     'null'.
     * </LI>
     * </OL>
     * 
     * @see #cssClasses()
     * @see #AV(String)
     * @see StringParse#WHITE_SPACE_REGEX
     * @see CSSStrException#check(Stream)
     */
    public Stream<String> cssClasses()
    {
        // The CSS Class is just an attribute/inner-tag within an HTML Element.
        String classes = AV("class"); 

        // IF the "class" attribute was not present, OR (after trimming) was empty, return "empty stream"
        if ((classes == null) || ((classes = classes.trim()).length() == 0)) return Stream.empty();

        // STEP 1: Split the string on white-space
        // STEP 2: Check each element of the output Stream using the "CSSStrException Checker"
        return CSSStrException.check(StringParse.WHITE_SPACE_REGEX.splitAsStream(classes));
    }

    /**
     * This method sets the CSS {@code Class} attribute-<B STYLE="color: red;">value</B>, applying
     * either one, or many, CSS {@code Class}-Names.
     * 
     * <BR /><BR /><IMG SRC='setCSSClasses.png' CLASS=JDIMG ALT='example'>
     *
     * @param quote It should become a habit to chose which quote to use when setting HTML
     * {@code TagNode} attributes.  Though CSS {@code Class}-Names are not allowed to contain
     * either single or double-quotes - so it should not matter which quote is used - force of
     * habit and consistency requires this parameter be used.  This parameter may be passed 'null'
     * - and if it is, the original quotation provided in the element will be used if there were
     * quotations, or no-quotes will be used if the {@code 'class'} inner-tag was not defined in
     * the element.
     *
     * @param appendOrClobber When this parameter is <B>TRUE</B>, new class-names will be appended
     * to any, already-existing, {@code class}-names in the {@code TagNode 'class'} 
     * attribute-<B STYLE="color: red;">value</B>.  When this parameter is <B>FALSE</B>, the new 
     * {@code class}-names will replace the current {@code TagNode's 'class'} attribute's
     * <B STYLE="color: red;">value</B>/definition.  If <B>FALSE</B> is used, and this
     * {@code TagNode} does not have a {@code 'class'} attribute-<B STYLE="color: red;">value</B>
     * assigned to it yet, a new one will be created.
     *
     * @param cssClasses This var-args ({@code String[]} array, or 'list-of-{@code String's}) will
     * accept any combination of valid CSS {@code Class}-Names.  It is important to know that the
     * elements of the input-parameter {@code 'cssClasses'} will each be checked for validity
     * based on the standard CSS {@code Class}-Naming Rules.  There is a regular-expression in the
     * exception {@code class CSSStrException} that depicts exactly what constitutes a valid CSS
     * {@code Class}-Name.
     *
     * <BR /><BR /><B>NOTE:</B> If the programmer is using a web-development tool that relies on
     * bypassing the browser's CSS Styling Rules, and intends to dynamically update
     * {@code class}-names (using some form of CSS pre-processor), then perhaps he/she may wish to
     * use non-standard CSS {@code class}-names in his {@code TagNode} elements.  If so, inserting
     * non-standard names into the {@code 'class'} attribute-<B STYLE="color: red;">value</B> of a
     * {@code TagNode} should be done by calling the general-purpose method
     * {@code TagNode.setAV("class", "any-CSS-Class-String")}. 
     * 
     * <BR /><BR />The user may also use the general-purpose
     * {@code TagNode.appendAV("class", "any-CSS-Class-String", boolean, SD)}, if appending a
     * non-standard CSS {@code class}-name {@code String}, rather than clobbering or setting it is
     * the desired result.  In this way, the programmer <B><I>can avoid the "Invalid CSS Class"
     * Exception</B></I>, which would certainly be thrown for most pre-processor CSS directives.
     *
     * @return This will return an updated {@code TagNode}.  {@code TagNode's} are immutable, and
     * cannot be changed.  This is identical behavior to Java's {@code class String} Libraries and
     * Classes. The updated {@code TagNode} that is returned will have it's original
     * {@code 'class'} attribute eliminated (if it had one), and a new {@code 'class'}
     * attribute-<B STYLE="color: red;">value</B> will be assigned to contain the CSS
     * {@code classes} named by the var-args {@code String}-parameter, each separated by a space
     * character.
     *
     * @throws CSSStrException This exception shall throw if any of the {@code 'cssClasses'} in the
     * var-args {@code String...} parameter do not meet the HTML 5 CSS {@code Class} naming rules.
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @throws QuotesException Quotation marks are not intended to be used in a {@code class}
     * inner-tag definition.  However, if there happened to be one in a non-standard
     * {@code class}-attribute definition and the same quote is selected to wrap the updated class
     * definition, this exception will throw.  If this parameter is passed 'null', and the updated
     * HTML Element {@code class}-attribute definition would require quotation marks, then this
     * exception will also throw - <I>because an unquoted
     * attribute-<B STYLE="color: red;">value</B> would have white-space in its definition</I>,
     * which is not allowed either.
     *
     * @see CSSStrException#check(String[])
     * @see CSSStrException#VALID_CSS_CLASS_OR_NAME_TOKEN
     * @see #appendToAV(String, String, boolean, SD)
     * @see #setAV(String, String, SD)
     */
    public TagNode setCSSClasses(SD quote, boolean appendOrClobber, String... cssClasses)
    {
        // Throw CSSStrException if any of the input strings are invalid CSS Class-Names.
        CSSStrException.check(cssClasses);

        // Build the CSS 'class' Attribute String.  This will be inserted into the TagNode Element.
        StringBuilder   sb      = new StringBuilder();
        boolean         first   = true;

        for (String c : cssClasses) 
        { sb.append((first ? "" : " ") + c.trim()); first=false; }

        return appendOrClobber
            ? appendToAV("class", " " + sb.toString(), false, quote)
            : setAV("class", sb.toString(), quote);
    }

    /**
     * Adds another CSS {@code Class} Name into {@code 'this' TagNode}
     * 
     * <BR /><BR /><IMG SRC="appendCSSClass.png" CLASS=JDIMG alt="example">
     * 
     * @param cssClass This is the CSS-{@code Class} name that is being inserted into
     * {@code 'this'} instance of {@code TagNode}
     * 
     * @param quote This is the quote to use for this attribute.  This parameter may be null, and
     * if it is the current-quote already in place will be used.  If this parameter is null, and
     * the {@code "class"} attribute is not defined in {@code 'this'} instance of {@code TagNode},
     * <I>then no quotation mark will be used.</I>
     * 
     * @return A newly instantiated {@code TagNode} with updated CSS {@code Class} Name(s).
     *
     * @throws CSSStrException This exception shall throw if any of the {@code 'cssClasses'} in the
     * var-args {@code String...} parameter do not meet the HTML 5 CSS {@code Class} naming rules.
     * 
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     *
     * @throws QuotesException Quotation marks within the provided {@code CSS Class} are not
     * compapitable with the quotation marks used by the attribute, itself.  Generally, quotations
     * are not used with CSS Classes; however, if a proprietary-implementation requires them, it
     * becomes necessary to heed the requirements set forth by a browser's parser.
     */
    public TagNode appendCSSClass(String cssClass, SD quote)
    {
        // Do a validity check on the class.  If this is "problematic" due to use of specialized / 
        // pre-processed CSS Class directives, use the general purpose "setAV(...)" method

        CSSStrException.check(cssClass);

        String curCSSClassSetting = AV("class");

        // If there wasn't a CSS Class already defined, use "setAV(...)", 
        // otherwise use "appendToAV(...)"

        if ((curCSSClassSetting == null) || (curCSSClassSetting.length() == 0))
            return setAV("class", cssClass, quote);
        else
            return appendToAV("class", cssClass + ' ', true, quote);
    }

    // ********************************************************************************************
    // Methods for "CSS Style"
    // ********************************************************************************************

    /**
     * This is a regular-expression matching for picking out all CSS {@code Style} Elements.  There
     * are myriad 'ways and means' when it comes to CSS {@code style} elements.  The official line
     * is that CSS declarations and definitions, when inside an HTML {@code TagNode} Element, 
     * {@code 'style'} attribute-names must obey a few simple rules.  The declaration-name - which
     * includes things like {@code 'width', 'height', 'font-weight', 'border',} etc... should be
     * first. That declaration must be followed by a colon {@code ':'} character.  Afterwards, the
     * {@code Style}-Definition must either end, or a semi-color {@code ';'} must be present, and 
     * another {@code Style}-Definition may follow.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">SANITY-CHECK:</B></SPAN> At any point, an
     * invocation of the {@code TagNode.AV(...)} method, using the parameter {@code 'style'} -
     * <I>as in {@code TagNode.AV("style")}</I> - should always return the complete inline
     * CSS-Style Attribute <B STYLE="color: red;">Value</B>.  Because of the sheer-number of
     * variation of style-properties, this method will refrain from any type of validity-checking.
     * <I>So long as the rules declared by the Regular-Expression
     * {@link AttrRegEx#CSS_INLINE_STYLE_REGEX} are obeyed,</I> this method will return a usable
     * {@code java.util.Properties} instance.  
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDCSSST">
     *
     * @return This shall return an instance of Java's {@code 'Properties'} class, and it will
     * contain all the style definitions and their values.
     *
     * <BR /><BR /><B>NOTE:</B> All style-declaration names <I>shall be saved using lower-case.</I>
     * The style attribute-values, however, <I>will not</I> be converted to lower-case.
     *
     * <BR /><BR /><B>NULL NOTE:</B> This method will not return null.  Rather, if {@code 'this'}
     * instance of {@code TagNode} Element does not have a style attribute, an empty (non-null)
     * instance of {@code java.util.Properties} which contains zero CSS Style-Declaration Key-Value
     * Pairs will be returned instead.
     *
     * @see AttrRegEx#CSS_INLINE_STYLE_REGEX
     * @see #AV(String)
     */
    public Properties cssStyle()
    {
        Properties  p           = new Properties();
        String      styleStr    = AV("style");
            // Returns the complete attribute-value of "style" in the TagNode

        if (styleStr == null)           return p;
            // There was no STYLE='...' attribute found, return empty Properties.

        styleStr = styleStr.trim();
            // Standard String-trim routine

        if (styleStr.length() == 0)     return p;

        Matcher m = AttrRegEx.CSS_INLINE_STYLE_REGEX.matcher(styleStr);

            // This reg-ex "iterates" over matches of strings that follow the (very basic) form:
            // declaration-name: declaration-string;
            //
            // Where the ":" (color), and ";" (semi-colon) are the only watched/monitored tokens.
            // See the reg-ex definition in "See Also" tag.

        while (m.find()) p.put(m.group(1).toLowerCase(), m.group(2));

            // m.group(1): declaration-name     (stuff before the ":")
            // m.group(2): declaration-string   (stuff before the next ";", or end-of-string)
            // 
            // For Example, if the style attribute-value was specified as:
            // STYLE="font-weight: bold;   margin: 1em 1em 1em 2em;   color: #0000FF"
            //
            // The returned Properties object would contain the string key-value pair elements:
            // "font-weight"    -> "bold"
            // "margin"         -> "1em 1em 1em 2em"
            // "color"          -> "#0000FF"

        return p;
    }

    /**
     * This will set {@code 'this'} instance of {@code TagNode}'s CSS-{@code Style} Attribute field
     * such that it contains the CSS Definition Property-Value Pairs that are contained in the
     * {@code java.util.Properties} input-parameter.
     *
     * @param p This should be a map between CSS Definition Property-Names to Property-Values.
     * <B>Some examples would include (below):</B>
     *
     * <BR /><TABLE CLASS="BRIEFSAMPLETABLE">
     * <TR><TH>Property-Name</TH><TH>Property-Value</TH></TR>
     * <TR><TD>font-weight</TD><TD>bold</TD></TR>
     * <TR><TD>background</TD><TD>lightyellow</TD></TR>
     * <TR><TD>width</TD><TD>200px</TD></TR>
     * <TR><TD>height</TD><TD>20em</TD></TR>
     * <TR><TD>border</TD><TD>5px 10px 5px 15px</TD></TR>
     * <TR><TD>box-shadow</TD><TD>inset 0 0 1em brown</TD></TR>
     * </TABLE>
     *
     * @param quote It is expected that the user will decide which quote to use -
     * {@code SD.SingleQuotes} or {@code SD.DoubleQuotes} - when building the new {@code TagNode}
     * Element.
     *
     * @param appendOrClobber When this parameter is <B>TRUE</B> new {@code style}-definitions will
     * be appended to any, already-existing, {@code style}-definitions in the
     * {@code TagNode 'style'} attribute-value.  When this parameter is <B>FALSE</B>, the new
     * {@code style}-definitions will replace the HTML Element {@code 'style'} attributes
     * current-definition (or build a new one, if {@code 'this' TagNode} does not have a
     * {@code 'style'} attribute).
     *
     * @return This will return a new, updated HTML {@code TagNode} element with the new values
     * inserted (or replaced).  The {@code class TagNode} is immutable - <I>as it is mostly a
     * wrapper on a Java-{@code String}</I>.
     *
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @throws CSSStrException If there is an invalid CSS Style Property Name.
     * 
     * @throws QuotesException If the style-element's quotation marks are incompatible with any
     * and all quotation marks employed by the style-element definitions.
     * 
     * @see CSSStrException#VALID_CSS_CLASS_OR_NAME_TOKEN
     * @see #appendToAV(String, String, boolean, SD)
     * @see #setAV(String, String, SD)
     */
    public TagNode setCSSStyle(Properties p, SD quote, boolean appendOrClobber)
    {
        // this is used in the "exception constructor" below (which means, it might not be used).
        int counter = 0;

        // Follows the "FAIL-FAST" philosophy, and does not allow invalid CSS declaration-name
        // tokens.  Use TagNode.setAV("style", ...), or TagNode.appendToAV("style", ...), to
        // bypass exception-check.
        for (String key : p.stringPropertyNames())

            if (! CSSStrException.VALID_CSS_CLASS_OR_NAME_TOKEN_PRED.test(key))
            {
                String[] keyArr = new String[p.size()];

                throw new CSSStrException(

                    "CSS Style Definition Property: [" + key + "] does not conform to the valid, " +
                    "HTML 5, regular-expression for CSS Style Definitions Properties:\n[" + 
                    CSSStrException.VALID_CSS_CLASS_OR_NAME_TOKEN.pattern() + "].",

                    p.stringPropertyNames().toArray(keyArr), ++counter
                    // One minor "PRESUMPTION" that is the Iterator will return the elements of 
                    // Properties in the EXACT SAME ORDER on both creations / instantiations of the
                    // iterator.  Specifically: two invocations of method .iterator(), will return
                    // the same-list of property-keys, in the same order, BOTH TIMES.  Once for the
                    // for-loop, and once for the exception message.  This only matters if there is
                    // an exception.
                );
            }
            else ++counter; 

        // Follows the "FAIL-FAST" philosophy, and does not allow "quotes-within-quote" problems
        // to occur.  An attribute-value surrounded by single-quotes, cannot contain a
        // single-quote inside, and double-within-double.
        counter = 0;

        for (String key : p.stringPropertyNames())

            if (StrCmpr.containsOR(p.get(key).toString(), ("" + quote.quote), ";"))
            {
                String[] keyArr = new String[p.size()];

                throw new CSSStrException(
                    "CSS Style Definition Property: [" + key + "], which maps to style-definition " +
                    "property-value:\n[" + p.get(key) + "], contains either a semi-colon ';' " +
                    "character, or the same quotation-mark specified: [" + quote.quote + "], and is " +
                    "therefore not a valid assignment for a CSS Definition Property.",

                    p   .stringPropertyNames()
                        .stream()
                        .map((String propertyName) -> p.get(propertyName))
                        .toArray((int i) -> new String[i]),

                    ++counter
                );
            }
            else ++counter;

        // ERROR-CHECKING: FINISHED, NOW JUST BUILD THE ATTRIBUTE-VALUE STRING (using StringBuilder),
        // AND INSERT IT.
        StringBuilder sb = new StringBuilder(); 
        for (String key : p.stringPropertyNames()) sb.append(key + ": " + p.get(key) + ";");

        return appendOrClobber
            ? appendToAV("style", " " + sb.toString(), false, quote)
            : setAV("style", sb.toString(), quote);
    }

    // ********************************************************************************************
    // Methods for "CSS ID"
    // ********************************************************************************************

    /**
     * Convenience Method. Invokes {@link #AV(String)}.
     * <BR /><BR />Uses {@code String "id"}, the CSS-ID attribute-<B STYLE="color: red;">name</B>.
     * <BR /><BR /><IMG SRC='getID.png' CLASS=JDIMG ALT='example'>
     */
    public String getID() { return AV("id").trim(); }

    /**
     * This merely sets the current CSS {@code 'ID'} Attribute <B STYLE="color: red;">Value</B>.
     *
     * @param id This is the new CSS {@code 'ID'} attribute-<B STYLE="color: red;">value</B> that
     * the user would like applied to {@code 'this'} instance of {@code TagNode}.
     * 
     * @param quote All operations which involve modifying an HTML attribute 
     * <B STYLE="color: red;">key-value</B> pair are expected to choose between the
     * {@code SD.SingleQuotes} or {@code SD.DoubleQuotes} option.  This can help avoid 
     * quotes-within-quotes problems, as HTML does not provide a way to escape quotes in
     * attribute-<B STYLE="color: red;">value</B> definitions.
     *
     * @return Returns a new instance of {@code TagNode} that has an updated {@code 'ID'} 
     * attribute-<B STYLE="color: red;">value</B>.
     *
     * @see #setAV(String, String, SD)
     * 
     * @throws IllegalArgumentException This exception shall throw if an invalid
     * {@code String}-token has been passed to parameter {@code 'id'}.
     *
     * <BR /><BR /><B>BYPASS NOTE:</B> If the user would like to bypass this exception-check, for
     * instance because he / she is using a CSS Pre-Processor, then applying the general-purpose
     * method {@code TagNode.setAV("id", "some-new-id")} ought to suffice.  This other method will
     * not apply validity checking, beyond scanning for the usual "quotes-within-quotes" problems,
     * which is always disallowed.
     *
     * @throws ClosingTagNodeException <EMBED CLASS="external-html" DATA-FILE-ID="CTNEX">
     * 
     * @see CSSStrException#VALID_CSS_CLASS_OR_NAME_TOKEN
     * @see #setAV(String, String, SD)
     */
    public TagNode setID(String id, SD quote)
    {
        if (! CSSStrException.VALID_CSS_CLASS_OR_NAME_TOKEN_PRED.test(id))
            throw new IllegalArgumentException(
                "The id parameter provide: [" + id + "], does not conform to the standard CSS " +
                "Names.\nEither try using the generic TagNode.setAV(\"id\", yourNewId, quote); " +
                "method to bypass this check, or change the value passed to the 'id' parameter here."
            );

        return setAV("id", id.trim(), quote);
    }

    // ********************************************************************************************
    // Attributes that begin with "data-..."
    // ********************************************************************************************


    /** Convenience Method.  Invokes {@link #AV(String)} with {@code "data-"} prepended to {@code 'dataName'} */
    public String dataAV(String dataName) { return AV("data-" + dataName); }

    /**
     * This method will remove any HTML <B STYLE="color: red;">'data'</B> Attributes - if there are
     * any present.   "Data Inner-Tags" are simply the attributes inside of HTML Elements whose 
     * <B STYLE="color: red;">names</B> begin with <B STYLE="color: red;">{@code "data-"}</B>.
     * 
     * <BR /><BR />Since {@code class TagNode} is immutable, a new {@code TagNode} must be
     * instantiated, if any data-inner-tags are removed.  If no data-attributes are removed,
     * {@code 'this'} instance {@code TagNode} shall be returned instead.
     *
     * @return This will return a newly constructed {@code 'TagNode'} instance, if there were any
     * "<B STYLE="color: red;">Data</B> Attributes" that were removed by request.  If the original
     * {@code TagNode} has remained unchanged, a reference to {@code 'this'} shall be returned.
     * 
     * @throws ClosingTagNodeException This exception throws if {@code 'this'} instance of 
     * {@code TagNode} is a closing-version of the HTML Element.  Closing HTML Elements may not
     * have data attributes, because they simply are not intended to contain <I>any</I> attributes.
     */
    public TagNode removeDataAttributes() 
    {
        // Because this method expects to modify the TagNode, this exception-check is necessary.
        ClosingTagNodeException.check(this);

        // Make sure to keep the quotes that were already used, we are removing attributes, and the
        // original attributes that aren't removed need to preserve their quotation marks.
        Properties          p       = this.allAV(true, true);
        Enumeration<Object> keys    = p.keys();
        int                 oldSize = p.size();

        // Visit each Property Element, and remove any properties that have key-names which
        // begin with the word "data-"
        while (keys.hasMoreElements())
        {
            String key = keys.nextElement().toString();
            if (key.startsWith("data-")) p.remove(key);
        }

        // If any of properties were removed, we have to rebuild the TagNode, and replace it.
        // REMEMBER: 'null' is passed to the 'SD' parameter, because we preserved the original
        //           quotes above.
        return (p.size() == oldSize) ? this : new TagNode(this.tok, p, null, this.str.endsWith("/>"));
    }

    /**
     * Convenience Method.  Invokes {@link getDataAV(boolean)}.  
     * <BR /><BR />Attribute-<B STYLE="color: red;">names</B> will be in lower-case.
     */
    public Properties getDataAV() { return getDataAV(false); }

    /**
     * This will retrieve and return any/all <B STYLE="color: red;">'data'</B> HTML Attributes.
     * "Data Inner-Tags" are simply the attributes inside of HTML Elements whose 
     * <B STYLE="color: red;">names</B> begin with <B STYLE="color: red;">{@code "data-"}</B>.
     *
     * @param preserveKeysCase When this parameter is passed <B>TRUE</B>, the case of the attribute
     * <B STYLE="color: red;">names</B> in the returned {@code Properties} table will have been
     * preserved.  When <B>FALSE</B> is passed, all {@code Properties}
     * <B STYLE="color: red">keys</B> shall have been converted to lower-case first.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @return This will return a {@code java.util.Properties} of all 
     * <B STYLE="color: red;">data</B>-attributes which are found in {@code 'this'} HTML Element.
     * If no such attributes were found, 'null' shall not be returned by this method, but rather an
     * empty {@code Properties} instance will be provided, instead.
     *
     * @see TagNode#isClosing
     * @see TagNode#str
     * @see TagNode#tok
     * @see AttrRegEx#DATA_ATTRIBUTE_REGEX
     */
    public Properties getDataAV(boolean preserveKeysCase) 
    {
        Properties ret = new Properties();

        // NOTE: OPTIMIZED, "closing-versions" of the TagNode, and TagNode's whose 'str'
        //       field is only longer than the token, itself, by 3 or less characters cannot have
        //       attributes.v In that case, just return an empty 'Properties' instance.
        if (isClosing || (str.length() <= (tok.length() + 3))) return ret;

        // This RegEx Matcher 'matches' against Attribute/InnerTag Key-Value Pairs
        //      ONLY PAIRS WHOSE KEY BEGINS WITH "data-" WILL MATCH
        // m.group(2): returns the 'key' portion of the key-value pair, before an '=' (equals-sign).
        // m.group(3): returns the 'value' portion of the key-value pair, after an '='
        Matcher m = AttrRegEx.DATA_ATTRIBUTE_REGEX.matcher(this.str);

        // NOTE: HTML mandates attributes must be 'case-insensitive' to the attribute 'key-part'
        //      (but not necessarily the 'value-part')
        // HOWEVER: Java does not require anything for the 'Properties' class.
        // ALSO: Case is PRESERVED for the 'value-part' of the key-value pair.
        if (preserveKeysCase)
            while (m.find())
                ret.put(m.group(2), StringParse.ifQuotesStripQuotes(m.group(3)));
        else
            while (m.find())
                ret.put(m.group(2).toLowerCase(), StringParse.ifQuotesStripQuotes(m.group(3)));
 
        return ret;
    }

    /**
     * Convenience Method.  Invokes {@link getDataAN(boolean)}.
     * <BR /><BR />Attribute-<B STYLE="color: red;">names</B> will be in lower-case.
     */
    public Stream<String> getDataAN() { return getDataAN(false); }

    /**
     * This method will only return a list of all data-attribute <B STYLE="color: red;">names</B>.
     * The data-attribute <B STYLE="color: red;">values</B> shall not be included in the result.
     * An HTML Element "data-attribute" is any attribute inside of an HTML {@code TagNode} whose 
     * <B STYLE="color: red;">key-value</B> pair uses a <B STYLE="color: red;">key</B> that begins
     * with <B STYLE="color: red;">{@code "data-"}</B>...  <I>It is that simple!</I>
     *
     * @param preserveKeysCase When this parameter is passed <B>TRUE</B>, the case of the attribute
     * <B STYLE="color: red;">names</B> that are returned by this method will have been
     * preserved.  When <B>FALSE</B> is passed, they shall be converted to lower-case first.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDPC">
     *
     * @return Returns an instance of {@code Stream<String>}.  The attribute 
     * <B STYLE="color: red;">names</B> that are returned, are all converted to lower-case.
     * 
     * <BR /><BR />A return type of {@code Stream<String>} is used.  Please see the list below for
     * how to convert a {@code Stream} to another data-type.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="STRMCNVT">
     *
     * <BR /><B>NOTE:</B> This method shall never return 'null' - even if there are no
     * <B STYLE="color: red;">data-</B>attribute <B STYLE="color: red;">key-value</B> pairs
     * contained by the {@code TagNode}.  If there are strictly zero such attributes, 
     * ({@code Stream.empty()}) shall be returned, instead.
     * 
     * @see #str
     * @see #tok
     * @see AttrRegEx#DATA_ATTRIBUTE_REGEX
     */
    public Stream<String> getDataAN(boolean preserveKeysCase) 
    {
        // Java Stream's can be quickly and easily converted to any data-structure the user needs.
        Stream.Builder<String> b = Stream.builder();

        // NOTE: OPTIMIZED, "closing-versions" of the TagNode, and TagNode's whose 'str'
        //       field is only longer than the token, itself, by 3 or less characters cannot have
        //       attributes.  In that case, just return an empty 'Properties' instance.
        if (isClosing || (str.length() <= (tok.length() + 3))) return Stream.empty();

        // This RegEx Matcher 'matches' against Attribute/InnerTag Key-Value Pairs
        //      ONLY PAIRS WHOSE KEY BEGINS WITH "data-" WILL MATCH
        // m.group(2): returns the 'key' portion of the key-value pair, before an '=' (equals-sign).
        // m.group(3): returns the 'value' portion of the key-value pair, after an '='
        Matcher m = AttrRegEx.DATA_ATTRIBUTE_REGEX.matcher(this.str);

        // NOTE: HTML mandates attributes must be 'case-insensitive' to the attribute 'key-part'
        //      (but not necessarily the 'value-part')
        // HOWEVER: Java does not require anything for the 'Properties' class.
        // ALSO: Case is PRESERVED for the 'value-part' of the key-value pair.
        if (preserveKeysCase)   while (m.find()) b.accept(m.group(2));
        else                    while (m.find()) b.accept(m.group(2).toLowerCase());
 
        return b.build();
    }

    // ********************************************************************************************
    // Java Methods
    // ********************************************************************************************

    /**
     * This does a "longer version" of the parent {@code toString()} method.  This is because it
     * also parses and prints inner-tag <B STYLE="color: red;">key-value</B> pairs.  The ordinary
     * {@code public String toString()} method that is inherited from parent {@code class HTMLNode}
     * will just return the value of {@code class HTMLNode} field: {@code public final String str}.
     * 
     * @return A String with the inner-tag <B STYLE="color: red;">key-value</B> pairs specified.
     * 
     * <DIV CLASS="EXAMPLE">{@code 
     * // The following code, would output the text below
     * TagNode tn = new TagNode("<BUTTON CLASS='MyButtons' ONCLICK='MyListener();'>");
     * System.out.println(tn.toStringAV());
     *
     * // Outputs the following Text:
     * 
     * // TagNode.str: [<BUTTON class='MyButtons' onclick='MyListener();'>], TagNode.tok: [button], TagNode.isClosing: [false]
     * // CONTAINS a total of (2) attributes / inner-tag key-value pairs:
     * // (KEY, VALUE):   [onclick], [MyListener();]
     * // (KEY, VALUE):   [class], [MyButtons]
     * }</DIV>
     * 
     * @see #allAV()
     * @see #tok
     * @see #isClosing
     * @see HTMLNode#toString()
     */
    public String toStringAV()
    {
        StringBuilder sb = new StringBuilder();

        // Basic information.  This info is common to ALL instances of TagNode
        sb.append(
            "TagNode.str: [" + this.str + "], TagNode.tok: [" + this.tok + "], " +
            "TagNode.isClosing: [" + this.isClosing + "]\n"
        );

        // Not all instances of TagNode will have attributes.
        Properties attributes = this.allAV(false, true);
        sb.append(
            "CONTAINS a total of (" + attributes.size() + ") attributes / inner-tag " +
            "key-value pairs" + (attributes.size() == 0 ? "." : ":") + "\n"
        );

        // If there are inner-tags / attributes, then add them to the output-string, each on a
        // separate line.
        for (String key : attributes.stringPropertyNames())
            sb.append("(KEY, VALUE):\t[" + key + "], [" + attributes.get(key) + "]\n");

        // Build the string from the StringBuilder, and return it.
        return sb.toString();    
    }

    /**
     * Java's {@code interface Cloneable} requirements.  This instantiates a new {@code TagNode}
     * with identical <SPAN STYLE="color: red;">{@code String str}</SPAN> fields, and also
     * identical <SPAN STYLE="color: red;">{@code boolean isClosing}</SPAN> and
     * <SPAN STYLE="color: red;">{@code String tok}</SPAN> fields.
     * 
     * @return A new {@code TagNode} whose internal fields are identical to this one.
     */
    public TagNode clone() { return new TagNode(str); }

    /**
     * This sorts by:
     * 
     * <BR /><BR /><OL CLASS="JDOL">
     * <LI> by {@code String 'tok'} fields character-order (ASCII-alphabetical).
     *      <BR />The following {@code final String 'tok'} fields are ASCII ordered:
     *      {@code 'a', 'button', 'canvas', 'div', 'em', 'figure' ...}
     * </LI>
     * <LI>then (if {@code 'tok'} fields are equal) by the {@code public final boolean 'isClosing'}
     *      field. <BR />{@code TagNode's} that have a {@code 'isClosing'} set to <B>FALSE</B> come
     *      before {@code TagNode's} whose {@code 'isClosing'} field is set to <B>TRUE</B>
     * </LI>
     * <LI> finally, if the {@code 'tok'} and {@code 'isClosing'} fields are equal, they are
     *      sorted by <I>the integer-length of</I> {@code final String 'str'} field.
     * </LI>
     * </OL>
     * 
     * @param n Any other {@code TagNode} to be compared to {@code 'this' TagNode}
     * 
     * @return An integer that fulfils Java's
     * {@code interface Comparable<T> public boolean compareTo(T t)} method requirements.
     * 
     * @see #tok
     * @see #isClosing
     * @see #str
     */
    public int compareTo(TagNode n)
    {
        // Utilize the standard "String.compare(String)" method with the '.tok' string field.
        // All 'tok' fields are stored as lower-case strings.
        int compare1 = this.tok.compareTo(n.tok);

        // Comparison #1 will be non-zero if the two TagNode's being compared had different
        // .tok fields
        if (compare1 != 0) return compare1;

        // If the '.tok' fields were the same, use the 'isClosing' field for comparison instead.
        // This comparison will only be used if they are different.
        if (this.isClosing != n.isClosing) return (this.isClosing == false) ? -1 : 1;
    
        // Finally try using the entire element '.str' String field, instead.  
        return this.str.length() - n.str.length();
    }

    // ********************************************************************************************
    // Internally used Regular Expressions, (STATIC FIELDS INSIDE STATIC CLASS)
    // ********************************************************************************************

    /**
     * <CODE>TagNode Attribute Regular Expressions - Documentation</CODE><BR /><BR />
     * <EMBED CLASS="external-html" DATA-FILE-ID="TGARE">
     */
    public static final class AttrRegEx
    {
        private AttrRegEx() { }

        /**
         * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDKVR">
         * @see TagNode#allAV(boolean, boolean)
         */
        public static final Pattern KEY_VALUE_REGEX = Pattern.compile(
            "(?:\\s+?" +                    // mandatory leading white-space
                "(([\\w-]+?)=(" +           // inner-tag name (a.k.a. 'key' or 'attribute-name')
                    "'[^']*?'"     + "|" +  // inner-tag value using single-quotes ... 'OR'
                    "\"[^\"]*?\""   + "|" + // inner-tag value using double-quotes ... 'OR'
                    "[^\"'>\\s]*"   +       // inner-tag value without quotes
            ")))",
            Pattern.CASE_INSENSITIVE | Pattern.DOTALL
        );

        /**
         * A {@code Predicate<String>} Regular-Expression.
         * @see #KEY_VALUE_REGEX
         */
        public static final Predicate<String> KEY_VALUE_REGEX_PRED =
            KEY_VALUE_REGEX.asPredicate();

        /**
         * <SPAN STYLE="color: red;"><B>LEGACY-REGEX:</B></SPAN> Was used by the method
         * {@code TagNode.AV(String)}, among others.  Note that this regular-expression will be
         * deprecated, since it is redundant.
         *
         * <BR /><BR /><B>CAPTURE GROUPS:</B> <I>Nearly</I> the entire Reg-Ex is surrounding by
         * parenthesis.  {@code m.group(1)} shall return a {@code String} that differs with
         * {@code m.group()}, less a leading {@code '='} (equals-sign).
         *
         * @see TagNode#AV(String)
         */
        public static final Pattern QUOTES_AND_VALUE_REGEX = Pattern.compile(
            // Matches, for example:  ='MyClass'   or    ="MyClass"   or   =MyClass
            "=(" + 
                "\"[^\"]*?\""   + "|" + // inner-tag value using single-quotes ... 'OR'
                "'[^']*?'"      + "|" + // inner-tag value using double-quotes ... 'OR'
                "[\\w-]+"       +       // inner-tag value without quotes
            ")",
            Pattern.DOTALL
        );

        /**
         * A {@code Predicate<String>} Regular-Expression.
         * @see #QUOTES_AND_VALUE_REGEX
         */
        public static final Predicate<String> QUOTES_AND_VALUE_REGEX_PRED =
            QUOTES_AND_VALUE_REGEX.asPredicate();

        /**
         * This matches all valid attribute-<B STYLE="color: red;">keys</B> <I>(not values)</I> of
         * HTML Element <B STYLE="color: red;">key-value pairs</B>.
         * 
         * <BR /><BR /><UL CLASS="JDUL">
         * <LI> <B>PART-1:</B> {@code [A-Za-z_]} The first character must be a letter or the
         *      underscore.
         * </LI>
         * <LI> <B>PART-2:</B> {@code [A-Za-z0-9_-]} All other characters must be alpha-numeric,
         *      the dash {@code '-'}, or the underscore {@code '_'}.
         * </LI>
         * </UL>
         * 
         * @see InnerTagKeyException#check(String[])
         * @see #allKeyOnlyAttributes(boolean)
         */
        public static final Pattern ATTRIBUTE_KEY_REGEX = 
            Pattern.compile("^[A-Za-z_][A-Za-z0-9_-]*$");

        /**
         * A {@code Predicate<String>} Regular-Expression.
         * @see #ATTRIBUTE_KEY_REGEX
         */
        public static final Predicate<String> ATTRIBUTE_KEY_REGEX_PRED =
            ATTRIBUTE_KEY_REGEX.asPredicate();

        /**
         * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDDAR">
         * @see TagNode#getDataAN()
         * @see TagNode#getDataAV()
         */
        public static final Pattern DATA_ATTRIBUTE_REGEX = Pattern.compile(
            // regex will match, for example:   data-src="https://cdn.imgur.com/MyImage.jpg"
            "(?:\\s+?" +                            // mandatory leading white-space
                "(data-([\\w-]+?)=" +               // data inner-tag name 
                    "(" +   "'[^']*?'"      + "|" + // inner-tag value using single-quotes ... 'OR'
                            "\"[^\"]*?\""   + "|" + // inner-tag value using double-quotes ... 'OR
                            "[^\"'>\\s]*"   +       // inner-tag value without quotes
                ")))",
            Pattern.CASE_INSENSITIVE | Pattern.DOTALL  
        );

        /**
         * A {@code Predicate<String>} Regular-Expression.
         * @see #DATA_ATTRIBUTE_REGEX
         */
        public static final Predicate<String> DATA_ATTRIBUTE_REGEX_PRED =
            DATA_ATTRIBUTE_REGEX.asPredicate();

        /**
         * <EMBED CLASS="external-html" DATA-FILE-ID="TGNDCSS">
         * @see TagNode#cssStyle()
         */
        public static final Pattern CSS_INLINE_STYLE_REGEX = Pattern.compile(
                // regex will match, for example:  font-weight: bold;
                "([_\\-a-zA-Z]+" + "[_\\-a-zA-Z0-9]*)" +    // CSS Style Property Name - Must begin with letter or underscore
                "\\s*?" + ":" + "\\s*?" +                   // The ":" symbol between property-name and property-value
                "([^;]+?\\s*)" +                            // CSS Style Property Value
                "(;|$|[\\w]+$)"                             // text after the "Name : Value" definition    
        );

        /**
         * A {@code Predicate<String>} Regular-Expression.
         * @see #CSS_INLINE_STYLE_REGEX
         */
        public static final Predicate<String> CSS_INLINE_STYLE_REGEX_PRED =
            CSS_INLINE_STYLE_REGEX.asPredicate();
    }

}