Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 347 lines (297 sloc) 14.963 kB
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
1 *TextTransform.txt* Create text transformation mappings and commands.
2
3 TEXT TRANSFORM by Ingo Karkat
4 *TextTransform.vim*
5 description |TextTransform-description|
6 usage |TextTransform-usage|
7 installation |TextTransform-installation|
8 limitations |TextTransform-limitations|
9 known problems |TextTransform-known-problems|
10 todo |TextTransform-todo|
11 history |TextTransform-history|
12
13 ==============================================================================
14 DESCRIPTION *TextTransform-description*
15
16 This plugin allows you to build your own text transformations. You only supply
17 the transformation algorithm in the form of a Vim function that takes a string
18 and returns the transformed text (think |substitute()|), and TextTransform
19 will create all appropriate mappings and / or commands with a single call!
20
21 Do you often perform the same |:substitute| commands over and over again? You
22 may be able to save yourself a lot of typing by creating custom commands and
23 mappings for it. Because the mappings (like built-in Vim commands such as |gU|
24 or |g?|) are applicable to text moved over by {motion}, entire lines, and the
25 visual selection, you'll also have way more flexibility and places where you
26 can apply them (compared to the line-based range of :substitute).
27
28 RELATED WORKS *
29
30 - Idea, design and implementation are based on Tim Pope's unimpaired.vim
31 plugin (vimscript #1590). It implements XML, URL and C String encoding
32 mappings, but isn't extensible with other algorithms.
33 The TextTransform plugin enhances unimpaired's transformation function with
34 handling of text objects and a list of selection fallbacks, and allows to
35 not only create mappings, but also transformation commands.
36
37 ==============================================================================
38 USAGE *TextTransform-usage*
39
40 *TextTransform#MakeMappings()*
4509deb Version 1.01
Ingo Karkat authored
41 TextTransform#MakeMappings( {mapArgs}, {key}, {algorithm} [, {selectionModes}] )
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
42
43 Create normal and visual mode mappings that apply
44 {algorithm} to the text covered by {motion}, [count]
45 line(s), and the visual selection.
46
47 When {key} is <Leader>xy, the following mappings will
48 be created:
49 - <Leader>xy{motion} applies to moved-over text
50 - <Leader>xyy applies to entire current line
51 - {Visual}<Leader>xy applies to visual selection
52 For the linewise normal mode mapping, the last
53 character of {key} is doubled, as is customary in Vim.
54
55 When {key} is empty, only <Plug> mappings are created;
56 mappings are also skipped when there are existing
57 mappings to the <Plug> mappings. When {algorithm} is
58 "MyTransform", the following <Plug> mappings are
59 generated: >
60 nmap <Plug>TextTMyTransformOperator
61 nmap <Plug>TextTMyTransformLine
62 vmap <Plug>TextTMyTransformVisual
63 < Use this to selectively override or disable individual
64 mappings.
65
66 |:map-arguments| can be passed in {mapArgs}, e.g.
67 "<buffer>" to make the generated mappings
68 buffer-local.
69 *TextTransform-algorithm*
70 {algorithm} is the name of a function: "MyTransform",
71 or a |Funcref|: function("MyTransform"). This function
72 must take one string argument and return a string. >
73 function MyTransform( text )
74 return '[' . toupper(a:text) . ']'
75 endfunction
76 < When the text that the mapping applies to spans more
77 than one line, {algorithm} is invoked only once with
78 the entire, newline-delimited text. You need to
79 consider that when using regular expression atoms like
6ee1e40 Version 1.10
Ingo Karkat authored
80 |^| and |$|. *g:TextTransformContext*
81 If the algorithm needs to inspect the place in the
82 buffer from where the text was retrieved, this
83 information is provided in g:TextTransformContext, a
84 dictionary with the following keys:
d0befb8 Version 1.20
Ingo Karkat authored
85 "mapMode": indicates what triggered the
86 transformation, one of
87 "n": normal mode mapping for line(s)
88 e.g. <Leader>xyy
89 "o": operator pending mode mapping for
90 moved-over text
91 e.g. <Leader>xy{motion}
92 "v": visual mode mapping
93 e.g. {Visual}<Leader>xy
94 "c": custom Ex command
6ee1e40 Version 1.10
Ingo Karkat authored
95 "mode": indicates the selection mode, one of "v",
96 "V", or "^V" (like |visualmode()|)
97 "startPos": the start position of the text
98 "endPos" : the end position of the text
d0befb8 Version 1.20
Ingo Karkat authored
99 "arguments":List of optional passed command
100 arguments (when arguments have been
101 configured for a command; always empty
102 for mappings).
c3b3311 Version 1.24
Ingo Karkat authored
103 "isBang": Flag whether a [!] was passed to the
104 command; always 0 for mappings.
d0befb8 Version 1.20
Ingo Karkat authored
105 "isAlgorithmRepeat":
106 Flag whether the same
107 |TextTransform-algorithm| is used
108 (either through another mapping /
109 command invocation, or via a mapping
110 repeat |.|) as the last time.
111 "isRepeat": Flag whether the last used mapping
112 with the same algorithm has been
113 repeated via the |.| command. For
114 commands that process each line
115 individually, is 1 on subsequently
116 processed lines after the first line.
117
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
118 The function can |:throw| an exception to signal an
119 error. When the original text is returned,
120 TextTransform will print an error that nothing was
121 transformed. Do this when the transformation is not
122 applicable.
123
124 By default, the <Leader>xyy mapping will be applied to
125 the entire line. For some transformations, a different
126 default scope may make more sense, like the text
127 between quotes. After all, the <Leader>xyy mapping is
128 often faster than <Leader>xy{motion} or first doing a
129 visual selection, and is easiest to commit to muscle
130 memory, so it should "do what I mean".
131 *TextTransform-selectionModes*
132 The optional {selectionModes} argument is a single
133 text object (such as "aw"), motion (e.g. "$"),
881b68a Version 1.23
Ingo Karkat authored
134 |Funcref| (for a custom selection), /-delimited
135 "/{pattern}/" (which selects the text region under /
136 after the cursor that matches {pattern}), or the
137 string "lines", which represents the default behavior.
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
138 If you pass a list of these, TextTransform tries each
139 selectionMode, one after the other, until one captures
140 non-empty text. For example, the passed list ['i"',
141 "i'", "lines"] will cause TextTransform to first try
142 to capture the text inside double quotes, then fall
143 back to text inside single quotes when the first one
144 doesn't yield any text. Finally, the "lines" will
145 transform the entire line if the single quote capture
146 failed, too.
147 A custom function should create a visual selection and
148 return a non-zero value if the selection can be made.
149 (Otherwise, the next selectionMode in the list is
150 tried.) Here's a senseless example which selects
151 [count] characters to the right of the cursor: >
152 function! MySelect()
153 execute 'normal! lv' . v:count1 . "l\<Esc>"
154 return 1
155 endfunction
156 <
157 *TextTransform#MakeCommand()*
4509deb Version 1.01
Ingo Karkat authored
158 TextTransform#MakeCommand( {commandOptions}, {commandName}, {algorithm} [, {options}] )
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
159
160 Create a custom command {commandName} that takes a
161 range (defaulting to the current line), and applies
c3b3311 Version 1.24
Ingo Karkat authored
162 {algorithm} to the line(s). With an optional [!], the
163 usual "Nothing transformed" error is suppressed.
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
164
165 |:command| attributes can be passed in
166 {commandOptions}. For example, pass "-range=%" to make
167 the command apply to the entire buffer when no range
d0befb8 Version 1.20
Ingo Karkat authored
168 is specified. You can pass "-nargs=..." to pass
169 arguments to the algorithm (via
170 |g:TextTransformContext|.arguments).
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
171
172 {algorithm} is the name of a function or a |Funcref|,
173 cp. |Transform-algorithm|.
174
175 The optional {options} dictionary can contain the
176 following keys:
177 isProcessEntireText Flag whether all lines are passed as one
178 newline-delimited string to {algorithm}, like mappings
179 from |TextTransform#MakeMappings()| do. Off by
180 default, so that each line is passed to {algorithm}
181 individually (without the newline). This allows for a
d0befb8 Version 1.20
Ingo Karkat authored
182 more efficient transformation. For subsequent lines,
183 |g:TextTransformContext|.isRepeat is set to 1.
184 You need to enable this if {algorithm} transforms the
185 newline, adds or removes lines.
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
186
187 *TextTransform#MakeSelectionCommand()*
188 TextTransform#MakeSelectionCommand( {commandOptions}, {commandName}, {algorithm}, {selectionModes} )
189
190 Create a custom command {commandName} that applies
191 {algorithm} on the |TextTransform-selectionModes|
192 specified by {selectionModes}, or the current visual
193 selection (when invoked from visual mode).
194 This is useful for algorithms that do not make sense
195 on entire lines. It's the command-variant of the
196 line-based mapping created by
197 |TextTransform#MakeMappings()|. For seldomly used
198 transformations, a command may have advantages over a
199 mapping: It doesn't take up precious mapping keys and
200 is more explorable via command-line completion.
201
202 Rest of the arguments as with |TextTransform#MakeCommand()|.
203
204
205 EXAMPLE *TextTransform-example*
206
207 Here's a stupid transformation function that replaces all alphabetic
208 characters with "X": >
209 function! BlankOut( text )
210 return substitute(a:text, '\a', 'X', 'g')
211 endfunction
212 With this, this single call: >
213 call TextTransform#MakeMappings('', '<Leader>x', 'BlankOut')
214 creates this set of mappings:
215
216 <Leader>x{motion} transforms the text covered by {motion}
217 <Leader>xx transforms [count] line(s)
218 {Visual}<Leader>x transforms the visual selection
219
220 You can set up a command for this transformation just as easily: >
221 call TextTransform#MakeCommand('', 'TextBlankOut', 'BlankOut')
222 so you can blank out the next three lines via >
223 :.,.+2TextBlankOut
224 <
225 ==============================================================================
226 INSTALLATION *TextTransform-installation*
227
228 This script is packaged as a |vimball|. If you have the "gunzip" decompressor
6f818e6 Version 1.03
Ingo Karkat authored
229 in your PATH, simply edit the *.vmb.gz package in Vim; otherwise, decompress
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
230 the archive first, e.g. using WinZip. Inside Vim, install by sourcing the
231 vimball or via the |:UseVimball| command. >
6f818e6 Version 1.03
Ingo Karkat authored
232 vim TextTransform*.vmb.gz
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
233 :so %
234 To uninstall, use the |:RmVimball| command.
235
236 DEPENDENCIES *TextTransform-dependencies*
237
238 - Requires Vim 7.0 or higher.
30df295 Version 1.21
Ingo Karkat authored
239 - Requires the |ingo-library.vim| plugin (vimscript #4433), version 1.015 or
fa2dd0d Version 1.11
Ingo Karkat authored
240 higher.
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
241 - repeat.vim (vimscript #2136) plugin (optional)
242 - visualrepeat.vim (vimscript #3848) plugin (optional)
243
244 ==============================================================================
245 LIMITATIONS *TextTransform-limitations*
246
247 KNOWN PROBLEMS *TextTransform-known-problems*
248
249 TODO *TextTransform-todo*
250
251 IDEAS *TextTransform-ideas*
252
d0befb8 Version 1.20
Ingo Karkat authored
253 - Provide a :[range]TextTransform {commandName1} [{commandName2} ...] with
254 custom completion of defined commands that applies all transformations to
255 the same [range]. Suggested by Zhao Cai.
256 - Offer utility functions to split the text according to the used syntax
257 groups (through g:TextTransformContext and synID()), to simplify selective
258 application in algorithms. Suggested by Zhao Cai.
259
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
260 ==============================================================================
261 HISTORY *TextTransform-history*
262
c3b3311 Version 1.24
Ingo Karkat authored
263 1.24 19-Jun-2014
264 - ENH: Allow optional [!] for made commands, and suppress the "Nothing
265 transformed" error in that case. This can help when using the resulting
266 command as an optional step, as prefixing with :silent! can be difficult to
267 combine with ranges, and would suppress _all_ transformation errors.
268 - ENH: Add g:TextTransformContext.isBang (for custom transformation commands).
269
881b68a Version 1.23
Ingo Karkat authored
270 1.23 31-May-2014
271 - ENH: Support selection mode "/{pattern}/", which selects the text region
272 under / after the cursor that matches {pattern}.
273 - Minor: Also handle :echoerr in the algorithm.
274
46902dd Version 1.22: - Add TextTransform/Selections.vim.
Ingo Karkat authored
275 1.22 06-Mar-2014
276 - Add TextTransform/Selections.vim.
277
30df295 Version 1.21
Ingo Karkat authored
278 1.21 15-Jan-2014
279 - Minor: Use functions for newer ingo-library.
280 - Need to use ingo#compat#setpos() to restore the selection in Vim versions
281 before 7.3.590.
282 *** You need to update to ingo-library (vimscript #4433) version 1.015! ***
283
d0befb8 Version 1.20
Ingo Karkat authored
284 1.20 25-Sep-2013
285 - Minor: Make substitute() robust against 'ignorecase'.
286 - FIX: When the selection mode is a text object, and the text is at the end of
287 the line, the replacement is inserted one-off to the left.
288 - Implement abort on error for generated commands.
289 - Add g:TextTransformContext.mapMode context information so that
290 transformations can query from which source (line- or motion-mapping, or
291 custom command) they've been triggered.
292 - Add g:TextTransformContext.isAlgorithmRepeat and
293 g:TextTransformContext.isRepeat context information (the latter through
294 additional <Plug>TextR... mappings) so that transformations that e.g. query
295 the user for something can skip the query and re-use the previously entered
296 value on a repeat of the mapping. It also allows commands that process the
297 lines individually to do different processing (or caching of expensive
298 values) for the first processed line.
299 - Allow to pass command arguments, which are then accessible to the algorithm
300 through g:TextTransformContext.arguments.
301
fa2dd0d Version 1.11
Ingo Karkat authored
302 1.11 17-May-2013
303 - Avoid changing the jumplist.
304 - Add dependency to ingo-library (vimscript #4433).
305 - FIX: When the selection mode is a text object, must still establish a visual
306 selection of the yanked text so that g:TextTransformContext contains valid
307 data for use by a:algorithm.
308
6ee1e40 Version 1.10
Ingo Karkat authored
309 1.10 19-Jan-2013
310 - FIX: In a blockwise visual selection with $ to the end of the lines, only
311 the square block from '< to '> is transformed. Need to yank the selection
312 with gvy instead of defining a new selection with the marks, a mistake
313 inherited from the original unimpaired.vim implementation.
314 - Save and restore the original visual area to avoid clobbering the '< and '>
315 marks and gv by line- and motion mappings.
316 - Temporarily set g:TextTransformContext to the begin and end of the currently
317 transformed area to offer an extended interface to algorithms.
318
6f818e6 Version 1.03
Ingo Karkat authored
319 1.03 05-Sep-2012
320 - For the custom operators, handle readonly and nomodifiable buffers by
321 printing just the warning / error, without the multi-line function error.
322 - Avoid clobbering the expression register (for commands that use
323 options.isProcessEntireText).
324
144df14 Version 1.02
Ingo Karkat authored
325 1.02 28-Jul-2012
326 Avoid "E706: Variable type mismatch" when TextTransform#Arbitrary#Expression()
327 is used with both Funcref- and String-type algorithms.
328
4509deb Version 1.01
Ingo Karkat authored
329 1.01 05-Apr-2012
330 In mappings and selection commands, place the cursor at the beginning of the
331 transformed text, to be consistent with built-in transformation commands like
332 gU, and because it makes much more sense.
333
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
334 1.00 05-Apr-2012
335 First published version.
336
337 0.01 07-Mar-2011
338 Started development.
339
340 ==============================================================================
30df295 Version 1.21
Ingo Karkat authored
341 Copyright: (C) 2011-2014 Ingo Karkat
fa2dd0d Version 1.11
Ingo Karkat authored
342 The VIM LICENSE applies to this plugin; see |copyright|.
46bd1c6 Version 1.00: Initial upload
Ingo Karkat authored
343
344 Maintainer: Ingo Karkat <ingo@karkat.de>
345 ==============================================================================
346 vim:tw=78:ts=8:ft=help:norl:
Something went wrong with that request. Please try again.