]> git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/Align.txt
c4473726faddbf58efab20682c05005cd63198b7
[rbdr/dotfiles] / vim / doc / Align.txt
1 *align.txt* The Alignment Tool Mar 04, 2009
2
3 Author: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamily.AbizM>
4 (remove NOSPAM from Campbell's email first)
5 Copyright: (c) 2004-2008 by Charles E. Campbell, Jr. *Align-copyright*
6 The VIM LICENSE applies to Align.vim, AlignMaps.vim, and Align.txt
7 (see |copyright|) except use "Align and AlignMaps" instead of "Vim"
8 NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
9
10 ==============================================================================
11 1. Contents *align* *align-contents* {{{1
12
13 1. Contents.................: |align-contents|
14 2. Alignment Manual.........: |align-manual|
15 3. Alignment Usage..........: |align-usage|
16 Alignment Concepts.......: |align-concepts|
17 Alignment Commands.......: |align-commands|
18 Alignment Control........: |align-control|
19 Separators.............: |alignctrl-separators|
20 Initial Whitespace.....: |alignctrl-w| |alignctrl-W| |alignctrl-I|
21 Justification..........: |alignctrl-l| |alignctrl-r| |alignctrl-c|
22 Justification Control..: |alignctrl--| |alignctrl-+| |alignctrl-:|
23 Cyclic/Sequential......: |alignctrl-=| |alignctrl-C|
24 Separator Justification: |alignctrl-<| |alignctrl->| |alignctrl-||
25 Line (de)Selection.....: |alignctrl-g| |alignctrl-v|
26 Temporary Settings.....: |alignctrl-m|
27 Padding................: |alignctrl-p| |alignctrl-P|
28 Current Options........: |alignctrl-settings| |alignctrl-|
29 Alignment................: |align-align|
30 4. Alignment Maps...........: |align-maps|
31 \a,....................: |alignmap-a,|
32 \a?....................: |alignmap-a?|
33 \a<....................: |alignmap-a<|
34 \abox..................: |alignmap-abox|
35 \acom..................: |alignmap-acom|
36 \anum..................: |alignmap-anum|
37 \ascom.................: |alignmap-ascom|
38 \adec..................: |alignmap-adec|
39 \adef..................: |alignmap-adef|
40 \afnc..................: |alignmap-afnc|
41 \adcom.................: |alignmap-adcom|
42 \aocom.................: |alignmap-aocom|
43 \tsp...................: |alignmap-tsp|
44 \tsq...................: |alignmap-tsq|
45 \tt....................: |alignmap-tt|
46 \t=....................: |alignmap-t=|
47 \T=....................: |alignmap-T=|
48 \Htd...................: |alignmap-Htd|
49 5. Alignment Tool History...: |align-history|
50
51 ==============================================================================
52 2. Align Manual *alignman* *alignmanual* *align-manual* {{{1
53
54 Align comes as a vimball; simply typing >
55 vim Align.vba.gz
56 :so %
57 < should put its components where they belong. The components are: >
58 .vim/plugin/AlignPlugin.vim
59 .vim/plugin/AlignMapsPlugin.vim
60 .vim/plugin/cecutil.vim
61 .vim/autoload/Align.vim
62 .vim/autoload/AlignMaps.vim
63 .vim/doc/Align.txt
64 < To see a user's guide, see |align-userguide|
65 To see examples, see |alignctrl| and |alignmaps|
66 >
67 /=============+=========+=====================================================\
68 || \ Default/ ||
69 || Commands \ Value/ Explanation ||
70 || | | ||
71 ++==============+====+=======================================================++
72 || AlignCtrl | | =Clrc-+:pPIWw [..list-of-separator-patterns..] ||
73 || | +-------------------------------------------------------+|
74 || | | may be called as a command or as a function: ||
75 || | | :AlignCtrl =lp0P0W & \\ ||
76 || | | :call Align#AlignCtrl('=lp0P0W','&','\\') ||
77 || | | ||
78 || | +-------------------------------------------------------++
79 || 1st arg | = | = all separator patterns are equivalent and are ||
80 || | | simultaneously active. Patterns are |regexp|. ||
81 || | | C cycle through separator patterns. Patterns are ||
82 || | | |regexp| and are active sequentially. ||
83 || | | ||
84 || | < | < left justify separator Separators are justified, ||
85 || | | > right justify separator too. Separator styles ||
86 || | | | center separator are cyclic. ||
87 || | | ||
88 || | l | l left justify Justification styles are always ||
89 || | | r right justify cyclic (ie. lrc would mean left j., ||
90 || | | c center then right j., then center, repeat. ||
91 || | | - skip this separator ||
92 || | | + re-use last justification method ||
93 || | | : treat rest of text as a field ||
94 || | | ||
95 || | p1 | p### pad separator on left by # blanks ||
96 || | P1 | P### pad separator on right by # blanks ||
97 || | | ||
98 || | I | I preserve and apply first line's leading white ||
99 || | | space to all lines ||
100 || | | W preserve leading white space on every line, even ||
101 || | | if it varies from line to line ||
102 || | | w don't preserve leading white space ||
103 || | | ||
104 || | | g second argument is a selection pattern -- only ||
105 || | | align on lines that have a match (inspired by ||
106 || | | :g/selection pattern/command) ||
107 || | | v second argument is a selection pattern -- only ||
108 || | | align on lines that _don't_ have a match (inspired ||
109 || | | by :v/selection pattern/command) ||
110 || | | ||
111 || | | m Map support: AlignCtrl will immediately do an ||
112 || | | AlignPush() and the next call to Align() will do ||
113 || | | an AlignPop at the end. This feature allows maps ||
114 || | | to preserve user settings. ||
115 || | | ||
116 || | | default ||
117 || | | AlignCtrl default ||
118 || | | will clear the AlignCtrl ||
119 || | | stack & set the default: AlignCtrl "Ilp1P1=" '=' ||
120 || | | ||
121 || +----+-------------------------------------------------------+|
122 || More args | More arguments are interpreted as describing separators ||
123 || +------------------------------------------------------------+|
124 || No args | AlignCtrl will display its current settings ||
125 ||==============+============================================================+|
126 ||[range]Align | [..list-of-separators..] ||
127 ||[range]Align! | [AlignCtrl settings] [..list-of-separators..] ||
128 || +------------------------------------------------------------+|
129 || | Aligns text over the given range. The range may be ||
130 || | selected via visual mode (v, V, or ctrl-v) or via ||
131 || | the command line. The Align operation may be invoked ||
132 || | as a command or as a function; as a function, the first ||
133 || | argument is 0=separators only, 1=AlignCtrl option string ||
134 || | followed by a list of separators. ||
135 || | :[range]Align ||
136 || | :[range]Align [list of separators] ||
137 || | :[range]call Align#Align(0) ||
138 || | :[range]call Align#Align(0,"list","of","separators",...) ||
139 \=============================================================================/
140
141 ==============================================================================
142 3. Alignment Usage *alignusage* *align-usage* *align-userguide* {{{1
143
144
145 ALIGNMENT CONCEPTS *align-concept* *align-concepts* {{{2
146
147 The typical text to be aligned is considered to be:
148
149 * composed of two or more fields
150 * separated by one or more separator pattern(s):
151 * two or more lines
152 >
153 ws field ws separator ws field ws separator ...
154 ws field ws separator ws field ws separator ...
155 <
156 where "ws" stands for "white space" such as blanks and/or tabs,
157 and "fields" are arbitrary text. For example, consider >
158
159 x= y= z= 3;
160 xx= yy= zz= 4;
161 zzz= yyy= zzz= 5;
162 a= b= c= 3;
163 <
164 Assume that it is desired to line up all the "=" signs; these,
165 then, are the separators. The fields are composed of all the
166 alphameric text. Assuming they lie on lines 1-4, one may align
167 those "=" signs with: >
168 :AlignCtrl l
169 :1,4Align =
170 < The result is: >
171 x = y = z = 3;
172 xx = yy = zz = 4;
173 zzz = yyy = zzz = 5;
174 a = b = c = 3;
175
176 < Note how each "=" sign is surrounded by a single space; the
177 default padding is p1P1 (p1 means one space before the separator,
178 and P1 means one space after it). If you wish to change the
179 padding, say to no padding, use (see |alignctrl-p|) >
180 :AlignCtrl lp0P0
181
182 < Next, note how each field is left justified; that's what the "l"
183 (a small letter "ell") does. If right-justification of the fields
184 had been desired, an "r" could've been used: >
185 :AlignCtrl r
186 < yielding >
187 x = y = z = 3;
188 xx = yy = zz = 4;
189 zzz = yyy = zzz = 5;
190 a = b = c = 3;
191 < There are many more options available for field justification: see
192 |alignctrl-c| and |alignctrl--|.
193
194 Separators, although commonly only one character long, are actually
195 specified by regular expressions (see |regexp|), and one may left
196 justify, right justify, or center them, too (see |alignctrl-<|).
197
198 Assume that for some reason a left-right-left-right-... justification
199 sequence was wished. This wish is simply achieved with >
200 :AlignCtrl lr
201 :1,4Align =
202 < because the justification commands are considered to be "cylic"; ie.
203 lr is the same as lrlrlrlrlrlrlr...
204
205 There's a lot more discussed under |alignctrl|; hopefully the examples
206 there will help, too.
207
208
209 ALIGNMENT COMMANDS *align-command* *align-commands* {{{2
210
211 The <Align.vim> script includes two primary commands and two
212 minor commands:
213
214 AlignCtrl : this command/function sets up alignment options
215 which persist until changed for later Align calls.
216 It controls such things as: how to specify field
217 separators, initial white space, padding about
218 separators, left/right/center justification, etc. >
219 ex. AlignCtrl wp0P1
220 Interpretation: during subsequent alignment
221 operations, preserve each line's initial
222 whitespace. Use no padding before separators
223 but provide one padding space after separators.
224 <
225 Align : this command/function operates on the range given it to
226 align text based on one or more separator patterns. The
227 patterns may be provided via AlignCtrl or via Align
228 itself. >
229
230 ex. :%Align ,
231 Interpretation: align all commas over the entire
232 file.
233 < The :Align! format permits alignment control commands
234 to precede the alignment patterns. >
235 ex. :%Align! p2P2 =
236 < This will align all "=" in the file with two padding
237 spaces on both sides of each "=" sign.
238
239 NOTE ON USING PATTERNS WITH ALIGN:~
240 Align and AlignCtrl use |<q-args>| to obtain their
241 input patterns and they use an internal function to
242 split arguments at whitespace unless inside "..."s.
243 One may escape characters inside a double-quote string
244 by preceding such characters with a backslash.
245
246 AlignPush : this command/function pushes the current AlignCtrl
247 state onto an internal stack. >
248 ex. :AlignPush
249 Interpretation: save the current AlignCtrl
250 settings, whatever they may be. They'll
251 also remain as the current settings until
252 AlignCtrl is used to change them.
253 <
254 AlignPop : this command/function pops the current AlignCtrl
255 state from an internal stack. >
256 ex. :AlignPop
257 Interpretation: presumably AlignPush was
258 used (at least once) previously; this command
259 restores the AlignCtrl settings when AlignPush
260 was last used.
261 < Also see |alignctrl-m| for a way to automatically do
262 an AlignPop after an Align (primarily this is for maps).
263
264 ALIGNMENT OPTIONS *align-option* *align-options* {{{2
265 *align-utf8* *align-utf* *align-codepoint* *align-strlen* *align-multibyte*
266
267 For those of you who are using 2-byte (or more) characters such as are
268 available with utf-8, Align now provides a special option which you
269 may choose based upon your needs:
270
271 Use Built-in strlen() ~
272 >
273 let g:Align_xstrlen= 0
274
275 < This is the fastest method, but it doesn't handle multibyte characters
276 well. It is the default for:
277
278 enc=latin1
279 vim compiled without multi-byte support
280 $LANG is en_US.UTF-8 (assuming USA english)
281
282 Number of codepoints (Latin a + combining circumflex is two codepoints)~
283 >
284 let g:Align_xstrlen= 1 (default)
285 <
286 Number of spacing codepoints (Latin a + combining circumflex is one~
287 spacing codepoint; a hard tab is one; wide and narrow CJK are one~
288 each; etc.)~
289 >
290 let g:Align_xstrlen= 2
291 <
292 Virtual length (counting, for instance, tabs as anything between 1 and~
293 'tabstop', wide CJK as 2 rather than 1, Arabic alif as zero when~
294 immediately preceded by lam, one otherwise, etc.)~
295 >
296 let g:Align_xstrlen= 3
297 <
298 By putting one of these settings into your <.vimrc>, Align will use an
299 internal (interpreted) function to determine a string's length instead
300 of the Vim's built-in |strlen()| function. Since the function is
301 interpreted, Align will run a bit slower but will handle such strings
302 correctly. The last setting (g:Align_xstrlen= 3) probably will run
303 the slowest but be the most accurate. (thanks to Tony Mechelynck for
304 these)
305
306
307 ALIGNMENT CONTROL *alignctrl* *align-control* {{{2
308
309 This command doesn't do the alignment operation itself; instead, it
310 controls subsequent alignment operation(s).
311
312 The first argument to AlignCtrl is a string which may contain one or
313 more alignment control settings. Most of the settings are specified
314 by single letters; the exceptions are the p# and P# commands which
315 interpret a digit following the p or P as specifying padding about the
316 separator.
317
318 The typical text line is considered to be composed of two or more
319 fields separated by one or more separator pattern(s): >
320
321 ws field ws separator ws field ws separator ...
322 <
323 where "ws" stands for "white space" such as blanks and/or tabs.
324
325
326 SEPARATORS *alignctrl-separators* {{{3
327
328 As a result, separators may not have white space (tabs or blanks) on
329 their outsides (ie. ": :" is fine as a separator, but " :: " is
330 not). Usually such separators are not needed, although a map has been
331 provided which works around this limitation and aligns on whitespace
332 (see |alignmap-tsp|).
333
334 However, if you really need to have separators with leading or
335 trailing whitespace, consider handling them by performing a substitute
336 first (ie. s/ :: /@/g), do the alignment on the temporary pattern
337 (ie. @), and then perform a substitute to revert the separators back
338 to their desired condition (ie. s/@/ :: /g).
339
340 The Align#Align() function will first convert tabs over the region into
341 spaces and then apply alignment control. Except for initial white
342 space, white space surrounding the fields is ignored. One has three
343 options just for handling initial white space:
344
345
346 --- *alignctrl-w*
347 wWI INITIAL WHITE SPACE *alignctrl-W* {{{3
348 --- *alignctrl-I*
349 w : ignore all selected lines' initial white space
350 W : retain all selected lines' initial white space
351 I : retain only the first line's initial white space and
352 re-use it for subsequent lines
353
354 Example: Leading white space options: >
355 +---------------+-------------------+-----------------+
356 |AlignCtrl w= :=| AlignCtrl W= := | AlignCtrl I= := |
357 +------------------+---------------+-------------------+-----------------+
358 | Original | w option | W option | I option |
359 +------------------+---------------+-------------------+-----------------+
360 | a := baaa |a := baaa | a : = baaa | a := baaa |
361 | caaaa := deeee |caaaa := deeee | caaaa : = deeee| caaaa := deeee|
362 | ee := f |ee := f | ee : = f | ee := f |
363 +------------------+---------------+-------------------+-----------------+
364 <
365 The original has at least one leading white space on every line.
366 Using Align with w eliminated each line's leading white space.
367 Using Align with W preserved each line's leading white space.
368 Using Align with I applied the first line's leading white space
369 (three spaces) to each line.
370
371
372 ------ *alignctrl-l*
373 lrc-+: FIELD JUSTIFICATION *alignctrl-r* {{{3
374 ------ *alignctrl-c*
375
376 With "lrc", the fields will be left-justified, right-justified, or
377 centered as indicated by the justification specifiers (lrc). The
378 "lrc" options are re-used by cycling through them as needed:
379
380 l means llllll....
381 r means rrrrrr....
382 lr means lrlrlr....
383 llr means llrllr....
384
385 Example: Justification options: Align = >
386 +------------+-------------------+-------------------+-------------------+
387 | Original | AlignCtrl l | AlignCtrl r | AlignCtrl lr |
388 +------------+-------------------+-------------------+-------------------+
389 | a=bb=ccc=1 |a = bb = ccc = 1| a = bb = ccc = 1|a = bb = ccc = 1|
390 | ccc=a=bb=2 |ccc = a = bb = 2|ccc = a = bb = 2|ccc = a = bb = 2|
391 | dd=eee=f=3 |dd = eee = f = 3| dd = eee = f = 3|dd = eee = f = 3|
392 +------------+-------------------+-------------------+-------------------+
393 | Alignment |l l l l| r r r r|l r l r|
394 +------------+-------------------+-------------------+-------------------+
395 <
396 AlignCtrl l : The = separator is repeatedly re-used, as the
397 cycle only consists of one character (the "l").
398 Every time left-justification is used for fields.
399 AlignCtrl r : The = separator is repeatedly re-used, as the
400 cycle only consists of one character (the "l").
401 Every time right-justification is used for fields
402 AlignCtrl lr: Again, the "=" separator is repeatedly re-used,
403 but the fields are justified alternately between
404 left and right.
405
406 Even more separator control is available. With "-+:":
407
408 - : skip treating the separator as a separator. *alignctrl--*
409 + : repeat use of the last "lrc" justification *alignctrl-+*
410 : : treat the rest of the line as a single field *alignctrl-:*
411
412 Example: More justification options: Align = >
413 +------------+---------------+--------------------+---------------+
414 | Original | AlignCtrl -l | AlignCtrl rl+ | AlignCtrl l: |
415 +------------+---------------+--------------------+---------------+
416 | a=bb=ccc=1 |a=bb = ccc=1 | a = bb = ccc = 1 |a = bb=ccc=1 |
417 | ccc=a=bb=2 |ccc=a = bb=2 |ccc = a = bb = 2 |ccc = a=bb=2 |
418 | dd=eee=f=3 |dd=eee = f=3 | dd = eee = f = 3 |dd = eee=f=3 |
419 +------------+---------------+--------------------+---------------+
420 | Alignment |l l | r l l l |l l |
421 +------------+---------------+--------------------+---------------+
422 <
423 In the first example in "More justification options":
424
425 The first "=" separator is skipped by the "-" specification,
426 and so "a=bb", "ccc=a", and "dd=eee" are considered as single fields.
427
428 The next "=" separator has its (left side) field left-justified.
429 Due to the cyclic nature of separator patterns, the "-l"
430 specification is equivalent to "-l-l-l ...".
431
432 Hence the next specification is a "skip", so "ccc=1", etc are fields.
433
434 In the second example in "More justification options":
435
436 The first field is right-justified, the second field is left
437 justified, and all remaining fields repeat the last justification
438 command (ie. they are left justified, too).
439
440 Hence rl+ is equivalent to rlllllllll ...
441 (whereas plain rl is equivalent to rlrlrlrlrl ... ).
442
443 In the third example in "More justification options":
444
445 The text following the first separator is treated as a single field.
446
447 Thus using the - and : operators one can apply justification to a
448 single separator.
449
450 ex. 1st separator only: AlignCtrl l:
451 2nd separator only: AlignCtrl -l:
452 3rd separator only: AlignCtrl --l:
453 etc.
454
455
456 --- *alignctrl-=*
457 =C CYCLIC VS ALL-ACTIVE SEPARATORS *alignctrl-C* {{{3
458 ---
459
460 The separators themselves may be considered as equivalent and
461 simultaneously active ("=") or sequentially cycled through ("C").
462 Separators are regular expressions (|regexp|) and are specified as the
463 second, third, etc arguments. When the separator patterns are
464 equivalent and simultaneously active, there will be one pattern
465 constructed: >
466
467 AlignCtrl ... pat1 pat2 pat3
468 \(pat1\|pat2\|pat3\)
469 <
470 Each separator pattern is thus equivalent and simultaneously active.
471 The cyclic separator AlignCtrl option stores a list of patterns, only
472 one of which is active for each field at a time.
473
474 Example: Equivalent/Simultaneously-Active vs Cyclic Separators >
475 +-------------+------------------+---------------------+----------------------+
476 | Original | AlignCtrl = = + -| AlignCtrl = = | AlignCtrl C = + - |
477 +-------------+------------------+---------------------+----------------------+
478 |a = b + c - d|a = b + c - d |a = b + c - d |a = b + c - d |
479 |x = y = z + 2|x = y = z + 2 |x = y = z + 2|x = y = z + 2 |
480 |w = s - t = 0|w = s - t = 0 |w = s - t = 0 |w = s - t = 0 |
481 +-------------+------------------+---------------------+----------------------+
482 <
483 The original is initially aligned with all operators (=+-) being
484 considered as equivalent and simultaneously active field separators.
485 Thus the "AlignCtrl = = + -" example shows no change.
486
487 The second example only accepts the '=' as a field separator;
488 consequently "b + c - d" is now a single field.
489
490 The third example illustrates cyclic field separators and is analyzed
491 in the following illustration: >
492
493 field1 separator field2 separator field3 separator field4
494 a = b + c - d
495 x = y = z + 2
496 w = s - t = 0
497 <
498 The word "cyclic" is used because the patterns form a cycle of use; in
499 the above case, its = + - = + - = + - = + -...
500
501 Example: Cyclic separators >
502 Label : this is some text discussing ":"s | ex. abc:def:ghi
503 Label : this is some text with a ":" in it | ex. abc:def
504 <
505 apply AlignCtrl lWC : | |
506 (select lines)Align >
507 Label : this is some text discussing ":"s | ex. abc:def:ghi
508 Label : this is some text with a ":" in it | ex. abcd:efg
509 <
510 In the current example,
511 : is the first separator So the first ":"s are aligned
512 | is the second separator but subsequent ":"s are not.
513 | is the third separator The "|"s are aligned, too.
514 : is the fourth separator Since there aren't two bars,
515 | is the fifth separator the subsequent potential cycles
516 | is the sixth separator don't appear.
517 ...
518
519 In this case it would probably have been a better idea to have used >
520 AlignCtrl WCl: : |
521 < as that alignment control would guarantee that no more cycling
522 would be used after the vertical bar.
523
524 Example: Cyclic separators
525
526 Original: >
527 a| b&c | (d|e) & f-g-h
528 aa| bb&cc | (dd|ee) & ff-gg-hh
529 aaa| bbb&ccc | (ddd|eee) & fff-ggg-hhh
530 <
531 AlignCtrl C | | & - >
532 a | b&c | (d|e) & f - g-h
533 aa | bb&cc | (dd|ee) & ff - gg-hh
534 aaa | bbb&ccc | (ddd|eee) & fff - ggg-hhh
535 <
536 In this example,
537 the first and second separators are "|",
538 the third separator is "&", and
539 the fourth separator is "-",
540
541 (cycling)
542 the fifth and sixth separators are "|",
543 the seventh separator is "&", and
544 the eighth separator is "-", etc.
545
546 Thus the first "&"s are (not yet) separators, and hence are treated as
547 part of the field. Ignoring white space for the moment, the AlignCtrl
548 shown here means that Align will work with >
549
550 field | field | field & field - field | field | field & field - ...
551 <
552
553 --- *alignctrl-<*
554 <>| SEPARATOR JUSTIFICATION *alignctrl->* {{{3
555 --- *alignctrl-|*
556
557 Separators may be of differing lengths as shown in the example below.
558 Hence they too may be justified left, right, or centered.
559 Furthermore, separator justification specifications are cyclic:
560
561 < means <<<<<... justify separator(s) to the left
562 > means >>>>>... justify separator(s) to the right
563 | means |||||... center separator(s)
564
565 Example: Separator Justification: Align -\+ >
566 +-----------------+
567 | Original |
568 +-----------------+
569 | a - bbb - c |
570 | aa -- bb -- ccc |
571 | aaa --- b --- cc|
572 +---------------------+-+-----------------+-+---------------------+
573 | AlignCtrl < | AlignCtrl > | AlignCtrl | |
574 +---------------------+---------------------+---------------------+
575 | a - bbb - c | a - bbb - c | a - bbb - c |
576 | aa -- bb -- ccc | aa -- bb -- ccc | aa -- bb -- ccc |
577 | aaa --- b --- cc | aaa --- b --- cc | aaa --- b --- cc |
578 +---------------------+---------------------+---------------------+
579 <
580
581 --- *alignctrl-g*
582 gv SELECTIVE APPLICATION *alignctrl-v* {{{3
583 ---
584
585
586 These two options provide a way to select (g) or to deselect (v) lines
587 based on a pattern. Ideally :g/pat/Align would work; unfortunately
588 it results in Align#Align() being called on each line satisfying the
589 pattern separately. >
590
591 AlignCtrl g pattern
592 <
593 Align will only consider those lines which have the given pattern. >
594
595 AlignCtrl v pattern
596 <
597 Align will only consider those lines without the given pattern. As an
598 example of use, consider the following example: >
599
600 :AlignCtrl v ^\s*/\*
601 Original :Align = :Align =
602 +----------------+------------------+----------------+
603 |one= 2; |one = 2; |one = 2; |
604 |three= 4; |three = 4; |three = 4; |
605 |/* skip=this */ |/* skip = this */ |/* skip=this */ |
606 |five= 6; |five = 6; |five = 6; |
607 +----------------+------------------+----------------+
608 <
609 The first "Align =" aligned with all "="s, including that one in the
610 "skip=this" comment.
611
612 The second "Align =" had a AlignCtrl v-pattern which caused it to skip
613 (ignore) the "skip=this" line when aligning.
614
615 To remove AlignCtrl's g and v patterns, use (as appropriate) >
616
617 AlignCtrl g
618 AlignCtrl v
619 <
620 To see what g/v patterns are currently active, just use the reporting
621 capability of an unadorned call to AlignCtrl: >
622
623 AlignCtrl
624 <
625
626 ---
627 m MAP SUPPORT *alignctrl-m* {{{3
628 ---
629
630 This option primarily supports the development of maps. The
631 Align#AlignCtrl() call will first do an Align#AlignPush() (ie. retain
632 current alignment control settings). The next Align#Align() will, in
633 addition to its alignment job, finish up with an Align#AlignPop().
634 Thus the Align#AlignCtrl settings that follow the "m" are only
635 temporarily in effect for just the next Align#Align().
636
637
638 ---
639 p### *alignctrl-p*
640 P### PADDING *alignctrl-P* {{{3
641 ---
642
643 These two options control pre-padding and post-padding with blanks
644 about the separator. One may pad separators with zero to nine spaces;
645 the padding number(s) is/are treated as a cyclic parameter. Thus one
646 may specify padding separately for each field or re-use a padding
647 pattern. >
648
649 Example: AlignCtrl p102P0
650 +---------+----------------------------------+
651 | Original| a=b=c=d=e=f=g=h=1 |
652 | Align = | a =b=c =d =e=f =g =h=1 |
653 +---------+----------------------------------+
654 | prepad | 1 0 2 1 0 2 1 0 |
655 +---------+----------------------------------+
656 <
657 This example will cause Align to:
658
659 pre-pad the first "=" with a single blank,
660 pre-pad the second "=" with no blanks,
661 pre-pad the third "=" with two blanks,
662 pre-pad the fourth "=" with a single blank,
663 pre-pad the fifth "=" with no blanks,
664 pre-pad the sixth "=" with two blanks,
665 etc.
666
667 --------------- *alignctrl-settings*
668 No option given DISPLAY STATUS *alignctrl-* {{{3
669 --------------- *alignctrl-no-option*
670
671 AlignCtrl, when called with no arguments, will display the current
672 alignment control settings. A typical display is shown below: >
673
674 AlignCtrl<=> qty=1 AlignStyle<l> Padding<1|1>
675 Pat1<\(=\)>
676 <
677 Interpreting, this means that the separator patterns are all
678 equivalent; in this case, there's only one (qty=1). Fields will be
679 padded on the right with spaces (left justification), and separators
680 will be padded on each side with a single space.
681
682 To change one of these items, see:
683
684 AlignCtrl......|alignctrl|
685 qty............|align-concept|
686 AlignStyle.....|alignctrl--| |alignctrl-+| |alignctrl-:||alignctrl-c|
687 Padding........|alignctrl-p| |alignctrl-P|
688
689 One may get a string which can be fed back into AlignCtrl: >
690
691 :let alignctrl= Align#AlignCtrl()
692 <
693 This form will put a string describing the current AlignCtrl options,
694 except for the "g" and "v" patterns, into a variable. The
695 Align#AlignCtrl() function will still echo its settings, however. One
696 can feed any non-supported "option" to AlignCtrl() to prevent this,
697 however: >
698
699 :let alignctrl= Align#AlignCtrl("d")
700 <
701
702 ALIGNMENT *align-align* {{{2
703
704 Once the alignment control has been determined, the user specifies a
705 range of lines for the Align command/function to do its thing.
706 Alignment is often done on a line-range basis, but one may also
707 restrict alignment to a visual block using ctrl-v. For any visual
708 mode, one types the colon (:) and then "Align". One may, of course,
709 specify a range of lines: >
710
711 :[range]Align [list-of-separators]
712 <
713 where the |:range| is the usual Vim-powered set of possibilities; the
714 list of separators is the same as the AlignCtrl capability. There is
715 only one list of separators, but either AlignCtrl or Align can be used
716 to specify that list.
717
718 An alternative form of the Align command can handle both alignment
719 control and the separator list: >
720
721 :[range]Align! [alignment-control-string] [list-of-separators]
722 <
723 The alignment control string will be applied only for this particular
724 application of Align (it uses |alignctrl-m|). The "g pattern" and
725 "v pattern" alignment controls (see |alignctrl-g| and |alignctrl-v|)
726 are also available via this form of the Align command.
727
728 Align makes two passes over the text to be aligned. The first pass
729 determines how many fields there are and determines the maximum sizes
730 of each field; these sizes are then stored in a vector. The second
731 pass pads the field (left/right/centered as specified) to bring its
732 length up to the maximum size of the field. Then the separator and
733 its AlignCtrl-specified padding is appended.
734
735 Pseudo-Code:~
736 During pass 1
737 | For all fields in the current line
738 || Determine current separator
739 || Examine field specified by current separator
740 || Determine length of field and save if largest thus far
741 Initialize newline based on initial whitespace option (wWI)
742 During pass 2
743 | For all fields in current line
744 || Determine current separator
745 || Extract field specified by current separator
746 || Prepend/append padding as specified by AlignCtrl
747 || (right/left/center)-justify to fit field into max-size field
748 || Append separator with AlignCtrl-specified separator padding
749 || Delete current line, install newly aligned line
750
751 The g and v AlignCtrl patterns cause the passes not to consider lines
752 for alignment, either by requiring that the g-pattern be present or
753 that the v-pattern not be present.
754
755 The whitespace on either side of a separator is ignored.
756
757
758 ==============================================================================
759 4. Alignment Maps *alignmaps* *align-maps* {{{1
760
761 There are a number of maps using Align#AlignCtrl() and Align#Align()
762 in the <AlignMapsPlugin.vim> file. This file may also be put into the
763 plugins subdirectory. Since AlignCtrl and Align supercede textab and
764 its <ttalign.vim> file, the maps either have a leading "t" (for
765 "textab") or the more complicated ones an "a" (for "alignment") for
766 backwards compatibility.
767
768 The maps are shown below with a leading backslash (\). Actually, the
769 <Leader> construct is used (see |mapleader|), so the maps' leading
770 kick-off character is easily customized.
771
772 Furthermore, all AlignMapsPlugin.vim maps use the <Plug> construct (see
773 |<Plug>|and |usr_41.txt|). Hence, if one wishes to override the
774 mapping entirely, one may do that, too. As an example: >
775 map <Leader>ACOM <Plug>AM_acom
776 < would have \ACOM do what \acom previously did (assuming that the
777 mapleader has been left at its default value of a backslash).
778
779 \a, : useful for breaking up comma-separated
780 declarations prior to \adec |alignmap-a,|
781 \a( : aligns ( and , (useful for prototypes) *alignmap-a(*
782 \a? : aligns (...)? ...:... expressions on ? and : |alignmap-a?|
783 \a< : aligns << and >> for c++ |alignmap-a<|
784 \a= : aligns := assignments |alignmap-a=|
785 \abox : draw a C-style comment box around text lines |alignmap-abox|
786 \acom : useful for aligning comments |alignmap-acom|
787 \adcom: useful for aligning comments in declarations |alignmap-adcom|
788 \anum : useful for aligning numbers |alignmap-anum|
789 NOTE: For the visual-mode use of \anum, <vis.vim> is needed!
790 See http://mysite.verizon.net/astronaut/vim/index.html#VIS
791 \aenum: align a European-style number |alignmap-anum|
792 \aunum: align a USA-style number |alignmap-anum|
793 \adec : useful for aligning declarations |alignmap-adec|
794 \adef : useful for aligning definitions |alignmap-adef|
795 \afnc : useful for aligning ansi-c style functions'
796 argument lists |alignmap-afnc|
797 \adcom: a variant of \acom, restricted to comment |alignmap-adcom|
798 containing lines only, but also only for
799 those which don't begin with a comment.
800 Good for certain declaration styles.
801 \aocom: a variant of \acom, restricted to comment |alignmap-aocom|
802 containing lines only
803 \tab : align a table based on tabs *alignmap-tab*
804 (converts to spaces)
805 \tml : useful for aligning the trailing backslashes |alignmap-tml|
806 used to continue lines (shell programming, etc)
807 \tsp : use Align to make a table separated by blanks |alignmap-tsp|
808 (left justified)
809 \ts, : like \t, but swaps whitespace on the right of *alignmap-ts,*
810 the commas to their left
811 \ts: : like \t: but swaps whitespace on the right of *alignmap-ts:*
812 the colons to their left
813 \ts< : like \t< but swaps whitespace on the right of *alignmap-ts<*
814 the less-than signs to their left
815 \ts= : like \t= but swaps whitespace on the right of *alignmap-ts=*
816 the equals signs to their left
817 \Tsp : use Align to make a table separated by blanks |alignmap-Tsp|
818 (right justified)
819 \tsq : use Align to make a table separated by blanks |alignmap-tsq|
820 (left justified) -- "strings" are not split up
821 \tt : useful for aligning LaTeX tabular tables |alignmap-tt|
822 \Htd : tabularizes html tables: |alignmap-Htd|
823 <TR><TD> ...field... </TD><TD> ...field... </TD></TR>
824
825 *alignmap-t|* *alignmap-t#* *alignmap-t,* *alignmap-t:*
826 *alignmap-t;* *alignmap-t<* *alignmap-t?* *alignmap-t~*
827 *alignmap-m=*
828 \tx : make a left-justified alignment on
829 character "x" where "x" is: ,:<=@|# |alignmap-t=|
830 \Tx : make a right-justified alignment on
831 character "x" where "x" is: ,:<=@# |alignmap-T=|
832 \m= : like \t= but aligns with %... style comments
833
834 The leading backslash is actually <leader> (see |mapleader| for how to
835 customize the leader to be whatever you like). These maps use the
836 <Align.vim> package and are defined in the <AlignMaps.vim> file.
837 Although the maps use AlignCtrl options, they typically use the "m"
838 option which pushes the options (AlignPush). The associated Align
839 call which follows will then AlignPop the user's original options
840 back.
841
842 ALIGNMENT MAP USE WITH MARK AND MOVE~
843 In the examples below, one may select the text with a "ma" at the
844 first line, move to the last line, then execute the map.
845
846 ALIGNMENT MAP USE WITH VISUAL MODE~
847 Alternatively, one may select the text with the "V" visual mode
848 command.
849
850 ALIGNMENT MAP USE WITH MENUS~
851 One may use the mark-and-move style (ma, move, use the menu) or
852 the visual mode style (use the V visual mode, move, then select
853 the alignment map with menu selection). The alignment map menu
854 items are under DrChip.AlignMaps .
855
856 One may even change the top level menu name to whatever is wished; by
857 default, its >
858 let g:DrChipTopLvlMenu= "DrChip."
859 < If you set the variable to the empty string (""), then no menu items
860 will be produced. Of course, one must have a vim with +menu, the gui
861 must be running, and |'go'| must have the menu bar suboption (ie. m
862 must be included).
863
864 COMPLEX ALIGNMENT MAP METHOD~
865
866 For those complex alignment maps which do alignment on constructs
867 (e.g. \acom, \adec, etc), a series of substitutes is used to insert
868 "@" symbols in appropriate locations. Align#Align() is then used to
869 do alignment directly on "@"s; then it is followed by further
870 substitutes to do clean-up. However, the maps \WS and \WE, used by
871 every map supported by AlignMaps, protect any original embedded "@"
872 symbols by first converting them to <DEL> characters, doing the
873 requested job, and then converting them back. >
874
875 \WS calls AlignMaps#WrapperStart()
876 \WE calls AlignMaps#WrapperEnd()
877 <
878
879 ---------------------------
880 Alignment Map Examples: \a, *alignmap-a,* {{{3
881 ---------------------------
882
883 Original: illustrates comma-separated declaration splitting: >
884 int a,b,c;
885 struct ABC_str abc,def;
886 <
887 Becomes: >
888 int a;
889 int b;
890 int c;
891 struct ABC_str abc;
892 struct ABC_str def;
893 <
894
895 ---------------------------
896 Alignment Map Examples: \a? *alignmap-a?* {{{3
897 ---------------------------
898
899 Original: illustrates ()?: aligning >
900 printf("<%s>\n",
901 (x == ABC)? "abc" :
902 (x == DEFG)? "defg" :
903 (x == HIJKL)? "hijkl" : "???");
904 <
905 Becomes: select "(x == ..." lines, then \a? >
906 printf("<%s>\n",
907 (x == ABC)? "abc" :
908 (x == DEFG)? "defg" :
909 (x == HIJKL)? "hijkl" : "???");
910 <
911
912 ---------------------------
913 Alignment Map Examples: \a< *alignmap-a<* {{{3
914 ---------------------------
915
916 Original: illustrating aligning of << and >> >
917 cin << x;
918 cin << y;
919 cout << "this is x=" << x;
920 cout << "but y=" << y << "is not";
921 <
922 Becomes: select "(x == ..." lines, then \a< >
923 cin << x;
924 cin << y;
925 cout << "this is x=" << x;
926 cout << "but y=" << y << "is not";
927 <
928
929 ---------------------------
930 Alignment Map Examples: \a= *alignmap-a=* {{{3
931 ---------------------------
932
933 Original: illustrates how to align := assignments >
934 aa:=bb:=cc:=1;
935 a:=b:=c:=1;
936 aaa:=bbb:=ccc:=1;
937 <
938 Bcomes: select the three assignment lines, then \a:= >
939 aa := bb := cc := 1;
940 a := b := c := 1;
941 aaa := bbb := ccc := 1;
942 <
943
944 ---------------------------
945 Alignment Map Examples: \abox *alignmap-abox* {{{3
946 ---------------------------
947
948 Original: illustrates how to comment-box some text >
949 This is some plain text
950 which will
951 soon be surrounded by a
952 comment box.
953 <
954 Becomes: Select "This..box." with ctrl-v, press \abox >
955 /***************************
956 * This is some plain text *
957 * which will *
958 * soon be surrounded by a *
959 * comment box. *
960 ***************************/
961 <
962
963 ---------------------------
964 Alignment Map Examples: \acom *alignmap-acom* {{{3
965 ---------------------------
966
967 Original: illustrates aligning C-style comments (works for //, too) >
968 if(itworks) { /* this */
969 then= dothis; /* is a */
970 } /* set of three comments */
971 <
972 Becomes: Select the three lines, press \acom >
973 if(itworks) { /* this */
974 then= dothis; /* is a */
975 } /* set of three comments */
976 <
977 Also see |alignmap-aocom|
978
979
980 ---------------------------
981 Alignment Map Examples: \anum *alignmap-anum* {{{3
982 ---------------------------
983
984 Original: illustrates how to get numbers lined up >
985 -1.234 .5678 -.901e-4
986 1.234 5.678 9.01e-4
987 12.34 56.78 90.1e-4
988 123.4 567.8 901.e-4
989 <
990 Becomes: Go to first line, ma. Go to last line, press \anum >
991 -1.234 .5678 -.901e-4
992 1.234 5.678 9.01e-4
993 12.34 56.78 90.1e-4
994 123.4 567.8 901.e-4
995 <
996 Original: >
997 | -1.234 .5678 -.901e-4 |
998 | 1.234 5.678 9.01e-4 |
999 | 12.34 56.78 90.1e-4 |
1000 | 123.4 567.8 901.e-4 |
1001 <
1002 Becomes: Select the numbers with ctrl-v (visual-block mode), >
1003 press \anum
1004 | -1.234 .5678 -.901e-4 |
1005 | 1.234 5.678 9.01e-4 |
1006 | 12.34 56.78 90.1e-4 |
1007 | 123.4 567.8 901.e-4 |
1008 <
1009 Original: >
1010 -1,234 ,5678 -,901e-4
1011 1,234 5,678 9,01e-4
1012 12,34 56,78 90,1e-4
1013 123,4 567,8 901,e-4
1014 <
1015 Becomes: Go to first line, ma. Go to last line, press \anum >
1016 -1,234 ,5678 -,901e-4
1017 1,234 5,678 9,01e-4
1018 12,34 56,78 90,1e-4
1019 123,4 567,8 901,e-4
1020 <
1021 In addition:
1022 \aenum is provided to support European-style numbers
1023 \aunum is provided to support USA-style numbers
1024
1025 One may get \aenum behavior for \anum >
1026 let g:alignmaps_euronumber= 1
1027 < or \aunum behavior for \anum if one puts >
1028 let g:alignmaps_usanumber= 1
1029 < in one's <.vimrc>.
1030
1031
1032 ---------------------------
1033 Alignment Map Examples: \ascom *alignmap-ascom* {{{3
1034 ---------------------------
1035
1036 Original: >
1037 /* A Title */
1038 int x; /* this is a comment */
1039 int yzw; /* this is another comment*/
1040 <
1041 Becomes: Select the three lines, press \ascom >
1042 /* A Title */
1043 int x; /* this is a comment */
1044 int yzw; /* this is another comment */
1045 <
1046
1047 ---------------------------
1048 Alignment Map Examples: \adec *alignmap-adec* {{{3
1049 ---------------------------
1050
1051 Original: illustrates how to clean up C/C++ declarations >
1052 int a;
1053 float b;
1054 double *c=NULL;
1055 char x[5];
1056 struct abc_str abc;
1057 struct abc_str *pabc;
1058 int a; /* a */
1059 float b; /* b */
1060 double *c=NULL; /* b */
1061 char x[5]; /* x[5] */
1062 struct abc_str abc; /* abc */
1063 struct abc_str *pabc; /* pabc */
1064 static int a; /* a */
1065 static float b; /* b */
1066 static double *c=NULL; /* b */
1067 static char x[5]; /* x[5] */
1068 static struct abc_str abc; /* abc */
1069 static struct abc_str *pabc; /* pabc */
1070 <
1071 Becomes: Select the declarations text, then \adec >
1072 int a;
1073 float b;
1074 double *c = NULL;
1075 char x[5];
1076 struct abc_str abc;
1077 struct abc_str *pabc;
1078 int a; /* a */
1079 float b; /* b */
1080 double *c = NULL; /* b */
1081 char x[5]; /* x[5] */
1082 struct abc_str abc; /* abc */
1083 struct abc_str *pabc; /* pabc */
1084 static int a; /* a */
1085 static float b; /* b */
1086 static double *c = NULL; /* b */
1087 static char x[5]; /* x[5] */
1088 static struct abc_str abc; /* abc */
1089 static struct abc_str *pabc; /* pabc */
1090 <
1091
1092 ---------------------------
1093 Alignment Map Examples: \adef *alignmap-adef* {{{3
1094 ---------------------------
1095
1096 Original: illustrates how to line up #def'initions >
1097 #define ONE 1
1098 #define TWO 22
1099 #define THREE 333
1100 #define FOUR 4444
1101 <
1102 Becomes: Select four definition lines, apply \adef >
1103 # define ONE 1
1104 # define TWO 22
1105 # define THREE 333
1106 # define FOUR 4444
1107 <
1108
1109 ---------------------------
1110 Alignment Map Examples: \afnc *alignmap-afnc* {{{3
1111 ---------------------------
1112
1113 This map is an exception to the usual selection rules.
1114 It uses "]]" to find the function body's leading "{".
1115 Just put the cursor anywhere in the function arguments and
1116 the entire function declaration should be processed.
1117
1118 Because "]]" looks for that "{" in the first column, the
1119 "original" and "becomes" examples are in the first column,
1120 too.
1121
1122 Original: illustrates lining up ansi-c style function definitions >
1123 int f(
1124 struct abc_str ***a, /* one */
1125 long *b, /* two */
1126 int c) /* three */
1127 {
1128 }
1129 <
1130 Becomes: put cursor anywhere before the '{', press \afnc >
1131 int f(
1132 struct abc_str ***a, /* one */
1133 long *b, /* two */
1134 int c) /* three */
1135 {
1136 }
1137 <
1138
1139 ---------------------------
1140 Alignment Map Examples: \adcom *alignmap-adcom* {{{3
1141 ---------------------------
1142
1143 Original: illustrates aligning comments that don't begin
1144 lines (optionally after some whitespace). >
1145 struct {
1146 /* this is a test */
1147 int x; /* of how */
1148 double y; /* to use adcom */
1149 };
1150 <
1151 Becomes: Select the inside lines of the structure,
1152 then press \adcom. The comment-only
1153 line is ignored but the other two comments
1154 get aligned. >
1155 struct {
1156 /* this is a test */
1157 int x; /* of how */
1158 double y; /* to use adcom */
1159 };
1160 <
1161
1162 ---------------------------
1163 Alignment Map Examples: \aocom *alignmap-aocom* {{{3
1164 ---------------------------
1165
1166 Original: illustrates how to align C-style comments (works for //, too)
1167 but restricted only to aligning with those lines containing
1168 comments. See the difference from \acom (|alignmap-acom|). >
1169 if(itworks) { /* this comment */
1170 then= dothis;
1171 } /* only appears on two lines */
1172 <
1173 Becomes: Select the three lines, press \aocom >
1174 if(itworks) { /* this comment */
1175 then= dothis;
1176 } /* only appears on two lines */
1177 <
1178 Also see |alignmap-acom|
1179
1180
1181 --------------------------- *alignmap-Tsp*
1182 Alignment Map Examples: \tsp *alignmap-tsp* {{{3
1183 ---------------------------
1184
1185 Normally Align can't use white spaces for field separators as such
1186 characters are ignored surrounding field separators. The \tsp and
1187 \Tsp maps get around this limitation.
1188
1189 Original: >
1190 one two three four five
1191 six seven eight nine ten
1192 eleven twelve thirteen fourteen fifteen
1193 <
1194 Becomes: Select the lines, \tsp >
1195 one two three four five
1196 six seven eight nine ten
1197 eleven twelve thirteen fourteen fifteen
1198 <
1199 Becomes: Select the lines, \Tsp >
1200 one two three four five
1201 six seven eight nine ten
1202 eleven twelve thirteen fourteen fifteen
1203 <
1204
1205 ---------------------------
1206 Alignment Map Examples: \tsq *alignmap-tsq* {{{3
1207 ---------------------------
1208
1209 The \tsp map is useful for aligning tables based on white space,
1210 but sometimes one wants double-quoted strings to act as a single
1211 object in spite of embedded spaces. The \tsq map was invented
1212 to support this. (thanks to Leif Wickland)
1213
1214 Original: >
1215 "one two" three
1216 four "five six"
1217 <
1218 Becomes: Select the lines, \tsq >
1219 "one two" three
1220 four "five six"
1221 <
1222
1223 ---------------------------
1224 Alignment Map Examples: \tt *alignmap-tt* {{{3
1225 ---------------------------
1226
1227 Original: illustrates aligning a LaTex Table >
1228 \begin{tabular}{||c|l|r||}
1229 \hline\hline
1230 one&two&three\\ \hline
1231 four&five&six\\
1232 seven&eight&nine\\
1233 \hline\hline
1234 \end{tabular}
1235 <
1236 Becomes: Select the three lines inside the table >
1237 (ie. one..,four..,seven..) and press \tt
1238 \begin{tabular}{||c|l|r||}
1239 \hline\hline
1240 one & two & three \\ \hline
1241 four & five & six \\
1242 seven & eight & nine \\
1243 \hline\hline
1244 \end{tabular}
1245 <
1246
1247 ----------------------------
1248 Alignment Map Examples: \tml *alignmap-tml* {{{3
1249 ----------------------------
1250
1251 Original: illustrates aligning multi-line continuation marks >
1252 one \
1253 two three \
1254 four five six \
1255 seven \\ \
1256 eight \nine \
1257 ten \
1258 <
1259 Becomes: >
1260 one \
1261 two three \
1262 four five six \
1263 seven \\ \
1264 eight \nine \
1265 ten \
1266 <
1267
1268 ---------------------------
1269 Alignment Map Examples: \t= *alignmap-t=* {{{3
1270 ---------------------------
1271
1272 Original: illustrates left-justified aligning of = >
1273 aa=bb=cc=1;/*one*/
1274 a=b=c=1;/*two*/
1275 aaa=bbb=ccc=1;/*three*/
1276 <
1277 Becomes: Select the three equations, press \t= >
1278 aa = bb = cc = 1; /* one */
1279 a = b = c = 1; /* two */
1280 aaa = bbb = ccc = 1; /* three */
1281 <
1282
1283 ---------------------------
1284 Alignment Map Examples: \T= *alignmap-T=* {{{3
1285 ---------------------------
1286
1287 Original: illustrates right-justified aligning of = >
1288 aa=bb=cc=1; /* one */
1289 a=b=c=1; /* two */
1290 aaa=bbb=ccc=1; /* three */
1291 <
1292 Becomes: Select the three equations, press \T= >
1293 aa = bb = cc = 1; /* one */
1294 a = b = c = 1; /* two */
1295 aaa = bbb = ccc = 1; /* three */
1296 <
1297
1298 ---------------------------
1299 Alignment Map Examples: \Htd *alignmap-Htd* {{{3
1300 ---------------------------
1301
1302 Original: for aligning tables with html >
1303 <TR><TD>...field one...</TD><TD>...field two...</TD></TR>
1304 <TR><TD>...field three...</TD><TD>...field four...</TD></TR>
1305 <
1306 Becomes: Select <TR>... lines, press \Htd >
1307 <TR><TD> ...field one... </TD><TD> ...field two... </TD></TR>
1308 <TR><TD> ...field three... </TD><TD> ...field four... </TD></TR>
1309 <
1310 ==============================================================================
1311 4. Alignment Tools' History *align-history* {{{1
1312
1313 ALIGN HISTORY {{{2
1314 35 : Nov 02, 2008 * g:loaded_AlignPlugin testing to prevent re-loading
1315 installed
1316 Nov 19, 2008 * new sanity check for an AlignStyle of just ":"
1317 Jan 08, 2009 * save&restore of |'mod'| now done with local
1318 variant
1319 34 : Jul 08, 2008 * using :AlignCtrl before entering any alignment
1320 control commands was causing an error.
1321 33 : Sep 20, 2007 * s:Strlen() introduced to support various ways
1322 used to represent characters and their effects
1323 on string lengths. See |align-strlen|.
1324 * Align now accepts "..." -- so it can accept
1325 whitespace as separators.
1326 32 : Aug 18, 2007 * uses |<q-args>| instead of |<f-args>| plus a
1327 custom argument splitter to allow patterns with
1328 backslashes to slide in unaltered.
1329 31 : Aug 06, 2007 * :[range]Align! [AlignCtrl settings] pattern(s)
1330 implemented.
1331 30 : Feb 12, 2007 * now uses |setline()|
1332 29 : Jan 18, 2006 * cecutil updated to use keepjumps
1333 Feb 23, 2006 * Align now converted to vim 7.0 style using
1334 auto-loading functions.
1335 28 : Aug 17, 2005 * report option workaround
1336 Oct 24, 2005 * AlignCtrl l: wasn't behaving as expected; fixed
1337 27 : Apr 15, 2005 : cpo workaround
1338 ignorecase workaround
1339 26 : Aug 20, 2004 : loaded_align now also indicates version number
1340 GetLatestVimScripts :AutoInstall: now supported
1341 25 : Jul 27, 2004 : For debugging, uses Dfunc(), Dret(), and Decho()
1342 24 : Mar 03, 2004 : (should've done this earlier!) visualmode(1)
1343 not supported until v6.2, now Align will avoid
1344 calling it for earlier versions. Visualmode
1345 clearing won't take place then, of course.
1346 23 : Oct 07, 2003 : Included Leif Wickland's ReplaceQuotedSpaces()
1347 function which supports \tsq
1348 22 : Jan 29, 2003 : Now requires 6.1.308 or later to clear visualmode()
1349 21 : Jan 10, 2003 : BugFix: similar problem to #19; new code
1350 bypasses "norm! v\<Esc>" until initialization
1351 is over.
1352 20 : Dec 30, 2002 : BugFix: more on "unable to highlight" fixed
1353 19 : Nov 21, 2002 : BugFix: some terminals gave an "unable to highlight"
1354 message at startup; Hari Krishna Dara tracked it
1355 down; a silent! now included to prevent noise.
1356 18 : Nov 04, 2002 : BugFix: re-enabled anti-repeated-loading
1357 17 : Nov 04, 2002 : BugFix: forgot to have AlignPush() push s:AlignSep
1358 AlignCtrl now clears visual-block mode when used so
1359 that Align won't try to use old visual-block
1360 selection marks '< '>
1361 16 : Sep 18, 2002 : AlignCtrl <>| options implemented (separator
1362 justification)
1363 15 : Aug 22, 2002 : bug fix: AlignCtrl's ":" now acts as a modifier of
1364 the preceding alignment operator (lrc)
1365 14 : Aug 20, 2002 : bug fix: AlignCtrl default now keeps &ic unchanged
1366 bug fix: Align, on end-field, wasn't using correct
1367 alignop bug fix: Align, on end-field, was appending
1368 padding
1369 13 : Aug 19, 2002 : bug fix: zero-length g/v patterns are accepted
1370 bug fix: always skip blank lines
1371 bug fix: AlignCtrl default now also clears g and v
1372 patterns
1373 12 : Aug 16, 2002 : moved keep_ic above zero-length pattern checks
1374 added "AlignCtrl default"
1375 fixed bug with last field getting separator spaces
1376 at end line
1377 11 : Jul 08, 2002 : prevent separator patterns which match zero length
1378 -+: included as additional alignment/justification
1379 styles
1380 10 : Jun 26, 2002 : =~# used instead of =~ (for matching case)
1381 ignorecase option handled
1382 9 : Jun 25, 2002 : implemented cyclic padding
1383
1384 ALIGNMENT MAP HISTORY *alignmap-history* {{{2
1385 v41 Nov 02, 2008 * g:loaded_AlignMapsPlugin testing to prevent
1386 re-loading installed
1387 * AlignMaps now use 0x0f (ctrl-p) for special
1388 character substitutions (instead of 0xff).
1389 Seems to avoid some problems with having to
1390 use Strlen().
1391 * bug fixed with \ts,
1392 * new maps: \ts; \ts, \ts: \ts< \ts= \a(
1393 v40 Oct 21, 2008 * Modified AlignMaps so that its maps use <Plug>s
1394 and <script>s. \t@ and related maps have been
1395 changed to call StdAlign() instead. The
1396 WrapperStart function now takes an argument and
1397 handles being called via visual mode. The
1398 former nmaps and vmaps have thus been replaced
1399 with a simple map.
1400 Oct 24, 2008 * broke AlignMaps into a plugin and autoload
1401 pair of scripts.
1402 v39 Mar 06, 2008 : * \t= only does /* ... */ aligning when in *.c
1403 *.cpp files.
1404 v38 Aug 18, 2007 : * \tt altered so that it works with the new
1405 use of |<q-args>| plus a custom argument
1406 splitter
1407 v36 Sep 27, 2006 : * AlignWrapperStart() now has tests that marks
1408 y and z are not set
1409 May 15, 2007 * \anum and variants improved
1410 v35 Sep 01, 2006 : * \t= and cousins used "`"s. They now use \xff
1411 characters.
1412 * \acom now works with doxygen style /// comments
1413 * <char-0xff> used in \t= \T= \w= and \m= instead
1414 of backquotes.
1415 v34 Feb 23, 2006 : * AlignMaps now converted to vim 7.0 style using
1416 auto-loading functions.
1417 v33 Oct 12, 2005 : * \ts, now uses P1 in its AlignCtrl call
1418 v32 Jun 28, 2005 : * s:WrapperStart() changed to AlignWrapperStart()
1419 s:WrapperEnd() changed to AlignWrapperEnd()
1420 These changes let the AlignWrapper...()s to be
1421 used outside of AlignMaps.vim
1422 v31 Feb 01, 2005 : * \adcom included, with help
1423 * \a, now works across multiple lines with
1424 different types
1425 * AlignMaps now uses <cecutil.vim> for its mark and
1426 window-position saving and restoration
1427 Mar 04, 2005 * improved \a,
1428 Apr 06, 2005 * included \aenum, \aunum, and provided
1429 g:alignmaps_{usa|euro]number} options
1430 v30 Aug 20, 2004 : * \a, : handles embedded assignments and does \adec
1431 * \acom now can handle Doxygen-style comments
1432 * g:loaded_alignmaps now also indicates version
1433 * internal maps \WE and \WS are now re-entrant
1434 v29 Jul 27, 2004 : * \tml aligns trailing multi-line single
1435 backslashes (thanks to Raul Benavente!)
1436 v28 May 13, 2004 : * \a, had problems with leading blanks; fixed!
1437 v27 Mar 31, 2004 : * \T= was having problems with == and !=
1438 * Fixed more problems with \adec
1439 v26 Dec 09, 2003 : * \ascom now also ignores lines without comments
1440 * \tt \& now not matched
1441 * \a< handles both << and >>
1442 v25 Nov 14, 2003 : * included \anum (aligns numbers with periods and
1443 commas). \anum also supported with ctrl-v mode.
1444 * \ts, \Ts, : (aligns on commas, then swaps leading
1445 spaces with commas)
1446 * \adec ignores preprocessor lines and lines with
1447 with comments-only
1448 v23 Sep 10, 2003 : * Bugfix for \afnc - no longer overwrites marks y,z
1449 * fixed bug in \tsp, \tab, \Tsp, and \Tab - lines
1450 containing backslashes were having their
1451 backslashes removed. Included Leif Wickland's
1452 patch for \tsq.
1453 * \adef now ignores lines holding comments only
1454 v18 Aug 22, 2003 : \a< lines up C++'s << operators
1455 saves/restores gdefault option (sets to nogd)
1456 all b:..varname.. are now b:alignmaps_..varname..
1457 v17 Nov 04, 2002 : \afnc now handles // comments correctly and
1458 commas within comments
1459 v16 Sep 10, 2002 : changed : to :silent! for \adec
1460 v15 Aug 27, 2002 : removed some <c-v>s
1461 v14 Aug 20, 2002 : \WS, \WE mostly moved to functions, marks y and z
1462 now restored
1463 v11 Jul 08, 2002 : \abox bug fix
1464 v9 Jun 25, 2002 : \abox now handles leading initial whitespace
1465 : various bugfixes to \afnc, \T=, etc
1466
1467 ==============================================================================
1468 Modelines: {{{1
1469 vim:tw=78:ts=8:ft=help:fdm=marker: