README.md

June 24, 2026 · View on GitHub

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

`[VS CODE EXTENSION // NEON GRAMMAR // FIELD RECORDS // LSP + DAP]`

"Open a .awk. Patterns, actions, fields, and regex light up — and awkrs jacks in."

VS Code / VSCodium support for AWK — driven by awkrs, a pattern/action engine written in Rust (POSIX / gawk / mawk-style union CLI). A standalone TextMate grammar, filetype detection, language-server integration via awkrs --lsp, one-key running, and full debugging (breakpoints, stepping, variables) via awkrs --dap.

`Read the Docs` · `Engineering Report` · `vscode-stryke` · `zshrs`

[0x00] OVERVIEW

vscode-awk is the VS Code / VSCodium extension for AWK, backed by the awkrs interpreter. It provides:

Filetype detection — *.awk files and files whose first line is an AWK shebang (#!/usr/bin/awk -f, #!/usr/bin/env awk).
Syntax highlighting — a standalone TextMate grammar (source.awk).
Language server — awkrs --lsp via vscode-languageclient (diagnostics, hover, completion — whatever the server provides).
Run — AWK: Run File (Ctrl+F5) executes the active script in a terminal as awkrs -f <file>.
Debugging — breakpoints, stepping, call stack, variables, and watch via awkrs --dap.

The grammar covers the full AWK surface: the BEGIN / END special patterns, control-flow keywords, the built-in variables (NR, NF, FS, OFS, …), the built-in functions (length, substr, split, gsub, sprintf, sqrt, system, …), field references ($0, $1, $NF, $(expr)), /.../ regex literals, the ~ / !~ match operators, strings, numbers, and operators.

Created by MenkeTechnologies.

[0x01] FEATURE MATRIX

Capability	Status
Filetype detection — `*.awk`	Implemented — `contributes.languages` extension map
Filetype detection — shebang	Implemented — `firstLine` regex `^#!.*\bawk\b`
Syntax highlighting	Implemented — TextMate grammar (`source.awk`)
Comments / brackets / autoclose	Implemented — `language-configuration.json`
Indentation	Implemented — brace-based `indentationRules`
Language server	Implemented — `awkrs --lsp` via vscode-languageclient
Run	Implemented — `AWK: Run File` (Ctrl+F5 / editor-title ▶) runs `awkrs -f <file>` in a terminal
Debugging	Implemented — breakpoints, step over/into/out, call stack, scopes, variables, watch/hover, run-without-debugging, via `awkrs --dap` (native DAP)
Config	`awk.path`, `awk.lsp.enabled`, `awk.lsp.args`

The language server needs the awkrs binary. The extension resolves it from $PATH plus the common install locations (/opt/homebrew/bin, /usr/local/bin, ~/.cargo/bin, ~/.local/bin) — so it works even when the editor is launched from the macOS Dock / Finder, which doesn't inherit your shell $PATH. Install with cargo install awkrs. If it lives elsewhere, set awk.path to the absolute path.

[0x02] INSTALL

This extension is not yet on the Marketplace. Build and install the .vsix locally:

git clone https://github.com/MenkeTechnologies/vscode-awk
cd vscode-awk
npm install
npx @vscode/vsce package          # produces vscode-awk-<version>.vsix
code --install-extension vscode-awk-*.vsix

Or drop the folder into your extensions dir for development:

git clone https://github.com/MenkeTechnologies/vscode-awk \
    ~/.vscode/extensions/vscode-awk

Open any .awk file — it lights up. The language server starts automatically when awkrs is on $PATH.

[0x03] RUN & DEBUG

Run — open a .awk file and press Ctrl+F5, click the ▶ in the editor title bar, or run AWK: Run File from the command palette. The file is saved and executed as awkrs -f <file> in an integrated terminal.

Debug — set breakpoints in the gutter and press F5 (or click the debug icon in the editor title bar). No launch.json is required: F5 on a .awk file debugs the active file. You get the full debugger — breakpoints, step over/into/out, call stack, scopes, local + global variables, watch expressions, and hover-to-evaluate — driven by the native debug adapter (awkrs --dap).

For a saved configuration, add to .vscode/launch.json:

{
  "type": "awk",
  "request": "launch",
  "name": "AWK: Debug Current File",
  "program": "${file}",
  "cwd": "${workspaceFolder}",
  "stopOnEntry": false,
  "args": []
}

Launch attributes: program, args, cwd, stopOnEntry, noDebug, interpreterArgs, and awkPath (override the binary for one session). The adapter binary is resolved the same way as the language server, so it works under the macOS GUI $PATH.

[0x04] SYNTAX // SCOPES

The grammar maps AWK tokens to standard TextMate scopes, so every VS Code theme colors them:

Token group	Scope	Sample
Special patterns	`keyword.other.special-pattern.awk`	`BEGIN` `END`
Control flow	`keyword.control.awk`	`if` `else` `while` `for` `do` `break` `continue` `next` `nextfile` `exit` `return`
Delete / membership	`keyword.control.delete.awk` / `keyword.operator.word.awk`	`delete` `in`
I/O statements	`keyword.other.io.awk`	`print` `printf` `getline`
Function intro	`storage.type.function.awk`	`function` `func`
Built-in variables	`variable.language.awk`	`NR` `NF` `FS` `OFS` `ORS` `RS` `FILENAME` `FNR` `RSTART` `RLENGTH` `SUBSEP` `ARGC` `ARGV` `ENVIRON` `CONVFMT` `OFMT`
String functions	`support.function.string.awk`	`length` `substr` `index` `split` `sub` `gsub` `match` `sprintf` `tolower` `toupper`
Math functions	`support.function.math.awk`	`sin` `cos` `atan2` `exp` `log` `sqrt` `int` `rand` `srand`
I/O functions	`support.function.io.awk`	`system` `close` `fflush`
Field references	`variable.language.field.awk`	`$0` `$1` `$NF` `$(NF-1)`
Match operators	`keyword.operator.match.awk`	`~` `!~`

Strings (double-quoted with escapes), /.../ regex literals, numbers (integer, float, scientific, hex), comments (#), and the full operator set (assignment, comparison, logical, arithmetic, ternary, pipe) are scoped too.

[0x05] LANGUAGE SERVER

The extension launches awkrs --lsp (stdio JSON-RPC) through vscode-languageclient. Configure it in Settings:

Setting	Default	Effect
`awk.path`	`awkrs`	Path to the awkrs executable
`awk.lsp.enabled`	`true`	Start the language server (set `false` for highlighting only)
`awk.lsp.args`	`["--lsp"]`	Args passed to start the server

The transport is omitted so the client spawns bare awkrs --lsp and never appends --stdio — the arg-rejection / "connection got disposed" failure mode learned from vscode-stryke. If the binary is missing, the extension shows one non-fatal warning and syntax highlighting keeps working.

[0x06] VERIFYING THE GRAMMAR

Verify the grammar tokenizes correctly with the real VS Code grammar engine (vscode-textmate + vscode-oniguruma, the engine VS Code itself uses):

npm install
node scripts/tokenize_test.js

[0x07] LAYOUT

vscode-awk/
├── package.json                 # extension manifest (language, grammar, config, LSP, DAP)
├── language-configuration.json  # comments, brackets, autoclose, indent rules
├── extension.js                 # LSP client (awkrs --lsp) + run + debug (awkrs --dap)
├── lib/resolveBinary.js         # GUI-PATH-safe awkrs binary resolver
├── syntaxes/awk.tmLanguage.json # TextMate grammar (source.awk)
├── scripts/tokenize_test.js     # tokenizes a sample with vscode-textmate + asserts scopes
├── scripts/resolver_test.js     # unit tests for the binary resolver
└── scripts/activate_test.js     # LSP/DAP spawn-contract regression tests

Read the Docs · Engineering Report · vscode-stryke · zshrs

`Read the Docs` · `Engineering Report` · `vscode-stryke` · `zshrs`