SpaceVim
A modular Vim/Neovim configuration
Home | About | Quick start guide | Documentation | Development | Community | Sponsors | 中文
:memo: Add comment or doc.:gift: New feature.:bug: Bug fix.:bomb: Breaking compatibility.:white_check_mark: Write test.:fire: Remove something.:beer: I’m happy like reduced code complexity.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:
Prefer single quoted strings
Double quoted strings are semantically different in vimscript, and you probably don’t want them (they break regexes).
Use double quoted strings when you need an escape sequence (such as “\n”) or if you know it doesn’t matter and you need to embed single quotes.
Use the =~# or =~? operator families over the =~ family.
The matching behavior depends upon the user’s ignorecase and smartcase settings and on whether you compare them with the =~, =~#, or =~? family of operators. Use the =~# and =~? operator families explicitly when comparing strings unless you explicitly need to honor the user’s case sensitivity settings.
Prefix all regexes with one of \m, \v, \M, or \V.
In addition to the case sensitivity settings, regex behavior depends upon the user’s nomagic setting. To make regexes act like nomagic and noignorecase are set, prepend all regexes with one of \m, \v, \M, or \V.
You are welcome to use other magic levels (\v) and case sensitivities (\c) so long as they are intentional and explicit.
Avoid commands with unintended side effects.
Avoid using :s[ubstitute] as it moves the cursor and prints error messages. Prefer functions (such as search()) better suited to scripts.
The meaning of the 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.
For many Vim commands, functions exist that do the same thing with fewer side effects. See :help functions for a list of built-in functions.
Avoid commands that rely on user settings.
Always use normal! instead of normal. The latter depends upon the user’s key mappings and could do anything.
Avoid :s[ubstitute], as its behavior depends upon a number of local settings.
The same applies to other commands not listed here.
Match error codes, not error text.
Error text may be locale dependent.
Message the user infrequently.
Loud scripts are annoying. Message the user only when:
Use strict and explicit checks where possible.
Vimscript has unsafe, unintuitive behavior when dealing with some types. For instance, 0 == ‘foo’ evaluates to true.
Use strict comparison operators where possible. When comparing against a string literal, use the is# operator. Otherwise, prefer maktaba#value#IsEqual or check type() explicitly.
Check variable types explicitly before using them. Use functions from maktaba#ensure, or check maktaba#value or type() and throw your own errors.
Use :unlet for variables that may change types, particularly those assigned inside loops.
Use sparingly.
Use python only when it provides critical functionality, for example when writing threaded code.
Use Vimscript instead.
Avoid using other scripting languages such as ruby and lua. We cannot guarantee that the end user’s Vim has been compiled with support for non-vimscript languages.
Organize functionality into modular plugins
Group your functionality as a plugin, unified in one directory (or code repository) which shares your plugin’s name (with a “vim-“ prefix or “.vim” suffix if desired). It should be split into plugin/, autoload/, etc. subdirectories as necessary, and it should declare metadata in the addon-info.json format (see the Vim documentation for details).
In the autoload/ directory, defined with [!] and [abort].
Autoloading allows functions to be loaded on demand, which makes startup time faster and enforces function namespacing.
Script-local functions are welcome, but should also live in autoload/ and be called by autoloaded functions.
Non-library plugins should expose commands instead of functions. Command logic should be extracted into functions and autoloaded.
[!] allows developers to reload their functions without complaint.
[abort] forces the function to halt when it encounters an error.
In the plugin/commands.vim or under the ftplugin/ directory, defined without [!].
General commands go in plugin/commands.vim. Filetype-specific commands go in ftplugin/.
Excluding [!] prevents your plugin from silently clobbering existing commands. Command conflicts should be resolved by the user.
Place them in plugin/autocmds.vim, within augroups.
Place all autocommands in augroups.
The augroup name should be unique. It should either be, or be prefixed with, the plugin name.
Clear the augroup with autocmd! before defining new autocommands in the augroup. This makes your plugin re-entrable.
Place them in plugin/mappings.vim, using maktaba#plugin#MapPrefix to get a prefix.
All key mappings should be defined in plugin/mappings.vim.
Partial mappings (see :help using-
Always use the noremap family of commands.
Your plugins generally shouldn’t introduce mappings, but if they do, the map command respects the users existing mappings and could do anything.
When using catch, match the error codes rather than the error text.
Change settings locally
Use :setlocal and &l: instead of :set and & unless you have explicit reason to do otherwise.
Follow google style conventions. When in doubt, treat vimscript style like python style.
Similar to python.
This does not apply to arguments to commands.
let s:variable = “concatenated “ . “strings” command -range=% MyCommand
You need not go out of your way to remove it.
Trailing whitespace is allowed in mappings which prep commands for user input,
such as “noremap
+command -bang MyCommand call myplugin#foo()
+command MyCommand2 call myplugin#bar()
-command -bang MyCommand call myplugin#foo()
-command MyCommand2 call myplugin#bar()
+command SomeLongCommand
+ \ call some#function()
-command SomeLongCommand call
- \ some#function()
When continuing a multi-line command a pipe can be substituted for this space as necessary, as follows:
autocommand BufEnter <buffer>
\ if !empty(s:var)
\| call some#function()
\|else
\| call some#function(s:var)
\|endif
plugin-names-like-thisFunctionNamesLikeThisCommandNamesLikeThisaugroup_names_like_thisvariable_names_like_this<Down>, <Up>.SPC, WIN.SPC t w, <Leader> f o./ for alternative sequences: <Tab> / Ctrl-n.Ctrl-e rather than <C-e> in documentation.kebab-case for key binding short descriptionPowered by Jekyll