Build Your First Vim Plugin

Slide 1

Slide 1 text

WRITING YOUR FIRST PLUGIN

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

We have 30% off friends and family coupons!

Slide 4

Slide 4 text

WHY WRITE A VIM PLUGIN? Scratch an itch. Add support to for a new language. Understand and configure. Become a Vim legend.

Slide 5

Slide 5 text

WHAT YOU NEED Scriptease. Learn VimScript The Hard Way (book). Be a regex ninja (and know magic). :h magic Patience.

Slide 6

Slide 6 text

WHAT’S IN A VIM PLUGIN It’s essentially a .vimrc file. You may want it to be reusable.

Slide 7

Slide 7 text

: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.”

Slide 8

Slide 8 text

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.

Slide 9

Slide 9 text

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.

Slide 10

Slide 10 text

MAPPING Use noremap. Can limit to current . You can create your own text objects! :map j gg :map Q j :noremap W j

Slide 11

Slide 11 text

xkcd - workflow

Slide 12

Slide 12 text

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)

Slide 13

Slide 13 text

:normal! Lets you execute a normal mode action. normal! not normal. Will not enter insert mode. :normal! gg=G

Slide 14

Slide 14 text

Operator-Pending Mappings You can create your own text objects! The CTRL-U () removes the range that Vim may insert. :h omap-info :onoremap in( :normal! f(vi(

Slide 15

Slide 15 text

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 "

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

FUNCTIONS Use function!. Scope and lazy-load. Use a:varname to access arguments.

Slide 18

Slide 18 text

autocmd Event Binding. Can be filtered. Should be grouped.[1] :h autocmd-events :autocmd BufWrite * :echom "Writing buffer!"

Slide 19

Slide 19 text

execute Takes a VimScript and executes it as a command. Essentially eval. Not too evil. Meta-programming. :execute “autocmd BufWrite * :echom \”Writing buffer!\””

Slide 20

Slide 20 text

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)’)

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

HEADER 1 " Vim global plugin for correcting typing mistakes 2 " Last Change: 2016 Jan 15 3 " Maintainer: Bram Moolenaar 4 " License: This file is placed in the public domain.

Slide 23

Slide 23 text

HOW TO PUBLISH 1 yourplugin/ 2 doc/ 3 yourplugin.txt 4 plugin/ 5 yourplugin.vim 6 ... 7 README 8 LICENSE 9 CONTRIBUTING

Slide 24

Slide 24 text

SOURCE DIVE https://github.com/dkarter/bullets.vim bullets.vim

Slide 25

Slide 25 text

STYLE Build small things. When possible. Comment Comment Comment. Folding will keep you sane.

Slide 26

Slide 26 text

DO THINGS THE “VIM WAY”

Slide 27

Slide 27 text

DOCUMENTATION :h write-local-help

Slide 28

Slide 28 text

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.

Slide 29

Slide 29 text

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..)

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

QUESTIONS? @dorian_escplan

Slide 32

Slide 32 text

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")

Slide 33

Slide 33 text

you deserve a break VimScript is hard