*lastnextprevious.txt*		Move forward and backward as the last movement

Version 0.2.0
Script ID: ????
Copyright © 2012 Alejandro Exojo Piqueras <http://disperso.net/>
License: MIT license  {{{
	Permission is hereby granted, free of charge, to any person obtaining
	a copy of this software and associated documentation files (the
	"Software"), to deal in the Software without restriction, including
	without limitation the rights to use, copy, modify, merge, publish,
	distribute, sublicense, and/or sell copies of the Software, and to
	permit persons to whom the Software is furnished to do so, subject to
	the following conditions:

	The above copyright notice and this permission notice shall be included
	in all copies or substantial portions of the Software.

	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
	OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
	MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
	IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
	CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
	TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
	SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}}}

CONTENTS					*lastnextprevious-contents*

Introduction				|lastnextprevious-introduction|
	Installation			|lastnextprevious-installation|
	Configuration and usage		|lastnextprevious-configuration|
Movement table				|lastnextprevious-table|
Customization				|lastnextprevious-customization|
Bugs and limitations			|lastnextprevious-bugs|
Credits and considerations		|lastnextprevious-credits|
Changelog				|lastnextprevious-changelog|


==============================================================================
INTRODUCTION					*lastnextprevious-introduction*

*lastnextprevious* is a Vim plugin that saves the user from typing some
movement (or action) commands that may be short, but are very inconvenient to
type repeatedly (specially in some keyboard layouts). Vim has many key
combinations of this style (for example, |]c| or |gT|).

With this plugin, when the user performs one of the configured movements by
pressing the appropriate key strokes, the movement is performed as usual, but
the type of movement is also saved ("last") for later. So if it has to be
repeated ("next"), or it has to be performed in the other direction
("previous"), the user might save some inconvenient key pressing using the
shortcut provided by this plugin. Is an equivalent of |n| and |N|, but instead
of repeating a search, it repeats other customizable actions.

For example, moving one tab page backwards is not difficult: just press |gT|.
However, if you want to review all tab pages one by one, your fingers will
have to repeat gTgTgTgT... Likewise, imagine pressing repeatedly |g;| for
revisiting the places where you did changes to a file, possibly reversing the
sense of the movement if you did a mistake: g;g;g;g,g;...

The solution this plugin offers is to press the keys for the desired movement
only once, optionally edit or do something at that position, and continue the
movement backward or forward with one single key press. For example: g;--+-
(and so on).

------------------------------------------------------------------------------
INSTALLATION					*lastnextprevious-installation*

The usual for any other Vim plugin: copy the files where Vim will look for
them with the same directory layout that came with the plugin. If you use
other plugins, color schemes, etc. that are installed by you, you probably
know where that is. In UNIX-like systems (Linux, Mac OS X), is some place like
$HOME/.vim, and on Windows $HOME/vimfiles. See |vimfiles| for details.

If you don't have installed any plugins yet, I strongly recommend to first
install and configure a plugin manager (a plugin to help you with other
plugins), and then install |lastnextprevious|. My recommendation is that you
start with Pathogen because is very simple and it works very well with a
version control system. Find it at:
	https://github.com/tpope/vim-pathogen

------------------------------------------------------------------------------
CONFIGURATION AND USAGE				*lastnextprevious-configuration*

Think a couple of keys that you don't use much or nothing at all in normal
mode. Good candidates are |+| and |-| or |CTRL-P| and |CTRL-N|, but any pair
of keys will work. Just make sure that you are not going to miss them. Now map
them to the plugin actions in your |vimrc|, like this: >
	nmap <silent> + <Plug>lastnextprevious_forward
	nmap <silent> - <Plug>lastnextprevious_backward
<

Now you can perform a movement or action from the |lastnextprevious-table| in
the usual way, and to repeat it, just press "+". To repeat it in the opposite
direction, press "-". For example, to go forward through the list of
misspelled words, just press "]s+++++" instead of "]s]s]s]s]s]s".

==============================================================================
MOVEMENT TABLE					*lastnextprevious-table*

By default, the plugin provides the following table of mappings:

	NAME			BACK	FORWARD
	----------------------------------------
	section-start		[[	]]
	section-end		[]	][
	brace-block		[{	]}
	bracket-block		[(	])
	method			[m	]m
	change			[c	]c
	foldborder		[z	]z
	foldnext		zk	zj
	changelist		g;	g,
	undolist		g-	g+
	spell			[s	]s
	spellstrict		[S	]S

See the next section to learn how to change this table.

==============================================================================
CUSTOMIZATION					*lastnextprevious-customization*

By default, if you start Vim and immediately press the key that triggers
<Plug>lastnextprevious_forward or <Plug>lastnextprevious_backward (that was
"+" and "-" in our previous example) when no movement has been done first,
"section-start" is used as initial value. Remember that this will change once
you start doing movements listed in the table, but if you want to start with
some predefined value, add something like this to your |vimrc|: >
	let g:lastnextprevious#last = 'changelist'
<

If you want to extend the table of available actions to provide your own, is
very easy to do so. You just have to add values to the table, which is in
a Vim |Dictionary| variable: >
	call extend(g:lastnextprevious#table,
	\ { 'tabcycle': {'b': 'gT', 'f': 'gt'} }
	\)
<

On the other hand, if you want to do the opposite, and remove some key
combinations so the plugin doesn't remap them, you will have to remove the
keys from the variable. Again, add something like the following to your
|vimrc| file: >
	call remove(g:lastnextprevious#table, 'changelist')
<

Also, note that the plugin tries to be smart and tries to cooperate with other
plugins, so if the key combination in the table is already mapped to something
else because you or a plugin did so, it reads and stores that mapping to
execute it when needed, instead of overwriting it. So if you have installed
the |unimpaired| plugin, you can have >
	call extend(g:lastnextprevious#table,
	\   'quickfix': {'b': '[q', 'f': ']q'} }
	\)
<
and it will work as if |[q| and |]q| where native Vim movements. The
|unimpaired| plugin provides many useful additional mappings that contain an
initial bracket, so this plugin might be useful to repeat those motions. It
can be found at: >
	https://github.com/tpope/vim-unimpaired
<

==============================================================================
BUGS						*lastnextprevious-bugs*

At the moment, there is no known issue, but is very likely that there will be,
so your feedback is welcome.

Feel free to contact the author through Gitorious or GitHub:
	https://gitorious.org/vim-for-qt-kde/vim-lastnextprevious
	https://github.com/suy/vim-lastnextprevious

==============================================================================
CREDITS AND CONSIDERATIONS			*lastnextprevious-credits*

This plugin is largely inspired by other plugins that provide similar
behaviour/experience. Those are vim-space by Henrik Öhman and vim-submode by
Kana Natsuno:
	https://github.com/spiiph/vim-space
	http://github.com/kana/vim-submode

If you find that this plugin doesn't suit your needs, consider giving a look
at those other two. More specifically, vim-submode is much more powerful at
providing more possibilities when you are performing an action, but if you
want to do something not defined in that submode, then you exit the submode
and have to enter it again. Is a great plugin that can have many uses, and can
be used in parallel with this.

And vim-space is more or less intended to do the same as this plugin, but at
the time lastnextprevious was written, vim-space had some issues. First, it
wasn't possible to use a different key other than space to go forward. Second,
it has quite a different approach, and attempts not only to map normal mode
keys, but also to parse every Ex command in case you entered a command like
|:cnext| to go forward in the |quickfix| list. Since I wasn't using those
commands because |unimpaired| provides more convenient ways to do the same, I
found very little value in that code, that also complicates extending the
plugin.

Also, I didn't see the point of providing mappings for movements that already
provide a one key shortcut to repeat the movement forward or backward like the
|jumplist| or the search.

I considered improving vim-space, but the code was too large and complex to be
useful to me, so I started from scratch, and at the moment of this writing I
accomplished what I expected from vim-space and more with only 10% of the
code. The functionality of parsing the command line input to do something
extra should be delegated to some specific plugin to do just that (do only one
thing, and do it properly), like Kana's vim-altercmd.

Oh, and, of course there is the fun implied in trying to write something from
scratch that suits exactly your needs, and the small ego boost that means
accomplishing it. :-)

==============================================================================
CHANGELOG					*lastnextprevious-changelog*

0.2.0	2012-12-07
	- Support actions that are not native to Vim, but are triggered in
	  some plugin mapping.

0.1.0	2012-10-14
	- First public release.

==============================================================================
vim:tw=78:ts=8:ft=help:norl:fen:fdl=0:fdm=marker: