Ⅰ. 插件描述

Create custom motions and text objects via repeated jumps.

Ⅱ. 基本信息

创建日期： 2010-06-22

使用用户： 23

Github星： 6

插件作者： Ingo Karkat

Ⅲ. 安装方法

使用Vundle管理器安装

在你的.vimrc下添加:

Plugin 'inkarkat/countjump'

… 然后在Vim中运行以下命令:

:source %
:PluginInstall

对于Vundle版本 < 0.10.2，请用上面的Bundle替换Plugin。

使用NeoBundle管理器安装

在你的.vimrc下添加:

NeoBundle 'inkarkat/countjump'

… 然后在Vim中运行以下命令:

:source %
:NeoBundleInstall

使用VimPlug管理器安装

在你的.vimrc下添加:

Plug 'inkarkat/countjump'

… 然后在Vim中运行以下命令:

:source %
:PlugInstall

使用Pathogen管理器安装

在终端中运行以下命令:

cd ~/.vim/bundle
git clone https://github.com/vim-scripts/CountJump

Ⅳ. 文档说明

COUNT JUMP

by Ingo Karkat

DESCRIPTION

Though it is not difficult to write a custom movement (basically a :map
that executes some kind of search or jump) and a custom text-object (an
:omap that selects a range of text), this is too complex for a novice user
and often repetitive.
This plugin covers the common use case where the movement and boundaries of a
text object can be specified via start and end patterns, and offers a single
function to set up related mappings. With it, you can enhance some built-in
Vim mappings to take an optional [count], and quickly define new mappings for
help file sections, diff hunks, embedded macros, and so on...

As a generalization of the start and end patterns, the movement and boundaries
of a text object can also be specified via jump functions, i.e. Funcrefs of
functions that position the cursor on the appropriate location and return that

This can be used where the jump is difficult to express with a
regular expression, the jump may need adapting depending on the

context, or other uses.
This plugin contains some support for movement and text objects consisting of
text regions that can be defined by continuous lines that match a particular
pattern, e.g. comment blocks that all start with /^\s*#/.

RELATED WORKS

motpat.vim (vimscript #3030) offers similar functions to setup motion
mappings, but no text objects (yet).
textobj-user (vimscript #2100) has support for user-defined text objects via
regular expressions, but they don't support selecting multiple via [count].
movealong.vim (vimscript #4691) provides a :Movealong command (and optional
mappings) that repeatedly executes a motion until a condition of a syntax,

pattern match, or arbitrary expression is met.

USAGE

The plugin defines several functions, which set up the appropriate mappings
based on the arguments that you supply. The following is an overview; you'll
find the details directly in the implementation files in the
autoload/CountJump/ directory.

CountJump#Motion#MakeBracketMotion( mapArgs, keyAfterBracket, inverseKeyAfterBracket, patternToBegin, patternToEnd, isEndPatternToEnd, ... )

This function sets up mappings starting with [ and ] for movement (with
optional [count]) relative to the current cursor position, targeting either a
text pattern at the beginning ([{keyAfterBracket} mapping) or a text pattern
at the end (]{inverseKeyAfterBracket} mapping) of whatever you want to treat
as a text block.

CountJump#Motion#MakeBracketMotionWithJumpFunctions( mapArgs, keyAfterBracket, inverseKeyAfterBracket, JumpToBeginForward, JumpToBeginBackward, JumpToEndForward, JumpToEndBackward, isEndJumpToEnd, ... )

This function sets up mappings starting with [ and ] for movement (with
optional [count]) relative to the current cursor position, but rely on four
passed jump functions instead of text patterns to do the movement.

CountJump#TextObject#MakeWithCountSearch( mapArgs, textObjectKey, types, selectionMode, patternToBegin, patternToEnd )

Defines a complete set of mappings for inner and/or outer text objects that
support an optional [count] and are driven by search patterns for the
beginning and end of a block. Outer text objects include the matched pattern
text, inner ones not. Selection can be characterwise, linewise or blockwise.

CountJump#TextObject#MakeWithJumpFunctions( mapArgs, textObjectKey, types, selectionMode, JumpToBegin, JumpToEnd )

This is a generalization of CountJump#TextObject#MakeWithCountSearch() that
invokes custom functions instead of searching for a fixed pattern. This is
useful if the check for a match is too complex for a single regular
expression, or if you need to adjust the match position depending on the
circumstances.

Often, a region can be defined as a block of continuous lines that all match a
certain pattern (or, even more generic, where a provided predicate function
returns a match position). The following functions aid in implementing
movements to the boundaries of these regions and text objects consisting of
the region:

CountJump#Region#JumpToRegionEnd( count, Expr, isMatch, step, isToEndOfLine )

Starting from the current line, search for the position where the count'th
region ends. Use this function to build Funcrefs for forward / backward jumps
that can then be passed to CountJump#TextObject#MakeWithJumpFunctions().

CountJump#Region#JumpToNextRegion( count, Expr, isMatch, step, isAcrossRegion, isToEndOfLine )

Starting from the current line, search for the position where the count'th
region begins/ends.

CountJump#Region#Motion#MakeBracketMotion( mapArgs, keyAfterBracket, inverseKeyAfterBracket, Expr, isMatch, ... )

This function sets up mappings starting with [ and ] for movement (with
optional [count]) relative to the current cursor position, targeting a text
region defined by contiguous lines that (don't) match a:Expr.

CountJump#Region#TextObject#Make( mapArgs, textObjectKey, types, selectionMode, Expr, isMatch )

Defines a complete set of mappings for inner and/or outer text objects that
support an optional [count] and select regions of lines which are defined by
contiguous lines that (don't) match a:Expr.
The inner text object comprises all lines of the region itself, while the
outer text object also includes all adjacent lines above and below which do
not themselves belong to a region.

The custom Funcrefs for jumps and predicates of lines belonging to a range may
be invoked multiple times until the CountJump function arrives at its
destination. To help the Funcrefs to determine where in this sequence they
are, an empty g:CountJump_MotionContext dictionary is initialized at the
start of a range motion (for pattern / jump functions, this isn't necessary;
there's either no custom code or just a single invocation), and an empty
g:CountJump_TextObjectContext dictionary is initialized at the start of a text
object. Funcrefs can put custom information (e.g. the particular comment
prefix on the current line) in there and evaluate this in subsequent
invocations.

EXAMPLE

Let's illustrate the usage by developing custom motions and text objects for
Pascal begin..end blocks.

We want to move around blocks, and override the default section movements for
it:
]] Go to [count] next start of a block.
][ Go to [count] next end of a block.
[[ Go to [count] previous start of a block.
[] Go to [count] previous end of a block.

call CountJump#Motion#MakeBracketMotion('<buffer>', '', '', '\c^begin\n\zs', '\c^.*\nend', 0)

The begin pattern positions the cursor on the beginning of the line following
the "begin" keyword, the end pattern on the beginning of the line
preceding the "end" keyword.

We want to select a block, either including or excluding the lines with the
begin..end keywords:
ib "inner block" text object, select [count] contents of

                    a block.

ab "a block" text object, select [count] blocks.

call CountJump#TextObject#MakeWithCountSearch('<buffer>', 'b', 'ai', 'V', '\c^begin\n', '\c^end.*$')

If there is a filetype detection for Pascal files, we can simply put the
above calls in a ~/.vim/ftplugin/pascal_movement.vim script and are done.

INSTALLATION

The code is hosted in a Git repo at

https://github.com/inkarkat/vim-CountJump

You can use your favorite plugin manager, or "git clone" into a directory used
for Vim packages. Releases are on the "stable" branch, the latest unstable
development snapshot on "master".

This script is also packaged as a vimball. If you have the "gunzip"
decompressor in your PATH, simply edit the *.vmb.gz package in Vim; otherwise,
decompress the archive first, e.g. using WinZip. Inside Vim, install by
sourcing the vimball or via the :UseVimball command.

vim CountJump*.vmb.gz
:so %

To uninstall, use the :RmVimball command.

DEPENDENCIES

Requires Vim 7.0 or higher.
Requires the ingo-library.vim plugin (vimscript #4433), version 1.041 or
higher.

INTEGRATION

If you want to define motions that do not start with [ / ], and the plugin
that employs CountJump offers a configuration variable like
g:PluginName_mapping to influence the mapped key(s), you can define
intermediate <Plug>-mappings (using-<Plug>), and then define your own custom
mappings based on them:

let g:PluginName_mapping = '<Plug>PluginName%s'
nmap { <Plug>PluginNameBackward
nmap } <Plug>PluginNameForward
omap { <Plug>PluginNameBackward
omap } <Plug>PluginNameForward
vmap { <Plug>PluginNameBackward
vmap } <Plug>PluginNameForward

If you want to define text objects that do not start with i / a, and the plugin
that employs CountJump offers a configuration variable like
g:PluginName_mapping to influence the mapped key(s), you can define
intermediate <Plug>-mappings (using-<Plug>), and then define your own custom
mappings based on them:

let g:PluginName_mapping = '<Plug>PluginName%s'
omap ,p <Plug>PluginNameInner
omap ,P <Plug>PluginNameOuter
vmap ,p <Plug>PluginNameInner
vmap ,P <Plug>PluginNameOuter

KNOWN PROBLEMS

An outer text object cannot consist of the same, multiple characters;
nothing will be selected (because the end pattern also matches at the begin

position). A same single character pattern works, though.

For blockwise text objects, the original cursor position should be required
to be inside the selection. However, this requires translation of the

byte-indices here into screen columns, and is thus non-trivial to implement.

The behavior with wrap messages is slightly inconsistent: Like normal
/pattern search, we print the wrap message, but don't print an error message

(like "Pattern not found"), but beep instead (like the built-in ]m etc.
mappings (but not the ), }, ]] mappings, which fail silently?!)).

A repeat (via .) of the operator-pending mapping loses the previously
given [count], and operates on just one search / jump.

IDEAS

Add customization parameter so that the motion / text object includes the
start / end of buffer in case patternToBegin / patternToEnd do not match any

more.

CONTRIBUTING

Report any bugs, send patches, or suggest features via the issue tracker at
https://github.com/inkarkat/vim-CountJump/issues or email (address below).

HISTORY

1.91 RELEASEME

ENH: Allow Funcref for a:searchArguments / first search argument /
a:patternTo{Begin,End}
ENH: Allow to influence given [count] via
CountJump#CountCountJumpWithWrapMessage() variant of

CountJump#CountJumpWithWrapMessage().

FIX: Avoid "Error detected while processing :" additional line above an
exception thrown (from a client-supplied Funcref).
ENH: Allow client-supplied Funcrefs to throw a "CountJump: <error text>"
exception to issue custom errors.
Prevent a custom text object from clobbering the register passed to a custom
operator (as :omaps defined by this plugin).

You need to update to ingo-library (vimscript #4433) version 1.041!

1.90 11-Feb-2018

Rename g:CountJump_Context to g:CountJump_MotionContext, to avoid a clash
with the text object in CountJump#TextObject#TextObjectWithJumpFunctions().

Clear g:CountJump_MotionContext at the end of the function.

Rename g:CountJump_Context to g:CountJump_TextObjectContext. When using
CountJump#Region#TextObject#Make(), the generated jump functions also set

that context, and there's a clash with
CountJump#TextObject#TextObjectWithJumpFunctions(). In particular, one
cannot store a context for the entire text object (both jumps to begin and
end), as the individual jump functions clear the identical context. Clear
g:CountJump_TextObjectContext at the end of the function.

ENH: Support non-argument Funcref for a:Expr that gets evaluated once at the
beginning, and should yield a regular expression that is then used in its

stead.

1.86 24-Jul-2017

CountJump#Motion#MakeBracketMotion(): The a:patternToBegin, a:patternToEnd,
a:searchName arguments may contain special characters that need escaping in

a map. Use ingo#escape#command#mapescape().

CountJump#Region#Motion#MakeBracketMotion(): The a:Expr argument may contain
special characters that need escaping in a map. Use

ingo#escape#command#mapescape().

Retire duplicated fallback for ingo#motion#helper#AdditionalMovement();
since version 1.85, the ingo-library is now a mandatory dependency.
CountJump#Motion#MakeBracketMotionWithJumpFunctions(),
CountJump#TextObject#MakeWithJumpFunctions(),

CountJump#Region#Motion#MakeBracketMotion(): Catch all exceptions and
report only the text. My ErrorMotion.vim plugin could be slow to find the
next error if there is none. Aborting with <C-c> would print a long
multi-line exception: "Error detected while processing function
ErrorMotion#Forward[1]..CountJump#JumpFunc[39]..HlgroupMotion#JumpWithWrapMessage[26]..CountJump#CountJumpFuncWithWrapMessage[35]..HlgroupMotion#SearchFirstHlgroup:
line 67: Interrupted". As we apparently cannot avoid the printing of "Type
:quit<Enter> to exit Vim", suppress the Vim:Interrupt exception, and
:echoerr all others.

1.85 23-Dec-2014

Use ingo/pos.vim.
Use ingo#msg#WarningMsg().
Make test for 'virtualedit' option values also account for multiple values.

__You need to install / update to ingo-library (vimscript #4433) version
1.019! It is now mandatory for the plugin.__

1.84 25-Apr-2014

Pin down the 'virtualedit' setting (to "onemore") during
CountJump#TextObject#TextObjectWithJumpFunctions() to avoid that a

characterwise outer text object that ends at the end of a line includes the
line's newline character when 'selection' is "exclusive".

FIX: There are no buffer-local functions with a b: scope prefix, and Vim
7.4.264 disallows those invalid function names now. Previously, multiple

buffer-local text objects with the same key would override each other.
Instead, make the functions created by
CountJump#TextObject#MakeWithCountSearch() and
CountJump#Region#TextObject#Make() buffer-scoped by prefixing "s:B" and the
buffer number.

1.83 23-Jan-2014

Use more canonical way of invoking the Funcrefs in
CountJump#Motion#MakeBracketMotionWithJumpFunctions(); this will then also

work with passed String function names.

FIX: Need to save v:count1 before issuing the normal mode "gv" command.
Minor: Make substitute() robust against 'ignorecase'.
Add optional dependency to ingo-library (vimscript #4433).

1.82 30-Oct-2012 (unreleased)

FIX: In text objects, when the end position is before the begin position,
that's not a valid selection. Test for this and abort in that case.
For linewise selections, always position the cursor at the start of the end
line to be consistent with the built-in text objects, and to avoid

complicating the search patterns when attempting to do this through them.

1.81 16-Oct-2012

ENH: Add optional a:searchName argument to
CountJump#Motion#MakeBracketMotion() to make searches wrap around when

'wrapscan' is set. Custom jump functions can do this since version 1.70;
now, this can also be utilized by motions defined via a search pattern.

BUG: Wrong variable scope for copied a:isBackward in
CountJump#CountSearchWithWrapMessage().

1.80 15-Oct-2012

FIX: In CountJump#TextObject#TextObjectWithJumpFunctions(), do not beep when
there's no end position. In this case, the jump function (often

CountJump#CountSearch()) should have emitted a beep already, and we want to
avoid a double beep.

Also handle move to the buffer's very last character in operator-pending
mode with a pattern to end "O" motion.
Add CountJump#CountJumpFuncWithWrapMessage() / CountJump#CountJumpFunc() to
help implement custom motions with only a simple function that performs a

single jump.

FIX: Visual end pattern / jump to end with 'selection' set to "exclusive"
also requires the special additional treatment of moving one right, like

operator-pending mode.

BUG: Operator-pending motion with end pattern / jump to end operates on one
character too few when moving to begin.
Clear any previous wrap message when wrapping is enabled; it's confusing
otherwise.

1.70 03-Sep-2012

ENH: Check for searches wrapping around the buffer and issue a corresponding
warning, like the built-in searches do. Though the mappings that can be made

with CountJump currently do not use 'wrapscan', other plugins that define
their own jump functions and use the CountJump#CountJump() function for it
may use it. Create function overloads CountJump#CountJumpWithWrapMessage()
and CountJump#CountSearchWithWrapMessage().

1.60 27-Mar-2012

ENH: Allow motions that do not start with [ / ] and text objects that do not
start with i / a by passing keys that begin with <Plug>. With this, plugins

using CountJump can offer the expected customizability. Since most users
probably still prefer the default keys, it is recommended that plugins do
not use <Plug> mappings from the start, but make the a:keyAfterBracket /
a:inverseKeyAfterBracket / a:textObjectKey configurable via a
g:PluginName_mapping variable, and instruct users to set this to
"<Plug>PluginName%s" and create their own mappings based on them, as
described in CountJump-integration.

1.50 30-Aug-2011

For regions of lines, also support a match()-like Funcref instead of a
pattern to define the range. This for example enables to define a range of

diff changes via a predicate function that checks diff_hlID() != 0.

Initialize global g:CountJump_Context object for custom use by Funcrefs.

1.41 13-Jun-2011

FIX: Directly ring the bell to avoid problems when running under :silent!.

1.40 20-Dec-2010

ENH: Added CountJump#Region#TextObject#Make() to easily define text objects
for regions.
Interface change: Jump functions again return position (and actual,
corrected one for a:isToEndOfLine). Though the position is not used for

motions, it is necessary for text objects to differentiate between "already
at the begin/end position" and "no such position".

1.30 20-Dec-2010

ENH: Added CountJump#Region#Motion#MakeBracketMotion() to easily define
bracket motions for regions.
Interface changes:
- Jump functions don't necessarily return jump position any more; this
  special case is only required for text objects.
- Moved CountJump#Region#Jump() to CountJump#JumpFunc().
- Added a:isToEndOfLine argument to CountJump#Region#JumpToRegionEnd() and
  CountJump#Region#JumpToNextRegion(), which is useful for operator-pending
and characterwise visual mode mappings; the entire last line will then be
operated on / selected.
- Added a:isMatch argument to CountJump#Region#SearchForRegionEnd(),
  CountJump#Region#JumpToRegionEnd(),
CountJump#Region#SearchForNextRegion(),
CountJump#Region#JumpToNextRegion(). This allows definition of regions via
non-matches, which can be substantially simpler (and faster to match) than
coming up with a "negative" regular expression.

1.22 06-Aug-2010

No more motion mappings and text objects for select mode; as the mappings
start with a printable character, no select-mode mapping should be defined.

1.21 03-Aug-2010

FIX: A 2]] jump inside a region (unless last line) jumped like a 1]] jump.
The search for next region must not decrease the iteration counter when

not searching across the region.

FIX: Must not do (characterwise) end position adaptation for linewise text
object that does not exclude boundaries.
Switched example from email fortunes to Pascal begin..end blocks, as they
are conceptually easier.

1.20 02-Aug-2010

ENH: In CountJump#Motion#MakeBracketMotion(), a:keyAfterBracket and
a:inverseKeyAfterBracket can now be empty, the resulting mappings are then
1. Likewise, any jump function can be empty in
  CountJump#Motion#MakeBracketMotionWithJumpFunctions().
With the added CountJump#Motion#MakeBracketMotionWithJumpFunctions() motions
can be defined via jump functions, similar to how text objects can be

defined.

Added CountJump/Region.vim to move to borders of a region defined by lines
matching a pattern.
FIX: CountJump#CountJump() with mode "O" didn't add original position to
jump list.
The previous visual selection is kept when the text object could not be
1. (Beforehand, a new selection of the text object's selection type
2. created.)
The adjustment movements after the jumps to the text object boundaries now
do not cause beeps if that movement cannot be done (e.g. a 'j' at the end of

the buffer).

1.10 19-Jul-2010

Changed behavior if there aren't [count] matches: Instead of jumping to the
last available match (and ringing the bell), the cursor stays at the

original position, like with the old vi-compatible motions.

ENH: Only adding to jump list if there actually is a match. This is like the
built-in Vim motions work.
FIX: For a linewise text object, the end cursor column is not important; do
not compare with the original cursor column in this case.

1.00 22-Jun-2010

First published version.

0.01 14-Feb-2009

Started development.

Maintainer: Ingo Karkat <ingo@karkat.de>

Ⅰ. 插件描述

Ⅱ. 基本信息

Ⅲ. 安装方法

使用Vundle管理器安装

使用NeoBundle管理器安装

使用VimPlug管理器安装

使用Pathogen管理器安装

Ⅳ. 文档说明

COUNT JUMP

DESCRIPTION

SEE ALSO

RELATED WORKS

USAGE

EXAMPLE

INSTALLATION

DEPENDENCIES

INTEGRATION

KNOWN PROBLEMS

IDEAS

CONTRIBUTING

HISTORY

1.91 RELEASEME

1.90 11-Feb-2018

1.86 24-Jul-2017

1.85 23-Dec-2014

1.84 25-Apr-2014

1.83 23-Jan-2014

1.82 30-Oct-2012 (unreleased)

1.81 16-Oct-2012

1.80 15-Oct-2012

1.70 03-Sep-2012

1.60 27-Mar-2012

1.50 30-Aug-2011

1.41 13-Jun-2011

1.40 20-Dec-2010

1.30 20-Dec-2010

1.22 06-Aug-2010

1.21 03-Aug-2010

1.20 02-Aug-2010

1.10 19-Jul-2010

1.00 22-Jun-2010

0.01 14-Feb-2009

添加新评论