1<?xml version = '1.0'?> 2<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?> 3<GUIDE title="Google Vimscript Guide"> 4 <p class="revision"> 5 6 Revision 1.1 7 </p> 8 9 10 <address> 11 Nate Soares<br/> 12 Joshua Hoak<br/> 13 David Barnett<br/> 14 </address> 15 16 <OVERVIEW> 17 <CATEGORY title="Background"> 18 <p> 19 This is the in-depth vimscript guide. If you're just a casual user 20 looking to write a plugin, the 21 <a href="vimscriptguide.html">abbreviated style guide</a> is for you. 22 </p> 23 <p> 24 This rather rotund guide dives into justifications and clarifications. 25 It provides an idealized set of rules that are rather too draconian to 26 push on casual scripters. 27 </p> 28 29 <p> 30 It's for users who want to know why certain decisions were made in the 31 abbreviated guide and who want to learn a thing or two about using 32 vimscript safely. 33 </p> 34 <p> 35 Fair warning: Vimscript is a maddening abyss. When you gaze into it, it 36 gazes also into you. Proceed with caution. 37 </p> 38 </CATEGORY> 39 </OVERVIEW> 40 41 <CATEGORY title="Portability"> 42 <p> 43 Vim is highly configurable. Users can change many of the default 44 settings, including the case sensitivity, the regular expression rules, 45 the substitution rules, and more. In order for your vimscript to work 46 for all users, follow these guidelines: 47 </p> 48 <ul> 49 <li> 50 Always prefix regular expressions with one of <code>\m</code>, 51 <code>\v</code>, <code>\M</code>, or <code>\V</code> (prefer 52 tersity) 53 <ul> 54 <li> 55 Users can change the global "magic level" of regular expressions. 56 This changes how atoms are parsed in regular expressions, 57 including <code>.</code>, <code>*</code>, and <code>{</code>. 58 </li> 59 <li> 60 Even if your regular expression does not contain characters which 61 are affected by the <code>magic</code> setting you must prefix it 62 with one of the magic control atoms. This future-proofs your 63 regular expression against other devs modifying it and forgetting 64 to add the control atom. 65 </li> 66 <li> 67 If you have no opinion about what type of regular expression to 68 use, prefer the one which makes your regular expression most 69 concise. 70 </li> 71 </ul> 72 </li> 73 <li> 74 Avoid using <code>:s[ubstitute]</code> in scripts. 75 <ul> 76 <li> 77 <code>:substitute</code> moves the cursor. 78 </li> 79 <li> 80 <code>:substitute</code> outputs an error message when the match 81 does not exist. 82 </li> 83 <li> 84 The meaning of the <code>g</code> flag depends upon the 85 <code>gdefault</code> setting. If you do use 86 <code>:substitute</code> you must save <code>gdefault</code>, set 87 it to <code>0</code> or <code>1</code>, perform the substitution, 88 and then restore it. 89 </li> 90 <li> 91 Script authors who want a safe way to replace text in the buffer 92 are encouraged to use <code>maktaba#buffer#Replace</code>. 93 </li> 94 </ul> 95 </li> 96 <li> 97 Always use case-explicit operators for strings (<code>=~#</code> and 98 <code>=~?</code>, never <code>=~</code>). 99 <ul> 100 <li> 101 This also applies to <code>!~ == != > >= <</code> and 102 <code><=</code> 103 </li> 104 <li> 105 This only applies for strings. <code>==</code> and 106 <code>>=</code> are fine for numbers, but <code>==#</code> and 107 <code>>=#</code> must be used for strings. 108 </li> 109 <li> 110 The behavior of <code>=~</code> and friends is dependant upon the 111 <code>ignorecase</code> setting. 112 </li> 113 <li> 114 You may break this rule when you explicitly want to obey the 115 user's <code>ignorecase</code> setting. Be prepared to justify 116 your reasoning. 117 </li> 118 </ul> 119 </li> 120 <li> 121 When using regular expressions as arguments to functions, prepend them 122 with <code>\c</code> or <code>\C</code>. 123 <ul> 124 <li> 125 This forces case to be either explicitly matched or ignored. 126 </li> 127 <li> 128 This is recommended, but not required, when comparing regexes with 129 operators that specify case sensitivity (<code>=~#</code>, etc.). 130 </li> 131 <li> 132 This rule applies when your regexes are matching syntax, external 133 APIs, external messages, and most other cases. 134 </li> 135 <li> 136 It does not apply when matching text in the buffer. When matching 137 text in the buffer you should honor the <code>ignorecase</code> 138 setting. 139 </li> 140 <li> 141 You may also ignore this rule any time that you explicitly want to 142 honor the <code>ignorecase</code> setting. Be prepared to justify 143 your reasoning. 144 </li> 145 </ul> 146 </li> 147 <li> 148 Always use <code>normal!</code> instead of <code>normal</code>. 149 <ul> 150 <li> 151 If you forgo the <code>!</code> the command will use the user's 152 key mappings and you have literally no idea what your macro will 153 do. 154 </li> 155 </ul> 156 </li> 157 <li> 158 Always use the <code>noremap</code> family of commands. 159 <ul> 160 <li> 161 Your plugins generally shouldn't introduce mappings, but if they 162 do, the <code>map</code> command respects the users existing 163 mappings and could do anything. 164 </li> 165 </ul> 166 </li> 167 <li> 168 When using <code>catch</code>, match the error code rather than the 169 error text. 170 <ul> 171 <li> 172 The error text may be locale-dependant. 173 </li> 174 <li> 175 See <code>:help error-messages</code>. 176 </li> 177 </ul> 178 </li> 179 </ul> 180 <p> 181 In general, guard all commands and functions against user settings. 182 </p> 183 184 </CATEGORY> 185 <CATEGORY title="Language Guide"> 186 <ul> 187 188 189 <li> 190 Line continuations: <strong>Yes</strong> 191 <ul> 192 193 <li> 194 Plugins that support vi compatibility mode must save and restore 195 compatibility options as described in the 196 <strong>Errata section</strong> so line continuations work properly. 197 </li> 198 </ul> 199 </li> 200 <li> 201 Exceptions: <strong>Yes, with caution</strong> 202 <ul> 203 <li> 204 Always use an error code in thrown exception messages. 205 </li> 206 <li> 207 Prefer the <code>maktaba#error</code> codes found in 208 <code>maktaba</code>. 209 </li> 210 <li> 211 Fall back to the vim error codes. See 212 <code>:help error-messages</code>. 213 </li> 214 <li> 215 Generate custom error messages using 216 <code>maktaba#error#Message</code>. 217 </li> 218 </ul> 219 </li> 220 <li> 221 Global Variables: <strong>As configuration only</strong> 222 <ul> 223 <li> 224 See the plugin guide. 225 </li> 226 </ul> 227 </li> 228 <li> 229 Messaging: <strong>As little as possible.</strong> 230 <ul> 231 <li> 232 Loud scripts are annoying. 233 </li> 234 <li> 235 Message the user when an error has occured. 236 </li> 237 <li> 238 Message the user when an operation which takes a long time has 239 begun work. 240 </li> 241 <li> 242 Avoid messaging otherwise. 243 </li> 244 </ul> 245 </li> 246 <li> 247 Type checking: 248 <strong>Use strict and explicit checks where possible.</strong> 249 <ul> 250 <li> 251 Vimscript has unsafe, unintuitive behavior when dealing with some 252 types. For instance, <code>0 == 'foo'</code> evaluates to true. 253 </li> 254 <li> 255 Use strict comparison operators where possible. When comparing 256 against a string literal, use the <code>is#</code> operator. 257 Otherwise, prefer <code>maktaba#value#IsEqual</code> or check 258 <code>type()</code> explicitly. 259 </li> 260 <li> 261 Check variable types explicitly before using them. Use functions 262 from <code>maktaba#ensure</code>, or check 263 <code>maktaba#value</code> or <code>type()</code> and throw your own 264 errors. 265 </li> 266 <li> 267 Use <code>:unlet</code> for variables that may change types, 268 particularly those assigned inside loops. 269 </li> 270 </ul> 271 </li> 272 <li> 273 FuncRefs: <strong>No in most cases.</strong> 274 <ul> 275 <li> 276 FuncRefs have inconsistently enforced naming restrictions. 277 (Functions can have names that FuncRefs can not.) 278 </li> 279 <li> 280 FuncRefs have inconsistent ability to be reassigned (in Vim 281 7.2 and before you must unlet a FuncRef before assigning it). 282 </li> 283 <li> 284 In most instances where a FuncRef is needed a string works 285 just as well: just pass the string that you would use to make 286 the FuncRef. 287 </li> 288 <li> 289 Consider using <code>maktaba#function</code> instead to create and 290 manipulate handles to functions. 291 </li> 292 </ul> 293 </li> 294 <li> 295 Python: <strong>Sparingly</strong> 296 <ul> 297 298 <li> 299 Hurts code reuse since python code embedded in python plugins is 300 awkward to share between plugins. 301 </li> 302 <li> 303 Using python introduces python language version dependencies, which 304 are likely to get stale. 305 </li> 306 <li> 307 Exception: It's reasonable to use python for plugin functionality 308 that needs to do work in the background, as vimscript can not do 309 this. 310 </li> 311 </ul> 312 </li> 313 <li> 314 Ruby: <strong>No</strong> 315 <ul> 316 <li> 317 We can not assume ruby interoperability. 318 </li> 319 <li> 320 You shouldn't depend upon the version of the ruby language that the 321 user has installed. 322 </li> 323 </ul> 324 </li> 325 <li> 326 Lua: <strong>No</strong> 327 <ul> 328 <li> 329 For the same reasons an Ruby. 330 </li> 331 </ul> 332 </li> 333 <li> 334 Dict Functions: <strong>Encouraged</strong> 335 <ul> 336 <li> 337 Vimscript can attach functions to dictionaries. Such functions 338 have access to the <code>self</code> parameter which access 339 the dict state. 340 </li> 341 <li> 342 Use these where you would use a class in python. 343 </li> 344 <li> 345 Do not over-use this feature; it is not necessary for helper 346 functions or API functions, only for encapsulated objects. 347 </li> 348 </ul> 349 </li> 350 </ul> 351 <p> 352 All other language features are fair game. 353 </p> 354 </CATEGORY> 355 <CATEGORY title="Structure"> 356 <ul> 357 <li> 358 Provided functionality should be packed into modular plugins. 359 <ul> 360 <li> 361 Every function in your plugin should be specific to your 362 plugin. 363 </li> 364 <li> 365 General utility functions should be abstracted into library plugins. 366 </li> 367 <li> 368 Manage dependencies with <code>maktaba</code>. 369 </li> 370 </ul> 371 </li> 372 <li> 373 <code>plugin-names-like-this</code> 374 <ul> 375 <li> 376 Plugin names should be descriptive and concise. 377 </li> 378 379 380 </ul> 381 </li> 382 <li> 383 Each plugin must consist of one directory (or code repository), sharing 384 a name with the plugin (with a "vim-" prefix or ".vim" suffix if 385 desired). 386 </li> 387 <li> 388 Plugin metadata should be declared in the addon-info.json format (see 389 the <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a> for details). 390 </li> 391 <li> 392 Functions should go in the <code>autoload/</code> subdirectory of 393 your plugin. 394 <ul> 395 <li> 396 This allows them to be late-loaded, which speeds up startup 397 time. 398 </li> 399 <li> 400 This helps vim enforce namespacing conventions. 401 </li> 402 </ul> 403 </li> 404 <li> 405 Each file in the <code>plugin/</code> or <code>instant/</code> directory 406 should begin with the boilerplate 407 <CODE_SNIPPET> 408 let [s:plugin, s:enter] = maktaba#plugin#Enter(expand('<sfile>:p')) 409 if !s:enter 410 finish 411 endif 412 </CODE_SNIPPET> 413 (This prevents re-entry and allows users to selectively disable 414 functionality.) 415 </li> 416 <li> 417 User configuration should be via plugin flags defined in 418 <code>instant/flags.vim</code>. 419 <ul> 420 <li> 421 Define flags with 422 <code>call s:plugin.Flag('FLAGNAME', DEFAULT_VALUE)</code>. 423 </li> 424 <li> 425 Users can configure these flags using the <code>:Glaive</code> 426 command (see <a href="https://github.com/google/glaive">glaive</a>). 427 </li> 428 </ul> 429 </li> 430 <li> 431 Commands, autocommands, mappings, and settings changes should 432 occur either in the <code>plugin/</code> or the 433 <code>ftplugin/</code> subdirectories. 434 <ul> 435 <li> 436 All commands should be defined in <code>plugin/commands.vim</code> 437 or <code>ftplugin/</code> files. 438 </li> 439 <li> 440 Autocommands should be defined in <code>plugin/autocmds.vim</code>, 441 inside an augroup. 442 </li> 443 <li> 444 Mappings should be defined in <code>plugin/mappings.vim</code> and 445 will be disabled unless explicitly enabled by users. 446 </li> 447 <li> 448 If the plugin configures any standard vim settings, those should be 449 configured in <code>plugin/settings.vim</code> or 450 <code>instant/settings.vim</code>. 451 </li> 452 </ul> 453 </li> 454 <li> 455 Avoid using the <code>after/</code> subdirectory. 456 <ul> 457 <li> 458 <code>after/</code> should be reserved for the user. 459 </li> 460 <li> 461 It is difficult for the user to add their own overrides when 462 plugins use <code>after/</code>. 463 </li> 464 </ul> 465 </li> 466 </ul> 467 468 <STYLEPOINT title="Libraries vs. Functionality"> 469 <SUMMARY> 470 Separate library-providing plugins from command-providing plugins. 471 </SUMMARY> 472 <BODY> 473 <p> 474 Many plugins provide either user functionality (commands, 475 autocommands, etc) or an API (of autoloaded functions) but not both. 476 This separation is encouraged, as it allows other plugins to pull in a 477 library without also pulling in commands, setting changes, and other 478 plugin functionality that affects the end user. 479 </p> 480 </BODY> 481 </STYLEPOINT> 482 483 <STYLEPOINT title="Configuration"> 484 <SUMMARY> 485 Don't clobber user settings. Provide as much configurability as 486 possible: that's what Vim's all about. 487 </SUMMARY> 488 <BODY> 489 <ul> 490 <li> 491 Use maktaba flags for plugin configuration. Users can configure them 492 using the <code>:Glaive</code> command. 493 494 </li> 495 <li> 496 Check if configuration variables exist before setting them. 497 <CODE_SNIPPET> 498 if !exists('g:myplugin_option') 499 let g:myplugin_option = 1 500 endif 501 </CODE_SNIPPET> 502 </li> 503 </ul> 504 </BODY> 505 </STYLEPOINT> 506 </CATEGORY> 507 <CATEGORY title="Style Guide"> 508 <p> 509 Follow google-wide style conventions. Mimic google python style when 510 in doubt. 511 </p> 512 513 514 515 <STYLEPOINT title="Documentation"> 516 <SUMMARY> 517 Use <a href="https://github.com/google/vimdoc">vimdoc</a>. 518 </SUMMARY> 519 <BODY> 520 <p> 521 Provide help files generated by 522 <a href="https://github.com/google/vimdoc">vimdoc</a>. Write 523 documentation in .vim files in conformance with the vimdoc standards 524 and include fields like "description" and "author" in the 525 addon-info.json file (see the 526 <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a>). 527 </p> 528 </BODY> 529 </STYLEPOINT> 530 531 <STYLEPOINT title="Whitespace"> 532 <SUMMARY> 533 Follow google-wide conventions. 534 </SUMMARY> 535 <BODY> 536 <ul> 537 <li> 538 Use two spaces for indents. 539 </li> 540 <li> 541 Do not use tabs. 542 </li> 543 <li> 544 Use spaces around operators except for arguments to commands. 545 <ul> 546 <li> 547 Using spaces around operators for commands is often invalid 548 syntax. This is inconsistently enforced by vimscript. To be 549 safe, always omit whitespace around arguments to commands. 550 </li> 551 <li> 552 <CODE_SNIPPET> 553 let s:variable = "concatenated " . "strings" 554 command -range=% MyCommand 555 </CODE_SNIPPET> 556 <BAD_CODE_SNIPPET> 557 let s:variable="concatenated "."strings" 558 command -range = % MyCommand 559 </BAD_CODE_SNIPPET> 560 </li> 561 </ul> 562 </li> 563 <li> 564 Do not introduce trailing whitespace. 565 <ul> 566 <li> 567 You need not go out of your way to remove it. 568 </li> 569 </ul> 570 </li> 571 <li> 572 Restrict lines to 80 columns wide. 573 </li> 574 <li> 575 Indent continued lines by two tabs (four spaces). 576 </li> 577 <li> 578 Do not waste whitespace aligning common segments of similar 579 commands. It is both difficult and expensive to maintain. 580 <ul> 581 <li> 582 <CODE_SNIPPET> 583 command -bang MyCommand call myplugin#foo() 584 command MyCommand2 call myplugin#bar() 585 </CODE_SNIPPET> 586 <BAD_CODE_SNIPPET> 587 command -bang MyCommand call myplugin#foo() 588 command MyCommand2 call myplugin#bar() 589 </BAD_CODE_SNIPPET> 590 </li> 591 </ul> 592 </li> 593 </ul> 594 <SUBSECTION title="Line Continuations"> 595 <ul start="7"> 596 <li> 597 Prefer line continuations on semantic boundaries. 598 <ul> 599 <li> 600 <CODE_SNIPPET> 601 command SomeLongCommand 602 \ call some#function() 603 </CODE_SNIPPET> 604 <BAD_CODE_SNIPPET> 605 command SomeLongCommand call 606 \ some#function() 607 </BAD_CODE_SNIPPET> 608 </li> 609 <li> 610 Use your best judgement. 611 </li> 612 </ul> 613 </li> 614 <li> 615 Place one space after the backslash denoting a line continuation. 616 <ul> 617 <li> 618 When continuing a multi-line command a pipe can be substituted 619 for this space as necessary, as follows: 620 <CODE_SNIPPET> 621 autocommand BufEnter <buffer> 622 \ if !empty(s:var) 623 \| call some#function() 624 \|else 625 \| call some#function(s:var) 626 \|endif 627 </CODE_SNIPPET> 628 </li> 629 </ul> 630 </li> 631 <li> 632 Do not continue multi-line commands when you can avoid it. Prefer 633 function calls. 634 </li> 635 </ul> 636 </SUBSECTION> 637 <SUBSECTION title="Comments"> 638 <ul> 639 <li> 640 Place a space after the <code>"</code> before the comment text. 641 <ul> 642 <li> 643 <CODE_SNIPPET> 644 " I am a line comment. 645 call call(s:my_function) 646 </CODE_SNIPPET> 647 </li> 648 </ul> 649 </li> 650 <li> 651 Do not use inline comments. 652 <ul> 653 <li> 654 Some commands treat them as comments and others as unclosed 655 quotes. There are many edge cases. It's difficult to get 656 right and difficult to maintain. 657 </li> 658 <li> 659 Where you would use an inline comment, put a line comment on 660 the line above. 661 </li> 662 </ul> 663 </li> 664 <li> 665 When leaving blank lines in comments, include the quote in the 666 blank line. 667 <ul> 668 <li> 669 <CODE_SNIPPET> 670 " I am one continuous 671 " 672 " comment block 673 </CODE_SNIPPET> 674 </li> 675 </ul> 676 </li> 677 </ul> 678 </SUBSECTION> 679 </BODY> 680 </STYLEPOINT> 681 682 <STYLEPOINT title="Variables"> 683 <SUMMARY> 684 <p> 685 <code>plugin-names-like-this</code>, 686 <code>FunctionNamesLikeThis</code>, 687 <code>CommandNamesLikeThis</code>, 688 <code>augroup_names_like_this</code>, 689 <code>variable_names_like_this</code>. 690 </p> 691 <p> 692 Prefix all variables with their scope. 693 </p> 694 </SUMMARY> 695 <BODY> 696 <ul> 697 <li> 698 <code>variable_names_like_this</code> 699 <ul> 700 <li> 701 FuncRef variables count as functions and should be named like 702 functions. 703 </li> 704 <li> 705 This (pathological) convention is enforced by vim itself. 706 </li> 707 </ul> 708 </li> 709 <li> 710 Prefix global variables with <code>g:</code> 711 <ul> 712 <li> 713 Vimscript allows you to create global variables without 714 prefixing them. 715 </li> 716 <li> 717 It is very bad practice to introduce non-prefixed global 718 variables into scope. 719 </li> 720 <li> 721 Global variables should only be used for plugin configuration. 722 </li> 723 <li> 724 This does not apply to functions defined in 725 <code>autoload</code> directories. 726 </li> 727 </ul> 728 </li> 729 <li> 730 Prefix script-local variables with <code>s:</code> 731 <ul> 732 <li> 733 This prevents namespace collisions between plugins. 734 </li> 735 <li> 736 This also applies to script-local functions. 737 </li> 738 </ul> 739 </li> 740 <li> 741 Prefix function arguments with <code>a:</code> 742 <ul> 743 <li> 744 This is enforced by vim itself. 745 </li> 746 </ul> 747 </li> 748 <li> 749 Prefix function-local variables with <code>l:</code> 750 <ul> 751 <li> 752 This is not enforced by vimscript but is good practice. 753 </li> 754 <li> 755 It helps you remember that all other variables must be 756 prefixed with scope. 757 </li> 758 <li> 759 <code>l:</code> disambiguates between function-local and 760 vim-predefined variables. For example, <code>count</code> 761 refers to 762 <code>v:count</code>, not <code>l:count</code>. 763 </li> 764 <li> 765 It future proofs your scripts against the introduction of new 766 vim-predefined variables. 767 </li> 768 </ul> 769 </li> 770 <li> 771 Prefix pre-defined vim variables with <code>v:</code> 772 <ul> 773 <li> 774 This is not enforced by vimscript but is good practice. 775 </li> 776 <li> 777 It provides context as to where the (undeclared) variable is 778 coming from. 779 </li> 780 <li> 781 It reminds you that the variable can not be assigned to. 782 </li> 783 </ul> 784 </li> 785 <li> 786 Prefix buffer-local variables with <code>b:</code> 787 <ul> 788 <li> 789 This is useful for plugins that keep per-buffer state. 790 </li> 791 </ul> 792 </li> 793 </ul> 794 </BODY> 795 </STYLEPOINT> 796 797 <STYLEPOINT title="Strings"> 798 <SUMMARY> 799 Prefer single quotes. 800 </SUMMARY> 801 <BODY> 802 <p> 803 Prefer single quoted strings. Specifically, in order of precedence: 804 </p> 805 <ul> 806 <li> 807 Always use single quotes for regular expressions. 808 <ul> 809 <li> 810 <code>'\s*'</code> is not the same as <code>"\s*"</code> 811 </li> 812 <li> 813 Single quotes will prevent the need for excessive backslashes. 814 </li> 815 <li> 816 Double single quotes escape to one single quote in single 817 quoted strings: <code>'example ('')'</code> represents the 818 string 819 <code>example (')</code> 820 </li> 821 </ul> 822 </li> 823 <li> 824 If your string requires escape characters (<code>\n</code>, 825 <code>\t</code>, etc.) use double quotes. 826 <ul> 827 <li> 828 Escapes can not be expressed in single quoted strings. 829 </li> 830 <li> 831 Remember that <code>'\n'</code> in a regex does not represent a 832 newline, but rather "\n". You only need to use double quotes 833 when you want to embed the represented character itself (e.g. a 834 newline) in the string. 835 </li> 836 </ul> 837 </li> 838 <li> 839 If your string contains no escapes nor single quotes, use single 840 quoted strings. 841 <ul> 842 <li> 843 Most strings in vimscript are regexes, so this provides maximum 844 consistency. 845 </li> 846 </ul> 847 </li> 848 <li> 849 If your non-regex string contains single quotes but no double 850 quotes, use double quotes. 851 <ul> 852 <li> 853 Don't bother escaping strings if you don't have to. 854 </li> 855 <li> 856 This is similar to the python string rules. 857 </li> 858 </ul> 859 </li> 860 <li> 861 If your string contains both single and double quotes, use whichever 862 quoting style requires less escaping. 863 <ul> 864 <li> 865 Break ties in favor of single quotes. 866 </li> 867 </ul> 868 </li> 869 </ul> 870 </BODY> 871 </STYLEPOINT> 872 873 <STYLEPOINT title="Settings"> 874 <SUMMARY> 875 Prefer long names. Set settings locally. 876 </SUMMARY> 877 <BODY> 878 <ul start="6"> 879 <li> 880 Prefer long names of built in settings (i.e. <code>tabstop</code> 881 over 882 <code>ts</code>). 883 </li> 884 <li> 885 Set local settings unless you explicitly want to set global 886 settings. 887 <ul> 888 <li> 889 Use <code>setlocal</code> and <code>&l:</code> instead of 890 <code>set</code> and <code>&</code>. 891 </li> 892 </ul> 893 </li> 894 </ul> 895 </BODY> 896 </STYLEPOINT> 897 </CATEGORY> 898 <CATEGORY title="Usage Guide"> 899 <p> 900 Vim plugins should provide any or all of the following: 901 <strong>Commands,</strong> <strong>Autocommands,</strong> 902 <strong>Functions,</strong> <strong>Statusline Flags, and</strong> 903 <strong>Mappings.</strong> 904 </p> 905 906 <STYLEPOINT title="Commands"> 907 <SUMMARY> 908 <ul> 909 <li>Define in <code>plugin/commands.vim</code>.</li> 910 <li>CommandNamesLikeThis.</li> 911 <li>Prefer semantic names to a unified prefix.</li> 912 <li>Do not use <code>[!]</code></li> 913 <li>Extract logic into functions.</li> 914 </ul> 915 </SUMMARY> 916 <BODY> 917 <ul> 918 <li> 919 <code>CommandNamesLikeThis</code> 920 </li> 921 <li> 922 Commands should be defined in one block with no whitespace between 923 them. 924 <ul> 925 <li> 926 Name commands semantically at the expense of a common prefix. 927 </li> 928 <li> 929 <BAD_CODE_SNIPPET> 930 command WhitespaceFixTrailing 931 command WhitespaceFixIndentation 932 </BAD_CODE_SNIPPET> 933 <CODE_SNIPPET> 934 command FixTrailingWhitespace 935 command FixIndentation 936 </CODE_SNIPPET> 937 </li> 938 </ul> 939 </li> 940 <li> 941 Use <code>command</code> without a bang. 942 <ul> 943 <li> 944 This notifies users to command name conflicts immediately at 945 startup. 946 </li> 947 <li> 948 Command name collisions are an error and should not fail 949 silently. 950 </li> 951 <li> 952 Plugins are guarded against re-entry, so a single vim session 953 should never attempt to re-define defined commands. 954 </li> 955 </ul> 956 </li> 957 <li> 958 Do not put logic in commands. 959 <ul> 960 <li> 961 Delegate to functions instead. 962 </li> 963 <li> 964 Pass non-argument command parameters (<code><bang></code>, 965 <code><register></code>, etc.) before argument parameters 966 (<code><f-args></code>, etc.). 967 </li> 968 <li> 969 Otherwise variable-length argument functions are difficult to 970 implement. 971 </li> 972 </ul> 973 </li> 974 <li> 975 Do not autoload commands. 976 <ul> 977 <li> 978 Autoloaded commands will not be available until after a function 979 in the same file is called. 980 </li> 981 <li> 982 Commands intended to be used in the .vimrc should be defined in 983 a <code>instant/commands.vim</code> file in plugins using 984 maktaba, or explicitly installed via an autoload function in 985 non-maktaba plugins. 986 </li> 987 </ul> 988 </li> 989 </ul> 990 <SUBSECTION title="Conventions"> 991 <ul> 992 <li> 993 Pass <code><bang></code> to functions with 994 <code>'<bang>' == '!'</code>. 995 <ul> 996 <li> 997 The function should receive a boolean parameter, not a string. 998 </li> 999 </ul> 1000 </li> 1001 </ul> 1002 </SUBSECTION> 1003 </BODY> 1004 </STYLEPOINT> 1005 1006 <STYLEPOINT title="Autocommands"> 1007 <SUMMARY> 1008 <ul> 1009 <li>Define in <code>plugin/autocmds.vim</code>.</li> 1010 <li>Use augroups.</li> 1011 <li>augroup_names_like_this.</li> 1012 <li>Clear the augroup first.</li> 1013 <li>Extract logic into functions.</li> 1014 </ul> 1015 </SUMMARY> 1016 <BODY> 1017 <ul> 1018 <li> 1019 All autocommands should be defined in the 1020 <code>plugin/autocmds.vim</code> file. 1021 <ul> 1022 <li> 1023 This allows users to disable your autocommands with 1024 <code>Glaive myplugin !plugin[autocmds]</code>. 1025 </li> 1026 </ul> 1027 </li> 1028 <li> 1029 Declare all autocommands in an <code>augroup</code> block. 1030 <ul> 1031 <li> 1032 This allows your autocommands to be cleared with 1033 <code>autocmd!</code>. 1034 </li> 1035 <li> 1036 If your plugin only has one <code>augroup</code>, the 1037 <code>augroup</code> name should be the same as your plugin 1038 name, with underscores in place of any hyphens. 1039 </li> 1040 <li> 1041 Otherwise <code>augroup</code> names should start with your 1042 plugin name followed by an underscore. 1043 </li> 1044 </ul> 1045 </li> 1046 <li> 1047 Do not put logic in autocommands. 1048 <ul> 1049 <li> 1050 Delegate to functions instead. 1051 </li> 1052 </ul> 1053 </li> 1054 <li> 1055 When creating a new <code>augroup</code>, clear it with 1056 <code>autocmd!</code> 1057 <ul> 1058 <li> 1059 This allows your plugins to be re-enterable. 1060 </li> 1061 </ul> 1062 </li> 1063 </ul> 1064 </BODY> 1065 </STYLEPOINT> 1066 1067 <STYLEPOINT title="Functions"> 1068 <SUMMARY> 1069 <ul> 1070 <li>FunctionNamesLikeThis.</li> 1071 <li>Autoload all functions.</li> 1072 <li>Prefix script-local functions with <code>s:</code></li> 1073 <li>Use <code>[!]</code>.</li> 1074 <li>Use <code>[abort]</code>.</li> 1075 </ul> 1076 </SUMMARY> 1077 <BODY> 1078 <ul> 1079 <li> 1080 <code>FunctionNamesLikeThis</code> 1081 </li> 1082 <li> 1083 Prefix all script-local functions with <code>s:</code> 1084 </li> 1085 <li> 1086 Do not provide global functions. Use autoloaded functions instead. 1087 </li> 1088 <li> 1089 Place two blank lines between top-level functions. 1090 </li> 1091 <li> 1092 Declare all functions with <code>abort</code>. 1093 <ul> 1094 <li> 1095 If you do not do this, the function's behavior depends upon 1096 whether it is called within a <code>try..endtry</code> block 1097 somewhere on the stack. 1098 </li> 1099 <li> 1100 The <code>abort</code> keyword forces the function to act 1101 consistently. 1102 </li> 1103 <li> 1104 Without it, the function may (or may not) attempt to continue 1105 execution after an error occurs. 1106 </li> 1107 </ul> 1108 </li> 1109 <li> 1110 Use <code>function!</code> with a bang. 1111 <ul> 1112 <li> 1113 This allows developers to re-source their scripts and have the 1114 functions reloaded without complaint. 1115 </li> 1116 <li> 1117 Function names should never collide because functions should 1118 always be either script-local or defined in an 1119 <code>autoload</code> directory. 1120 </li> 1121 <li> 1122 Failing to use a bang in any function in an autoload file will 1123 lead to cryptic errors if vim tries to re-source the file 1124 (e.g., if you refer to an nonexistent autoload function). 1125 </li> 1126 </ul> 1127 </li> 1128 <li> 1129 Use <code>...</code> for optional arguments, not for lists of 1130 arguments. 1131 <ul> 1132 <li> 1133 Vimscript functions take at most 20 arguments. 1134 </li> 1135 <li> 1136 Lists have no such length restriction. 1137 </li> 1138 <li> 1139 Your function is likely to break when given too many arguments 1140 if you use <code>...</code> for a list of arguments. 1141 </li> 1142 </ul> 1143 </li> 1144 <li> 1145 Throw exceptions rather than printing errors. 1146 <ul> 1147 <li> 1148 Printed errors can not be caught. 1149 </li> 1150 <li> 1151 Top-level functions expecting errors may catch them and print 1152 error messages, but even those should throw their own errors 1153 when they choke. 1154 </li> 1155 </ul> 1156 </li> 1157 </ul> 1158 </BODY> 1159 </STYLEPOINT> 1160 1161 <STYLEPOINT title="Mappings"> 1162 <SUMMARY> 1163 <ul> 1164 <li> 1165 Provide opt-in key mappings in <code>plugin/mappings.vim</code>. 1166 </li> 1167 <li> 1168 <code><Plug></code> mappings can be defined in 1169 <code>plugin/plugs.vim</code> (unlike mappings.vim, plugs.vim is 1170 opt-out). 1171 </li> 1172 </ul> 1173 </SUMMARY> 1174 <BODY> 1175 <ul> 1176 <li> 1177 Define key mappings in <code>plugin/mappings.vim</code>, using 1178 <code>maktaba#plugin#MapPrefix</code> to get a prefix. 1179 <ul> 1180 <li> 1181 Mappings defined in the special <code>plugin/mappings.vim</code> 1182 file will be disabled by default (by the standard 1183 <code>maktaba#plugin#Enter()</code> boilerplate). 1184 </li> 1185 <li> 1186 Users can enable key mappings with 1187 <code>Glaive myplugin plugin[mappings]</code>. 1188 </li> 1189 </ul> 1190 </li> 1191 <li> 1192 Make all mappings with <code><unique></code>. 1193 <ul> 1194 <li> 1195 This will inform the user when they have a mapping conflict 1196 instead of silently clobbering their existing mappings. 1197 </li> 1198 </ul> 1199 </li> 1200 <li> 1201 You may provide pseudo-mappings using <code><Plug></code> and 1202 your plugin's name in <code>plugin/plugs.vim</code> (separate from 1203 standard key mappings). 1204 <ul> 1205 <li> 1206 <code><Plug></code> is a sequence which can not be typed. 1207 </li> 1208 <li> 1209 You can do something like 1210 <code>noremap <Plug>namespace#MappingName 1211 some_key_sequence</code> 1212 and then users can do 1213 <code>noremap <leader>x 1214 <Plug>namespace#MappingName</code> 1215 to take advantage of your pseudo-mapping. 1216 </li> 1217 <li> 1218 Pseudo-mappings should <strong>not</strong> be in 1219 <code>plugin/mappings.vim</code> or they will be disabled by 1220 default. 1221 </li> 1222 <li> 1223 Such pseudo-mappings should be named <code><Plug></code> 1224 followed by your plugin name, a pound sign, and a unique mapping 1225 name (CamelCased like a function). 1226 </li> 1227 </ul> 1228 </li> 1229 <li> 1230 Always use the <code>noremap</code> family of commands. Never use 1231 the <code>map</code> family. 1232 <ul> 1233 <li> 1234 <code>map</code> depends upon the user's existing mappings, and 1235 could do anything. 1236 </li> 1237 </ul> 1238 </li> 1239 <li> 1240 Only use <code>noremap</code> for commands that both make a motion 1241 and take a range. 1242 <ul> 1243 <li> 1244 <code>noremap</code> makes mappings in normal, visual, and 1245 operator-pending modes. 1246 </li> 1247 <li> 1248 If you don't want all these use <code>nnoremap</code> 1249 <code>onoremap</code> or <code>vnoremap</code> explicitly. 1250 </li> 1251 </ul> 1252 </li> 1253 <li> 1254 Always use <code><SID></code> in place of <code>s:</code> when 1255 accessing script locals in mappings. 1256 <ul> 1257 <li> 1258 Using <code>s:</code> will often fail as the mapping attempts to 1259 type a literal s and colon. 1260 </li> 1261 </ul> 1262 </li> 1263 </ul> 1264 </BODY> 1265 </STYLEPOINT> 1266 </CATEGORY> 1267 <CATEGORY title="Conventions"> 1268 <STYLEPOINT title="Dependency Checking"> 1269 <SUMMARY> 1270 Declare dependencies in addon-info.json and use <code>maktaba</code>. 1271 </SUMMARY> 1272 <BODY> 1273 <p> 1274 Declaring dependencies in addon-info.json allows conformant plugin 1275 managers (like VAM) to ensure dependencies are installed. See the 1276 <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a> for details. 1277 </p> 1278 <p> 1279 Calling <code>maktaba#library#Require</code> from dependent code at 1280 runtime ensures that dependencies have been installed and that they 1281 don't include unsafe non-library files. 1282 </p> 1283 </BODY> 1284 </STYLEPOINT> 1285 1286 <STYLEPOINT title="Statusline Flags"> 1287 <SUMMARY> 1288 Use <code><plugin-name>#status#Status()</code> or its 1289 finer-grained variants to provide statusline flags. 1290 </SUMMARY> 1291 <BODY> 1292 <p> 1293 Following is a convention for exposing statusline flags to the user. A 1294 plugin should never modify the user's statusline except for when that 1295 is the only purpose of the plugin (powerline, etc.). 1296 </p> 1297 <ul> 1298 <li> 1299 Provide the 1300 <code class="green">Info</code>, 1301 <code class="yellow">Alert</code>, 1302 <code class="orange">Warning</code>, and 1303 <code class="red">Error</code> functions under the 1304 <code><plugin-name>#status</code> namespace. 1305 </li> 1306 <li> 1307 <code class="green">Info</code> should provide information about the 1308 state of the buffer. 1309 <ul> 1310 <li> 1311 Example: The current git branch. 1312 </li> 1313 </ul> 1314 </li> 1315 <li> 1316 <code class="yellow">Alert</code> should provide a quiet reminder 1317 that the buffer is non-standard. 1318 <ul> 1319 <li> 1320 Example: The readonly setting is on. 1321 </li> 1322 </ul> 1323 </li> 1324 <li> 1325 <code class="orange">Warning</code> should provide a warning about 1326 the current state of the buffer. 1327 <ul> 1328 <li> 1329 Example: The file has been edited elsewhere. 1330 </li> 1331 </ul> 1332 </li> 1333 <li> 1334 <code class="red">Error</code> should bring to attention a loud 1335 issue with the buffer. 1336 <ul> 1337 <li> 1338 Example: The file does not pass the syntax checker. 1339 </li> 1340 </ul> 1341 </li> 1342 <li> 1343 By following these conventions, users can easily build up their own 1344 statusline customizing the verbosity and colors to their tastes. 1345 </li> 1346 <li> 1347 All functions should take no arguments and should return either 1348 empty strings or strings enclosed by square brackets, e.g. 1349 <code>[Google]</code>. For example: 1350 <ul> 1351 <li> 1352 A trailing whitespace plugin might return <code>[$]</code> if 1353 the file contains trailing whitespace 1354 </li> 1355 <li> 1356 A prose writing plugin might return <code>[write]</code> if vim 1357 is in writing mode. 1358 </li> 1359 </ul> 1360 </li> 1361 <li> 1362 Consider providing the 1363 <code><plugin-name>#status#Status</code> function. 1364 <ul> 1365 <li> 1366 It should return the first non-empty of <code>Error</code>, 1367 <code>Warning</code>, <code>Alert</code>, or <code>Info</code>. 1368 </li> 1369 <li> 1370 This is useful for users who want only the most relevant flag 1371 and do not have a colored statusline. 1372 </li> 1373 </ul> 1374 </li> 1375 </ul> 1376 </BODY> 1377 </STYLEPOINT> 1378 </CATEGORY> 1379 <CATEGORY title="Forbidden Commands"> 1380 <p> 1381 These are commands which can only be used by a limited number of 1382 plugins, and should not in general be used by yours. 1383 </p> 1384 <ul> 1385 <li> 1386 Do not use <code>:match :2match</code> or <code>:3match</code> 1387 <ul> 1388 <li> 1389 These are reserved for the user and for vim itself. 1390 </li> 1391 <li> 1392 Use <code>matchadd()</code> to create a matchlevel unique to your 1393 plugin. 1394 </li> 1395 </ul> 1396 </li> 1397 <li> 1398 Do not use <code>echoerr</code>. 1399 <ul> 1400 <li> 1401 <code>echoerr</code> does not print the red error message that you 1402 might think it does. 1403 </li> 1404 <li> 1405 <code>echoerr</code> prints an error message as well as context 1406 about the code where <code>echoerr</code> was called. 1407 </li> 1408 <li> 1409 <code>echoerr</code> is best suited for debugging. 1410 </li> 1411 <li> 1412 Use <code>echohl</code> in tandem with <code>echomsg</code> if 1413 you want the red error bar. 1414 </li> 1415 </ul> 1416 </li> 1417 <li> 1418 Use <code>echomsg</code> instead of <code>echo</code>. 1419 <ul> 1420 <li> 1421 <code>echomsg</code> messages can be reviewed with the 1422 <code>:messages</code> command. 1423 </li> 1424 <li> 1425 <code>echo</code> messages disappear permanently on redraw, which 1426 can be very annoying to users who failed to read the message in 1427 time. 1428 </li> 1429 </ul> 1430 </li> 1431 </ul> 1432 </CATEGORY> 1433 <CATEGORY title="Layout"> 1434 <p> 1435 Lay out <code>plugin/</code> files in the following sections, if 1436 applicable, separated by two blank lines: 1437 </p> 1438 <ul> 1439 <li> 1440 Declaration of script constants 1441 </li> 1442 <li> 1443 Declaration of configuration variables 1444 </li> 1445 <li> 1446 Other declarations (commands in <code>commands.vim</code> file, 1447 autocommands in <code>autocmds.vim</code> file, etc.) 1448 </li> 1449 </ul> 1450 <p> 1451 Lay out <code>autoload/</code> files in the following sections, if 1452 applicable, separated by two blank lines: 1453 </p> 1454 <ul> 1455 <li> 1456 <code>maktaba#library#Require</code> calls 1457 </li> 1458 <li> 1459 Script-local variables 1460 </li> 1461 <li> 1462 Script-local functions 1463 </li> 1464 <li> 1465 Private autoloaded functions 1466 </li> 1467 <li> 1468 Public autoloaded functions 1469 </li> 1470 </ul> 1471 <p> 1472 This is recommended convention and is not enforced. 1473 </p> 1474 1475 </CATEGORY> 1476 <CATEGORY title="Recommended Shortcuts"> 1477 1478 <p> 1479 Use the following shortcuts: 1480 </p> 1481 <ul> 1482 <li> 1483 <code>catch</code> over <code>catch /.*/</code> 1484 </li> 1485 <li> 1486 <code>return</code> over <code>return 0</code> when the return value 1487 has no semantic purpose. 1488 </li> 1489 </ul> 1490 1491 </CATEGORY> 1492 <CATEGORY title="Errata"> 1493 <p> 1494 This section plumbs some of the darker corners of vimscript, explaining 1495 the language pathologies that you wish you didn't have to know. 1496 1497 </p> 1498 1499 <STYLEPOINT title="Compatibility Mode"> 1500 <SUMMARY> 1501 If you don't support vi-compatibility mode, fail gracefully. 1502 </SUMMARY> 1503 <BODY> 1504 <p> 1505 When <code>compatible</code> is set, many vim features are not 1506 available. The vim feature which most commonly affects vimscript 1507 authors is line continuations. 1508 </p> 1509 <p> 1510 If you want your plugin to work in vim with vi compatibility on, you 1511 will need to save the compatibility options at the beginning of each 1512 plugin file, clear them, and restore them at the end of each plugin 1513 file. See <code>:help use-cpo-save</code> for details. 1514 </p> 1515 <p> 1516 Plugins that depend on maktaba generally don't need to worry about 1517 compatible mode since maktaba currently just disables it, printing a 1518 warning. 1519 </p> 1520 </BODY> 1521 </STYLEPOINT> 1522 </CATEGORY> 1523 1524 <p align="right"> 1525 Revision 1.1 1526 </p> 1527 1528 1529 <address> 1530 Nate Soares<br/> 1531 Joshua Hoak<br/> 1532 David Barnett<br/> 1533 </address> 1534</GUIDE> 1535