sponsor Vim development Vim logo Vim Book Ad

TextTransform : Create text transformation mappings and commands.

 script karma  Rating 17/5, Downloaded by 1049    Comments, bugs, improvements  Vim wiki

created by
Ingo Karkat
script type
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.

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.

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).

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).

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
install details
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.

- Requires Vim 7.0 or higher.
- Requires the ingo-library.vim plugin (vimscript #4433), version 1.015 or
- repeat.vim (vimscript #2136) plugin (optional)
- visualrepeat.vim (vimscript #3848) plugin (optional)

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
TextTransform-1.24.vmb.gz 1.24 2014-06-19 7.0 Ingo Karkat - ENH: Allow optional [!] for made commands, and suppress the "Nothing transformed" error in that case. This can help when using the resulting command as an optional step, as prefixing with :silent! can be difficult to combine with ranges, and would suppress _all_ transformation errors.
- ENH: Add g:TextTransformContext.isBang (for custom transformation commands).
TextTransform-1.23.vmb.gz 1.23 2014-05-31 7.0 Ingo Karkat - ENH: Support selection mode "/{pattern}/", which selects the text region under / after the cursor that matches {pattern}.
- Minor: Also handle :echoerr in the algorithm.
TextTransform-1.22.vmb.gz 1.22 2014-03-06 7.0 Ingo Karkat - Add TextTransform/Selections.vim.
TextTransform-1.21.vmb.gz 1.21 2014-01-15 7.0 Ingo Karkat - Minor: Use functions for newer ingo-library.
- Need to use ingo#compat#setpos() to restore the selection in Vim versions before 7.3.590.
TextTransform-1.20.vmb.gz 1.20 2013-09-25 7.0 Ingo Karkat - FIX: When the selection mode is a text object, and the text is at the end of the line, the replacement is inserted one-off to the left.
- Implement abort on error for generated commands.
- Add g:TextTransformContext.mapMode context information so that transformations can query from which source (line- or motion-mapping, or custom command) they've been triggered.
- Add g:TextTransformContext.isAlgorithmRepeat and g:TextTransformContext.isRepeat context information (the latter through additional <Plug>TextR... mappings) so that transformations that e.g. query the user for something can skip the query and re-use the previously entered value on a repeat of the mapping. It also allows commands that process the lines individually to do different processing (or caching of expensive values) for the first processed line.
- Allow to pass command arguments, which are then accessible to the algorithm through g:TextTransformContext.arguments.
- Minor: Make substitute() robust against 'ignorecase'.
TextTransform-1.11.vmb.gz 1.11 2013-05-17 7.0 Ingo Karkat - Avoid changing the jumplist.
- Add dependency to ingo-library (vimscript #4433).
- FIX: When the selection mode is a text object, must still establish a visual selection of the yanked text so that g:TextTransformContext contains valid data for use by a:algorithm.
TextTransform-1.10.vmb.gz 1.10 2013-01-21 7.0 Ingo Karkat - 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.
TextTransform-1.03.vmb.gz 1.03 2012-09-05 7.0 Ingo Karkat - 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 us  options.isProcessEntireText).
TextTransform.vba.gz 1.02 2012-07-30 7.0 Ingo Karkat Avoid "E706: Variable type mismatch" when TextTransform#Arbitrary#Expression() is used with both Funcref- and String-type algorithms.
TextTransform.vba.gz 1.01 2012-04-05 7.0 Ingo Karkat 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.
TextTransform.vba.gz 1.00 2012-04-05 7.0 Ingo Karkat Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
SourceForge.net Logo