Align : Help folks to align text, eqns, declarations, tables, etc
| script karma
Downloaded by 40621
Comments, bugs, improvements
script versions (upload new version)
| [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)
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.
Align on '=' signs
:'<,'>Align = + - \* /
Align on any of the five separator characters shown.
Note that visual block mode was used to fire off Align.
= 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
Gives help for Align
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
(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
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).
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)
|1. You'll need to have plugins enabled: in your home directory, have at least the following two lines in your .vimrc file:
filetype plugin on
2. Using vim 7.1 or later:
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)
Click on the package to download.
ip used for rating: 18.104.22.168
||(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
||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: 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,
||(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 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
||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.
||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.
||* \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 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
||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 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: 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)