align.txt The Alignment Tool Oct 21, 2016
Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2016 by Charles E. Campbell Align-copyright
The VIM LICENSE applies to Align.vim, AlignMaps.vim, and Align.txt
(see copyright) except use "Align and AlignMaps" instead of "Vim"
NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
==============================================================================
1. Contents align align-contents {{{1
1. Contents.................: align-contents
2. Alignment Manual.........: align-manual
3. Alignment Usage..........: align-usage
Alignment Concepts.......: align-concepts
Alignment Commands.......: align-commands
Alignment Control........: align-control
Separators.............: alignctrl-separators
Initial Whitespace.....: alignctrl-w alignctrl-W alignctrl-I
Justification..........: alignctrl-l alignctrl-r alignctrl-c
Justification Control..: alignctrl-- alignctrl-+ alignctrl-:
Cyclic/Sequential......: alignctrl-= alignctrl-C
Separator Justification: alignctrl-< alignctrl-> alignctrl-
Line (de)Selection.....: alignctrl-g alignctrl-v
Temporary Settings.....: alignctrl-m
Padding................: alignctrl-p alignctrl-P
Current Options........: alignctrl-settings alignctrl-
Alignment Control Init...: alignctrl-init
Alignment................: align-align
4. Alignment Maps...........: align-maps
\a,....................: alignmap-a,
\a?....................: alignmap-a?
\a<....................: alignmap-a<
\abox..................: alignmap-abox
\acom..................: alignmap-acom
\anum..................: alignmap-anum
\ascom.................: alignmap-ascom
\adec..................: alignmap-adec
\adef..................: alignmap-adef
\afnc..................: alignmap-afnc
\adcom.................: alignmap-adcom
\aocom.................: alignmap-aocom
\tbar..................: alignmap-tbar
\tsp...................: alignmap-tsp
\tsq...................: alignmap-tsq
\tt....................: alignmap-tt
\t=....................: alignmap-t=
\T=....................: alignmap-T=
\Tbar..................: alignmap-Tbar
\Htd...................: alignmap-Htd
5. Alignment Tool History...: align-history
==============================================================================
2. Align Manual alignman alignmanual align-manual {{{1
Align comes as a vimball; simply typing
should put its components where they belong. The components are:
To see a user's guide, see align-userguide
To see examples, see alignctrl and alignmaps
/=============+=========+=====================================================\
|| \ Default/ ||
|| Commands \ Value/ Explanation ||
|| | | ||
+====+=======================================================++
|| AlignCtrl | | =Clrc-+:pPIWw [..list-of-separator-patterns..] ||
|| | +-------------------------------------------------------+|
|| | | may be called as a command or as a function: ||
|| | | :AlignCtrl =lp0P0W & \\ ||
|| | | :call Align#AlignCtrl('=lp0P0W','&','\\') ||
|| | | ||
|| | +-------------------------------------------------------++
|| 1st arg | = | = all separator patterns are equivalent and are ||
|| | | simultaneously active. Patterns are regexp. ||
|| | | C cycle through separator patterns. Patterns are ||
|| | | regexp and are active sequentially. ||
|| | | ||
|| | < | < left justify separator Separators are justified, ||
|| | | > right justify separator too. Separator styles ||
|| | | | center separator are cyclic. ||
|| | | ||
|| | l | l left justify Justification styles are always ||
|| | | r right justify cyclic (ie. lrc would mean left j., ||
|| | | c center then right j., then center, repeat. ||
|| | | - skip this separator ||
|| | | + re-use last justification method ||
|| | | : treat rest of text as a field ||
|| | | * use AlignSkip() function (to skip or not) ||
|| | | ||
|| | p1 | p### pad separator on left by # blanks ||
|| | P1 | P### pad separator on right by # blanks ||
|| | | ||
|| | I | I preserve and apply first line's leading white ||
|| | | space to all lines ||
|| | | W preserve leading white space on every line, even ||
|| | | if it varies from line to line ||
|| | | w don't preserve leading white space ||
|| | | ||
|| | | g second argument is a selection pattern -- only ||
|| | | align on lines that have a match (inspired by ||
|| | | :g/selection pattern/command) ||
|| | | v second argument is a selection pattern -- only ||
|| | | align on lines that _don't_ have a match (inspired ||
|| | | by :v/selection pattern/command) ||
|| | | ||
|| | | m Map support: AlignCtrl will immediately do an ||
|| | | AlignPush() and the next call to Align() will do ||
|| | | an AlignPop at the end. This feature allows maps ||
|| | | to preserve user settings. ||
|| | | ||
|| | | default ||
|| | | AlignCtrl default ||
|| | | will clear the AlignCtrl ||
|| | | stack & set the default: AlignCtrl "Ilp1P1=" '=' ||
|| | | ||
|| +----+-------------------------------------------------------+|
|| More args | More arguments are interpreted as describing separators ||
|| +------------------------------------------------------------+|
|| No args | AlignCtrl will display its current settings ||
||==============+============================================================+|
||[range]Align | [..list-of-separators..] ||
||[range]Align! | [AlignCtrl settings] [..list-of-separators..] ||
|| +------------------------------------------------------------+|
|| | Aligns text over the given range. The range may be ||
|| | selected via visual mode (v, V, or ctrl-v) or via ||
|| | the command line. The Align operation may be invoked ||
|| | as a command or as a function; as a function, the first ||
|| | argument is 0=separators only, 1=AlignCtrl option string ||
|| | followed by a list of separators. ||
|| | :[range]Align ||
|| | :[range]Align [list of separators] ||
|| | :[range]call Align#Align(0) ||
|| | :[range]call Align#Align(0,"list","of","separators",...) ||
\=============================================================================/
==============================================================================
3. Alignment Usage alignusage align-usage align-userguide {{{1
ALIGNMENT CONCEPTS align-concept align-concepts alignctrl {{{1
The typical text to be aligned is considered to be:
* composed of two or more fields
* separated by one or more separator pattern(s):
* two or more lines
where "ws" stands for "white space" such as blanks and/or tabs,
and "fields" are arbitrary text.
For example, consider
Assume that it is desired to line up all the "=" signs; these, then,
are the separators, and all else are fields. The fields are composed
of all the alphameric text. Assuming they lie on lines 1-4, one may
align those "=" signs with:
Actually, the :AlignCtrl l wasn't necessary, because its in the default
alignment control setting.
The result is:
Note how each "=" sign is surrounded by a single space; the
default padding is p1P1 (p1 means one space before the separator,
and P1 means one space after it). If you wish to change the
padding, say, to no padding, use (see alignctrl-p)
Next, note how each field is left justified; that's what the "l"
in the AlignCtrl parameters does (a small letter "ell"). If
right-justification of the fields had been desired, an "r"
could have been used:
yielding
There are many more options available for field justification: see
alignctrl-c and alignctrl--.
Separators, although commonly only one character long, are actually
specified by regular expressions (see regexp), and one may left
justify, right justify, or center them, too (see alignctrl-<).
Assume that for some reason a left-right-left-right-... justification
sequence was desired. This wish is simply achieved with
because the justification commands are considered to be "cyclic"; ie.
lr is the same as lrlrlrlrlrlrlr...
There's a lot more discussed under alignctrl; hopefully the examples
there will help, too.
ALIGNMENT COMMANDS align-command align-commands {{{2
The <Align.vim> script includes two primary commands and two
minor commands:
AlignCtrl : this command/function sets up alignment options
which persist until changed for later Align calls.
It controls such things as: how to specify field
separators, initial white space, padding about
separators, left/right/center justification, etc.
Align : this command/function operates on the range given it to
align text based on one or more separator patterns. The
patterns may be provided via AlignCtrl or via Align
itself.
The :Align! format permits alignment control commands
to precede the alignment patterns.
This will align all "=" in the file with two padding
spaces on both sides of each "=" sign.
NOTE ON USING PATTERNS WITH ALIGN:
Align and AlignCtrl use <q-args> to obtain their
input patterns and they use an internal function to
split arguments at whitespace unless inside "..."s.
One may escape characters inside a double-quote string
by preceding such characters with a backslash.
AlignPush : this command/function pushes the current AlignCtrl
state onto an internal stack.
AlignPop : this command/function pops the current AlignCtrl
state from an internal stack.
Also see alignctrl-m for a way to automatically do
an AlignPop after an Align (primarily this is for maps).
ALIGNMENT OPTIONS align-option align-options align-xstrlen {{{2
align-utf8 align-utf align-codepoint align-strlen align-multibyte
For those of you who are using 2-byte (or more) characters such as are
available with utf-8, Align now provides a special option which you
may choose based upon your needs:
Use Built-in strlen()
This is the fastest method, but it doesn't handle multibyte characters
well. It is the default for:
enc=latin1
vim compiled without multi-byte support
$LANG is en_US.UTF-8 (assuming USA english)
Number of codepoints (Latin a + combining circumflex are two codepoints)
Number of spacing codepoints (Latin a + combining circumflex is one
spacing codepoint; a hard tab is one; wide and narrow CJK are one
each; etc.)
Virtual length (counting, for instance, tabs as anything between 1 and
'tabstop', wide CJK as 2 rather than 1, Arabic alif as zero when
immediately preceded by lam, one otherwise, etc.)
User may specify a function to compute the string length
This method will cause Align to call upon the named function returning
string length. it should resemble the strlen() function, taking one
argument (the string) for input and returning the string length.
By putting one of these settings into your <.vimrc>, Align will use an
internal (interpreted) function to determine a string's length instead
of Vim's built-in strlen() function. Since the function is
interpreted, Align will run a bit slower but will handle such strings
correctly. The last settings (g:Align_xstrlen= 3 and
g:Align_xstrlen="userfuncname") probably will run the slowest but be
the most accurate. (thanks to Tony Mechelynck for these)
ALIGNMENT CONTROL :AlignCtrl align-control {{{2
This command doesn't do the alignment operation itself; instead, it
controls subsequent alignment operation(s).
The first argument to AlignCtrl is a string which may contain one or
more alignment control settings. Most of the settings are specified
by single letters; the exceptions are the p# and P# commands which
interpret a digit following the p or P as specifying padding about the
separator.
The typical text line is considered to be composed of two or more
fields separated by one or more separator pattern(s):
where "ws" stands for "white space" such as blanks and/or tabs.
SEPARATORS alignctrl-separators {{{3
As a result, separators may not have white space (tabs or blanks) on
their outsides (ie. ": :" is fine as a separator, but " :: " is
not). Usually such separators are not needed, although a map has been
provided which works around this limitation and aligns on whitespace
(see alignmap-tsp).
However, if you really need to have separators with leading or
trailing whitespace, consider handling them by performing a substitute
first (ie. s/ :: /@/g), do the alignment on the temporary pattern
(ie. @), and then perform a substitute to revert the separators back
to their desired condition (ie. s/@/ :: /g).
The Align#Align() function (the function that is invoked by the :Align
command) will first convert tabs over the region into spaces and then
apply alignment control. Except for initial white space, white space
surrounding the fields is ignored. One has three options just for
handling initial white space:
--- alignctrl-w
wWI INITIAL WHITE SPACE alignctrl-W {{{3
--- alignctrl-I
w : ignore all selected lines' initial white space
W : retain all selected lines' initial white space
I : retain only the first line's initial white space and
re-use it for subsequent lines
Example: Leading white space options:
The original has at least one leading white space on every line.
Using Align with w eliminated each line's leading white space.
Using Align with W preserved each line's leading white space.
Using Align with I applied the first line's leading white space
(three spaces) to each line.
------ alignctrl-l
lrc-+: FIELD JUSTIFICATION alignctrl-r {{{3
------ alignctrl-c
With "lrc", the fields will be left-justified, right-justified, or
centered as indicated by the justification specifiers (lrc). The
"lrc" options are re-used by cycling through them as needed:
l means llllll....
r means rrrrrr....
lr means lrlrlr....
llr means llrllr....
Example: Justification options: Align =
AlignCtrl l : The = separator is repeatedly re-used, as the
cycle only consists of one character (the "l").
Every time left-justification is used for fields.
AlignCtrl r : The = separator is repeatedly re-used, as the
cycle only consists of one character (the "r").
Every time right-justification is used for fields
AlignCtrl lr: Again, the "=" separator is repeatedly re-used,
but the fields are justified alternately between
left and right.
Even more separator control is available! With "-+:":
- : skip treating the separator as a separator. alignctrl--
+ : repeat use of the last "lrc" justification alignctrl-+
: : treat the rest of the line as a single field alignctrl-:
* : like -, but only if g:AlignSkip() returns true alignctrl-star
(see alignctrl-alignskip)
Example: More justification options: Align =
In the first example in "More justification options":
The first "=" separator is skipped by the "-" specification,
and so "a=bb", "ccc=a", and "dd=eee" are considered as single fields.
The next "=" separator has its (left side) field left-justified.
Due to the cyclic nature of separator patterns, the "-l"
specification is equivalent to "-l-l-l ...".
Hence the next specification is a "skip", so "ccc=1", etc are fields.
In the second example in "More justification options":
The first field is right-justified, the second field is left
justified, and all remaining fields repeat the last justification
command (ie. they are left justified, too).
Hence rl+ is equivalent to rlllllllll ...
(whereas plain rl is equivalent to rlrlrlrlrl ... ).
In the third example in "More justification options":
The text following the first separator is treated as a single field.
Thus using the - and : operators one can apply justification to a
single separator.
ex. 1st separator only: AlignCtrl l:
2nd separator only: AlignCtrl -l:
3rd separator only: AlignCtrl --l:
etc.
g:AlignSkip
Align Skip Control alignctrl-alignskip
The separator control '*' permits a function to decide whether or
not a character which matches the current separator pattern should
instead be skipped.
1. Define a function; example:
Input: lineno: current line number
indx : index to character; leftmost character
in the line has an indx of 0 (like strpart())
Output: 0 : if separator is ok
1 : skip separator like it was a '-'
2. Set up g:AlignSkip as a function reference (see Funcref):
3. Use * as a separator control where a separator potentially should
be skipped over.
--- alignctrl-=
=C CYCLIC VS ALL-ACTIVE SEPARATORS alignctrl-C {{{3
---
The separators themselves may be considered as equivalent and
simultaneously active ("=") or sequentially cycled through ("C").
Separators are regular expressions (regexp) and are specified as the
second, third, etc arguments. When the separator patterns are
equivalent and simultaneously active, there will be one pattern
constructed:
becomes
(ie. pat1 -or- pat2 -or- pat3; see /bar)
Each separator pattern is thus equivalent and simultaneously active.
The cyclic separator AlignCtrl option stores a list of patterns, only
one of which is active for each field at a time.
Example: Equivalent/Simultaneously-Active vs Cyclic Separators
The original is initially aligned with all operators (=+-) being
considered as equivalent and simultaneously active field separators.
Thus the "AlignCtrl = = + -" example shows no change.
The second example only accepts the '=' as a field separator;
consequently "b + c - d" is now a single field.
The third example illustrates cyclic field separators and is analyzed
in the following illustration:
The word "cyclic" is used because the patterns form a cycle of use; in
the above case, its = + - = + - = + - = + -...
Example: Cyclic separators
apply AlignCtrl lWC : | |
(select lines)Align
In the current example,
: is the first separator So the first ":"s are aligned
| is the second separator but subsequent ":"s are not.
| is the third separator The "|"s are aligned, too.
: is the fourth separator Since there aren't two bars,
| is the fifth separator the subsequent potential cycles
| is the sixth separator don't appear.
...
In this case it would probably have been a better idea to have used
as that alignment control would guarantee that no more cycling
would be used after the vertical bar.
Example: Cyclic separators
Original:
AlignCtrl C | | & -
In this example,
the first and second separators are "|",
the third separator is "&", and
the fourth separator is "-",
(cycling)
the fifth and sixth separators are "|",
the seventh separator is "&", and
the eighth separator is "-", etc.
Thus the first "&"s are (not yet) separators, and hence are treated as
part of the field. Ignoring white space for the moment, the AlignCtrl
shown here means that Align will work with
--- alignctrl-<
<>| SEPARATOR JUSTIFICATION alignctrl-> {{{3
--- alignctrl-|
Separators may be of differing lengths as shown in the example below.
Hence they too may be justified left, right, or centered.
Furthermore, separator justification specifications are cyclic:
< means <<<<<... justify separator(s) to the left
> means >>>>>... justify separator(s) to the right
| means |||||... center separator(s)
Example: Separator Justification: Align -\+
--- alignctrl-g
gv SELECTIVE APPLICATION alignctrl-v {{{3
---
These two options provide a way to select (g) or to deselect (v) lines
based on a pattern. Ideally :g/pat/Align would work; unfortunately
it results in Align#Align() being called on each line satisfying the
pattern separately.
Align will only consider those lines which have the given pattern.
Align will only consider those lines without the given pattern. As an
example of use, consider the following example:
The first "Align =" aligned with all "="s, including the one in the
"/* skip=this */" comment.
The second "Align =" had a AlignCtrl v-pattern which caused it to skip
(ignore) the "/* skip=this */" line when aligning.
To remove AlignCtrl's g and v patterns, use (as appropriate)
To see what g/v patterns are currently active, just use the reporting
capability of an unadorned call to AlignCtrl:
---
m MAP SUPPORT alignctrl-m {{{3
---
This option primarily supports the development of maps. The
Align#AlignCtrl() call will first do an Align#AlignPush() (ie. retain
current alignment control settings). The next Align#Align() will, in
addition to its alignment job, finish up with an Align#AlignPop().
Thus the Align#AlignCtrl settings that follow the "m" are only
temporarily in effect for just the next Align#Align().
---
p### alignctrl-p
P### PADDING alignctrl-P {{{3
---
These two options control pre-padding and post-padding with blanks
about the separator. One may pad separators with zero to nine spaces;
the padding number(s) is/are treated as a cyclic parameter. Thus one
may specify padding separately for each field or re-use a padding
pattern.
This example will cause Align to:
pre-pad the first "=" with a single blank,
pre-pad the second "=" with no blanks,
pre-pad the third "=" with two blanks,
pre-pad the fourth "=" with a single blank,
pre-pad the fifth "=" with no blanks,
pre-pad the sixth "=" with two blanks,
etc.
--------------- alignctrl-settings
No option given DISPLAY STATUS alignctrl- {{{3
--------------- alignctrl-no-option
AlignCtrl, when called with no arguments, will display the current
alignment control settings. A typical display is shown below:
Interpreting, this means that the separator patterns are all
equivalent; in this case, there's only one (qty=1). Fields will be
padded on the right with spaces (left justification), and separators
will be padded on each side with a single space.
To change one of these items, see:
AlignCtrl......alignctrl
qty............align-concept
AlignStyle.....alignctrl-- alignctrl-+ alignctrl-: alignctrl-c
Padding........alignctrl-p alignctrl-P
One may get a string which can be fed back into AlignCtrl:
This form will put a string describing the current AlignCtrl options,
except for the "g" and "v" patterns, into a variable. The
Align#AlignCtrl() function will still echo its settings, however. One
can feed any non-supported "option" to AlignCtrl() to prevent this,
however:
ALIGNMENT CONTROL INITIALIZATION alignctrl-init alignctrl-initialization {{{2
If you'd like to have your own default AlignCtrl, you'll be wanting to
put it in a file such as:
Anything in that file would be sourced at startup, but after your
.vimrc and after $HOME/.vim/plugin/AlignPlugin.vim; hence, :Align
and :AlignCtrl will then be defined.
ALIGNMENT :Align align-align {{{2
Once the alignment control has been determined, the user specifies a
range of lines for the Align command/function to do its thing.
Alignment is often done on a line-range basis, but one may also
restrict alignment to a visual block using ctrl-v. For any visual
mode, one types the colon (:) and then "Align". One may, of course,
specify a range of lines:
where the :range is the usual Vim-powered set of possibilities; the
list of separators is the same as the AlignCtrl capability. There is
only one list of separators, but either AlignCtrl or Align can be used
to specify that list.
An alternative form of the Align command can handle both alignment
control and the separator list:
The alignment control string will be applied only for this particular
application of Align (it uses alignctrl-m). The "g pattern" and
"v pattern" alignment controls (see alignctrl-g and alignctrl-v)
are also available via this form of the Align command.
Align makes two passes over the text to be aligned. The first pass
determines how many fields there are and determines the maximum sizes
of each field; these sizes are then stored in a vector. The second
pass pads the field (left/right/centered as specified) to bring its
length up to the maximum size of the field. Then the separator and
its AlignCtrl-specified padding is appended.
Pseudo-Code:
During pass 1
| For all fields in the current line
|| Determine current separator
|| Examine field specified by current separator
|| Determine length of field and save if largest thus far
Initialize newline based on initial whitespace option (wWI)
During pass 2
| For all fields in current line
|| Determine current separator
|| Extract field specified by current separator
|| Prepend/append padding as specified by AlignCtrl
|| (right/left/center)-justify to fit field into max-size field
|| Append separator with AlignCtrl-specified separator padding
|| Delete current line, install newly aligned line
The g and v AlignCtrl patterns cause the passes not to consider lines
for alignment, either by requiring that the g-pattern be present or
that the v-pattern not be present.
The whitespace on either side of a separator is ignored.
==============================================================================
4. Alignment Maps alignmaps align-maps {{{1
There are a number of maps provided in the AlignMaps plugin which
depend upon the Align plugin. The maps provided by AlignMaps
typically start with a leading "t" (for the older "textab" program
which Align supercedes) or with an "a" for the more complicated
alignment maps.
The AlignMaps plugin, although provided in the vimball containing
Align.vim, is really a separate plugin (Align doesn't depend on
AlignMaps). Consequently, if you'd rather not have AlignMaps's
mappings, just use the :AlignMapsClean command to remove its
components. The :AlignMapsClean command does not remove any maps
generated by AlignMaps in the current instance of vim.
The maps are shown below with a leading backslash (\). However, the
actual maps use the <Leader> construct (see mapleader), so the maps'
leading kick-off character is easily customized.
Furthermore, all the maps specified by the AlignMaps plugin use the
<Plug> construct (see <Plug>and usr_41.txt). Hence, if one wishes
to override the mapping(s) entirely, one may do that, too. As an
example:
would have \ACOM do
what \acom previously did (assuming that the mapleader has been left
at its default value of a backslash).
\a, : useful for breaking up comma-separated
declarations prior to \adec alignmap-a,
\a( : aligns ( and , (useful for prototypes) alignmap-a(
\a? : aligns (...)? ...:... expressions on ? and : alignmap-a?
\a< : aligns << and >> for c alignmap-a<
\a= : aligns := assignments alignmap-a=
\abox : draw a C-style comment box around text lines alignmap-abox
\acom : useful for aligning comments alignmap-acom
\adcom: useful for aligning comments in declarations alignmap-adcom
\anum : useful for aligning numbers alignmap-anum
NOTE: For the visual-mode use of \anum, <vis.vim> is needed!
See http://www.drchip.org/astronaut/vim/index.html#VIS
\aenum: align a European-style number alignmap-aenum
\aunum: align a USA-style number alignmap-anum
\adec : useful for aligning declarations alignmap-adec
\adef : useful for aligning definitions alignmap-adef
\afnc : useful for aligning ansi-c style functions'
argument lists alignmap-afnc
\adcom: a variant of \acom, restricted to comment alignmap-adcom
containing lines only, but also only for
those which don't begin with a comment.
Good for certain declaration styles.
\aocom: a variant of \acom, restricted to comment alignmap-aocom
containing lines only
\tab : align a table based on tabs alignmap-tab
(converts to spaces)
\tml : useful for aligning the trailing backslashes alignmap-tml
used to continue lines (shell programming, etc)
\tbar : useful for aligning |s alignmap-tbar
\tsp : use Align to make a table separated by blanks alignmap-tsp
(left justified)
\ts, : like \t, but swaps whitespace on the right of alignmap-ts,
the commas to their left
\ts: : like \t: but swaps whitespace on the right of alignmap-ts:
the colons to their left
\ts< : like \t< but swaps whitespace on the right of alignmap-ts<
the less-than signs to their left
\ts= : like \t= but swaps whitespace on the right of alignmap-ts=
the equals signs to their left
\Tsp : use Align to make a table separated by blanks alignmap-Tsp
(right justified)
\tsq : use Align to make a table separated by blanks alignmap-tsq
(left justified) -- "strings" are not split up
\tt : useful for aligning LaTeX tabular tables alignmap-tt
\Htd : tabularizes html tables: alignmap-Htd
<TR><TD> ...field... </TD><TD> ...field... </TD></TR>
alignmap-t| alignmap-t# alignmap-t, alignmap-t:
alignmap-t; alignmap-t< alignmap-t? alignmap-t~
alignmap-m=
\tx : make a left-justified alignment on
character "x" where "x" is: ,:<=@|# alignmap-t=
\Tbar : useful for aligning |s alignmap-Tbar
\Tx : make a right-justified alignment on
character "x" where "x" is: ,:<=@# alignmap-T=
\m= : like \t= but aligns with %... style comments
The leading backslash is actually <leader> (see mapleader to learn
how to customize the leader to be whatever you like). These maps use
the <Align.vim> package and are defined in the <AlignMaps.vim> file.
Although the maps use AlignCtrl options, they typically use the "m"
option which pushes the options (AlignPush). The associated Align
call which follows will then AlignPop the user's original options
back.
ALIGNMENT MAP USE WITH MARK AND MOVE
In the examples below, one may select the text with a "ma" at the
first line, move to the last line, then execute the map.
ALIGNMENT MAP USE WITH VISUAL MODE
Alternatively, one may select the text with the "V" visual mode
command.
If you want to use visual-block mode (ctrl-v), I suggest using
an AlignMap with the vis.vim plugin, available at either
stable: http://vim.sourceforge.net/scripts/script.php?script_id=1195
devel : http://www.drchip.org/astronaut/vim/index.html#VIS
Use it with commands such as
ALIGNMENT MAP USE WITH MENUS
One may use the mark-and-move style (ma, move, use the menu) or
the visual mode style (use the V visual mode, move, then select
the alignment map with menu selection). The alignment map menu
items are under DrChip.AlignMaps .
One may even change the top level menu name to whatever is wished; by
default, its
If you set the variable to the empty string (""), then no menu items
will be produced. Of course, one must have a vim with +menu, the gui
must be running, and 'go' must have the menu bar suboption (ie. m
must be included).
COMPLEX ALIGNMENT MAP METHOD
For those complex alignment maps which do alignment on constructs
(e.g. \acom, \adec, etc), a series of substitutes is used to insert
"@" symbols in appropriate locations. Align#Align() is then used to
do alignment directly on "@"s; then it is followed by further
substitutes to do clean-up. However, the maps \WS and \WE, used by
every map supported by AlignMaps, protect any original embedded "@"
symbols by first converting them to <DEL> characters, doing the
requested job, and then converting them back.
---------------------------
Alignment Map Examples: \a, alignmap-a, {{{3
---------------------------
Original: illustrates comma-separated declaration splitting:
Becomes:
---------------------------
Alignment Map Examples: \a? alignmap-a? {{{3
---------------------------
Original: illustrates ()?: aligning
Becomes: select "(x == ..." lines, then \a?
---------------------------
Alignment Map Examples: \a< alignmap-a< {{{3
---------------------------
Original: illustrating aligning of << and >>
Becomes: select "(x == ..." lines, then \a<
---------------------------
Alignment Map Examples: \a= alignmap-a= {{{3
---------------------------
Original: illustrates how to align := assignments
Bcomes: select the three assignment lines, then \a:=
---------------------------
Alignment Map Examples: \abox alignmap-abox {{{3
---------------------------
Original: illustrates how to comment-box some text
Becomes: Select "This..box." with ctrl-v, press \abox
---------------------------
Alignment Map Examples: \acom alignmap-acom {{{3
---------------------------
Original: illustrates aligning C-style comments (works for //, too)
Becomes: Select the three lines, press \acom
Also see alignmap-aocom
--------------------------- alignmap-aenum
Alignment Map Examples: \anum alignmap-anum {{{3
---------------------------
First, note that the behavior of the \anum map depends on the existence
of either the vim variable
or
when AlignMaps is loaded. One may also use
or
to align numbers which include 1000s separators ("," for usa, "." for
euro). The latter two variable/settings don't cause AlignMaps to
insert 1000s separators; they simply cause AlignMaps to treat them the
same as digits.
Essentially, "usa" numbers use "."s and "euro" numbers use ","s to
separate the integer from the fractional portion of a number.
"Usa" numbers are default.
Original: illustrates how to get numbers lined up
Becomes: Go to first line, ma. Go to last line, press \anum
Original:
Becomes: Select the numbers with ctrl-v (visual-block mode),
Original:
Becomes: (assuming g:alignmaps_euronumber exists)
Go to first line, ma. Go to last line, press \anum
In addition:
\aenum is provided to support European-style numbers
\aunum is provided to support USA-style numbers
g:alignmaps_usanumber g:alignmaps_euronumber
One may get \aenum behavior for \anum by putting
or \aunum behavior for \anum by putting
in one's <.vimrc>.
g:alignmaps_usanumber1000 g:alignmaps_euronumber1000
Like g:alignmaps_usanumber and g:alignmaps_euronumber,
one may specify \aenum behavior for \anum by putting
or \aunum behavior for \anum by putting
in one's <.vimrc>.
In addition, these maps will permit usa: "," and euro: "." separators
as part of the numbers (ie. for usa: 1,002,003 for euro: 1.002.003).
---------------------------
Alignment Map Examples: \ascom alignmap-ascom {{{3
---------------------------
Original:
Becomes: Select the three lines, press \ascom
---------------------------
Alignment Map Examples: \adec alignmap-adec {{{3
---------------------------
Original: illustrates how to clean up C/C declarations
Becomes: Select the declarations text, then \adec
---------------------------
Alignment Map Examples: \adef alignmap-adef {{{3
---------------------------
Original: illustrates how to line up #def'initions
Becomes: Select four definition lines, apply \adef
---------------------------
Alignment Map Examples: \afnc alignmap-afnc {{{3
---------------------------
This map is an exception to the usual selection rules.
It uses "]]" to find the function body's leading "{".
Just put the cursor anywhere in the function arguments and
the entire function declaration should be processed.
Because "]]" looks for that "{" in the first column, the
"original" and "becomes" examples are in the first column,
too.
Original: illustrates lining up ansi-c style function definitions
Becomes: put cursor anywhere before the '{', press \afnc
---------------------------
Alignment Map Examples: \adcom alignmap-adcom {{{3
---------------------------
Original: illustrates aligning comments that don't begin
lines (optionally after some whitespace).
Becomes: Select the inside lines of the structure,
then press \adcom. The comment-only
line is ignored but the other two comments
get aligned.
---------------------------
Alignment Map Examples: \aocom alignmap-aocom {{{3
---------------------------
Original: illustrates how to align C-style comments (works for //, too)
but restricted only to aligning with those lines containing
comments. See the difference from \acom (alignmap-acom).
Becomes: Select the three lines, press \aocom
Also see alignmap-acom
--------------------------- alignmap-Tsp
Alignment Map Examples: \tsp alignmap-tsp {{{3
---------------------------
Normally Align can't use white spaces for field separators as such
characters are ignored surrounding field separators. The \tsp and
\Tsp maps get around this limitation.
Original:
Becomes: Select the lines, \tsp
Becomes: Select the lines, \Tsp
---------------------------
Alignment Map Examples: \tsq alignmap-tsq {{{3
---------------------------
The \tsp map is useful for aligning tables based on white space,
but sometimes one wants double-quoted strings to act as a single
object in spite of embedded spaces. The \tsq map was invented
to support this. (thanks to Leif Wickland)
Original:
Becomes: Select the lines, \tsq
---------------------------
Alignment Map Examples: \tt alignmap-tt {{{3
---------------------------
Original: illustrates aligning a LaTex Table
Becomes: Select the three lines inside the table
----------------------------
Alignment Map Examples: \tml alignmap-tml {{{3
----------------------------
Original: illustrates aligning multi-line continuation marks
Becomes:
---------------------------
Alignment Map Examples: \t= alignmap-t= {{{3
---------------------------
Original: illustrates left-justified aligning of =
Becomes: Select the three equations, press \t=
---------------------------
Alignment Map Examples: \T= alignmap-T= {{{3
---------------------------
Original: illustrates right-justified aligning of =
Becomes: Select the three equations, press \T=
---------------------------
Alignment Map Examples: \Htd alignmap-Htd {{{3
---------------------------
Original: for aligning tables with html
Becomes: Select <TR>... lines, press \Htd
==============================================================================
4. Alignment Tools' History align-history {{{1
ALIGN HISTORY {{{2
v40 Oct 21, 2016 * (Taylor Venable) 'paste', when set, saves a
number of options inside vim itself. When
'paste' is reset, those options are then
restored. Must set/reset paste with this
effect in mind.
(in particular, this affects Align's
sequence in temporarily setting and
restoring 'et' and 'paste')
v39 Sep 05, 2013 * strdisplaywidth() now used by default in
s:Strlen().
v38 Mar 18, 2013 * (Gary Johnson) pointed out that changing
cedit to <Esc> caused problems with visincr;
the cedit setting is now bypassed in Align, too.
v37 Nov 29, 2012 * (Kim Jang-hwan) reported that with g:Align_xstrlen
set to 3 that the cursor was moved (linewise)
after invocation. Fixed.
Jan 07, 2013 * now has visual mode mappings to accompany all
normal mode mappings (use V to invoke)
v36 May 20, 2009 * Previously, the "W" AlignCtrl setting, intended
to retain initial white space, did so by convert-
ing any leading tabs into an equivalent quantity
of blanks (using the current tabstop setting).
Align will now retain leading tabs.
Nov 24, 2009 * QArgSplitter() used split(), intending to split
on white space only. However, the \tab map
uses ctrl-o as a separator instead of tabs; the
split() function treated the ctrl-o as a whitespace
character, too. Solution: give split() an explicit
pattern matching blanks and tabs, only. \tab now
works again!
Jun 29, 2010 * included g:AlignSkip and alignctrl-star support
May 10, 2011 * if the range is only one line, then Align will
automatically grow the range to accommodate all
lines containing the first separator pattern
surrounding the current line.
Aug 05, 2011 * g:Align_xstrlen usage extended to permit users to
specify a function by name which computes string
length.
Oct 27, 2011 * (reported by Fco Javier) reported a problem with
the default s:Strlen() result; there was a missing
"let". Fixed.
Nov 10, 2011 * (Lewis Thompson) Align was doing "set noet" when
it should've been doing "setlocal noet".
Dec 22, 2011 * modifed s:Strlen() to use strdisplaywidth() when
g:Align_xstrlen is zero.
v35 Nov 02, 2008 * g:loaded_AlignPlugin testing to prevent re-loading
installed
Nov 19, 2008 * new sanity check for an AlignStyle of just ":"
Jan 08, 2009 * save&restore of 'mod' now done with local
variant
v34 Jul 08, 2008 * using :AlignCtrl before entering any alignment
control commands was causing an error.
v33 Sep 20, 2007 * s:Strlen() introduced to support various ways
used to represent characters and their effects
on string lengths. See align-strlen.
* Align now accepts "..." -- so it can accept
whitespace as separators.
v32 Aug 18, 2007 * uses <q-args> instead of <f-args> plus a
custom argument splitter to allow patterns with
backslashes to slide in unaltered.
v31 Aug 06, 2007 * :[range]Align! [AlignCtrl settings] pattern(s)
implemented.
v30 Feb 12, 2007 * now uses setline()
v29 Jan 18, 2006 * cecutil updated to use keepjumps
Feb 23, 2006 * Align now converted to vim 7.0 style using
auto-loading functions.
v28 Aug 17, 2005 * report option workaround
Oct 24, 2005 * AlignCtrl l: wasn't behaving as expected; fixed
v27 Apr 15, 2005 * cpo workaround
ignorecase workaround
v26 Aug 20, 2004 * loaded_align now also indicates version number
GetLatestVimScripts :AutoInstall: now supported
v25 Jul 27, 2004 * For debugging, uses Dfunc(), Dret(), and Decho()
v24 Mar 03, 2004 * (should've done this earlier!) visualmode(1)
not supported until v6.2, now Align will avoid
calling it for earlier versions. Visualmode
clearing won't take place then, of course.
v23 Oct 07, 2003 * Included Leif Wickland's ReplaceQuotedSpaces()
function which supports \tsq
v22 Jan 29, 2003 * Now requires 6.1.308 or later to clear visualmode()
v21 Jan 10, 2003 * BugFix: similar problem to #19; new code
bypasses "norm! v\<Esc>" until initialization
is over.
v20 Dec 30, 2002 * BugFix: more on "unable to highlight" fixed
v19 Nov 21, 2002 * BugFix: some terminals gave an "unable to highlight"
message at startup; Hari Krishna Dara tracked it
down; a silent! now included to prevent noise.
v18 Nov 04, 2002 * BugFix: re-enabled anti-repeated-loading
v17 Nov 04, 2002 * BugFix: forgot to have AlignPush() push s:AlignSep
AlignCtrl now clears visual-block mode when used so
that Align won't try to use old visual-block
selection marks '< '>
v16 Sep 18, 2002 * AlignCtrl <>| options implemented (separator
justification)
v15 Aug 22, 2002 * bug fix: AlignCtrl's ":" now acts as a modifier of
the preceding alignment operator (lrc)
v14 Aug 20, 2002 * bug fix: AlignCtrl default now keeps &ic unchanged
bug fix: Align, on end-field, wasn't using correct
alignop bug fix: Align, on end-field, was appending
padding
v13 Aug 19, 2002 * bug fix: zero-length g/v patterns are accepted
bug fix: always skip blank lines
bug fix: AlignCtrl default now also clears g and v
patterns
v12 Aug 16, 2002 * moved keep_ic above zero-length pattern checks
added "AlignCtrl default"
fixed bug with last field getting separator spaces
at end line
v11 Jul 08, 2002 * prevent separator patterns which match zero length
-+: included as additional alignment/justification
styles
v10 Jun 26, 2002 * =~# used instead of =~ (for matching case)
ignorecase option handled
v09 Jun 25, 2002 * implemented cyclic padding
ALIGNMENT MAP HISTORY alignmap-history {{{2
v44 Mar 30, 2013 * (Ethan Mallove) removed a duplicate mapping for
afnc (alignmap-afnc)
Jan 11, 2016 * having problems with \t| and \T|; couldn't
use the <Plug> notation to override these
maps. Now using \tbar and \Tbar instead.
Apr 11, 2016 * g:alignmaps_usanumber1000 and
g:alignmaps_euronumber1000 introduced
v43 Nov 28, 2012 * changed a lot of maps to use nnoremap (instead
of map)
Jan 07, 2013 *
v42 Jan 06, 2010 * new maps for \anum, \aenum, \aunum
Feb 16, 2010 * map for \t=, \T= now handles x = something;
for c, c correctly.
Oct 29, 2010 * added a note on having one's own default
AlignCtrl (see alignctrl-init)
Feb 22, 2011 * for menus, &go =~# used to insure correct case
Jun 10, 2011 * :AlignMapsClean command provided to make it
easy for those who would prefer not to have
AlignMaps' maps not to have them.
v41 Nov 02, 2008 * g:loaded_AlignMapsPlugin testing to prevent
re-loading installed
* AlignMaps now use 0x0f (ctrl-p) for special
character substitutions (instead of 0xff).
Seems to avoid some problems with having to
use Strlen().
* bug fixed with \ts,
* new maps: \ts; \ts, \ts: \ts< \ts= \a(
v40 Oct 21, 2008 * Modified AlignMaps so that its maps use <Plug>s
and <script>s. \t@ and related maps have been
changed to call StdAlign() instead. The
WrapperStart function now takes an argument and
handles being called via visual mode. The
former nmaps and vmaps have thus been replaced
with a simple map.
Oct 24, 2008 * broke AlignMaps into a plugin and autoload
pair of scripts.
v39 Mar 06, 2008 * \t= only does /* ... */ aligning when in *.c
*.cpp files.
v38 Aug 18, 2007 * \tt altered so that it works with the new
use of <q-args> plus a custom argument
splitter
v36 Sep 27, 2006 * AlignWrapperStart() now has tests that marks
y and z are not set
May 15, 2007 * \anum and variants improved
v35 Sep 01, 2006 * \t= and cousins used "`"s. They now use \xff
characters.
* \acom now works with doxygen style /// comments
* <char-0xff> used in \t= \T= \w= and \m= instead
of backquotes.
v34 Feb 23, 2006 * AlignMaps now converted to vim 7.0 style using
auto-loading functions.
v33 Oct 12, 2005 * \ts, now uses P1 in its AlignCtrl call
v32 Jun 28, 2005 * s:WrapperStart() changed to AlignWrapperStart()
s:WrapperEnd() changed to AlignWrapperEnd()
These changes let the AlignWrapper...()s to be
used outside of AlignMaps.vim
v31 Feb 01, 2005 * \adcom included, with help
* \a, now works across multiple lines with
different types
* AlignMaps now uses <cecutil.vim> for its mark and
window-position saving and restoration
Mar 04, 2005 * improved \a,
Apr 06, 2005 * included \aenum, \aunum, and provided
g:alignmaps_{usa|euro]number} options
v30 Aug 20, 2004 * * \a, : handles embedded assignments and does \adec
* \acom now can handle Doxygen-style comments
* g:loaded_alignmaps now also indicates version
* internal maps \WE and \WS are now re-entrant
v29 Jul 27, 2004 * \tml aligns trailing multi-line single
backslashes (thanks to Raul Benavente!)
v28 May 13, 2004 * \a, had problems with leading blanks; fixed!
v27 Mar 31, 2004 * \T= was having problems with == and !=
* Fixed more problems with \adec
v26 Dec 09, 2003 * \ascom now also ignores lines without comments
* \tt \& now not matched
* \a< handles both << and >>
v25 Nov 14, 2003 * included \anum (aligns numbers with periods and
commas). \anum also supported with ctrl-v mode.
* \ts, \Ts, : (aligns on commas, then swaps leading
spaces with commas)
* \adec ignores preprocessor lines and lines with
with comments-only
v23 Sep 10, 2003 * Bugfix for \afnc - no longer overwrites marks y,z
* fixed bug in \tsp, \tab, \Tsp, and \Tab - lines
containing backslashes were having their
backslashes removed. Included Leif Wickland's
patch for \tsq.
* \adef now ignores lines holding comments only
v18 Aug 22, 2003 * \a< lines up C's << operators
saves/restores gdefault option (sets to nogd)
all b:..varname.. are now b:alignmaps_..varname..
v17 Nov 04, 2002 * \afnc now handles // comments correctly and
commas within comments
v16 Sep 10, 2002 * changed : to :silent! for \adec
v15 Aug 27, 2002 * removed some <c-v>s
v14 Aug 20, 2002 * \WS, \WE mostly moved to functions, marks y and z
now restored
v11 Jul 08, 2002 * \abox bug fix
v9 Jun 25, 2002 * \abox now handles leading initial whitespace
various bugfixes to \afnc, \T=, etc
==============================================================================
Modelines: {{{1
vim:tw=78:ts=8:ft=help:fdm=marker: