unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
blob 81ccc4b5e2d6f721b2a1293c89ee002c5e16d77f 60919 bytes (raw)
name: lisp/align.el 	 # note: path name is non-authoritative(*)

   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
 
;;; align.el --- align text to a specific column, by regexp -*- lexical-binding:t -*-

;; Copyright (C) 1999-2024 Free Software Foundation, Inc.

;; Author: John Wiegley <johnw@gnu.org>
;; Maintainer: emacs-devel@gnu.org
;; Keywords: convenience languages lisp

;; This file is part of GNU Emacs.

;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.

;;; Commentary:

;; This mode allows you to align regions in a context-sensitive fashion.
;; The classic use is to align assignments:
;;
;;    int a = 1;
;;    short foo = 2;
;;    double blah = 4;
;;
;; becomes
;;
;;    int    a    = 1;
;;    short  foo  = 2;
;;    double blah = 4;

;;; Usage:

;; There are several variables which define how certain "categories"
;; of syntax are to be treated.  These variables go by the name
;; `align-CATEGORY-modes'.  For example, "c++" is such a category.
;; There are several rules which apply to c++, but since several other
;; languages have a syntax similar to c++ (e.g., c, java, etc), these
;; modes are treated as belonging to the same category.
;;
;; If you want to add a new mode under a certain category, just
;; customize that list, or add the new mode manually.  For example, to
;; make jde-mode a c++ category mode, use this code in your .emacs
;; file:
;;
;;    (setq align-c++-modes (cons 'jde-mode align-c++-modes))

;; In some programming modes, it's useful to have the aligner run only
;; after indentation is performed.  To achieve this, customize or set
;; the variable `align-indent-before-aligning' to t.

;;; Module Authors:

;; In order to incorporate align's functionality into your own
;; modules, there are only a few steps you have to follow.

;;  1. Require or load in the align.el library.
;;
;;  2. Define your alignment and exclusion rules lists, either
;;     customizable or not.
;;
;;  3. In your mode function, set the variables
;;     `align-mode-rules-list' and `align-mode-exclude-rules-list'
;;     to your own rules lists.

;; If there is any need to add your mode name to one of the
;; align-?-modes variables (for example, `align-dq-string-modes'), use
;; `add-to-list', or some similar function which checks first to see
;; if the value is already there.  Since the user may customize that
;; mode list, and then write your mode name into their init file,
;; causing the symbol already to be present the next time they load
;; your package.

;; Example:
;;
;;   (require 'align)
;;
;;   (defcustom my-align-rules-list
;;     '((my-rule
;;        (regexp . "Sample")))
;;     :type align-rules-list-type
;;     :risky t
;;     :group 'my-package)
;;
;;   (add-to-list 'align-dq-string-modes 'my-package-mode)
;;   (add-to-list 'align-open-comment-modes 'my-package-mode)
;;
;;   (defun my-mode ()
;;      ...
;;      (setq align-mode-rules-list my-align-rules-list))
;;
;; Note that if you need to install your own exclusion rules, then you
;; will also need to reproduce any double-quoted string, or open
;; comment exclusion rules that are defined in the standard
;; `align-exclude-rules-list'.  At the moment there is no convenient
;; way to mix both mode-local and global rules lists.

;;; History:

;; Version 1.0 was created in the earlier part of 1996, using a very
;; simple algorithm that understand only basic regular expressions.
;; Parts of the code were broken up and included in vhdl-mode.el
;; around this time.  After several comments from users, and a need to
;; find a more robust, higher performing algorithm, 2.0 was born in late
;; 1998.  Many different approaches were taken (mostly due to the
;; complexity of TeX tables), but finally a scheme was discovered
;; which worked fairly well for most common usage cases.  Development
;; beyond version 2.8 is not planned, except for problems that users
;; might encounter.

;;; Code:

(defgroup align nil
  "Align text to a specific column, by regexp."
  :version "21.1"
  :group 'fill)

;;; User Variables:

(defcustom align-load-hook nil
  "Hook that gets run after the aligner has been loaded."
  :type 'hook
  :group 'align)
(make-obsolete-variable 'align-load-hook
                        "use `with-eval-after-load' instead." "28.1")

(defcustom align-indent-before-aligning nil
  "If non-nil, indent the marked region before aligning it."
  :type 'boolean
  :group 'align)

(defcustom align-default-spacing 1
  "An integer that represents the default amount of padding to use.
If `align-to-tab-stop' is non-nil, this will represent the number of
tab stops to use for alignment, rather than the number of spaces.
Each alignment rule can optionally override both this variable and
`align-to-tab-stop'.  See `align-rules-list'."
  :type 'integer
  :group 'align)

(defcustom align-to-tab-stop 'indent-tabs-mode
  "If non-nil, alignments will always fall on a tab boundary.
It may also be a symbol, whose value will be taken."
  :type '(choice (const nil) symbol)
  :group 'align)

(defcustom align-region-heuristic 500
  "If non-nil, used as a heuristic by `align-current'.
Since each alignment rule can possibly have its own set of alignment
sections (whenever `align-region-separate' is non-nil, and not a
string), this heuristic is used to determine how far before and after
point we should search in looking for a region separator.  Larger
values can mean slower performance in large files, although smaller
values may cause unexpected behavior at times."
  :type '(choice (const :tag "Don't use heuristic when aligning a region" nil)
                 integer)
  :group 'align)

(defcustom align-highlight-change-face 'highlight
  "The face to highlight with if changes are necessary.
Used by the `align-highlight-rule' command."
  :type 'face
  :group 'align)

(defcustom align-highlight-nochange-face 'secondary-selection
  "The face to highlight with if no changes are necessary.
Used by the `align-highlight-rule' command."
  :type 'face
  :group 'align)

(defcustom align-large-region 10000
  "If an integer, defines what constitutes a \"large\" region.
If nil, then no messages will ever be printed to the minibuffer."
  :type '(choice (const :tag "Align a large region silently" nil) integer)
  :group 'align)

(defcustom align-c++-modes '( c++-mode c-mode java-mode)
  "A list of modes whose syntax resembles C/C++."
  :type '(repeat symbol)
  :group 'align)

(defcustom align-perl-modes '(perl-mode)
  "A list of modes where Perl syntax is to be seen."
  :type '(repeat symbol)
  :group 'align)

(defcustom align-lisp-modes
  '(emacs-lisp-mode lisp-interaction-mode lisp-mode scheme-mode)
  "A list of modes whose syntax resembles Lisp."
  :type '(repeat symbol)
  :group 'align)

(defcustom align-tex-modes
  '(tex-mode plain-tex-mode latex-mode slitex-mode)
  "A list of modes whose syntax resembles TeX (and family)."
  :type '(repeat symbol)
  :group 'align)

(defcustom align-text-modes '(text-mode outline-mode)
  "A list of modes whose content is plain text."
  :type '(repeat symbol)
  :group 'align)

(defcustom align-dq-string-modes
  (append align-lisp-modes align-c++-modes align-perl-modes
          '(python-base-mode vhdl-mode))
  "A list of modes where double quoted strings should be excluded."
  :type '(repeat symbol)
  :group 'align)

(defcustom align-sq-string-modes
  (append align-perl-modes '(python-base-mode))
  "A list of modes where single quoted strings should be excluded."
  :type '(repeat symbol)
  :group 'align)

(defcustom align-open-comment-modes
  (append align-lisp-modes align-c++-modes align-perl-modes
          '(python-base-mode makefile-mode vhdl-mode))
  "A list of modes with a single-line comment syntax.
These are comments as in Lisp, which have a beginning, but end with
the line (i.e., `comment-end' is an empty string)."
  :type '(repeat symbol)
  :group 'align)

(defcustom align-region-separate "^\\s-*[{}]?\\s-*$"
  "Select the method by which alignment sections will be separated.
If this is a symbol, that symbol's value will be used.

For the sake of clarification, consider the following example, which
will be referred to in the descriptions below.

    int alpha = 1; /* one */
    double beta = 2.0;
    long gamma; /* ten */

    unsigned int delta = 1; /* one */
    long double epsilon = 3.0;
    long long omega; /* ten */

The possible settings for `align-region-separate' are:

 `entire'  The entire region being aligned will be considered as a
	   single alignment section.  Assuming that comments were not
	   being aligned to a particular column, the example would
	   become:

	     int          alpha    = 1;   /* one */
	     double       beta     = 2.0;
	     long         gamma;          /* ten */

	     unsigned int delta    = 1;   /* one */
	     long double  epsilon;
	     long long    chi      = 10;  /* ten */

 `group'   Each contiguous set of lines where a specific alignment
	   occurs is considered a section for that alignment rule.
	   Note that each rule may have any entirely different set
           of section divisions from another.

	     int    alpha = 1; /* one */
	     double beta  = 2.0;
	     long   gamma; /* ten */

	     unsigned int delta = 1; /* one */
	     long double  epsilon;
	     long long    chi = 10; /* ten */

 `largest' When contiguous rule sets overlap, the largest section
	   described will be taken as the alignment section for each
	   rule touched by that section.

	     int    alpha = 1;   /* one */
	     double beta  = 2.0;
	     long   gamma;       /* ten */

	     unsigned int delta    = 1;  /* one */
	     long double  epsilon;
	     long long    chi      = 10; /* ten */

	   NOTE: This option is not supported yet, due to algorithmic
	   issues which haven't been satisfactorily resolved.  There
	   are ways to do it, but they're both ugly and resource
	   consumptive.

 regexp    A regular expression string which defines the section
	   divider.  If the mode you're in has a consistent divider
	   between sections, the behavior will be very similar to
	   `largest', and faster.  But if the mode does not use clear
	   separators (for example, if you collapse your braces onto
	   the preceding statement in C or Perl), `largest' is
	   probably the better alternative.

 function  A function that will be passed the beginning and ending
	   locations of the region in which to look for the section
	   separator.  At the very beginning of the attempt to align,
	   both of these parameters will be nil, in which case the
	   function should return non-nil if it wants each rule to
	   define its own section, or nil if it wants the largest
	   section found to be used as the common section for all
	   rules that occur there.

 list      A list of markers within the buffer that represent where
	   the section dividers lie.  Be certain to use markers!  For
	   when the aligning begins, the ensuing contract/expanding of
	   whitespace will throw off any non-marker positions.

	   This method is intended for use in Lisp programs, and not
	   by the user."
  :type '(choice
	  (const :tag "Entire region is one section" entire)
	  (const :tag "Align by contiguous groups" group)
;         (const largest)
	  (regexp :tag "Regexp defines section boundaries")
	  (function :tag "Function defines section boundaries"))
  :risky t
  :group 'align)

(defvar align-rules-list-type
  '(repeat
    (cons
     :tag "Alignment rule"
     (symbol :tag "Title")
     (cons :tag "Required attributes"
	   (cons :tag "Regexp"
		 (const :tag "(Regular expression to match)" regexp)
		 (choice :value "\\(\\s-+\\)" regexp function))
	   (repeat
	    :tag "Optional attributes"
	    (choice
	     (cons :tag "Repeat"
		   (const :tag "(Repeat this rule throughout line)"
			  repeat)
		   (boolean :value t))
	     (cons :tag "Paren group"
		   (const :tag "(Parenthesis group to use)" group)
		   (choice :value 2
			   integer (repeat integer)))
	     (cons :tag "Modes"
		   (const :tag "(Modes where this rule applies)" modes)
		   (sexp :value (text-mode)))
	     (cons :tag "Case-fold"
		   (const :tag "(Should case be ignored for this rule)"
			  case-fold)
		   (boolean :value t))
	     (cons :tag "To Tab Stop"
		   (const :tag "(Should rule align to tab stops)"
			  tab-stop)
		   (boolean :value nil))
	     (cons :tag "Valid"
		   (const :tag "(Return non-nil if rule is valid)"
			  valid)
		   (function :value always))
	     (cons :tag "Run If"
		   (const :tag "(Return non-nil if rule should run)"
			  run-if)
		   (function :value always))
	     (cons :tag "Column"
		   (const :tag "(Column to fix alignment at)" column)
		   (choice :value comment-column
			   integer symbol))
	     (cons :tag "Spacing"
		   (const :tag "(Amount of spacing to use)" spacing)
		   (integer :value 1))
	     (cons :tag "Justify"
		   (const :tag "(Should text be right justified)"
			  justify)
		   (boolean :value t))
	     ;; make sure this stays up-to-date with any changes
	     ;; in `align-region-separate'
	     (cons :tag "Separate"
		   (const :tag "(Separation to use for this rule)"
			  separate)
		   (choice :value "^\\s-*$"
			   (const entire)
			   (const group)
;                          (const largest)
			   regexp function)))))))
  "The `type' form for any `align-rules-list' variable.")

(defcustom align-rules-list
  `((lisp-second-arg
     (regexp   . "\\(^\\s-+[^( \t\n]\\|(\\(\\S-+\\)\\s-+\\)\\S-+\\(\\s-+\\)")
     (group    . 3)
     (modes    . align-lisp-modes)
     (run-if   . ,(lambda () current-prefix-arg)))

    (lisp-alist-dot
     (regexp   . "\\(\\s-*\\)\\.\\(\\s-*\\)")
     (group    . (1 2))
     (modes    . align-lisp-modes))

    (open-comment
     (regexp   . ,(lambda (end reverse)
                    (funcall (if reverse 're-search-backward
                               're-search-forward)
                             (concat "[^ \t\n\\]"
                                     (regexp-quote comment-start)
                                     "\\(.+\\)$") end t)))
     (modes    . align-open-comment-modes))

    (c-macro-definition
     (regexp   . "^\\s-*#\\s-*define\\s-+\\S-+\\(\\s-+\\)")
     (modes    . align-c++-modes))

    (c-variable-declaration
     (regexp   . ,(concat "[*&0-9A-Za-z_]>?[][&*]*\\(\\s-+[*&]*\\)"
			  "[A-Za-z_][][0-9A-Za-z:_]*\\s-*\\(\\()\\|"
			  "=[^=\n].*\\|(.*)\\|\\(\\[.*\\]\\)*\\)"
			  "\\s-*[;,]\\|)\\s-*$\\)"))
     (group    . 1)
     (modes    . align-c++-modes)
     (justify  . t)
     (valid
      . ,(lambda ()
           (not (or (save-excursion
                      (goto-char (match-beginning 1))
                      (backward-word 1)
                      (looking-at
                       "\\(goto\\|return\\|new\\|delete\\|throw\\)"))
                    (if font-lock-mode
                        (eq (get-text-property (point) 'face)
                            'font-lock-comment-face)
                      (eq (caar (c-guess-basic-syntax)) 'c)))))))

    (c-assignment
     (regexp   . ,(concat "[^-=!^&*+<>/| \t\n]\\(\\s-*[-=!^&*+<>/|]*\\)"
			  "=\\(\\s-*\\)\\([^= \t\n]\\|$\\)"))
     (group    . (1 2))
     (modes    . align-c++-modes)
     (justify  . t)
     (tab-stop . nil))

    (perl-assignment
     (regexp   . ,(concat "[^=!^&*+<>/| \t\n-]\\(\\s-*\\)=[~>]?"
			  "\\(\\s-*\\)\\([^>= \t\n]\\|$\\)"))
     (group    . (1 2))
     (modes    . align-perl-modes)
     (tab-stop . nil))

    (python-assignment
     (regexp   . ,(concat "[^=!<> \t\n]\\(\\s-*\\)="
			  "\\(\\s-*\\)\\([^>= \t\n]\\|$\\)"))
     (group    . (1 2))
     (modes    . '(python-base-mode))
     (tab-stop . nil))

    (make-assignment
     (regexp   . "^\\s-*\\w+\\(\\s-*\\):?=\\(\\s-*\\)\\([^\t\n \\]\\|$\\)")
     (group    . (1 2))
     (modes    . '(makefile-mode))
     (tab-stop . nil))

    (c-comma-delimiter
     (regexp   . ",\\(\\s-*\\)[^/ \t\n]")
     (repeat   . t)
     (modes    . align-c++-modes)
     (run-if   . ,(lambda () current-prefix-arg)))
					;      (valid
                                        ;       . ,(lambda ()
					;	    (memq (caar (c-guess-basic-syntax))
					;		  '(brace-list-intro
					;		    brace-list-entry
                                        ;		    brace-entry-open)))))

    ;; With a prefix argument, comma delimiter will be aligned.  Since
    ;; perl-mode doesn't give us enough syntactic information (and we
    ;; don't do our own parsing yet), this rule is too destructive to
    ;; run normally.
    (basic-comma-delimiter
     (regexp   . ",\\(\\s-*\\)[^# \t\n]")
     (repeat   . t)
     (modes    . (append align-perl-modes '(python-base-mode)))
     (run-if   . ,(lambda () current-prefix-arg)))

    (c++-comment
     (regexp   . "\\(\\s-*\\)\\(//.*\\|/\\*.*\\*/\\s-*\\)$")
     (modes    . align-c++-modes)
     (column   . comment-column)
     (valid    . ,(lambda ()
                    (save-excursion
                      (goto-char (match-beginning 1))
                      (not (bolp))))))

    (c-chain-logic
     (regexp   . "\\(\\s-*\\)\\(&&\\|||\\|\\<and\\>\\|\\<or\\>\\)")
     (modes    . align-c++-modes)
     (valid    . ,(lambda ()
                    (save-excursion
                      (goto-char (match-end 2))
                      (looking-at "\\s-*\\(/[*/]\\|$\\)")))))

    (perl-chain-logic
     (regexp   . "\\(\\s-*\\)\\(&&\\|||\\|\\<and\\>\\|\\<or\\>\\)")
     (modes    . align-perl-modes)
     (valid    . ,(lambda ()
                    (save-excursion
                      (goto-char (match-end 2))
                      (looking-at "\\s-*\\(#\\|$\\)")))))

    (python-chain-logic
     (regexp   . "\\(\\s-*\\)\\(\\<and\\>\\|\\<or\\>\\)")
     (modes    . '(python-base-mode))
     (valid    . ,(lambda ()
                    (save-excursion
                      (goto-char (match-end 2))
                      (looking-at "\\s-*\\(#\\|$\\|\\\\\\)")))))

    (c-macro-line-continuation
     (regexp   . "\\(\\s-*\\)\\\\$")
     (modes    . align-c++-modes)
     (column   . c-backslash-column))
					;      (valid
                                        ;       . ,(lambda ()
					;	    (memq (caar (c-guess-basic-syntax))
                                        ;		  '(cpp-macro cpp-macro-cont)))))

    (basic-line-continuation
     (regexp   . "\\(\\s-*\\)\\\\$")
     (modes    . '(python-base-mode makefile-mode)))

    (tex-record-separator
     (regexp . ,(lambda (end reverse)
                  (align-match-tex-pattern "&" end reverse)))
     (group    . (1 2))
     (modes    . align-tex-modes)
     (repeat   . t))

    (tex-tabbing-separator
     (regexp   . ,(lambda (end reverse)
                    (align-match-tex-pattern "\\\\[=>]" end reverse)))
     (group    . (1 2))
     (modes    . align-tex-modes)
     (repeat   . t)
     (run-if   . ,(lambda ()
                    (eq major-mode 'latex-mode))))

    (tex-record-break
     (regexp   . "\\(\\s-*\\)\\\\\\\\")
     (modes    . align-tex-modes))

    ;; Align space delimited text as columns.
    (text-column
     (regexp   . "\\(^\\|\\S-\\)\\([ \t]+\\)\\(\\S-\\|$\\)")
     (group    . 2)
     (modes    . align-text-modes)
     (repeat   . t)
     (run-if   . ,(lambda ()
                    (and (not (eq '- current-prefix-arg))
                         (not (derived-mode-p align-tex-modes))))))

    ;; With a negative prefix argument, lists of dollar figures will
    ;; be aligned.
    (text-dollar-figure
     (regexp   . "\\$?\\(\\s-+[0-9]+\\)\\.")
     (modes    . align-text-modes)
     (justify  . t)
     (run-if   . ,(lambda ()
                    (eq '- current-prefix-arg))))

    (css-declaration
     (regexp . "^\\s-*\\(?:\\w-?\\)+:\\(\\s-*\\).*;")
     (group . (1))
     (modes . '(css-base-mode html-mode)))

    (toml-assignment
     (regexp . ,(rx (group (zero-or-more (syntax whitespace)))
                    "="
                    (group (zero-or-more (syntax whitespace)))))
     (group . (1 2))
     (modes . '(conf-toml-mode lua-mode)))

    (double-dash-comment
     (regexp . ,(rx (group (zero-or-more (syntax whitespace)))
                    "--"
                    (zero-or-more nonl)))
     (modes  . '(lua-mode))
     (column . comment-column)
     (valid  . ,(lambda ()
                  (save-excursion
                    (goto-char (match-beginning 1))
                    (not (bolp)))))))
  "A list describing all of the available alignment rules.
The format is:

   ((TITLE
     (ATTRIBUTE . VALUE) ...)
    ...)

The following attributes are meaningful:

`regexp'    This required attribute must be either a string describing
	    a regular expression, or a function (described below).
	    For every line within the section that this regular
	    expression matches, the given rule will be applied to that
	    line.  The exclusion rules denote which part(s) of the
	    line should not be modified; the alignment rules cause the
	    identified whitespace group to be contracted/expanded such
	    that the \"alignment character\" (the character
	    immediately following the identified parenthesis group),
	    occurs in the same column for every line within the
	    alignment section (see `align-region-separate' for a
	    description of how the region is broken up into alignment
	    sections).

	    The `regexp' attribute describes how the text should be
	    treated.  Within this regexp, there must be at least one
	    group of characters (typically whitespace) identified by
	    the special opening and closing parens used in regexp
	    expressions (`\\\\(' and `\\\\)') (see the Emacs manual on
	    the syntax of regular expressions for more info).

	    If `regexp' is a function, it will be called as a
	    replacement for `re-search-forward'.  This means that it
	    should return nil if nothing is found to match the rule,
	    or it should set the match data appropriately, move point
	    to the end of the match, and return the value of point.

`group'     For exclusion rules, the group identifies the range of
	    characters that should be ignored.  For alignment rules,
	    these are the characters that will be deleted/expanded for
	    the purposes of alignment.  The \"alignment character\" is
	    always the first character immediately following this
	    parenthesis group.  This attribute may also be a list of
	    integers, in which case multiple alignment characters will
	    be aligned, with the list of integers identifying the
	    whitespace groups which precede them.  The default for
	    this attribute is 1.

`modes'     The `modes' attribute, if set, should name a list of
	    major modes -- or evaluate to such a value -- in which the
	    rule is valid.  If not set, the rule will apply to all
	    modes.

`case-fold' If `regexp' is an ordinary regular expression string
	    containing alphabetic character, sometimes you may want
	    the search to proceed case-insensitively (for languages
	    that ignore case, such as Pascal for example).  In that
	    case, set `case-fold' to a non-nil value, and the regular
	    expression search will ignore case.  If `regexp' is set to
	    a function, that function must handle the job of ignoring
	    case by itself.

`tab-stop'  If the `tab-stop' attribute is set, and non-nil, the
	    alignment character will always fall on a tab stop
	    (whether it uses tabs to get there or not depends on the
	    value of `indent-tabs-mode').  If the `tab-stop' attribute
	    is set to nil, tab stops will never be used.  Otherwise,
	    the value of `align-to-tab-stop' determines whether or not
	    to align to a tab stop.  The `tab-stop' attribute may also
	    be a list of t or nil values, corresponding to the number
	    of parenthesis groups specified by the `group' attribute.

`repeat'    If the `repeat' attribute is present, and non-nil, the
	    rule will be applied to the line continuously until no
	    further matches are found.

`valid'     If the `valid' attribute is set, it will be used to
	    determine whether the rule should be invoked.  This form
	    is evaluated after the regular expression match has been
	    performed, so that it is possible to use the results of
	    that match to determine whether the alignment should be
	    performed.  The buffer should not be modified during the
	    evaluation of this form.

`run-if'    Like `valid', the `run-if' attribute tests whether the
	    rule should be run at all -- even before any searches are
	    done to determine if the rule applies to the alignment
	    region.  This can save time, since `run-if' will only be
	    run once for each rule.  If it returns nil, the rule will
	    not be attempted.

`column'    For alignment rules, if the `column' attribute is set --
	    which must be an integer, or a symbol whose value is an
	    integer -- it will be used as the column in which to align
	    the alignment character.  If the text on a particular line
	    happens to overrun that column, a single space character,
	    or tab stop (see `align-to-tab-stop') will be added
	    between the last text character and the alignment
	    character.

`spacing'   Alignment rules may also override the amount of spacing
	    that would normally be used by providing a `spacing'
	    attribute.  This must be an integer, or a list of integers
	    corresponding to the number of parenthesis groups matched
	    by the `group' attribute.  If a list of value is used, and
	    any of those values is nil, `align-default-spacing' will
	    be used for that subgroup.  See `align-default-spacing'
	    for more details on spacing, tab stops, and how to
	    indicate how much spacing should be used.  If TAB-STOP is
	    present, it will override the value of `align-to-tab-stop'
	    for that rule.

`justify'   It is possible with `regexp' and `group' to identify a
	    character group that contains more than just whitespace
	    characters.  By default, any non-whitespace characters in
	    that group will also be deleted while aligning the
	    alignment character.  However, if the `justify' attribute
	    is set to a non-nil value, only the initial whitespace
	    characters within that group will be deleted.  This has
	    the effect of right-justifying the characters that remain,
	    and can be used for outdenting or just plain old right-
	    justification.

`separate'  Each rule can define its own section separator, which
	    describes how to identify the separation of \"sections\"
	    within the region to be aligned.  Setting the `separate'
	    attribute overrides the value of `align-region-separate'
	    (see the documentation of that variable for possible
	    values), and any separation argument passed to `align'."
  :type align-rules-list-type
  :risky t
  :group 'align)

(defvar align-exclude-rules-list-type
  '(repeat
    (cons
     :tag "Exclusion rule"
     (symbol :tag "Title")
     (cons :tag "Required attributes"
	   (cons :tag "Regexp"
		 (const :tag "(Regular expression to match)" regexp)
		 (choice :value "\\(\\s-+\\)" regexp function))
	   (repeat
	    :tag "Optional attributes"
	    (choice
	     (cons :tag "Repeat"
		   (const :tag "(Repeat this rule throughout line)"
			  repeat)
		   (boolean :value t))
	     (cons :tag "Paren group"
		   (const :tag "(Parenthesis group to use)" group)
		   (choice :value 2
			   integer (repeat integer)))
	     (cons :tag "Modes"
		   (const :tag "(Modes where this rule applies)" modes)
		   (sexp :value (text-mode)))
	     (cons :tag "Case-fold"
		   (const :tag "(Should case be ignored for this rule)"
			  case-fold)
		   (boolean :value t)))))))
  "The `type' form for any `align-exclude-rules-list' variable.")

(defcustom align-exclude-rules-list
  `((exc-dq-string
     (regexp . "\"\\([^\"\n]+\\)\"")
     (repeat . t)
     (modes  . align-dq-string-modes))

    (exc-sq-string
     (regexp . "'\\([^'\n]+\\)'")
     (repeat . t)
     (modes  . align-sq-string-modes))

    (exc-open-comment
     (regexp
      . ,(lambda (end reverse)
           (funcall (if reverse 're-search-backward
                      're-search-forward)
                    (concat "[^ \t\n\\]"
                            (regexp-quote comment-start)
                            "\\(.+\\)$") end t)))
     (modes  . align-open-comment-modes))

    (exc-c-comment
     (regexp . "/\\*\\(.+\\)\\*/")
     (repeat . t)
     (modes  . align-c++-modes))

    (exc-c-func-params
     (regexp . "(\\([^)\n]+\\))")
     (repeat . t)
     (modes  . align-c++-modes))

    (exc-c-macro
     (regexp . "^\\s-*#\\s-*\\(if\\w*\\|endif\\)\\(.*\\)$")
     (group  . 2)
     (modes  . align-c++-modes)))
  "A list describing text that should be excluded from alignment.
See the documentation for `align-rules-list' for more info."
  :type align-exclude-rules-list-type
  :risky t
  :group 'align)

;;; Internal Variables:

(defvar-local align-mode-rules-list nil
  "Alignment rules specific to the current major mode.
See the variable `align-rules-list' for more details.")

(defvar-local align-mode-exclude-rules-list nil
  "Alignment exclusion rules specific to the current major mode.
See the variable `align-exclude-rules-list' for more details.")

(defvar align-highlight-overlays nil
  "The current overlays highlighting the text matched by a rule.")

(defvar align-regexp-history nil
  "Input history for the full user-entered regex in `align-regexp'.")

;; Sample extension rule set for vhdl-mode.  This is now obsolete.
(defcustom align-vhdl-rules-list
  `((vhdl-declaration
     (regexp   . "\\(signal\\|variable\\|constant\\)\\(\\s-+\\)\\S-")
     (group    . 2))

    (vhdl-case
     (regexp   . "\\(others\\|[^ \t\n=<]\\)\\(\\s-*\\)=>\\(\\s-*\\)\\S-")
     (group    . (2 3))
     (valid
      . ,(lambda ()
           (not (string= (downcase (match-string 1))
                         "others")))))

    (vhdl-colon
     (regexp   . "[^ \t\n:]\\(\\s-*\\):\\(\\s-*\\)[^=\n]")
     (group    . (1 2)))

    (direction
     (regexp   . ":\\s-*\\(in\\|out\\|inout\\|buffer\\)\\(\\s-*\\)")
     (group    . 2))

    (sig-assign
     (regexp   . "[^ \t\n=<]\\(\\s-*\\)<=\\(\\s-*\\)\\S-")
     (group    . (1 2)))

    (var-assign
     (regexp   . "[^ \t\n:]\\(\\s-*\\):="))

    (use-entity
     (regexp   . "\\(\\s-+\\)use\\s-+entity")))
  "Alignment rules for `vhdl-mode'.  See `align-rules-list' for more info."
  :type align-rules-list-type
  :risky t
  :group 'align)
(make-obsolete-variable 'align-vhdl-rules-list "no longer used." "27.1")

(defun align-set-vhdl-rules ()
  "Setup the `align-mode-rules-list' variable for `vhdl-mode'."
  (declare (obsolete nil "27.1"))
  (setq align-mode-rules-list align-vhdl-rules-list))

;;; User Functions:

;;;###autoload
(defun align (beg end &optional separate rules exclude-rules)
  "Attempt to align a region based on a set of alignment rules.
Interactively, BEG and END are the mark/point of the current region.

Many modes define specific alignment rules, and some of these
rules in some modes react to the current prefix argument.  For
instance, in `text-mode', \\`M-x align' will align into columns
based on space delimiters, while \\`C-u -' \\`M-x align' will align
into columns based on the \"$\" character.  See the
`align-rules-list' variable definition for the specific rules.

Also see `align-regexp', which will guide you through various
parameters for aligning text.

Non-interactively, if BEG and END are nil, the beginning and end
of the current alignment section will be calculated based on the
location of point, and the value of `align-region-separate' (or
possibly each rule's `separate' attribute).

If SEPARATE is non-nil, it overrides the value of
`align-region-separate' for all rules, except those that have their
`separate' attribute set.

RULES and EXCLUDE-RULES, if either is non-nil, will replace the
default rule lists defined in `align-rules-list' and
`align-exclude-rules-list'.  See `align-rules-list' for more details
on the format of these lists."
  (interactive "r")
  (let ((separator
	 (or separate
	     (if (and (symbolp align-region-separate)
		      (boundp align-region-separate))
		 (symbol-value align-region-separate)
	       align-region-separate)
	     'entire)))
    (if (not (or ;(eq separator 'largest)
		 (and (functionp separator)
		      (not (funcall separator nil nil)))))
	(align-region beg end separator
		      (or rules align-mode-rules-list align-rules-list)
		      (or exclude-rules align-mode-exclude-rules-list
			  align-exclude-rules-list))
      (let ((sec-first end)
	    (sec-last beg))
	(align-region beg end
		      separator
		      nil ; rules
                      (or exclude-rules
			  align-mode-exclude-rules-list
			  align-exclude-rules-list)
                      (lambda (b e mode)
                        (when (consp mode)
                          (setq sec-first (min sec-first b)
                                sec-last  (max sec-last e)))))
	(if (< sec-first sec-last)
	    (align-region sec-first sec-last 'entire
			  (or rules align-mode-rules-list align-rules-list)
			  (or exclude-rules align-mode-exclude-rules-list
			      align-exclude-rules-list)))))))

;;;###autoload
(defun align-regexp (beg end regexp &optional group spacing repeat)
  "Align the current region using an ad-hoc rule read from the minibuffer.
BEG and END mark the limits of the region.  Interactively, this function
prompts for the regular expression REGEXP to align with.

Interactively, if you specify a prefix argument, the function
will guide you through entering the full regular expression, and
then prompts for which subexpression parenthesis GROUP (default
1) within REGEXP to modify, the amount of SPACING (default
`align-default-spacing') to use, and whether or not to REPEAT the
rule throughout the line.

See `align-rules-list' for more information about these options.

For example, let's say you had a list of phone numbers, and wanted to
align them so that the opening parentheses would line up:

    Fred (123) 456-7890
    Alice (123) 456-7890
    Mary-Anne (123) 456-7890
    Joe (123) 456-7890

There is no predefined rule to handle this, but interactively,
all you would have to do is to mark the region, call `align-regexp'
and enter \"(\".

REGEXP must contain at least one parenthesized subexpression,
typically whitespace of the form \"\\\\(\\\\s-*\\\\)\", but in
interactive use, this is automatically added to the start of your
regular expression after you enter it.  Interactively, you only
need to supply the characters to be lined up, and any preceding
whitespace is replaced.

Non-interactively, you must enter the full regular expression,
including the subexpression.

The non-interactive form of the previous example would look something like:
  (align-regexp (point-min) (point-max) \"\\\\(\\\\s-*\\\\)(\")

This function is a nothing more than a small wrapper that helps you
construct a rule to pass to `align-region', which does the real work."
  (interactive
   (append
    (list (region-beginning) (region-end))
    (if current-prefix-arg
	(list (read-string "Complex align using regexp: "
                           "\\(\\s-*\\) " 'align-regexp-history)
	      (string-to-number
	       (read-string
		"Parenthesis group to modify (justify if negative): " "1"))
	      (string-to-number
	       (read-string "Amount of spacing (or column if negative): "
			    (number-to-string align-default-spacing)))
	      (y-or-n-p "Repeat throughout line? "))
      (list (concat "\\(\\s-*\\)"
		    (read-string "Align regexp: "))
	    1 align-default-spacing nil))))
  (or group (setq group 1))
  (or spacing (setq spacing align-default-spacing))
  (let ((rule
	 (list (list nil (cons 'regexp regexp)
		     (cons 'group (abs group))
		     (if (< group 0)
			 (cons 'justify t)
		       (cons 'bogus nil))
		     (if (>= spacing 0)
			 (cons 'spacing spacing)
		       (cons 'column (abs spacing)))
		     (cons 'repeat repeat)))))
    (align-region beg end 'entire rule nil nil)))

;;;###autoload
(defun align-entire (beg end &optional rules exclude-rules)
  "Align the selected region as if it were one alignment section.
BEG and END mark the extent of the region.  If RULES or EXCLUDE-RULES
is set to a list of rules (see `align-rules-list'), it can be used to
override the default alignment rules that would have been used to
align that section."
  (interactive "r")
  (align beg end 'entire rules exclude-rules))

;;;###autoload
(defun align-current (&optional rules exclude-rules)
  "Call `align' on the current alignment section.
This function assumes you want to align only the current section, and
so saves you from having to specify the region.  If RULES or
EXCLUDE-RULES is set to a list of rules (see `align-rules-list'), it
can be used to override the default alignment rules that would have
been used to align that section."
  (interactive)
  (align nil nil nil rules exclude-rules))

;;;###autoload
(defun align-highlight-rule (beg end title &optional rules exclude-rules)
  "Highlight the whitespace which a given rule would have modified.
BEG and END mark the extent of the region.  TITLE identifies the rule
that should be highlighted.  If RULES or EXCLUDE-RULES is set to a
list of rules (see `align-rules-list'), it can be used to override the
default alignment rules that would have been used to identify the text
to be colored."
  (interactive
   (list (region-beginning) (region-end)
	 (completing-read
	  "Title of rule to highlight: "
	  (mapcar
           (lambda (rule)
             (list (symbol-name (car rule))))
	   (append (or align-mode-rules-list align-rules-list)
		   (or align-mode-exclude-rules-list
		       align-exclude-rules-list))) nil t)))
  (let ((ex-rule (assq (intern title)
		       (or align-mode-exclude-rules-list
			   align-exclude-rules-list)))
	face)
    (align-unhighlight-rule)
    (align-region
     beg end 'entire
     (or rules (if ex-rule
		   (or exclude-rules align-mode-exclude-rules-list
		       align-exclude-rules-list)
		 (or align-mode-rules-list align-rules-list)))
     (unless ex-rule (or exclude-rules align-mode-exclude-rules-list
			 align-exclude-rules-list))
     (lambda (b e mode)
       (if (and mode (listp mode))
           (if (equal (symbol-name (car mode)) title)
               (setq face (cons align-highlight-change-face
                                align-highlight-nochange-face))
             (setq face nil))
         (when face
           (let ((overlay (make-overlay b e)))
             (setq align-highlight-overlays
                   (cons overlay align-highlight-overlays))
             (overlay-put overlay 'face
                          (if mode
                              (car face)
                            (cdr face))))))))))

;;;###autoload
(defun align-unhighlight-rule ()
  "Remove any highlighting that was added by `align-highlight-rule'."
  (interactive)
  (while align-highlight-overlays
    (delete-overlay (car align-highlight-overlays))
    (setq align-highlight-overlays
	  (cdr align-highlight-overlays))))

;;;###autoload
(defun align-newline-and-indent ()
  "A replacement function for `newline-and-indent', aligning as it goes.
The alignment is done by calling `align' on the region that was
indented."
  (interactive)
  (let ((separate (or (if (and (symbolp align-region-separate)
			       (boundp align-region-separate))
			  (symbol-value align-region-separate)
			align-region-separate)
		      'entire))
	(end (point)))
    (call-interactively 'newline-and-indent)
    (save-excursion
      (forward-line -1)
      (while (not (or (bobp)
		      (align-new-section-p (point) end separate)))
	(forward-line -1))
      (align (point) end))))

;;; Internal Functions:

(defun align-match-tex-pattern (regexp end &optional reverse)
  "Match REGEXP in TeX mode, counting backslashes appropriately.
END denotes the end of the region to be searched, while REVERSE, if
non-nil, indicates that the search should proceed backward from the
current position."
  (let (result)
    (while
	(and (setq result
		   (funcall
		    (if reverse 're-search-backward
		      're-search-forward)
		    (concat "\\(\\s-*\\)" regexp
			    "\\(\\s-*\\)") end t))
	     (let ((pos (match-end 1))
		   (count 0))
	       (while (and (> pos (point-min))
			   (eq (char-before pos) ?\\))
		 (setq count (1+ count) pos (1- pos)))
	       (eq (mod count 2) 1))
	     (goto-char (match-beginning (if reverse 1 2)))))
    result))

(defun align-new-section-p (beg end separator)
  "Is there a section divider between BEG and END?
SEPARATOR specifies how to look for the section divider.  See the
documentation for `align-region-separate' for more details."
  (cond ((or (not separator)
	     (eq separator 'entire))
	 nil)
	((eq separator 'group)
	 (let ((amount 2))
	   (save-excursion
	     (goto-char end)
	     (if (bolp)
		 (setq amount 1)))
	   (> (count-lines beg end) amount)))
	((stringp separator)
	 (save-excursion
	   (goto-char beg)
	   (re-search-forward separator end t)))
	((functionp separator)
	 (funcall separator beg end))
	((listp separator)
	 (let ((seps separator) yes)
	   (while seps
	     (if (and (>= (car seps) beg)
		      (<= (car seps) end))
		 (setq yes t seps nil)
	     (setq seps (cdr seps))))
	   yes))))

(defun align-adjust-col-for-rule (column _rule spacing tab-stop)
  "Adjust COLUMN according to the given RULE.
SPACING specifies how much spacing to use.
TAB-STOP specifies whether SPACING refers to tab-stop boundaries."
  (unless spacing
    (setq spacing align-default-spacing))
  (if (<= spacing 0)
      column
    (if (not tab-stop)
	(+ column spacing)
      (dotimes (_ spacing)
	(setq column (indent-next-tab-stop column)))
      column)))

(defsubst align-column (pos)
  "Given a position in the buffer, state what column it's in.
POS is the position whose column will be taken.  Note that this
function will change the location of point."
  (goto-char pos)
  (current-column))

(defsubst align-regions (regions props rule func)
  "Align the regions specified in REGIONS, a list of cons cells.
PROPS describes formatting features specific to the given regions.
RULE specifies exactly how to perform the alignments.
If FUNC is specified, it will be called with each region that would
have been aligned, rather than modifying the text."
  (while regions
    (save-excursion
      (align-areas (car regions) (car props) rule func))
    (setq regions (cdr regions)
	  props (cdr props))))

(defun align-areas (areas props rule func)
  "Given a list of AREAS and formatting PROPS, align according to RULE.
AREAS should be a list of cons cells containing beginning and ending
markers.  This function sweeps through all of the beginning markers,
finds out which one starts in the furthermost column, and then deletes
and inserts text such that all of the ending markers occur in the same
column.

If FUNC is non-nil, it will be called for each text region that would
have been aligned.  No changes will be made to the buffer."
  (let* ((column (cdr (assq 'column rule)))
	 (fixed (if (symbolp column)
		    (symbol-value column)
		  column))
	 (justify (cdr (assq 'justify rule)))
	 (col (or fixed 0))
	 (width 0)
	 ecol change)

    ;; Determine the alignment column.
    (let ((a areas))
      (while a
	(unless fixed
	  (setq col (max col (align-column (caar a)))))
	(unless change
	  (goto-char (cdar a))
	  (if ecol
	      (if (/= ecol (current-column))
		  (setq change t))
	    (setq ecol (current-column))))
	(when justify
	  (goto-char (caar a))
	  (if (and (re-search-forward "\\s-*" (cdar a) t)
		   (/= (point) (cdar a)))
	      (let ((bcol (current-column)))
		(setcdr (car a) (cons (point-marker) (cdar a)))
		(goto-char (cdr (cdar a)))
		(setq width (max width (- (current-column) bcol))))))
	(setq a (cdr a))))

    (unless fixed
      (setq col (+ (align-adjust-col-for-rule
		    col rule (car props) (cdr props)) width)))

    ;; Make all ending positions to occur in the goal column.  Since
    ;; the whitespace to be modified was already deleted by
    ;; `align-region', all we have to do here is indent.

    (unless change
      (setq change (and ecol (/= col ecol))))

    (when (or func change)
      (while areas
	(let ((area (car areas))
	      (gocol col) cur)
	  (when area
	    (if func
		(funcall func
                         (marker-position (car area))
                         (marker-position (if (and justify
                                                   (consp (cdr area)))
                                              (cadr area)
                                            (cdr area)))
                         change)
	      (if (not (and justify
			    (consp (cdr area))))
		  (goto-char (cdr area))
		(goto-char (cddr area))
		(let ((ecol (current-column)))
		  (goto-char (cadr area))
		  (setq gocol (- col (- ecol (current-column))))))
	      (setq cur (current-column))
	      (cond ((< gocol 0) t)     ; don't do anything
		    ((= cur gocol) t)   ; don't need to
		    ((< cur gocol)      ; just add space
		     ;; FIXME: It is stated above that "...the
		     ;;	       whitespace to be modified was already
		     ;;	       deleted by `align-region', all we have
		     ;;	       to do here is indent."  However, this
		     ;;	       doesn't seem to be true, so we first
		     ;;	       delete the whitespace to avoid tabs
		     ;;	       after spaces.
		     (delete-horizontal-space t)
		     (indent-to gocol))
		    (t
		     ;; This code works around an oddity in the
		     ;; FORCE argument of `move-to-column', which
		     ;; tends to screw up markers if there is any
		     ;; tabbing.
		     (let ((endcol (align-column
				    (if (and justify
					     (consp (cdr area)))
					(cadr area)
				      (cdr area))))
			   (abuts (<= gocol
				      (align-column (car area)))))
		       (if abuts
			   (goto-char (car area))
			 (move-to-column gocol t))
		       (let ((here (point)))
			 (move-to-column endcol t)
			 (delete-region here (point))
			 (if abuts
			     (indent-to (align-adjust-col-for-rule
					 (current-column) rule
					 (car props) (cdr props)))))))))))
	(setq areas (cdr areas))))))

(defmacro align--set-marker (marker-var pos &optional type)
  "If MARKER-VAR is a marker, move it to position POS.
Otherwise, create a new marker at position POS, with type TYPE."
  `(if (markerp ,marker-var)
       (move-marker ,marker-var ,pos)
     (setq ,marker-var (copy-marker ,pos ,type))))

(defun align--rule-should-run (rule)
  "Given an `align-rules-list' entry RULE, return t if it should run.
This is decided by the `modes' and `run-if' keys in the alist
RULE.  Their meaning is documented in `align-rules-list' (which see)."
  (let-alist rule
    (not (or (and .modes (not (derived-mode-p (eval .modes))))
             (and .run-if (not (funcall .run-if)))))))

(defun align-region (beg end separate rules exclude-rules
			 &optional func)
  "Align a region based on a given set of alignment rules.
BEG and END specify the region to be aligned.  Either may be nil, in
which case the range will stop at the nearest section division (see
`align-region-separate', and `align-region-heuristic' for more
information').

The region will be divided into separate alignment sections based on
the value of SEPARATE.

RULES and EXCLUDE-RULES are a pair of lists describing how to align
the region, and which text areas within it should be excluded from
alignment.  See the `align-rules-list' for more information on the
required format of these two lists.

If FUNC is specified, no text will be modified.  What `align-region'
will do with the rules is to search for the alignment areas, as it
regularly would, taking account for exclusions, and then call FUNC,
first with the beginning and ending of the region to be aligned
according to that rule (this can be different for each rule, if BEG
and END were nil), and then with the beginning and ending of each
text region that the rule would have applied to.

The signature of FUNC should thus be:

 (defun my-align-function (beg end mode)
   \"If MODE is a rule (a list), return t if BEG to END are to be searched.
Otherwise BEG to END will be a region of text that matches the rule's
definition, and MODE will be non-nil if any changes are necessary.\"
   (unless (and mode (listp mode))
     (message \"Would have aligned from %d to %d...\" beg end)))

This feature (of passing a FUNC) is used internally to locate the
position of exclusion areas, but could also be used for any other
purpose where you might want to know where the regions that the
aligner would have dealt with are."
  (let* ((end-mark (and end (copy-marker end t)))
	 (real-beg beg)
	 (report (and (not func) align-large-region beg end
		      (>= (- end beg) align-large-region)))
         (rules (seq-filter #'align--rule-should-run rules))
	 (rule-index 1)
	 (rule-count (length rules))
	 markers)
    (if (and align-indent-before-aligning real-beg end-mark)
	(indent-region real-beg end-mark nil))
    (while rules
      (let ((rule (car rules)))
        (progn
          ;; Search for a match for the rule.
	  (let* ((case-fold-search case-fold-search)
		 (case-fold (assq 'case-fold rule))
		 (regexp  (cdr (assq 'regexp rule)))
		 (regfunc (and (functionp regexp) regexp))
		 (rulesep (assq 'separate rule))
		 (thissep (if rulesep (cdr rulesep) separate))
		 same (eol 0)
		 search-start
                 (groups (ensure-list (or (cdr (assq 'group rule)) 1)))
                 (spacing (cdr (assq 'spacing rule)))
                 (tab-stop (let ((rule-ts (assq 'tab-stop rule)))
                              (cond (rule-ts
                                     (cdr rule-ts))
                                    ((symbolp align-to-tab-stop)
                                     (symbol-value align-to-tab-stop))
                                    (t
                                     align-to-tab-stop))))
                 (repeat (cdr (assq 'repeat rule)))
                 (valid (assq 'valid rule))
                 (first (car groups))
		 regions index
		 last-point
		 save-match-data
		 exclude-p
		 align-props)
	    (save-excursion
	      ;; if beg and end were not given, figure out what the
	      ;; current alignment region should be.  Depending on the
	      ;; value of `align-region-separate' it's possible for
	      ;; each rule to have its own definition of what that
	      ;; current alignment section is.
	      (if real-beg
		  (goto-char beg)
		(if (or (not thissep) (eq thissep 'entire))
		    (error "Cannot determine alignment region for `%s'"
			   (symbol-name (cdr (assq 'title rule)))))
		(beginning-of-line)
		(while (and (not (eobp))
			    (looking-at "^\\s-*$"))
		  (forward-line))
		(let* ((here (point))
		       (start here))
		  (while (and here
			      (let ((terminus
				     (and align-region-heuristic
					  (- (point)
					     align-region-heuristic))))
				(if regfunc
				    (funcall regfunc terminus t)
				  (re-search-backward regexp
						      terminus t))))
		    (if (align-new-section-p (point) here thissep)
			(setq beg here
			      here nil)
		      (setq here (point))))
		  (if (not here)
		      (goto-char beg))
		  (beginning-of-line)
		  (setq beg (point))
		  (goto-char start)
		  (setq here (point))
		  (while (and here
			      (let ((terminus
				     (and align-region-heuristic
					  (+ (point)
					     align-region-heuristic))))
				(if regfunc
				    (funcall regfunc terminus nil)
				  (re-search-forward regexp terminus t))))
		    (if (align-new-section-p here (point) thissep)
			(setq end here
			      here nil)
		      (setq here (point))))
		  (if (not here)
		      (goto-char end))
		  (forward-line)
		  (setq end (point))
                  (align--set-marker end-mark end t)
		  (goto-char beg)))

	      ;; If we have a region to align, and `func' is set and
	      ;; reports back that the region is ok, then align it.
	      (when (or (not func)
			(funcall func beg end rule))
                (let (rule-beg exclude-areas)
                  ;; determine first of all where the exclusions
                  ;; lie in this region
                  (when exclude-rules
                    (align-region
                     beg end 'entire
                     exclude-rules nil
                     (lambda (b e mode)
                       (or (and mode (listp mode))
                           (setq exclude-areas
                                 (cons (cons b e)
                                       exclude-areas)))))
                    (setq exclude-areas
                          (nreverse
                           (sort exclude-areas #'car-less-than-car))))

                  ;; set `case-fold-search' according to the
                  ;; (optional) `case-fold' property
                  (and case-fold
                       (setq case-fold-search (cdr case-fold)))

                  ;; while we can find the rule in the alignment
                  ;; region..
                  (while (and (< (point) end-mark)
                              (setq search-start (point))
                              (if regfunc
                                  (funcall regfunc end-mark nil)
                                (re-search-forward regexp
                                                   end-mark t)))

                    ;; give the user some indication of where we
                    ;; are, if it's a very large region being
                    ;; aligned
                    (if report
                        (let ((symbol (car rule)))
                          (if (and symbol (symbolp symbol))
                              (message
                               "Aligning `%s' (rule %d of %d) %d%%..."
                               (symbol-name symbol) rule-index rule-count
                               (floor (* (- (point) real-beg) 100.0)
                                      (- end-mark real-beg)))
                            (message
                             "Aligning %d%%..."
                             (floor (* (- (point) real-beg) 100.0)
                                    (- end-mark real-beg))))))

                    ;; if the search ended us on the beginning of
                    ;; the next line, move back to the end of the
                    ;; previous line.
                    (if (and (bolp) (> (point) search-start))
                        (forward-char -1))

                    ;; test whether we have found a match on the same
                    ;; line as a previous match
                    (when (> (point) eol)
                      (setq same nil)
                      (align--set-marker eol (line-end-position)))

                    ;; remember the beginning position of this rule
                    ;; match, and save the match-data, since either
                    ;; the `valid' form, or the code that searches for
                    ;; section separation, might alter it
                    (setq rule-beg (match-beginning first)
                          save-match-data (match-data))

                    (or rule-beg
                        (error "No match for subexpression %s" first))

                    ;; unless the `valid' attribute is set, and tells
                    ;; us that the rule is not valid at this point in
                    ;; the code..
                    (unless (and valid (not (funcall (cdr valid))))

                      ;; look to see if this match begins a new
                      ;; section.  If so, we should align what we've
                      ;; collected so far, and then begin collecting
                      ;; anew for the next alignment section
                      (when (and last-point
                                 (align-new-section-p last-point rule-beg
                                                      thissep))
                        (align-regions regions align-props rule func)
                        (setq regions nil)
                        (setq align-props nil))
                      (align--set-marker last-point rule-beg t)

                      ;; restore the match data
                      (set-match-data save-match-data)

                      ;; check whether the region to be aligned
                      ;; straddles an exclusion area
                      (let ((excls exclude-areas))
                        (setq exclude-p nil)
                        (while excls
                          (if (and (< (match-beginning (car groups))
                                      (cdar excls))
                                   (> (match-end (car (last groups)))
                                      (caar excls)))
                              (setq exclude-p t
                                    excls nil)
                            (setq excls (cdr excls)))))

                      ;; go through the parenthesis groups
                      ;; matching whitespace to be contracted or
                      ;; expanded (or possibly justified, if the
                      ;; `justify' attribute was set)
                      (unless exclude-p
                        (dolist (g groups)
                          ;; We must use markers, since
                          ;; `align-areas' may modify the buffer.
                          ;; Avoid polluting the markers.
                          (let* ((group-beg (copy-marker
                                             (match-beginning g) t))
                                 (group-end (copy-marker
                                             (match-end g) t))
                                 (region (cons group-beg group-end))
                                 (props (cons (if (listp spacing)
                                                  (car spacing)
                                                spacing)
                                              (if (listp tab-stop)
                                                  (car tab-stop)
                                                tab-stop))))
                            (push group-beg markers)
                            (push group-end markers)
                            (setq index (if same (1+ index) 0))
                            (cond
                             ((nth index regions)
                              (setcar (nthcdr index regions)
                                      (cons region
                                            (nth index regions))))
                             (regions
                              (nconc regions
                                     (list (list region)))
                              (nconc align-props (list props)))
                             (t
                              (setq regions
                                    (list (list region)))
                              (setq align-props (list props)))))
                          ;; If any further rule matches are found
                          ;; before `eol', they are on the same
                          ;; line as this one; this can only
                          ;; happen if the `repeat' attribute is
                          ;; non-nil.
                          (if (listp spacing)
                              (setq spacing (cdr spacing)))
                          (if (listp tab-stop)
                              (setq tab-stop (cdr tab-stop)))
                          (setq same t))

                        ;; if `repeat' has not been set, move to
                        ;; the next line; don't bother searching
                        ;; anymore on this one
                        (if (and (not repeat) (not (bolp)))
                            (forward-line))

                        ;; if the search did not change point,
                        ;; move forward to avoid an infinite loop
                        (if (= (point) search-start)
                            (forward-char)))))

                  ;; when there are no more matches for this rule,
                  ;; align whatever was left over
                  (if regions
                      (align-regions regions align-props rule func))))))))
      (setq rules (cdr rules)
	    rule-index (1+ rule-index)))
    ;; This function can use a lot of temporary markers, so instead of
    ;; waiting for the next GC we delete them immediately (Bug#10047).
    (when end-mark (set-marker end-mark nil))
    (dolist (m markers)
      (set-marker m nil))

    (if report
	(message "Aligning...done"))))

(provide 'align)

(run-hooks 'align-load-hook)

;;; align.el ends here

debug log:

solving 81ccc4b5e2d ...
found 81ccc4b5e2d in https://git.savannah.gnu.org/cgit/emacs.git

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).