>_EXECUTIVE SUMMARY
vim-viml is the Vim / Neovim editor support for VimL (Vimscript), targeting vimlrs — a standalone Vimscript interpreter, a Rust port of Neovim's eval engine running on fusevm. It ships as a standard Vim runtime tree (ftdetect/, syntax/, indent/, ftplugin/, compiler/, plugin/, doc/), so pathogen / vim-plug / native packages add it to runtimepath with no special handling. It augments Vim's built-in vim filetype: the ftplugin guards on its own b:did_ftplugin_vimlrs marker so it layers the vimlrs run / make wiring on top of the stock runtime rather than replacing it.
Design principle: the syntax file is a standalone VimL grammar covering the eval-engine surface vimlrs implements — not a wrapper around another language's syntax. The token surface (statement keywords, ex commands, scope sigils, special v: vars, and the funcs.c builtin subset) is hand-curated; scripts/gen_syntax.sh stamps the file with the vimlrs version it was verified against (currently v0.2.1).
~RUNTIME LAYOUT
Standard Vim runtime directories. Each file is loaded automatically when the plugin is on runtimepath; no entry point or sourcing call is required.
| File | Responsibility |
|---|---|
ftdetect/vim.vim | Sets filetype=vim for *.vim files, the vimrc / gvimrc / exrc / init.vim family, and any file whose first line is a vimlrs / vim / nvim shebang (e.g. #!/usr/bin/env vimlrs). |
syntax/vim.vim | Standalone VimL grammar — command-position comments / shebang, numbers, single- and double-quoted strings, scope-sigil vars, options / env / registers, special v: vars, statement keywords, ex commands, builtin functions, and operators, linked to standard highlight groups. |
indent/vim.vim | Standalone indentexpr (GetVimlIndent()) — indents after a block-opening keyword (if / while / for / function / try), dedents midpoints (else / elseif / catch / finally) and closers (endif / endfunction / endtry). |
ftplugin/vim.vim | Buffer-local options behind a b:did_ftplugin_vimlrs guard: commentstring=" %s, comments=:", comment-continuation formatoptions, :compiler vimlrs, the :VimlRun command and its <LocalLeader>r mapping, with a matching b:undo_ftplugin. |
compiler/vimlrs.vim | Defines the vimlrs compiler: makeprg=vimlrs % (positional file — no -f) with an errorformat for Vim-style EXXX: messages and file:line:col: forms, so :make routes them to the quickfix list. |
plugin/vim.vim | Global wiring: ALE linter definition (vimlrs %t), vim-lsp server registration, coc + nvim-dap snippets (commented), and the g:vim_viml_no_ale / g:vim_viml_no_lsp opt-outs, behind a load guard. |
doc/vimlrs.txt | Vim help (:help vim-viml) with tagged sections for install, detection, syntax, running, linting, LSP, DAP, and options. |
$SYNTAX COVERAGE
Token categories taken from the VimL language definition — the eval-engine surface vimlrs implements. Scope-sigil variables (g:, s:, b:, w:, t:, l:, a:, v:), options (&name), env vars ($NAME) and registers (@x) are first-class VimL constructs and are highlighted.
| Group | Tokens (sample) | Highlight link |
|---|---|---|
| Statements / control flow | if elseif else endif while for function return try catch finally let const call execute echo | Statement |
| Ex commands | source runtime normal set setlocal command autocmd augroup highlight syntax map nnoremap sign sleep | PreProc |
| Scope variables | g: s: b: w: t: l: a: v: · &option · $ENV · @reg | Identifier / Special |
Special v: vars | v:true v:false v:null v:count v:val v:key v:exception v:lnum v:errmsg v:shell_error | Constant |
| List / dict / string fns | add copy extend filter get has_key keys len map range reduce sort split string substitute type values | Function |
| Math / bit / JSON fns | abs ceil cos floor fmod pow round sin sqrt · and or xor invert · json_encode json_decode | Function |
| Literals & operators | 'literal' / "escaped\n" strings, numbers, . / .. concat, =~ / !~ match | String / Number / Operator |
#TOOLING INTEGRATION
All integrations degrade gracefully: each is guarded so the plugin loads cleanly whether or not ALE / vim-lsp / coc / nvim-dap is installed. The script file is a positional argument (no -f flag), --lsp starts the language server, and --dap the debug adapter. vimlrs has no standalone lint flag yet, so :make / ALE run the script and scrape Vim-style errors off stderr; the live, non-executing diagnostics path is the LSP. Each of --lsp / --dap is the sole flag (no appended --stdio), mirroring stryke --lsp; the vim-lsp / nvim-dap clients add no transport args.
| Integration | Mechanism |
|---|---|
| :make (compiler) | The vimlrs compiler sets makeprg=vimlrs % with an errorformat matching Vim-style EXXX: and file:line:col: diagnostics, routing them to the quickfix list. |
| :VimlRun | Buffer-local command running vimlrs % on the current program (positional file — no -f), mapped to <LocalLeader>r (skipped if g:vim_viml_no_maps is set). |
| ALE | Registers a linter via ale#linter#Define running vimlrs %t; the handler parses <file>:<line>: <message> and bare EXXX: codes into error items. Skipped if ALE is absent or g:vim_viml_no_ale is set. |
| vim-lsp | Registers a server (lsp#register_server) running vimlrs --lsp, allowlisted for the vim filetype. Skipped if vim-lsp is absent or g:vim_viml_no_lsp is set. |
| coc.nvim | A ready-to-paste languageserver block for coc-settings.json using vimlrs --lsp, documented in the plugin source and README. |
| nvim-dap | A ready-to-paste adapter / configuration block using vimlrs --dap, documented in the plugin source and README. |
@COMPATIBILITY
| Target | Status |
|---|---|
| Vim 8+ | Filetype, syntax, indent, ftplugin, compiler, doc |
| Neovim | Same runtime files (no Lua required for the core) |
| pathogen / vim-plug / native packages | Standard runtime layout — no plugin-manager-specific handling |
| ALE | vimlrs %t linter |
| vim-lsp | vimlrs --lsp language server wired |
| coc.nvim | languageserver config provided |
| nvim-dap | vimlrs --dap adapter config provided |