>_EXECUTIVE SUMMARY
vim-awk is the Vim / Neovim editor support for AWK, targeting awkrs — a pattern / action engine written in Rust with a POSIX / gawk / mawk-style union CLI. 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.
Design principle: the syntax file is a standalone AWK grammar covering the POSIX awk core plus the gawk / mawk extensions awkrs accepts — not a wrapper around another language's syntax. The token surface (keywords, statements, built-in variables, built-in functions) is hand-curated because AWK's grammar is small and fixed; scripts/gen_syntax.sh stamps the file with the awkrs version it was verified against (currently v0.4.18).
~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/awk.vim | Sets filetype=awk for *.awk files and for any file whose first line is an awk / awkrs / gawk / mawk shebang (e.g. #!/usr/bin/env awkrs). |
syntax/awk.vim | Standalone AWK grammar — comments / shebang, numbers, field references, strings, ERE regex literals, patterns, control flow, statements, built-in variables, built-in functions, and operators, linked to standard highlight groups. |
indent/awk.vim | Standalone indentexpr (GetAwkIndent()) — indents after a line opening a block / paren / bracket, dedents lines starting with a closing delimiter. |
ftplugin/awk.vim | Buffer-local options: commentstring=# %s, comments=:#, comment-continuation formatoptions, :compiler awkrs, the :AwkRun command and its <LocalLeader>r mapping, with a matching b:undo_ftplugin. |
compiler/awkrs.vim | Defines the awkrs compiler: makeprg=awkrs -L invalid -f % with an errorformat for awkrs / gawk-style diagnostics, so :make routes them to the quickfix list. |
plugin/awk.vim | Global wiring: ALE linter definition, vim-lsp server registration, coc + nvim-dap snippets (commented), and the g:vim_awk_no_ale / g:vim_awk_no_lsp opt-outs, behind a load guard. |
doc/awk.txt | Vim help (:help vim-awk) with tagged sections for install, detection, syntax, running, linting, LSP, DAP, and options. |
$SYNTAX COVERAGE
Token categories taken from the AWK language definition — the POSIX awk core plus the gawk / mawk extensions awkrs accepts in its union CLI. Field references ($0, $1, $NF, $(expr)) and the ~ / !~ match operators are first-class AWK constructs and are highlighted.
| Group | Tokens (sample) | Highlight link |
|---|---|---|
| Patterns | BEGIN END BEGINFILE ENDFILE | PreProc |
| Control flow | if else while for do break continue next nextfile exit return delete in | Statement |
| Statements | print printf getline | Statement |
| Function definition | function func | Keyword |
| Built-in variables | NR NF FS OFS ORS RS FILENAME FNR RSTART RLENGTH SUBSEP ARGC ARGV ENVIRON CONVFMT OFMT | Special |
| String functions | length substr index split sub gsub match sprintf tolower toupper | Function |
| Arithmetic functions | sin cos atan2 exp log sqrt int rand srand | Function |
| I/O functions | system close fflush | Function |
| Literals & vars | field refs ($0/$1/$NF), strings, ERE regex /.../, numbers, ~ / !~ | String / Number / Identifier |
#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. -L invalid lints, -f reads the program file, --lsp starts the language server, and --dap the debug adapter. 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 awkrs compiler sets makeprg=awkrs -L invalid -f % with an errorformat matching awkrs / gawk diagnostics, routing them to the quickfix list. |
| :AwkRun | Buffer-local command running awkrs -f % on the current program, mapped to <LocalLeader>r (skipped if g:vim_awk_no_maps is set). |
| ALE | Registers a linter via ale#linter#Define running awkrs -L invalid -f %t; the handler parses <file>:<line>: <message> into error items. Skipped if ALE is absent or g:vim_awk_no_ale is set. |
| vim-lsp | Registers a server (lsp#register_server) running awkrs --lsp, allowlisted for the awk filetype. Skipped if vim-lsp is absent or g:vim_awk_no_lsp is set. |
| coc.nvim | A ready-to-paste languageserver block for coc-settings.json using awkrs --lsp, documented in the plugin source and README. |
| nvim-dap | A ready-to-paste adapter / configuration block using awkrs --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 | awkrs -L invalid linter |
| vim-lsp | awkrs --lsp language server wired |
| coc.nvim | languageserver config provided |
| nvim-dap | awkrs --dap adapter config provided |