There is no spoon
Vim is a text editor
Editing with Vim
So you want to join the legions of masochists that edit files using the archaic VI-style keybindings? Editing using a VI clone may have a massive learning curve, but by and large the speed gains you get when mastering the editor outstrip any need for GUI hand-holding. Using Vim is truly Zen and the Art of Editing Source (IMHO anyway ;)).
This is all you need to know: http://www.vim.org
This page isn't meant to be a tutorial on generic editing but I will point out a few pages that are very helpful:
- The Best of Vim Tips (very good stuff here) http://www.rayninfo.co.uk/vimtips.html
- Linux Productivity Magazine article about VI and Vim with lots of good info http://www.troubleshooters.com/lpm/200212/200212.htm
- The Vim Cookbook with some neat stuff to do http://www.oualline.com/vim-cook.html
Vim has built-in UnrealScript syntax highlighting!
- BufExplorer for switching between multiple files at the same time: http://www.vim.org/scripts/script.php?script_id=42
- TagList source code browser (uses Tags discussed below): http://www.vim.org/scripts/script.php?script_id=273
One of the more useful things you can do in Vim is the build in Tags support. Implemented correctly navigating around the UnrealScript source is as easy as moving your cursor over a class or function name and pressing CTRL-]. This will open the associated file in a new buffer. Pressing CTRL-t will pop you back into the previously viewed file.
Getting all this to work correctly is a bit tricky, however. I suggest you take a look at the UltraEdit page which has thorough explanation of setting up the ctags file. Here are a couple of caveats:
- I use the default name 'tags' for all of my tag files since I'm editing different types of source and it's easier to use one filename than have to specify different filenames for every source I use tags with.
- Because of this my command for running ctags is
ctags --options=ctags.cfg -V -f "C:\UT2003\tags" "C:\UT2003"
- -V- is for verbose
- --options=ctags.cfg-- sets a file that holds command-line options (next caveat)
- Because of this my command for running ctags is
- I've updated the ctags config file from the UltraEdit page because I was getting odd results. This one works for UT2k3 (ctags.cfg):
--langdef=INI --langmap=INI:.ini --regex-INI=/^[ \t]*\[(.*)\]/\1/b,block/ --regex-INI=/^[ \t]*([^\[=]+)=(.*)/\1/k,key/ --langdef=unrealscript --langmap=unrealscript:.uc --regex-unrealscript=/^[ \t]*[cC]lass[ \t]*([a-zA-Z0-9_]+)/\1/c,class/ --regex-unrealscript=/^[ \t]*[sS]tate[() \t]*([a-zA-Z0-9]+)/\1/s,state/ --regex-unrealscript=/^[ \t]*[sS]imulated[ \t]*(.*)[ \t]+([a-zA-Z0-9_]+)\(/\2/i,simulated/ --regex-unrealscript=/^[ \t]*[eE]vent[ \t]*[^ \t]*[ \t]+([a-zA-Z0-9_]+)\(/\1/e,event/ --regex-unrealscript=/^[ \t]*[fF]unction[ \t]*(.*)[ \t]+([a-zA-Z0-9_]+)\(/\2/f,function/ --recurse
- Basically this tells the ctags utility what regular expressions to use to get points of interest. The one above tells ctags to take into account class, state, simulated, event and function declarations. You can use these five types declarations to browse the source tree after we're done.
The _vimrc file holds a user's settings and commands Vim will run on startup. This is where configuration commands should go get get this stuff to work. Here's is what will need to go into this file as well as some added helpful/useful items:
" search for tags file in parent directories set tags=tags;/ " For Taglist nnoremap <silent> <F8> :Tlist<CR> nnoremap <silent> <F9> :TlistSync<CR> let Tlist_Use_Right_Window = 1 " to make Taglist work with UnrealScript au FileType uc let Tlist_Ctags_Cmd = 'ctags.exe --options="C:\UT2003\ctags.cfg"' let tlist_uc_settings = 'unrealscript;c:class;f:function;i:simulated;e:event;s:state' " For File Browser nnoremap <silent> <F12> :Exp<CR> " auto-change the directory to the current buffer autocmd BufEnter * :cd %:p:h " BufExplorer nnoremap <silent> <F11> :BufExplorer<CR>
These will require some explanation. So in order:
- This tells Vim to search for the tags file named 'tags' starting with the directory of the open file and moving up the directory tree until it's found.
nnoremap <silent> <F8> :Tlist<CR>
- This is for opening and closing the Taglist script (http://www.vim.org/scripts/script.php?script_id=273)
nnoremap <silent> <F9> :TlistSync<CR>
- This is to force immediate syncing of the Taglist window with the current cursor position
let Tlist_Use_Right_Window = 1
- Makes the TagList appear on the right side
au FileType uc let Tlist_Ctags_Cmd = 'ctags.exe –options="C:\UT2003\ctags.cfg"'
- Specifies the ctags command the TagList should use. Since we must use a custom config file to specify the unrealscript file type that needs to be in the command.
let tlist_uc_settings = 'unrealscript;c:class;f:function;i:simulated;e:event;s:state'
- Specifies how the TagList should be displayed for unrealscript files.
nnoremap <silent> <F12> :Exp<CR>
- Opens a file explorer. Useful for opening files in the same directory as the current file.
autocmd BufEnter * :cd %:p:h
- This makes the Vim working directory move to the directory of the file is currently being edited
nnoremap <silent> <F11> :BufExplorer<CR>
- Opens the BufferExplorer (http://www.vim.org/scripts/script.php?script_id=42)
The Taglist script is an information window that mimics many IDEs which show a birds-eye-view of the code. All landmarks can be seen, function declarations and other things. The _vimrc file declared above should be adequate to get this to work. The
let tlist_uc_settings = 'unrealscript;c:class;f:function;i:simulated;e:event;s:state' line can be edited to change the order that the sections appear or be removed all together. just change the order of the s:state or e:event bits.
Vim's Make functionality can be changed to use ucc. On a compile-time error, Vim will move the cursor to the buffer and line number an error occured on.
Here's some more additions to your _vimrc file:
autocmd FileType uc set makeprg=C:\\UT2003\\system\\ucc\ make autocmd FileType uc set efm=%f(%l)\ :\ %m
Change your pathnames as appropiate of course. This will allow the command
:make to use ucc and it will recognize the error format correctly. Vim will automatically jump to the uc file and line number with the error even if it isn't open.
:cn will go to the next error,
:cp to the previous.
:cl will list all errors.
So far it will only recognize errors within code. Any warnings or problems with default properties it will not recognize. You will get a "shell returned 1" message however. In the future I want to modify the efm line above to recognize more errors and warnings from ucc to make it more streamlined. Omitting the line altogether actually works, Vim seems to get the general gist of ucc's error format.
:help quickfix within Vim for more commands and information on how to use this functionality.
SocratesJohnson: Well here's my first stab at how to get the Vim editor to work well with UnrealScript. Any questions/comments/rants please let me know!
Erik: vim comes with the appropriate fu, automagic on all my unix systems and even my winderz box... :) syntax/uc.vim notes that it was last modified "2001 May 10"