DrChip's Alignment Tool for Vim

You may quickly get to some examples by clicking: examples.

The Align.vba.gz file includes three files: <Align.vim>, <AlignMaps.vim>, and <Align.txt>. 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").

The s/w is also mentioned at Vim's sourceforge website as a tip: Alignment: =, LaTeX tables, declarations, etc. and <Align.tar.gz> is available there as a script: Align.vim (as requested by several users).

Directions: Simply put <Align.vim> and optionally <AlignMaps.vim> into your .vim/plugin directory. Put <Align.txt> into your .vim/doc directory.

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

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 supply the map sequence. In the latter case, the maps retain mark-a, and so it is easier to apply a sequence of maps.

Align and AlignCtrl Usage

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

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

l means llllll....

r means rrrrrr....

lr means lrlrlr....

- skip treating this separator as a separator

+ repeat use of the last (lrc) justification

: treat the rest of the line as a single field

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

AlignCtrl<=> qty=1 AlignStyle Padding<1|1>

Pat1<\(=\)>

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 usually done on a line basis, but one may restrict alignment to a visual block using ctrl-v. For any visual mode, one types the colon (:) and then "Align". One may also specify a line range:

:[range]Align [list-of-separators]

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

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

  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=

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=

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;

Example using \adec

\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).

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.

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.

 \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}