# DrChip's Alignment Tool for Vim

 Top of Page Examples Align and AlignCtrl Details DrChip's Vim Stuff DrChip's Home

(please note that Align is not a margin justification tool; for that, see either vimscript#177 or vimscript#2324)

### What are Align and AlignMaps?

Align and AlignMaps are plugins for Vim. They're good for aligning fields of text; for example, text delimited by "|"s, aligning C-style declarations, etc. <Align.vim> holds the primary Align function; <AlignMaps.vim> contains map support for more complicated aligning.

### Got any Examples?

You may quickly get to some examples of what Align is capable of by looking at the examples section below.

### What tasks can Align help accomplish?

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
such as:
  ws field ws separator ws field ws separator ...
ws field ws separator ws field ws separator ...

where "ws" stands for "white space" such as blanks and/or tabs; fields are simply arbitrary text. For example, :[range]Align = will align the equals signs in the text over the given range.

### What tasks can AlignMaps help accomplish?

The <AlignMaps.vim> maps handle aligning on =, LaTeX tabulars, |, :, ,, declarations, definitions, comments, and html tables. Use the help for <AlignMaps.vim> the various maps therein or refer to the accompanying help file (:help alignmaps).

One may select lines using visual-selection mode and then the map sequence, or one may mark the first line with "ma" and then move to the last line, then use the AlignMaps mapping command you want to use.

### How do I get Align and AlignMaps?

Align and AlignMaps (and their help file) comes as a vimball; you can get it by clicking on Align.vba.gz. The vimball contains:
• plugin/AlignPlugin.vim contains commands
• plugin/AlignMapsPlugin.vim contains most of the maps
• plugin/cecutil.vim contains some support script
• doc/Align.txt contains help for Align and AlignMaps
• autoload/Align.vim contains the primary alignment functions
• autoload/AlignMaps.vim contains some support functions for the AlignMaps

### Tell me more about AlignMaps...

The maps in <AlignMaps.vim> are maps which utilize the Align() function provided by <Align.vim> to a specific character or provide more sophisticated alignment operations by using substitutes and Align(). The @ character is often used by the latter maps. <Align.txt> provides online help (typically after bringing up vim and typing ":helptags ~/.vim/doc"). For even more information on Align and AlignMaps, see their manual.

The plugins are also available at vimscript#294, although the most recent and up-to-date versions are available here.

There's a nice demonstration of Align that nhooey made here.

### How do I install Align and AlignMaps?

Align and AlignMaps come as a vimball; simply
• vim Align.vba.gz
• :so %
• :q

### How may I Align as I Type?

Frequently people want to align "="s as they type. For that, you'll need the Align/AlignMaps plugin and one more plugin: the AutoAlign.vba.gz plugin (see the following link for its manual). AutoAlign also aligns such things as >> for C++, := for Maple, etc., as you type.

## Examples

The first example shows a typical usage of Align. The next example shows a typical usage of AlignCtrl. Subsequent examples show some alignment operations done using maps from <AlignMaps.vim>.

### Example using Justification Options

Align = is used to demonstrate how left and right justification may be done. Note that justification operators are cyclic; ie., they are re-used cyclically. There are other justification operators not illustrated here (c-+:).

 Original AlignCtrl l AlignCtrl r AlignCtrl lr a=bb=ccc=1 ccc=a=bb=2 dd=eee=f=3  a = bb = ccc = 1 ccc = a = bb = 2 dd = eee = f = 3   a = bb = ccc = 1 ccc = a = bb = 2 dd = eee = f = 3  a = bb = ccc = 1 ccc = a = bb = 2 dd = eee = f = 3  Alignment  l l l l   r r r r  l r l r 

### Example using Initial White Space Control

AlignCtrl's initial whitespace options are illustrated in the following example. All the examples use the separator pattern :=.

 AlignCtrl W= := AlignCtrl w= := AlignCtrl I= := Original W option w option I option (retain init ws) (remove init ws) (re-use first ws)  a := baaa caaaa := deeee ee := f   a := baaa caaaa := deeee ee := f  a := baaa caaaa := deeee ee := f   a := baaa caaaa := deeee ee := f 

### Example using \t=

\t= is a map provided in <AlignMaps.vim>; it does alignment on the "=" sign. There are two methods that may be used to invoke most maps from <AlignMaps.vim>:

1. Go to beginning of block, type ma
2. Go to end of block, type \t=

Alternatively,

1. Go to beginning of block, type V (visual line mode)
2. Go to end of block, type \t=

 Original Code After \t= After \T= a=1; ab=2; abc=3; abcd=4; abcde=5; a+=1; ab+=2; abc+=3; this_is_func(); abcd+=4; abcde+=5; a/=1; ab/=2; abc/=3; abcd/=4; abcde/=5;  a = 1; ab = 2; abc = 3; abcd = 4; abcde = 5; a += 1; ab += 2; abc += 3; this_is_func(); abcd += 4; abcde += 5; a /= 1; ab /= 2; abc /= 3; abcd /= 4; abcde /= 5;   a = 1; ab = 2; abc = 3; abcd = 4; abcde = 5; a += 1; ab += 2; abc += 3; this_is_func(); abcd += 4; abcde += 5; a /= 1; ab /= 2; abc /= 3; abcd /= 4; abcde /= 5; 

\adec re-formats declarations. It expects one declaration per line (ie. no commas), and aligns the variables, comments, and initializations. If your declarations code has comma-separated lists of variables, you need to use \a, first (which breaks up such lists of declarations into the one declaration per line format).

 Original Code After \adec int a; float b; double *c=NULL; char x[5]; struct abc_str abc; struct abc_str *pabc; int a; /* a */ float b; /* b */ double *c=NULL; /* b */ char x[5]; /* x[5] */ struct abc_str abc; /* abc */ struct abc_str *pabc; /* pabc */ static int a; /* a */ static float b; /* b */ static double *c=NULL; /* b */ static char x[5]; /* x[5] */ static struct abc_str abc; /* abc */ static struct abc_str *pabc; /* pabc */  int a; float b; double *c = NULL; char x[5]; struct abc_str abc; struct abc_str *pabc; int a; /* a */ float b; /* b */ double *c = NULL; /* b */ char x[5]; /* x[5] */ struct abc_str abc; /* abc */ struct abc_str *pabc; /* pabc */ static int a; /* a */ static float b; /* b */ static double *c = NULL; /* b */ static char x[5]; /* x[5] */ static struct abc_str abc; /* abc */ static struct abc_str *pabc; /* pabc */ 

### Example using \acom

\acom re-formats comments: it aligns both the left and right comment sides, in spite of initial tabs, etc.

 Original Code After \com x= 1; /* this is */ if(x == y) {/* an example */ x+= 2; /* of a completely useless */ y-= 3;/* set of comments */ }  x= 1; /* this is */ if(x == y) { /* an example */ x+= 2; /* of a completely useless */ y-= 3; /* set of comments */ } 

### Example using \tt

\tt re-formats LaTeX tables.

 Original Code After \tt  \begin{center}\begin{tabular}{||l|l|l||} \hline\hline \multicolumn{1}{||c|}{Column 1} & \multicolumn{1}{c|}{Column 2} & \multicolumn{1}{c||}{Column 3} \\ \hline a & bc & def \\ def & bc & a \\ \hline a & bc & def \\ def & bc & a \\ \hline\hline \end{tabular}\end{center}   \begin{center}\begin{tabular}{||l|l|l||} \hline\hline \multicolumn{1}{||c|}{Column 1} & \multicolumn{1}{c|}{Column 2} & \multicolumn{1}{c||}{Column 3} \\ \hline a & bc & def \\ def & bc & a \\ \hline a & bc & def \\ def & bc & a \\ \hline\hline \end{tabular}\end{center} 

## Align and AlignCtrl Details

The <Align.vim> script contains two commands: AlignCtrl and Align.

 AlignCtrl =ClrcpPIWw ..list-of-separators... = all separator patterns are equivalent and active simultaneously. Patterns are regexp C Cycle through separator patterns (ie. patterns are active sequentially) l left justify field r right justify field c center field p# pad separator on its left by # blanks P# pad separator on its right by # blanks I preserve and apply first line's leading white space to all aligned lines W preserve leading white space on every line, even if it varies from line to line w don't preserve leading white space AlignCtrl Display current alignment settings [range]Align [..list-sep..] Aligns text over the given range. The range may be selected via visual selection or by any vim-style range from the command line. If no list of separators is provided, the last list provided either to Align or via AlignCtrl will be used.

The first argument to AlignCtrl is a string which may contain one or more alignment control commands. Most of the commands are single-letter commands; the p# and P# commands interpret the number for padding about the separator.

The typical line is considered to be composed of two or more fields separated by some pattern:

ws+field+ws+separator+ws+field+ws+separator+...

where "ws" stands for "white space" such as blanks and/or tabs.

The Align() function will first convert tabs over the region into spaces and then apply alignment control. Except for the initial white space, white space surrounding the fields is ignored. One has three options for handling initial white space:

w: ignore it
W: retain it
I: retain only the first line's initial white space and re-use it for subsequent lines
The fields will be left-justified, right-justifed, or centered as indicated by the justification specifiers (lrc). The lrc specifiers are cycled through:
l means llllll....
r means rrrrrr....
lr means lrlrlr....
Justification operators also now include
- skip treating this separator as a separator
+ repeat use of the last (lrc) justification
: treat the rest of the line as a single field
These operators allow one to pick a single separator and align just on that. As an example, consider the following "AlignCtrl --l:":
 --l: skip first two instances of the separator left justify on the separator treat rest of line as a field
The separators themselves may be considered as equivalent and simultaneously active ("=") or cycled through ("C"). Separators are regular expressions (|regexp|) and are specified as the second, third, etc arguments.

AlignCtrl, when called with no arguments, will display the current alignment control settings. A typical display is shown below:

Pat1<$$=$$>