Skip to content


Subversion checkout URL

You can clone with
Download ZIP
tag: 1.10
Fetching contributors…

Cannot retrieve contributors at this time

261 lines (218 sloc) 11.025 kB
*TextTransform.txt* Create text transformation mappings and commands.
description |TextTransform-description|
usage |TextTransform-usage|
installation |TextTransform-installation|
integration |TextTransform-integration|
limitations |TextTransform-limitations|
known problems |TextTransform-known-problems|
todo |TextTransform-todo|
history |TextTransform-history|
DESCRIPTION *TextTransform-description*
This plugin allows you to build your own text transformations. You only supply
the transformation algorithm in the form of a Vim function that takes a string
and returns the transformed text (think |substitute()|), and TextTransform
will create all appropriate mappings and / or commands with a single call!
Do you often perform the same |:substitute| commands over and over again? You
may be able to save yourself a lot of typing by creating custom commands and
mappings for it. Because the mappings (like built-in Vim commands such as |gU|
or |g?|) are applicable to text moved over by {motion}, entire lines, and the
visual selection, you'll also have way more flexibility and places where you
can apply them (compared to the line-based range of :substitute).
- Idea, design and implementation are based on Tim Pope's unimpaired.vim
plugin (vimscript #1590). It implements XML, URL and C String encoding
mappings, but isn't extensible with other algorithms.
The TextTransform plugin enhances unimpaired's transformation function with
handling of text objects and a list of selection fallbacks, and allows to
not only create mappings, but also transformation commands.
USAGE *TextTransform-usage*
TextTransform#MakeMappings( {mapArgs}, {key}, {algorithm} [, {selectionModes}] )
Create normal and visual mode mappings that apply
{algorithm} to the text covered by {motion}, [count]
line(s), and the visual selection.
When {key} is <Leader>xy, the following mappings will
be created:
- <Leader>xy{motion} applies to moved-over text
- <Leader>xyy applies to entire current line
- {Visual}<Leader>xy applies to visual selection
For the linewise normal mode mapping, the last
character of {key} is doubled, as is customary in Vim.
When {key} is empty, only <Plug> mappings are created;
mappings are also skipped when there are existing
mappings to the <Plug> mappings. When {algorithm} is
"MyTransform", the following <Plug> mappings are
generated: >
nmap <Plug>TextTMyTransformOperator
nmap <Plug>TextTMyTransformLine
vmap <Plug>TextTMyTransformVisual
< Use this to selectively override or disable individual
|:map-arguments| can be passed in {mapArgs}, e.g.
"<buffer>" to make the generated mappings
{algorithm} is the name of a function: "MyTransform",
or a |Funcref|: function("MyTransform"). This function
must take one string argument and return a string. >
function MyTransform( text )
return '[' . toupper(a:text) . ']'
< When the text that the mapping applies to spans more
than one line, {algorithm} is invoked only once with
the entire, newline-delimited text. You need to
consider that when using regular expression atoms like
|^| and |$|. *g:TextTransformContext*
If the algorithm needs to inspect the place in the
buffer from where the text was retrieved, this
information is provided in g:TextTransformContext, a
dictionary with the following keys:
"mode": indicates the selection mode, one of "v",
"V", or "^V" (like |visualmode()|)
"startPos": the start position of the text
"endPos" : the end position of the text
The function can |:throw| an exception to signal an
error. When the original text is returned,
TextTransform will print an error that nothing was
transformed. Do this when the transformation is not
By default, the <Leader>xyy mapping will be applied to
the entire line. For some transformations, a different
default scope may make more sense, like the text
between quotes. After all, the <Leader>xyy mapping is
often faster than <Leader>xy{motion} or first doing a
visual selection, and is easiest to commit to muscle
memory, so it should "do what I mean".
The optional {selectionModes} argument is a single
text object (such as "aw"), motion (e.g. "$"),
|Funcref| (for a custom selection), or the string
"lines", which represents the default behavior.
If you pass a list of these, TextTransform tries each
selectionMode, one after the other, until one captures
non-empty text. For example, the passed list ['i"',
"i'", "lines"] will cause TextTransform to first try
to capture the text inside double quotes, then fall
back to text inside single quotes when the first one
doesn't yield any text. Finally, the "lines" will
transform the entire line if the single quote capture
failed, too.
A custom function should create a visual selection and
return a non-zero value if the selection can be made.
(Otherwise, the next selectionMode in the list is
tried.) Here's a senseless example which selects
[count] characters to the right of the cursor: >
function! MySelect()
execute 'normal! lv' . v:count1 . "l\<Esc>"
return 1
TextTransform#MakeCommand( {commandOptions}, {commandName}, {algorithm} [, {options}] )
Create a custom command {commandName} that takes a
range (defaulting to the current line), and applies
{algorithm} to the line(s).
|:command| attributes can be passed in
{commandOptions}. For example, pass "-range=%" to make
the command apply to the entire buffer when no range
is specified.
{algorithm} is the name of a function or a |Funcref|,
cp. |Transform-algorithm|.
The optional {options} dictionary can contain the
following keys:
isProcessEntireText Flag whether all lines are passed as one
newline-delimited string to {algorithm}, like mappings
from |TextTransform#MakeMappings()| do. Off by
default, so that each line is passed to {algorithm}
individually (without the newline). This allows for a
more efficient transformation. You need to enable this
if {algorithm} transforms the newline, adds or removes
TextTransform#MakeSelectionCommand( {commandOptions}, {commandName}, {algorithm}, {selectionModes} )
Create a custom command {commandName} that applies
{algorithm} on the |TextTransform-selectionModes|
specified by {selectionModes}, or the current visual
selection (when invoked from visual mode).
This is useful for algorithms that do not make sense
on entire lines. It's the command-variant of the
line-based mapping created by
|TextTransform#MakeMappings()|. For seldomly used
transformations, a command may have advantages over a
mapping: It doesn't take up precious mapping keys and
is more explorable via command-line completion.
Rest of the arguments as with |TextTransform#MakeCommand()|.
EXAMPLE *TextTransform-example*
Here's a stupid transformation function that replaces all alphabetic
characters with "X": >
function! BlankOut( text )
return substitute(a:text, '\a', 'X', 'g')
With this, this single call: >
call TextTransform#MakeMappings('', '<Leader>x', 'BlankOut')
creates this set of mappings:
<Leader>x{motion} transforms the text covered by {motion}
<Leader>xx transforms [count] line(s)
{Visual}<Leader>x transforms the visual selection
You can set up a command for this transformation just as easily: >
call TextTransform#MakeCommand('', 'TextBlankOut', 'BlankOut')
so you can blank out the next three lines via >
INSTALLATION *TextTransform-installation*
This script is 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 TextTransform*.vmb.gz
:so %
To uninstall, use the |:RmVimball| command.
DEPENDENCIES *TextTransform-dependencies*
- Requires Vim 7.0 or higher.
- repeat.vim (vimscript #2136) plugin (optional)
- visualrepeat.vim (vimscript #3848) plugin (optional)
INTEGRATION *TextTransform-integration*
LIMITATIONS *TextTransform-limitations*
KNOWN PROBLEMS *TextTransform-known-problems*
TODO *TextTransform-todo*
IDEAS *TextTransform-ideas*
HISTORY *TextTransform-history*
1.10 19-Jan-2013
- FIX: In a blockwise visual selection with $ to the end of the lines, only
the square block from '< to '> is transformed. Need to yank the selection
with gvy instead of defining a new selection with the marks, a mistake
inherited from the original unimpaired.vim implementation.
- Save and restore the original visual area to avoid clobbering the '< and '>
marks and gv by line- and motion mappings.
- Temporarily set g:TextTransformContext to the begin and end of the currently
transformed area to offer an extended interface to algorithms.
1.03 05-Sep-2012
- For the custom operators, handle readonly and nomodifiable buffers by
printing just the warning / error, without the multi-line function error.
- Avoid clobbering the expression register (for commands that use
1.02 28-Jul-2012
Avoid "E706: Variable type mismatch" when TextTransform#Arbitrary#Expression()
is used with both Funcref- and String-type algorithms.
1.01 05-Apr-2012
In mappings and selection commands, place the cursor at the beginning of the
transformed text, to be consistent with built-in transformation commands like
gU, and because it makes much more sense.
1.00 05-Apr-2012
First published version.
0.01 07-Mar-2011
Started development.
Copyright: (C) 2011-2013 Ingo Karkat
The VIM LICENSE applies to this script; see |copyright|.
Maintainer: Ingo Karkat <>
Jump to Line
Something went wrong with that request. Please try again.