Build Your First Vim Plugin

Build Your First Vim Plugin

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

0e752ec9121eb5ebc9924f5b2e4b788e?s=128

Dorian Karter

February 16, 2016
Tweet

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