Build Your First Vim Plugin

Talk I gave at Vim Chicago meetup about getting started with VimScript and building your first Vim Plugin

Transcript

1. WRITING YOUR FIRST PLUGIN
2. Sponsored by: Next meetup is Vim Lightning Talks. Submit your lightning talk idea. https://github.com/jonallured/vimchi.com/wiki/ Talk-Proposals @vimchi Dorian Karter https://github.com/dkarter @dorian_escplan
3. We have 30% off friends and family coupons!
4. WHY WRITE A VIM PLUGIN? Scratch an itch. Add support to for a new language. Understand and configure. Become a Vim legend.
5. WHAT YOU NEED Scriptease. Learn VimScript The Hard Way (book). Be a regex ninja (and know magic). :h magic Patience.
6. WHAT’S IN A VIM PLUGIN It’s essentially a .vimrc file. You may want it to be reusable.
7. :echo && :echom Your basic hello world - useful for debugging. :echo is temporary. :echom is persistant. :messages :echo “Hello world!” :echom “Hello world, I’m here to stay.”
8. VARIABLES let is used to set a variable. unlet is used to unset a variable. unlet! unsets a variable and suppresses the error if it doesn’t exist.
9. VARIABLE SCOPING 1 g:var "- global. 2 a:var "- function argument. 3 l:var "- local to function. 4 b:var "- local to buffer. 5 w:var "- local to window. 6 t:var "- local to tab. 7 v:var "- Predefined by Vim.
10. MAPPING Use noremap. Can limit to current <buffer>. You can create your own text objects! :map j gg :map Q j :noremap W j
11. xkcd - workflow
12. MAPPING BEST PRACTICES Don't use a map when a command will do. Show how vs Map. Use customizable prefix. Avoid common mappings. Avoid starting with a common key. (e.g. oo)
13. :normal! Lets you execute a normal mode action. normal! not normal. Will not enter insert mode. :normal! gg=G
14. Operator-Pending Mappings You can create your own text objects! The CTRL-U (<C-U>) removes the range that Vim may insert. :h omap-info :onoremap in( :<c-u>normal! f(vi(<cr>
15. command! Use command!. You can get autocomplete for arguments. :command! SayHi :echom “oh hi!” :command! Tick let s:counter = s:counter + 1 | echo s:counter :command! -nargs=1 -complete=buffer BufName echo "Buffer Name is <args>"
16. fun! 1 function! g:Foobar(arg1, arg2, ...) 2 let first_argument = a:arg1 3 let index = 1 4 let variable_arg_1 = a:{index} " same as a:1 5 return variable_arg_1 6 endfunction
17. FUNCTIONS Use function!. Scope and lazy-load. Use a:varname to access arguments.
18. autocmd Event Binding. Can be filtered. Should be grouped.[1] :h autocmd-events :autocmd BufWrite * :echom "Writing buffer!"
19. execute Takes a VimScript and executes it as a command. Essentially eval. Not too evil. Meta-programming. :execute “autocmd BufWrite * :echom \”Writing buffer!\””
20. USEFUL STUFF "." = cursor "'<" = selection start "'>" = selection end '\v' = very magic line(“.”) getpos(“.”) setpos(“.”, [0,12,3]) getline(12) setline(12, ”potato”) append(12, [“line after 12”, ”line after 13”]) matchend(“some string”, ‘\v.*’) matchlist(“some string”, ‘\v(regex|with|groups)’)
21. COMPATIBILITY CONSIDERATIONS 1 let s:save_cpo = &cpo 2 set cpo&vim 3 4 " .. your plugin code here .. 5 6 let &cpo = s:save_cpo 7 unlet s:save_cpo
22. HEADER 1 " Vim global plugin for correcting typing mistakes 2 " Last Change: 2016 Jan 15 3 " Maintainer: Bram Moolenaar <Bram@vim.org> 4 " License: This file is placed in the public domain.
23. HOW TO PUBLISH 1 yourplugin/ 2 doc/ 3 yourplugin.txt 4 plugin/ 5 yourplugin.vim 6 ... 7 README 8 LICENSE 9 CONTRIBUTING
24. SOURCE DIVE https://github.com/dkarter/bullets.vim bullets.vim
25. STYLE Build small things. When possible. Comment Comment Comment. Folding will keep you sane.
26. DO THINGS THE “VIM WAY”
27. DOCUMENTATION :h write-local-help
28. MORE BEST PRACTICES Don’t ever force push. Concise + informative commit messages. Stay backwards compatible. Avoid collisions. (As much as you can). Always use non-recursive options.
29. RESOURCES :h write-plugin Five Minute Vim Script http://andrewscala.com/vimscript/ Learn VimScript the Hard Way (Free Book) http://learnvimscriptthehardway.stevelosh.com/ Writing Vim Plugins - Best Practices http://stevelosh.com/blog/2011/09/writing-vim-plugins/ Tim Pope Reddit AMA (Google it..)
30. RESOURCES (CONT.) Vim Debugger https://github.com/haya14busa/vim-debugger Vim Undescore (yep.) https://github.com/haya14busa/underscore.vim Vital.vim (util functions for vim plugins) https://github.com/vim-jp/vital.vim Themis (Testing framework for VimScript) https://github.com/thinca/vim-themis
31. QUESTIONS? @dorian_escplan
32. boolean Let’s play a game: 1 :echo 1 . "foo" 2 :echo 1 + "1" 3 4 :fun! TrueFalse(arg) 5 : return a:arg? "true" : "false" 6 :endfun 7 8 :echo TrueFalse("foobar") 9 :echo TrueFalse("1000") 10 :echo TrueFalse("x1000") 11 :echo TrueFalse("1000x") 12 :echo TrueFalse("0")
33. you deserve a break VimScript is hard