- - Revision 1.1 -
- - - - Nate Soares- Each style point has a summary for which additional information is available - by toggling the accompanying arrow button that looks this way: - . - You may toggle all summaries with the big arrow button: -
-| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
- This is the in-depth vimscript guide. If you're just a casual user - looking to write a plugin, the - abbreviated style guide is for you. -
-- This rather rotund guide dives into justifications and clarifications. - It provides an idealized set of rules that are rather too draconian to - push on casual scripters. -
- -- It's for users who want to know why certain decisions were made in the - abbreviated guide and who want to learn a thing or two about using - vimscript safely. -
-- Fair warning: Vimscript is a maddening abyss. When you gaze into it, it - gazes also into you. Proceed with caution. -
-- Vim is highly configurable. Users can change many of the default - settings, including the case sensitivity, the regular expression rules, - the substitution rules, and more. In order for your vimscript to work - for all users, follow these guidelines: -
-\m,
- \v, \M, or \V (prefer
- tersity)
- ., *, and {.
- magic setting you must prefix it
- with one of the magic control atoms. This future-proofs your
- regular expression against other devs modifying it and forgetting
- to add the control atom.
- :s[ubstitute] in scripts.
- :substitute moves the cursor.
- :substitute outputs an error message when the match
- does not exist.
- g flag depends upon the
- gdefault setting. If you do use
- :substitute you must save gdefault, set
- it to 0 or 1, perform the substitution,
- and then restore it.
- maktaba#buffer#Replace.
- =~# and
- =~?, never =~).
- !~ == != > >= < and
- <=
- == and
- >= are fine for numbers, but ==# and
- >=# must be used for strings.
- =~ and friends is dependent upon the
- ignorecase setting.
- ignorecase setting. Be prepared to justify
- your reasoning.
- \c or \C.
- =~#, etc.).
- ignorecase
- setting.
- ignorecase setting. Be prepared to justify
- your reasoning.
- normal! instead of normal.
- ! the command will use the user's
- key mappings and you have literally no idea what your macro will
- do.
- noremap family of commands.
- map command respects the users existing
- mappings and could do anything.
- catch, match the error code rather than the
- error text.
- :help error-messages.
- - In general, guard all commands and functions against user settings. -
- -maktaba#error codes found in
- maktaba.
- :help error-messages.
- maktaba#error#Message.
- 0 == 'foo' evaluates to true.
- is# operator.
- Otherwise, prefer maktaba#value#IsEqual or check
- type() explicitly.
- maktaba#ensure, or check
- maktaba#value or type() and throw your own
- errors.
- :unlet for variables that may change types,
- particularly those assigned inside loops.
- maktaba#function instead to create and
- manipulate handles to functions.
- self parameter which access
- the dict state.
- - All other language features are fair game. -
-maktaba.
- plugin-names-like-this
- autoload/ subdirectory of
- your plugin.
- plugin/ or instant/ directory
- should begin with the boilerplate
- let [s:plugin, s:enter] = maktaba#plugin#Enter(expand('<sfile>:p'))
-if !s:enter
- finish
-endifinstant/flags.vim.
- call s:plugin.Flag('FLAGNAME', DEFAULT_VALUE).
- :Glaive
- command (see glaive).
- plugin/ or the
- ftplugin/ subdirectories.
- plugin/commands.vim
- or ftplugin/ files.
- plugin/autocmds.vim,
- inside an augroup.
- plugin/mappings.vim and
- will be disabled unless explicitly enabled by users.
- plugin/settings.vim or
- instant/settings.vim.
- after/ subdirectory.
- after/ should be reserved for the user.
- after/.
- - Follow google-wide style conventions. Mimic google python style when - in doubt. -
- - - - - - - -
- plugin-names-like-this,
- FunctionNamesLikeThis,
- CommandNamesLikeThis,
- augroup_names_like_this,
- variable_names_like_this.
-
- Prefix all variables with their scope. -
-- Vim plugins should provide any or all of the following: - Commands, Autocommands, - Functions, Statusline Flags, and - Mappings. -
- -plugin/commands.vim.[!]
-plugin/autocmds.vim.s:
-[!].[abort].plugin/mappings.vim.
- <Plug> mappings can be defined in
- plugin/plugs.vim (unlike mappings.vim, plugs.vim is
- opt-out).
- <plugin-name>#status#Status() or its
- finer-grained variants to provide statusline flags.
- - These are commands which can only be used by a limited number of - plugins, and should not in general be used by yours. -
-:match :2match or :3match
- matchadd() to create a matchlevel unique to your
- plugin.
- echoerr.
- echoerr does not print the red error message that you
- might think it does.
- echoerr prints an error message as well as context
- about the code where echoerr was called.
- echoerr is best suited for debugging.
- echohl in tandem with echomsg if
- you want the red error bar.
- echomsg instead of echo.
- echomsg messages can be reviewed with the
- :messages command.
- echo messages disappear permanently on redraw, which
- can be very annoying to users who failed to read the message in
- time.
-
- Lay out plugin/ files in the following sections, if
- applicable, separated by two blank lines:
-
commands.vim file,
- autocommands in autocmds.vim file, etc.)
-
- Lay out autoload/ files in the following sections, if
- applicable, separated by two blank lines:
-
maktaba#library#Require calls
- - This is recommended convention and is not enforced. -
- -- Use the following shortcuts: -
-catch over catch /.*/
- return over return 0 when the return value
- has no semantic purpose.
- - This section plumbs some of the darker corners of vimscript, explaining - the language pathologies that you wish you didn't have to know. - -
- - -- Revision 1.1 -
- - - - Nate Soares- - Revision 1.1 -
- - - - Nate Soares- Each style point has a summary for which additional information is available - by toggling the accompanying arrow button that looks this way: - . - You may toggle all summaries with the big arrow button: -
-| - | - |
| - | - |
| - | - |
- This is a casual version of the vimscript style guide, because - vimscript is a casual language. When submitting vim plugin code, you - must adhere to these rules. For clarifications, justifications, and - explanations about the finer points of vimscript, please refer to the - heavy guide. -
-- It's hard to get vimscript right. Many commands depend upon the user's - settings. By following these guidelines, you can hope to make your - scripts portable. -
- - - - - - -[!].
- plugin/mappings.vim, using
- maktaba#plugin#MapPrefix to get a prefix.
- - Follow google style conventions. When in doubt, treat vimscript style - like python style. -
- - - -
- In general, use
- plugin-names-like-this,
- FunctionNamesLikeThis,
- CommandNamesLikeThis,
- augroup_names_like_this,
- variable_names_like_this.
-
Always prefix variables with their scope.
-- Revision 1.1 -
- - - - Nate Soares