sponsor Vim development Vim logo Vim Book Ad

Align : Help folks to align text, eqns, declarations, tables, etc

 script karma  Rating 1931/866, Downloaded by 45842  Comments, bugs, improvements  Vim wiki

created by
Charles Campbell
 
script type
utility
 
description
                                                    [ALIGN/ALIGNMAPS NEEDS VIM 7.0 AS OF V29/34]

Align and AlignMaps lets you align statements on their equal signs, make comment boxes, align comments, align declarations, etc.

Note: this plugin is not a left&right margin justification tool!  See vimscript#177, vimscript#2324, or vimscript#3728 for that.
Note: if you have vim 7.1 or later, your vimball should unpack just fine without having to update it.

There are two basic commands provided by this package:

        AlignCtrl options sep1 sep2 sep3 ...
        [range]Align sep1 sep2 sep3 ...

The "sep#" are regular expressions which describe separators that delineate fields; Align will line up the separators. The range may be any Vim range, _including_ visual-blocks.  Align works on lines of the form:
(ws==whitespace, sep==separator, field==text)

    ws-field-ws-sep-ws-field-ws-sep-ws-field-...
    ws-field-ws-sep-ws-field-ws-sep-ws-field-...

Note that white-space (ws) surrounding separators is ignored.

The Align package includes:

  Align : the basic alignment command
  AlignCtrl : provides options for the next call to :Align
  AlignMaps : many three or four key maps which support aligning C/C++ style declarations, ()?..:.., expressions, C/C++ comments, numbers, C preprocessor definitions, tables based on tabs or spaces, and more.

In addition, AutoAlign (vimscript#884) uses the Align function to align =s as you type.

Align handles alignment on multiple separators, not just the first one, and the separators may be the same across the line or different.  With AlignCtrl one may specify that separators are cyclic (re-used sequentially) or equivalent (all separators are simultaneously active).

There are several options to help with deciding what to do with initial white space.   By default Align re-uses the first line's initial white space, but one may use AlignCtrl to retain or remove each line's initial white space.

The <Align.vim> and <AlignMaps.vim> files are plugins and require vim 6.1 or higher.


EXAMPLES:

:5,10Align =
    Align on '=' signs

:'<,'>Align = + - \* /
    Align on any of the five separator characters shown.
    Note that visual block mode was used to fire off Align.

:AlignCtrl =lp1P1I
    which means:
    = all separators are equivalent
    l fields will be left-justified
    p1 pad one space before each separator
    P1 pad one space after each separator
    I  preserve and apply the first line's leading white space to all
       Align'd lines

:help align
    Gives help for Align


ALIGNMENT CONTROL

Alignment control allows for left or right justification or centering of fields, cyclic (sequentially active) or equivalent (simultaneously active) regular expressions to specify field separators, initial white space control, optional visual-block use (ie. apply Alignment only within a block), user-specified white-space padding about separators, and multiple separators.

MANY ALIGNMENT MAPS

AlignMaps.vim provides a number of maps which make using this package easy.  They typically either apply to the range 'a,. (from mark a to current line) or use the visual-selection (V, v, or ctrl-v selected):

\t=  : align assignments (don't count logic, like == or !=)
\t,  : align on commas
\t|  : align on vertical bars (|)
\tsp : align on whitespace
\tt  : align LaTeX tabular tables

AlignMaps also provides some internally complex maps for aligning C declarations, Ansi C function arguments, html tables, LaTeX tabulars, and trailing comments:

\acom : align comments
\adec : align C declarations (one variable per line)
\afnc : align ansi-style C function input arguments
\Htd  : align html tables

To see some examples of this, check out

    http://www.drchip.org/astronaut/vim/align.html#Examples

(the proportional fonts used by most browsers in showing you this page preclude showing the examples here). The help for Align and AlignCtrl also contains many examples.
(for those of you who prefer not to have the maps that AlignMaps.vim provides, simply remove the AlignMapsPlugin.vim from .vim/plugin and AlignMaps.vim from .vim/autoload - that's why AlignMaps is separate from Align)

ALIGNMENT ON VISUAL BLOCKS AND g,v-LIKE CONTROL

Sometimes one wants to align only a subset of text in a range, based on patterns or column extents.  Align supports both types of restrictions!
    
    Visual-block selection may be used to restrict Align to operate only
    within that visual block.
    
    AlignCtrl supports "g" and "v" patterns that restrict Align to

    operate on lines which match (or don't match, respectively) those
    patterns.

NEW STUFF:

There's a number of new AlignCtrl options:
    
    - allows one to skip a separator (treat it as part of a field)
    + repeat the last lrc justification (ex. lr+ == lrrrrrr... )
    : treat the rest of the line as a field; acts as a modifier
      to the last lrc.
    < left-justify the separator
    > right-justify the separator
    | center the separator

These are, except for the ":", cyclic parameters.  In other words, >< is equivalent to ><><><><... .  Thus separators can be of differing lengths (ex.  -\+ as a separator pattern can match -, --, ---, etc and the separators will be left/right/center justified as you wish).

To get automatic, as-you-type, aligning of = in the C, vimL, and other languages, check out vimscript#884 for several ftplugins (which use Align).


Alternative Aligners:
    Gergely Kontra's vimscript#176

Thank you for rating Align!

---------------------------------------
DISCUSSION and COMMENTS:
---------------------------------------

Please use email for bugs.  Enjoy!

(alpha/beta version available at http://mysite.verizon.net/astronaut/vim/index.html#ALIGN)
 
install details
1. You'll need to have plugins enabled: in your home directory, have at least the following two lines in your .vimrc file:
   set nocp
   filetype plugin on

2. Using vim 7.1 or later:
  vim Align.vba.gz
   :so %
   :q

3. Using vim 7.0: see http://mysite.verizon.net/astronaut/vim/index.html#VIMBALL to get and install an up-to-date version of vimball.  Then follow the simple directions for installation of Align/AlignMaps above!  Or, preferably: upgrade your copy of vim.

(this version of Align/AlignMaps requires vim 7.0)
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
Align.vba.gz 37/43 2013-03-12 7.0 Charles Campbell (Align) has visual maps to accompany all normal mode mappings (use V to invoke them)
(Align) a bugfix (cursor moved when g:Align_xstrlen=3)
(AlignMaps) use nnoremaps instead of nmaps
Align.vba.gz 36/42 2012-06-18 7.3 Charles Campbell new     : users may specify a function to decide whether or not a character should be skipped with the AlignCtrl \"*\" character
new     : Align will automatically grow the range if the given range is only one line to accommodate all lines which match the first separator pattern
improved: AlignMaps' \\anum, \\aenum, \\aunum and \\t=, \\T=
bugfixes: various; see :help align-history
Align.vba.gz 35/41 2009-03-04 7.0 Charles Campbell Align: save and restore of mod now done with the local version of the option
Align: new sanity check for an AlignStyle of just ":"
AlignMaps: new maps: \ts; ts: \ts< \ts= \a(
AlignMaps: default g:Align_xstrlen often is now 1 for multi-byte support
AlignMaps: bug fixed for \ts,
Align.vba.gz 34/40 2008-10-29 7.0 Charles Campbell (AlignMaps) split into plugin/ and autoload/ sections (faster [g]vim startup)
(AlignMaps) maps use <Plug>s and <script>s: allowing users to invoke the maps how they wish, and preventing user maps from interfering with the internal workings of the maps.
(Align)     bugfix - using :AlignCtrl before entering any alignment ctrl cmds was causing an error
Align.vba.gz 33/39 2008-03-06 6.0 Charles Campbell * Align now aligns multi-byte characters correctly (see :help align-strlen) -- choose g:Align_xstrlen for the type of codepoint you want handled.

* Align now accepts \"...\" arguments, so one can pass whitespace to Align as a separator

* AlignMaps' \\t= map now avoids comment aligning when the filetype is not *.c or *.cpp
Align.vba.gz 32/38 2007-08-20 7.0 Charles Campbell The <leader>tt map wasn't working right; Align now uses <q-args> instead of <f-args>, so it does the argument splitting itself, thus allowing patterns containing backslashes to be used without lots of backslash-duplication.  This allows the \tt map in AlignMaps to work, and to work without a lot of extra backslashes.
Align.vba.gz 31/36 2007-08-16 7.0 Charles Campbell New feature -- one can embed AlignCtrl settings into Align (as a one-shot):

   [range]Align! [AlignCtrl settings] pattern(s)

Plus some small improvements to some of the AlignMaps.
Align.vba.gz 30/35 2006-09-20 7.0 Charles Campbell * \acom can now work with doxygen style /// comments
* \t= and cousins used "`"s.  They now use \xff characters.
* <char-0xff> used in \t= \T= \w= and \m= instead of backquotes.
Align.vba.gz 29/34 2006-04-25 7.0 Charles Campbell Align and AlignMaps now use vim 7.0 style autoloading (quicker startup, loads only when used)
cecutil updated to use keepjumps
Now being distributed as a vimball - simply :so % it after decompressing it to install
Align.tar.gz 28/33 2005-11-21 6.0 Charles Campbell bugfix: (Align) Align now works around the report option setting.
bugfix: (Align) AlignCtrl l: wasn't behaving as expected; fixed!
bugfix: (AlignMap) \ts, now uses P1 in its AlignCtrl call
Align.tar.gz 27/32 2005-07-12 6.0 Charles Campbell Align v27 : cpo and ignorecase workarounds
AlignMaps v32: s:WrapperStart() -> AlignWrapperStart(), s:WrapperEnd() -> AlignWrapperEnd()
These changes let the wrappers be used outside of AlignMaps.vim (customized map support)
Align.tar.gz 27/31 2005-04-15 6.0 Charles Campbell Align: GetLatestVimScripts/AutoInstall supported
AlignMaps: new map: \\adcom (align declaration-style comments), \\a, now wors across multiple lines with different types, cecutil.vim now used, more number alignment maps (\\aenum, \\aunum)
ip used for rating: 3.85.63.190

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
Vim at Github