AutoAlign.txt Automatic Alignment Nov 25, 2013
Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2013 by Charles E. Campbell autoalign-copyright
The VIM LICENSE applies to AutoAlign.vim and AutoAlign.txt
(see copyright) except use "AutoAlign" instead of "Vim"
No warranty, express or implied. Use At-Your-Own-Risk.
==============================================================================
1. Contents autoalign autoalign-contents
1. Contents.................: autoalign-contents
2. Installing...............: autoalign-install
3. AutoAlign Tutorial.......: autoalign-tutorial
4. AutoAlign Manual.........: autoalign-manual
5. AutoAlign Internals......: autoalign-internals
6. Elastic Tabs.............: autoalign-elastictabs
7. AutoAlign History........: autoalign-history
==============================================================================
2. Installing AutoAlign autoalign-install
1. AutoAlign needs the Align/AlignMaps utilities
which are available from either:
2. Using vim 7.1 or later:
This process will generate the following files on your runtimepath:
3. To enable plugins and filetype plugins generally, including
AutoAlign, have the following in your <.vimrc> file:
==============================================================================
3. AutoAlign Tutorial autoalign-tutorial
The tutorial assumes that you have already installed AutoAlign and the
Align/AlignMap plugins.
Example 1: when using C
Results in
and then
and finally
with the auto-alignment occurring upon the entry of the "="s.
Such alignments will not occur when the line begins with for,
if, while, or else.
Example 2: using C
with alignment occuring like it does with C.
C auto-alignment also handles << and >> operators, and for
C style comments (ie. //... ).
Example 3: using LaTeX
Nothing seems to happen so far. With the next line:
The trailing double-backslash triggers the alignment package,
yielding
Example 4: using Maple
Upon entry of the second line's ":=", the AutoAlign package will align
the ":="s, yielding
==============================================================================
4. AutoAlign Manual autoalign-man autoalign-manual
The AutoAlign filetype plugins operate while vim is in insert mode. They
apply appropriate Align/AlignMaps to the most recent contiguous region,
thereby keeping such things as "=" aligned. See align and alignmaps.
autoalign-AA autoalign-AAstart
There are two commands supported by AutoAlign:
The mark 'a is used by AutoAlign to indicate where the start of the
automatic alignment region begins. Changing 'a to some other place will
also stop AutoAlign from operating on that region. One may temporarily
suppress AutoAlignment that way.
Language AutoAlignment AutoAlignment
Trigger Taken On
-------- ------------- -------------
bib = =
c = =
cpp = =
< <<
> >>
maple = :=
tex \ & and \\
vim = =
The AutoAlignment trigger character invokes a call to the appropriate
filetype's AutoAlign. Only when:
* the current line matches a filetype specific pattern (to avoid
aligning <= >= == etc)
* the b:autoalign_vim variable records the first line which
satisfied the filetype specific pattern in the current
region. If it matches the mark ('a)'s line, then AutoAlignment
will occur. Thus the user can temporarily disable AutoAlignment
on the current region merely by changing where the mark 'a is
set to.
* Although frequently the trigger character is also used in
the alignment, sometimes a longer pattern is used (ex. maple's
:=) for alignment.
The AutoAlign plugin is fairly trivial to use -- just type. Alignment
will occur for the following patterns automatically. These patterns
are stored in b:autoalign_reqdpat1, b:autoalign_reqdpat2, etc.
FILETYPE PATTERNS
bib ^\(\s*\h\w*\(\[\d\+]\)\{0,}\(->\|\.\)\=\)\+\s*[-+*/^|%]\==
c ^\(\s*\*\{0,}\h\w*\%(\[\%(\d\+\|\h\w*\)]\)\{0,}\%(->\|\.\)\=\)\+\s*[-+*/^|%]\==
cpp ^\(\s*\h\w*\(\[\d\+]\)\{0,}\(->\|\.\)\=\)\+\s*[-+*/^|%]\==
cpp <<
cpp >>
maple :=
matlab \%(^.*=\)\&\%(^\s*\%(\%(if\>\|elseif\>\|while\>\|for\>\)\@!.\)*$
tex ^\([^&]*&\)\+[^&]*\\\{2
vim ^\s*let\>.*=
AutoAlign looks backwards from the current line, searching for the first
preceding line _not_ containing the pattern. It uses b:autoalign_notpat1,
b:autoalign_notpat2, etc for this. If the "not pattern" has moved since
the mark ('a) was made, AutoAlign will start aligning from the current
line.
AUTOALIGN FUNCREF AutoAlign_funcref
When AutoAlign is invoked and changes the line, an optional function
(or functions) may be called via Funcref(s):
or a list of such Funcref(s):
These functions will be executed after the aligning has been done, but
before control has been passed back to the user via a :startinsert.
The number ("10" in the example) following the funcref is the same as the
number passed to AutoAlign() due to the trigger character.
==============================================================================
5. AutoAlign Internals autoalign-internals
AutoAlign is triggered to operate during insert mode when a special
character (such as "=") is encountered using an inoremap. Each ftplugin
specifies its own triggers. The inoremap turns virtualedit off, calls
AutoAlign(), and then deletes the trigger character (which may have or may
not have moved) and then inserts it to keep the operation otherwise
transparent.
AutoAlign attempts to perform its automatic alignment on an "AutoAlign
region". Alignment, of course, is performed over that region. The idea
is to start an AutoAlign region upon receipt of a trigger character and
a matching required pattern; subsequently, alignment is done over the
AutoAlign region is active and whenever the region has more than one line
in it.
Such a region begins with the presence of a required pattern. That first
line is also marked with mark-a ('a). If the mark 'a is moved, then the
AutoAlign region is terminated. There are several ways that an AutoAlign
region may be terminated; see below.
Associated with each trigger character are several patterns and/or line
numbers. Also, each trigger character inoremap is to have an associated
numeric identifier (referred to as "#") below.
b:autoalign_reqdpat
b:autoalign_reqdpat#
This pattern is required for AutoAlign to deem that an AutoAlign
region has started. If a positive # is passed to AutoAlign(), then
the required pattern is needed to allow the AutoAlign region to
continue whenever a trigger character is encountered. A negative #, a
trigger character, and a failed match to b:autoalign_reqdpat# will
terminate the AutoAlign region.
b:autoalign_notpat
b:autoalign_notpat#
This pattern must match just before the AutoAlign region starts. It
is used to search before the current line. If the non-pattern
matching line is not the same as it was when the AutoAlign region
began, then the AutoAlign region is terminated.
b:autoalign_start
b:autoalign_start#
This holds a line number specifying where the AutoAlign region
starts. It is used instead of b:autoalign_reqdpat# and
b:autoalign_notpat#, in conjunction with b:autoalign_stop#.
(not a pattern)
b:autoalign_stop
b:autoalign_stop#
This holds a line number specifying where the AutoAlign region
starts. It is used instead of b:autoalign_reqdpat# and
b:autoalign_notpat#, in conjunction with b:autoalign_start#.
(not a pattern)
b:autoalign_suspend
b:autoalign_suspend#
This pattern is optional; if it matches, the AutoAlign region is
terminated. The fplugin/html/AutoAlign.vim script uses </table>, for
example, to terminate table aligning.
b:autoalign_cmd
b:autoalign_cmd#
This is the command used to invoke alignment on the AutoAlign region.
b:autoalign_trigger
b:autoalign_trigger#
This variable holds the trigger character.
Of course, the :AA command is also available to turn AutoAlign off.
==============================================================================
6. Elastic Tabs autoalign-eltab autoalign-elastictabs
Those of you who are interested in "elastic" non-uniform tab stops may find
the "eltab" filetype of use. Its not a pure non-uniform tab solution (that
would take a modification to vim itself); however, a filetype of eltab coupled
with AutoAlign makes for an almost elastic-tab solution.
If the tabstop is set to 1 (:set ts=1), then AlignMaps' \tab will do a
no-padding alignment on the tabs. Thus one gets tabs surrounded by spaces to
do the alignment (with no additional padding).
If your file has a modeline:
Subsequently, as you type, tabs will be auto-aligned within each current insertion
block of text; total file alignment can be done with 1V$\tab (ie. select
entire file, align it).
==============================================================================
7. AutoAlign History autoalign-history
14 : Sep 20, 2007 * now using startinsert! instead of startinsert.
Currently not using the various autoalign_trigger
strings; will see how modification works out.
* found some cases where startinsert! isn't a good
idea (ex. inserting an "="). New modification;
this one may use the autoalign_trigger string.
* The c plugin's AutoAlign.vim was overriding
the c plugin's AutoAlign.vim settings.
Feb 22, 2011 * for menus, &go =~# used to insure correct case
Apr 25, 2012 * added AutoAlign_funcref
Sep 18, 2012 * added b:autoalign_start and b:autoalign_stop
Nov 25, 2013 * (Gary Johnson) reported a problem with using C=
while atop an "=" sign. Fixed.
13 : Oct 19, 2006 * ftplugin/cpp/AutoAlign.vim fixed for < and >.
Introduced b:autoalign_trigger# so AutoAlign
can put cursor back where it belongs.
* AutoAlign now pluginkiller immune
Mar 26, 2007 * AutoAlign's invocation of Align sometimes caused
the cursor to jump to the first line rather than
the current line (ex: for Maple's :=). Fixed.
Aug 15, 2007 * Changed the imaps's right-hand-side to use,
typically, =<c-r>=AutoAlign(#) instead of
=<c-o>:silent call AutoAlign(#).
Thanks to Antony Scriven! Gets that "."
repeater working.
12 : Sep 19, 2006 * ftplugin/bib/AutoAlign.vim fixed
11 : Mar 23, 2006 * v10 had debugging enabled; this one has debugging
deactivated.
* now decides to use startinsert vs startinsert!
before the alignment by using the "atend" variable,
which holds the result of testing whether the cursor
is at the end-of-line or not.
10 : Mar 16, 2006 * using startinsert! to recommence editing
AutoAlign only triggered when the trigger character
is at the end of the current line being inserted.
* works with ve=all and ve= (see 've')
9 : Mar 16, 2006 * seems to have stopped working with virtualedit off.
Now works with virtualedit off or on. If vim 7.0
is in use, AutoAlign doesn't use SaveWinPosn()
or RestoreWinPosn(), so it may work faster.
8 : Jan 18, 2006 * cecutil updated to use keepjumps
* plugin/AutoAlign.vim was missing from distribution
7 : Mar 31, 2005 * supports html
* b:autoalign_suspend# for suspend-alignment pattern
implemented, along with using AutoAlign(-#) to avoid
having a reqdpat failure doing an AutoAlign suspension.
The absolute value of # is used to refer to
b:autoalign_reqdpat#, b:autoalign_notpat#, and
b:autoalign_suspend#.
Apr 22, 2005 * sanity check included to prevent an attempt to access
an undefined variable (b:autoalign_reqdpat{i})
6 : Mar 30, 2005 * AutoAlign is split into a plugin containing the
majority of vimscript; the supported ftplugins
contain the invoking imaps and pattern definitions
that the plugin uses.
5 : Jan 24, 2005 * first release of AutoAlign using vim's user-help.
* using g:mapleader instead of a built-in backslash to
access AlignMaps
* map and function changed to allow use of "." to
repeat entry of =... expressions.
4, Jul 02, 2004 * see i_CTRL-G_u -- breaks undo sequence at every align
3, Mar 03, 2004 * autoalign not taken if a no-pattern line is
in-between the keepalign line and the current line
2 * b:autoalign==0: turns autoalign off
b:autoalign==1: turns autoalign back on
* 'a now used during autoalign, and AlignMap's \t=
If user changes 'a, then AutoAlign recognizes that
it is not to keep aligning
* The :AA command can be used to toggle AutoAlign
1 * The Epoch
==============================================================================
vim:tw=78:ts=8:ft=help