swapit.txt Extensible Keyword Swapper Author: Michael Brown Usage Notes 1. SwapIt Introduction |swapit-intro| 2. Setup |swapit-setup| 2.1 Requirements |swapit-requirements| 2.2 Installation |swapit-installation| 2.3 Bugs |swapit-bugs| 2.4 Limitations/Annoyances |swapit-annoyances| 3. Swapping 3.1 Built in swap lists |swapit-builtin| 3.2 Defining a swap list |swapit-define| 3.3 xml/html swaps |swapit-html| 3.4 Multi word swaps |swapit-multiword| 4. Filetype Swaps |swapit-filetype| 4.1 Defining a filetype swap list |swapit-cleanup| 5. Omnicomplete Swapping |swapit-omnicomplete| ================================================================================ 1. SwapIt Introduction *swapit-intro* swapit.vim is a plugin designed to make it easier to perform common changes to various filetypes. It's designed to fill a niche where onmnicomplete for a given filetype is not providing any options. It is very easy to define your own lists for your own projects. It's most effective if you have a set of keywords between 2 and 10 in size. By default it uses the increment/decrement keystrokes |ctrl-a| |ctrl-x|. Although this can be custom mapped for screen users. A simple builtin example: setting=false moving the cursor over false in normal mode and pressing ctrl-a will result in setting=true The git repository is here http://github.com/mjbrownie/swapit/tree/master. I'd appreciate any additions. ================================================================================ 2. Setup *swapit-setup* 2.1 Requirements *swapit-requirements* Swapit has been tested on vim 7.0. If you are looking to use the xml/html tag complete option you need to have matchit.vim working correctly. 2.2 Installation *swapit-installation* Copy the swapit.tar.gz file in your ~/.vim/ directory and extract. 2.3 Bugs *swapit-bugs* This is still a work in progress. There are still some bugs where the swap gets stuck in visual mode and on some line extremities the cursor can jump away from where you want it. In some cases having |'selection'| set to exclusive mode can break things. Try: :set selection=inclusive 2.4 Limitations/Annoyances *swapit-annoyances* Swapping is based on naive lists so the biggest limitation is when there is the same keyword in more than one list. If this happens then a selection box comes up where you decide which list to use, but its not as smoothe an operation. To combat this issue lists are filetype specific. For example if you have the following two lists: :SwapList octave do re me fa so la ti :SwapList self me myself I trying to swap the keyword 'me' will result in an option list coming up. Swap Options: A . octave (me > fa) B . self (me > myself) (A), (B): It would probably be possible to differentiate lists with some regex but this plugin is probably overkill already. ================================================================================ 3 Swapping 3.1 Built in swap lists *swapit-builtin* swapit has a number of obvious lists defined eg. yes/no true/false etc. 3.2 Defining a swap list *SwapList* *swapit-define* :SwapList .. eg. :SwapList roman I II III IV V VI VII VIII IX X 3.3 xml/html swaps *swapit-html* One of the most recent and useful features is you can swap xml/html tags. If you vim has matchit.vim loaded you can swap. Eg:

This should be an h1

ctrl-a on the p will cycle to...

This should be an h1

This behavior is defined by the command SwapXmlMatchit which is as follows SwapXmlMatchit ... ~/.vim/after/ftplugin/html_swapit.vim SwapList formats h1 h2 h3 h4 p strong em a SwapList layout div span script style SwapXmlMatchit formats layout 3.4 Multi word swaps *swapit-multiword* swapit can handle multiword swapping by entering into visual mode. I wrote it and didn't find a use for it so defining multiword swaps isn't as easy as single word swaps. you could manually define a list. ~/.vim/after/ftplugin/{filetype}_swapit.vim ClearSwapList let g:swap_lists = [ \{'name':'hello_world', 'options': \['Hello World!','GoodBye Cruel World!' , 'See You Next Tuesday!']}, ... \] etc. ================================================================================ 4. Filetype Swaps 4.1 Defining a filetype swap list *SwapIdea* *swapit-filetype* The command :SwapIdea will open ~/.vim/after/ftplugin/{filetype}_swapit.vim The filetype file can be used to define custom swaps for 4.2 Clearing a Swap List *ClearSwapList* *swapit-cleanup* The ClearSwapList command cleans up existing swap lists. Its useful to put this at the top of an after/ftplugin file. ClearSwapList 5. Omnicomplete Swapping *swapit-omnicomplete* Rather than repeating SwapLists that are similar to omnicomplete patterns it would be more preferable to use the omnicomplete function for the language. Swapit is capable of experimental looking up omnicomplete patterns currently only for CSS as of writing. I'd appreciate any ideas and additions in this area. For additions please fork. http://github.com/mjbrownie/swapit/tree/master Example of setting up a callback swapit function is as follows Firstly define the callback function in the after/ftplugin/_swapit.vim file Eg in after/ftplugin/css_swapit.vim let b:swap_completefunc = 'cssswapit#CssSwapComplete' then define a function in the autoload folder autoload/cssswapit.vim. The function must take one argument specifying the direction 'forward' or 'backward' and return 1 on a successful swap or 0 if no matches are made. Look at the cssswapit for an example.