Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 156 lines (127 sloc) 8.485 kb
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
1 This is a mirror of http://www.vim.org/scripts/script.php?script_id=3130
2
3 DESCRIPTION
4 Though it is not difficult to write a custom movement (basically a :map
5 that executes some kind of search or jump) and a custom text-object (an
6 :omap that selects a range of text), this is too complex for a novice user
660d37b Version 1.60
Ingo Karkat authored
7 and often repetitive.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
8 This plugin covers the common use case where the movement and boundaries of a
9 text object can be specified via start and end patterns, and offers a single
10 function to set up related mappings. With it, you can enhance some built-in
11 Vim mappings to take an optional [count], and quickly define new mappings for
660d37b Version 1.60
Ingo Karkat authored
12 help file sections, diff hunks, embedded macros, and so on...
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
13
14 As a generalization of the start and end patterns, the movement and boundaries
15 of a text object can also be specified via jump functions, i.e. Funcrefs of
16 functions that position the cursor on the appropriate location and return that
17 location. This can be used where the jump is difficult to express with a
18 single regular expression, the jump may need adapting depending on the
660d37b Version 1.60
Ingo Karkat authored
19 context, or other uses.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
20 This plugin contains some support for movement and text objects consisting of
21 text regions that can be defined by continuous lines that match a particular
660d37b Version 1.60
Ingo Karkat authored
22 pattern, e.g. comment blocks that all start with /^\s*#/.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
23
24 SEE ALSO
660d37b Version 1.60
Ingo Karkat authored
25 The following ftplugins use this plugin:
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
26
660d37b Version 1.60
Ingo Karkat authored
27 diff_movement (vimscript #3180): Movement over diff hunks with ]] etc.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
28 fortunes_movement (vimscript #3181): Movement over email fortunes with ]] etc.
29 help_movement (vimscript #3179): Movement over Vim help sections with ]] etc.
30 mail_movement (vimscript #3182): Movement over email quotes with ]] etc.
c2c7725 Version 1.83
Ingo Karkat authored
31 diffwindow_movement: Movement over changes in a diff window.
32 (vimscript #3719)
33 JumpToTrailingWhitespace: Motions to locate unwanted whitespace at the end of lines.
34 (vimscript #3968)
660d37b Version 1.60
Ingo Karkat authored
35 TaskMotion (vimscript #3990): Motions to task and TODO markers.
ebae8c2 Version 1.70
Ingo Karkat authored
36 ConflictMotions (vimscript #3991): Motions to and inside SCM conflict markers.
660d37b Version 1.60
Ingo Karkat authored
37 vim_movement (vimscript #4002): Movement over Vim functions with ]m etc.
38 vbs_movement (vimscript #4003): Movement over VBScript classes /
39 functions / properties / subs with ]m etc.
40 dosbatch_movement (vimscript #4004): Movement over MSDOS batch file functions
41 / labels with ]m etc.
c2c7725 Version 1.83
Ingo Karkat authored
42 SameSyntaxMotion (vimscript #4338): Motions to the borders of the same syntax highlighting.
43 JumpToVerticalOccurrence: Like f{char}, but searching the same
44 (vimscript #4841) screen column, not line.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
45
46 RELATED WORKS
47 - motpat.vim (vimscript #3030) offers similar functions to setup motion
660d37b Version 1.60
Ingo Karkat authored
48 mappings, but no text objects (yet).
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
49 - textobj-user (vimscript #2100) has support for user-defined text objects via
81c678e Version 1.84
Ingo Karkat authored
50 regular expressions, but they don't support selecting multiple via [count].
c2c7725 Version 1.83
Ingo Karkat authored
51 - movealong.vim (vimscript #4691) provides a :Movealong command (and optional
52 mappings) that repeatedly executes a motion until a condition of a syntax,
53 pattern match, or arbitrary expression is met.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
54
55 USAGE
56 The plugin defines several functions, which set up the appropriate mappings
57 based on the arguments that you supply. The following is an overview; you'll
58 find the details directly in the implementation files in the
660d37b Version 1.60
Ingo Karkat authored
59 .vim/autoload/CountJump/ directory.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
60
61 CountJump#Motion#MakeBracketMotion( mapArgs, keyAfterBracket, inverseKeyAfterBracket, patternToBegin, patternToEnd, isEndPatternToEnd, ... )
62
63 This function sets up mappings starting with [ and ] for movement (with
64 optional [count]) relative to the current cursor position, targeting either a
65 text pattern at the beginning ([{keyAfterBracket} mapping) or a text pattern
66 at the end (]{inverseKeyAfterBracket} mapping) of whatever you want to treat
660d37b Version 1.60
Ingo Karkat authored
67 as a text block.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
68
69 CountJump#Motion#MakeBracketMotionWithJumpFunctions( mapArgs, keyAfterBracket, inverseKeyAfterBracket, JumpToBeginForward, JumpToBeginBackward, JumpToEndForward, JumpToEndBackward, isEndJumpToEnd, ... )
70
71 This function sets up mappings starting with [ and ] for movement (with
72 optional [count]) relative to the current cursor position, but rely on four
660d37b Version 1.60
Ingo Karkat authored
73 passed jump functions instead of text patterns to do the movement.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
74
75 CountJump#TextObject#MakeWithCountSearch( mapArgs, textObjectKey, types, selectionMode, patternToBegin, patternToEnd )
76
77 Defines a complete set of mappings for inner and/or outer text objects that
78 support an optional [count] and are driven by search patterns for the
79 beginning and end of a block. Outer text objects include the matched pattern
660d37b Version 1.60
Ingo Karkat authored
80 text, inner ones not. Selection can be characterwise, linewise or blockwise.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
81
82 CountJump#TextObject#MakeWithJumpFunctions( mapArgs, textObjectKey, types, selectionMode, JumpToBegin, JumpToEnd )
83
84 This is a generalization of CountJump#TextObject#MakeWithCountSearch() that
85 invokes custom functions instead of searching for a fixed pattern. This is
86 useful if the check for a match is too complex for a single regular
87 expression, or if you need to adjust the match position depending on the
660d37b Version 1.60
Ingo Karkat authored
88 circumstances.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
89
90 Often, a region can be defined as a block of continuous lines that all match a
660d37b Version 1.60
Ingo Karkat authored
91 certain pattern (or, even more generic, where a provided predicate function
92 returns a match position). The following functions aid in implementing
93 movements to the boundaries of these regions and text objects consisting of
94 the region:
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
95
660d37b Version 1.60
Ingo Karkat authored
96 CountJump#Region#JumpToRegionEnd( count, Expr, isMatch, step, isToEndOfLine )
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
97
98 Starting from the current line, search for the position where the count'th
99 region ends. Use this function to build Funcrefs for forward / backward jumps
660d37b Version 1.60
Ingo Karkat authored
100 that can then be passed to CountJump#TextObject#MakeWithJumpFunctions().
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
101
660d37b Version 1.60
Ingo Karkat authored
102 CountJump#Region#JumpToNextRegion( count, Expr, isMatch, step, isAcrossRegion, isToEndOfLine )
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
103
104 Starting from the current line, search for the position where the count'th
660d37b Version 1.60
Ingo Karkat authored
105 region begins/ends.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
106
660d37b Version 1.60
Ingo Karkat authored
107 CountJump#Region#Motion#MakeBracketMotion( mapArgs, keyAfterBracket, inverseKeyAfterBracket, Expr, isMatch, ... )
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
108
0a0ac1c Version 1.30
Ingo Karkat authored
109 This function sets up mappings starting with [ and ] for movement (with
110 optional [count]) relative to the current cursor position, targeting a text
660d37b Version 1.60
Ingo Karkat authored
111 region defined by contiguous lines that (don't) match a:Expr.
0a0ac1c Version 1.30
Ingo Karkat authored
112
660d37b Version 1.60
Ingo Karkat authored
113 CountJump#Region#TextObject#Make( mapArgs, textObjectKey, types, selectionMode, Expr, isMatch )
0a0ac1c Version 1.30
Ingo Karkat authored
114
115 Defines a complete set of mappings for inner and/or outer text objects that
116 support an optional [count] and select regions of lines which are defined by
660d37b Version 1.60
Ingo Karkat authored
117 contiguous lines that (don't) match a:Expr.
0a0ac1c Version 1.30
Ingo Karkat authored
118 The inner text object comprises all lines of the region itself, while the
119 outer text object also includes all adjacent lines above and below which do
660d37b Version 1.60
Ingo Karkat authored
120 not themselves belong to a region.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
121
c2c7725 Version 1.83
Ingo Karkat authored
122 The custom Funcrefs for jumps and predicates of lines belonging to a range may
123 be invoked multiple times until the CountJump function arrives at its
124 destination. To help the Funcrefs to determine where in this sequence they
125 are, an empty g:CountJump_Context dictionary is initialized at the start of
126 each CountJump function. Funcrefs can put custom information (e.g. the
127 particular comment prefix on the current line) in there and evaluate this in
128 subsequent invocations.
129
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
130 EXAMPLE
131 Let's illustrate the usage by developing custom motions and text objects for
660d37b Version 1.60
Ingo Karkat authored
132 Pascal begin..end blocks.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
133
134 We want to move around blocks, and override the default section movements for
660d37b Version 1.60
Ingo Karkat authored
135 it:
136 ]] Go to [count] next start of a block.
137 ][ Go to [count] next end of a block.
138 [[ Go to [count] previous start of a block.
139 [] Go to [count] previous end of a block.
c2c7725 Version 1.83
Ingo Karkat authored
140 >
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
141 call CountJump#Motion#MakeBracketMotion('<buffer>', '', '', '\c^begin\n\zs', '\c^.*\nend', 0)
142 The begin pattern positions the cursor on the beginning of the line following
143 the "begin" keyword, the end pattern on the beginning of the line
660d37b Version 1.60
Ingo Karkat authored
144 preceding the "end" keyword.
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
145
146 We want to select a block, either including or excluding the lines with the
660d37b Version 1.60
Ingo Karkat authored
147 begin..end keywords:
148 ib "inner block" text object, select [count] contents of
149 a block.
150 ab "a block" text object, select [count] blocks.
c2c7725 Version 1.83
Ingo Karkat authored
151 >
f6067fc Version 1.00: Initial upload
Ingo Karkat authored
152 call CountJump#TextObject#MakeWithCountSearch('<buffer>', 'b', 'ai', 'V', '\c^begin\n', '\c^end.*$')
153
154 If there is a filetype detection for Pascal files, we can simply put the
660d37b Version 1.60
Ingo Karkat authored
155 above calls in a ~/.vim/ftplugin/pascal_movement.vim script and are done.
Something went wrong with that request. Please try again.