VIM plugin for TrafficScript Auto-Completion (01/06/2011)
For all those of you who use VIM as the editor of choice, this plugin helps you write TrafficScript with a lot more ease. The plugin, fairly named ZeusTSComplete, provides code completion, syntax highlighting, function descriptions and rule compilation by only using a handful of keys.
Note: This plugin only works on Unix based systems for VIM 7.0 and above.
Installation
Use the following steps to install the ZeusTSComplete plugin.
Download the file attached to this article and unzip it to your "~/.vim" directory by doing unzip zeus_zts_vimplugin-1.0.zip -d ~/.vim/
The following files will be unzipped to the ~/.vim directory.
after/ftplugin/zts.vim
autoload/zeus/zts/complete.vim
/functions.vim
/popup.vim
/maycomplete.vim
/compile.vim
/settings.vim
/utils.vim
/functions.txt
doc/zeuscomplete.txt
- Update your ~/.vimrc file with the following settings -
set nocp
filetype plugin on "Load filetype plugins.
set completeopt=menuone,menu,longest,preview "Omni Complete options.
syntax on "syntax highlighting.
set shiftwidth=3 "indent with three space
set smartindent "auto-indent.
The 'shiftwidth' and 'smartindent' options are not required by the plugin, but they help in auto-indenting code files.
- Update filetype: For VIM to recognize that a particular file is of 'TrafficScript' type, create a file '~/.vim/after/filetype.vim' and add these lines to that file
augroup filetypedetect
au BufNewFile,BufRead .zts,/conf/rules/* set filetype=zts syn=zts
augroup END
This will tell VIM to recognize any file ending with '.zts' suffix or a file in '/conf/rules/' directory as a TrafficScript file and load the ZeusTSComplete plugin for it. You can also add these lines to your '.vimrc' files to get things working, but that would be less optimized.
- Update help: Open a file with '.zts' suffix and do ":helptags ~/.vim/doc". The help menu will be displayed using ":help ztscomplete"
To verify that the installation works, open a file with a '.zts' suffix and write some trafficscript code and use '.' and TAB to see if a pop-up menu appears. You will be able to use almost all features of the plugin fairly intuitively, but for more details read on...
Using the plugin
The plugin basically remaps the TAB and the '.' keys to provide auto-completion and function description. After the plugin is all set and working, a VIM TrafficScript editing session will look like:
Key mappings
Here are the key mappings to be used to trigger various features of this plugin.
- TAB : Auto complete a TrafficScript a module or function name. You can write part of a word and press TAB to see the possible TrafficScript function names that start with that word. If the word is a TrafficScript variable( i.e it starts with a '$' ) then TAB will show all variable names in the file starting with that token.
- Ctrl-X Ctrl-O: This key combination is the standard key-map to do auto-completion for OmniComplete. It works in the same way as the TAB, but TAB is certainly the way to go.
- '.' : As all TrafficScript functions are of type 'module.submodule.function' ( where submodule is optional ), the plugin remaps the '.' key to give a list of functions used by that module. The list of functions is shown in a pop-up menu which can be navigated using the Up/Down key. When selecting a function name from a pop-up menu, the description, parameters and sample code for that function will be displayed in a preview window.
- Ctrl-P: Use this keymap in Insert mode to close a preview window.
- ')' : When a function description is shown in a preview window, it's left open while you are typing the arguments for ease of lookup. As soon as you complete the function signature using the ')' key, the preview window will automatically close.
- F5: Compile the current rule. The environment variable 'ZEUSHOME' needs to point to the Stingray Traffic Manager installation.
- Ctrl-W Ctrl-P: In 'Normal' mode, this shuffles the cursor to and from the preview window. The preview window is set to be 30% of the window height, which accommodates most function descriptions. Use this keymap if it doesn't.
- Enter: If a function name is selected in the pop-up menu, it will insert the function and finish completion.
Syntax Highlighting
The syntax highlighting file is in ~/.vim/syntax/zts.vim which just overrides the syntax for perl with some additions and exceptions. To alter colours on the rule file you will need to edit the perl syntax colouring.
Editing existing rules
You can write new files with a '.zts' suffix to use the plugin and later copy them to the rules directory. The plugin also recognizes files in the '/conf/rules' directory to be TrafficScript files, so you may directly edit rule files from a Stingray Traffic Manager installation. The VIM user must either be root or in the sudoers file. Use sudo -E vim $ZEUSHOME/zxtm/conf/rules/test_rulename to edit a root installation rule file from a non-root user.+ Please note that editing files directly from inside a Stingray Installation is not supported and its recommended that you either use the CLI to upload rule files or see the "Integration with Firefox" section below.+
Settings
These settings modify a couple of features of the plugin.
- g:ZeusZTS_MayCompleteDot - Set :let ZeusZTS_MayCompleteDot=0 in the local buffer to disable auto-completion on '.'. You can add let ZeusZTS_MayCompleteDot=0 to your '.vimrc' file apply this setting to all buffers.
- g:ZeusZTS_AutoClosePreview - The preview window shows the function description for the function currently being written and is automatically closed when the ')' key is used. To disable this feature, add let ZeusZTS_AutoClosePreview=0 in '.vimrc' file.
For TrafficScript experts, who just want to see the function names and not their description in a preview window( a preview window every now and then can be annoying ), disable preview window by doing :set completeopt-=preview in the local buffer or by removing the 'preview' option from the 'completeopt' setting in your '.vimrc' file.
Integration with Firefox
Well, if you are used to writing rules from the Stingray Traffic Manager's UI and still want to use the slick features of this plugin, you can! Install the
<a title="iatplugin" href="https://addons.mozilla.org/en-US/firefox/addon/4125/" target="_blank">*IAT( Its all text ) plugin*</a>
in your Firefox browser. IAT helps you write code/text using the editor of your choice. To integrate the VIM editor to the IAT plugin, you will first need a script to fire VIM in a terminal. The script should look like
#!/bin/bash
#iat.sh
/usr/bin/rxvt -e vim [email protected]
Replace 'rxvt' above with the terminal you are using. Then, go to the firefox IAT plugin preferences( Tools/Its All Text/Preferences ) and update "Editor:" configuration to the above script (with absolute path). Also add ".zts" to the "File Extension" list on this window. We are almost there, just one more step...IAT can only edit plain text areas, so you will need to disable syntax highlighting for TrafficScript in the Stingray Traffic Managers UI. Go to Users>Local>admin and set user!admin!trafficscript_editor to 'No'. Go to a rule in the Rules page, right click on the 'edit' button just below the main text area and select "Edit as .zts". A vim session will be opened in your terminal with the auto-complete plugin loaded.
