README.md

June 24, 2026 · View on GitHub

██╗   ██╗██╗███╗   ███╗      █████╗ ██╗    ██╗██╗  ██╗
██║   ██║██║████╗ ████║     ██╔══██╗██║    ██║██║ ██╔╝
██║   ██║██║██╔████╔██║     ███████║██║ █╗ ██║█████╔╝
╚██╗ ██╔╝██║██║╚██╔╝██║     ██╔══██║██║███╗██║██╔═██╗
 ╚████╔╝ ██║██║ ╚═╝ ██║     ██║  ██║╚███╔███╔╝██║  ██╗
  ╚═══╝  ╚═╝╚═╝     ╚═╝     ╚═╝  ╚═╝ ╚══╝╚══╝ ╚═╝  ╚═╝

`[VIM PLUGIN // NEON SYNTAX // STANDALONE AWK GRAMMAR // ALE + LSP + DAP]`

"Load it with pathogen. Open a .awk. It lights up."

Vim / Neovim support for AWK, targeting awkrs — a pattern / action engine written in Rust with a POSIX / gawk / mawk-style union CLI. Standalone syntax highlighting, filetype detection, brace-aware indentation, :make / :AwkRun wiring, ALE linting, and vim-lsp / coc.nvim / nvim-dap integration. Zero configuration.

cd ~/.vim/bundle && git clone https://github.com/MenkeTechnologies/vim-awk   # pathogen

`Read the Docs` · `Engineering Report`

[0x00] OVERVIEW

vim-awk is Vim / Neovim 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, so pathogen / vim-plug / native packages add it to runtimepath with zero special handling and zero configuration.

The syntax file is a standalone AWK grammar covering the POSIX awk core plus the gawk / mawk extensions awkrs accepts. AWK's surface is small and fixed, so the keyword / built-in lists are hand-curated rather than generated; scripts/gen_syntax.sh stamps the file with the awkrs version it was verified against.

patterns — BEGIN END BEGINFILE ENDFILE, /regex/, expression patterns
built-in variables — NR NF FS OFS ORS RS FILENAME FNR RSTART RLENGTH SUBSEP ARGC ARGV ENVIRON CONVFMT OFMT (+ gawk FPAT, IGNORECASE, RT, …)
built-in functions — length substr index split sub gsub match sprintf sin cos atan2 exp log sqrt int rand srand tolower toupper system close fflush (+ gawk gensub, strftime, systime, bit ops, …)

The awkrs binary must be on $PATH for running, linting and LSP.

[0x01] FEATURE MATRIX

Capability	Status
Filetype detection — `*.awk`	Implemented — every `*.awk` buffer becomes `filetype=awk`
Filetype detection — shebang	Implemented — extensionless scripts with `#!/usr/bin/env awkrs` (or awk / gawk / mawk) are detected
Syntax highlighting	Implemented — standalone AWK grammar (patterns, control flow, statements, built-in variables, built-in functions, field references, regex literals, strings, operators)
Indentation	Implemented — standalone brace-aware indenter
Comments	Implemented — `commentstring=# %s`, comment-continuation `formatoptions`
Run / make	Implemented — `:compiler awkrs` (`:make` → quickfix) and `:AwkRun` (`<LocalLeader>r`)
Linting	Implemented — ALE linter running `awkrs -L invalid`
Language server (vim-lsp)	Implemented — `awkrs --lsp`, allowlisted for `awk`
Language server (coc.nvim)	Implemented — ready-to-paste `languageserver` config
Debug adapter (nvim-dap)	Implemented — ready-to-paste `awkrs --dap` adapter config
Help	Implemented — `:help vim-awk`
Config required	None — opt-outs to disable ALE, LSP, or the run mapping

[0x02] INSTALL

pathogen

cd ~/.vim/bundle
git clone https://github.com/MenkeTechnologies/vim-awk
# then inside vim:  :Helptags

vim-plug (add to ~/.vimrc / init.vim)

Plug 'MenkeTechnologies/vim-awk'

native packages (Vim 8+ / Neovim)

git clone https://github.com/MenkeTechnologies/vim-awk \
    ~/.vim/pack/plugins/start/vim-awk

Open any .awk file and it lights up — no further configuration. See :help vim-awk.

[0x03] SYNTAX // TOKEN CATEGORIES

The grammar classifies tokens into the categories the AWK language defines — POSIX awk plus the gawk / mawk extensions awkrs accepts:

Category	Tokens (sample)	Highlight
Patterns	`BEGIN` `END` `BEGINFILE` `ENDFILE` · `/regex/` · expression patterns	`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`
Field references	`$0` `$1` `$NF` `$(expr)`	`Identifier`

ERE regex literals (/.../), double-quoted strings with escapes, the ~ / !~ match operators, # comments, numbers, and the full operator set are all handled. Everything links to standard highlight groups, so every colorscheme covers it.

[0x04] RUN // LINT

:compiler awkrs wires :make to run the current program through awkrs in lint mode and route diagnostics to the quickfix list:

awkrs -L invalid -f %

To execute the current buffer as an AWK program: :AwkRun [files...] (mapped to <LocalLeader>r).

When ALE is installed, vim-awk registers a linter that runs the same awkrs -L invalid -f %t inline. Diagnostics of the form <file>:<line>: <message> are surfaced. Skipped silently if ALE is absent or g:vim_awk_no_ale is set.

[0x05] LANGUAGE SERVER

vim-lsp

Registered automatically as awkrs --lsp, allowlisted for the awk filetype — no extra config when vim-lsp is installed. awkrs must be invoked with only --lsp — it rejects an appended --stdio, so do not add transport args.

coc.nvim

Add to coc-settings.json:

{
  "languageserver": {
    "awkrs": {
      "command": "awkrs",
      "args": ["--lsp"],
      "filetypes": ["awk"]
    }
  }
}

[0x06] DEBUG ADAPTER

awkrs exposes a Debug Adapter via awkrs --dap (DAP on stdio). For nvim-dap, add to your Neovim config:

local dap = require('dap')
dap.adapters.awkrs = {
  type = 'executable',
  command = 'awkrs',
  args = { '--dap' },   -- no extra transport args; awkrs rejects them
}
dap.configurations.awk = {
  { type = 'awkrs', request = 'launch', name = 'Run AWK program',
    program = '${file}' },
}

[0x07] OPTIONS

Set before the plugin loads (e.g. in your vimrc):

Variable	Effect
`let g:vim_awk_no_ale = 1`	Skip ALE linter registration
`let g:vim_awk_no_lsp = 1`	Skip vim-lsp server registration
`let g:vim_awk_no_maps = 1`	Skip the `<LocalLeader>r` run mapping

[0x08] LAYOUT

vim-awk/
├── ftdetect/awk.vim     # *.awk + awk / awkrs shebang -> filetype=awk
├── syntax/awk.vim       # standalone AWK grammar (POSIX + gawk / mawk)
├── scripts/gen_syntax.sh # stamps syntax/awk.vim with the awkrs version
├── ftplugin/awk.vim     # commentstring '# %s', :compiler awkrs, :AwkRun
├── compiler/awkrs.vim   # :make via awkrs -L invalid -> quickfix
├── indent/awk.vim       # standalone brace-aware indenter
├── plugin/awk.vim       # ALE linter + vim-lsp + coc + nvim-dap wiring
└── doc/awk.txt          # :help vim-awk

Standard Vim runtime layout — pathogen / vim-plug / native packages add it to runtimepath with no special handling.

Read the Docs · Engineering Report

`Read the Docs` · `Engineering Report`