tree-sitter-irules
A tree-sitter parser for F5 iRules — the TCL-derived scripting language used to program traffic management on F5 BIG-IP.
Why use this
iRules has almost no modern editor support, so most tools fall back on crude keyword matching. This parser teaches tree-sitter the actual structure of an iRules script — its event handlers, namespaced commands, and operators — which unlocks the tooling other languages take for granted:
- Real syntax highlighting that knows an event from a command from a
variable, and updates as you type. Backed by the shipped
queries/irules/highlights.scm. - Structural folding of event handlers and blocks, so you can collapse
a rule to see its shape at a glance (
queries/irules/folds.scm). - A foundation for richer tooling — a precise syntax tree is what
code navigation (go-to-definition, find-references), linters that catch
mistakes (a misspelled event, a command used in the wrong context), and
project-wide refactoring are built on. The parse tree is in place; those
higher-level features land as the matching queries (
locals.scm,tags.scm) and integrations are added.
Because tree-sitter parses incrementally and tolerates errors, this works on every keystroke and even while a rule is half-written.
How iRules differs from TCL
iRules are syntactically a dialect of TCL with three additions:
- Event handlers:
when CLIENT_ACCEPTED { ... }, with optionalpriority Nandtiming on|offmodifiers. - Namespace-qualified built-in commands:
HTTP::host,IP::client_addr,LB::server,SSL::cert,TCP::respond, etc. - Extra expression operators on top of TCL's
eq/ne/in/ni:starts_with,ends_with,contains,equals,matches,matches_regex,matches_glob.
This grammar is built as an extension of
tree-sitter-tcl
by Lewis Russell, redistributed under the MIT license. See LICENSE.
Recognised iRules surface
Names below come from F5's authoritative sources:
Commands.html,
iRulesReference.html,
Operators.html, and
when.html. The list
reflects what queries/irules/highlights.scm will tag as
@function.builtin; commands outside the list still parse, they just fall
through to the generic @function capture.
Namespaced commands (<NS>::<command>):
| Group | Namespaces |
|---|---|
| Transport / IP | IP, TCP, UDP, SCTP, LINK, VLAN, ROUTE, DATAGRAM, DHCP, FLOW, FLOWTABLE, IPFIX, LSN, NSH, PCP |
| TLS | SSL, CLIENTSSL, SERVERSSL, TLS, X509, IKE |
| HTTP | HTTP, HTTP2, HTTP3, WS, WEBSOCKET, CACHE, COMPRESS, REWRITE, STREAM, URI, JSON, XML, HTML, SSE |
| Other application | DNS, SIP, SDP, RTSP, FTP, MQTT, FIX, DIAMETER, RADIUS, ICAP, GTP, TDS, NTLM, MR, GENERICMESSAGE, CONNECTOR, DNSMSG, IMAP, POP3, SIPALG, SMTPS, SOCKS |
| Load balancing / virtual | LB, POOL, NODE, MEMBER, VIRTUAL, SNAT, SNATPOOL, PERSIST, PROFILE, PROXY, ONECONNECT, RATELIMIT, SCRUBBER, GTM, TMM, TMSH, BWC, ISESSION, IVS, L7CHECK |
| Access / security | ACL, ACCESS, ACCESS2, AAA, AUTH, WEBSSO, VDI, WAM, TAP, ASM, BOTDEFENSE, ANTIFRAUD, DOSL7, CATEGORY, CLASSIFICATION, CLASSIFY, CLASS, ADM, APM, ECA, POLICY, PSC |
| Adaptation / data | ADAPT, PEM, AVR, STATS, TABLE, SESSION, EVENT, LOG, LOGGING, MEMORY, RESOLV, RESOLVER, REST, XLAT, NAME, HSL, ILX, QOE, MATRIX, NS, ISTATS, MESSAGE, SIDEBAND |
| Crypto / encoding | CRYPTO, AES, DES, RC4, HMAC, MD5, SHA1, SHA256, SHA384, SHA512, B64, HEX, BIGNUM, ASN1 |
Global (non-namespaced) iRules commands also tagged as
@function.builtin: accumulate, active_members, active_nodes,
after, b64decode, b64encode, call, clientside, clone,
collect, connect, crc32, decode_uri, discard, domain, drop,
event, findclass, findstr, forward, getfield, htonl, htons,
listen, matchclass, member, members, node, nodes, ntohl,
ntohs, peer, persist, pool, recv, reject, release, send,
serverside, session, sharedvar, snat, snatpool, substr,
table, virtual.
Event names are intentionally open: anything matching
/[A-Z][A-Z0-9_]*/ parses as an event_name. F5 documents 200+ events
across protocol families and adds new ones each BIG-IP release; encoding
a closed set in the parser would force a regen on every release. Validate
event spellings in a linter, not the parser.
TCL baseline
iRules is a TCL 8.4 dialect (per F5
K6091). TCL 8.5 features
(dict, lassign, ** operator, expanded lsearch switches) and
TCL 8.6 features (try/on error/finally, lmap, throw) are
available on BIG-IP 12.x and later when explicitly enabled. The grammar
follows the tree-sitter-tcl baseline, so 8.5/8.6 syntax parses
fine — but keep in mind that older BIG-IP runtimes will reject those
constructs.
A subset of TCL commands is disabled at runtime in iRules for safety
(exec, file, open, socket, and others; see F5's
DisabledTclCommands.html).
The parser does not enforce the disabled list — disabled commands
parse as ordinary TCL commands. Linting/validation is out of scope here.
Known limitations
- Bare-word operands in
exprcontexts must be quoted or braced, as in stock TCL.if {$x eq foo}produces an(ERROR ...)node because TCL's ownexprrejects unquoted barewords (invalid bareword "foo"); writeif {$x eq "foo"}orif {$x eq {foo}}.$var, numbers, booleans,[cmd], and"strings"are all accepted operands. - Plain
matchesoperator (no_glob/_regexsuffix) is accepted by the grammar but is not documented on F5's Operators page. It is retained for upstreamtree-sitter-tclcompatibility; prefermatches_globormatches_regex.
Status
Early. The grammar parses iRules as TCL plus iRules-specific event handlers
and tags iRules namespace commands and globals in queries/irules/highlights.scm.
Building
git clone https://github.com/dekobon/tree-sitter-irules.git
cd tree-sitter-irules
npm install
npx tree-sitter generate
make test
The committed src/parser.c is generated by the exact tree-sitter-cli
version recorded in package-lock.json and CI pins to that same version,
so contributors must regenerate parser.c with the locally-installed CLI
(npx tree-sitter generate) — never with a globally-installed one — when
bumping tree-sitter-cli. See AGENTS.md for the full versioning,
commit, and changelog conventions.
Using it
Pick the binding for your toolchain. All bindings expose
tree_sitter_irules (or the language-idiomatic equivalent) and resolve to
the same src/parser.c + src/scanner.c.
No release has been tagged yet, so all snippets below resolve from the
default branch. Once a release vX.Y.Z is cut, swap each snippet to a
pinned form: Cargo tag = "vX.Y.Z" (instead of branch = "main"), Go
@vX.Y.Z (instead of @latest), npm github:dekobon/tree-sitter-irules#vX.Y.Z,
pip git+https://github.com/dekobon/tree-sitter-irules@vX.Y.Z, or the
published package version once available on the relevant registry.
# Cargo.toml
[dependencies]
tree-sitter-irules = { git = "https://github.com/dekobon/tree-sitter-irules", branch = "main" }
# Go: resolves to a pseudo-version of the latest commit on main.
go get github.com/dekobon/tree-sitter-irules@latest
// package.json
"dependencies": { "tree-sitter-irules": "github:dekobon/tree-sitter-irules" }
# pyproject.toml
[project]
dependencies = ["tree-sitter-irules @ git+https://github.com/dekobon/tree-sitter-irules"]
Bindings ship the parser only. Editor / runtime integrations also need
to load queries/irules/highlights.scm (and optionally folds.scm /
indents.scm) for highlighting and structural navigation; consult your
editor's tree-sitter integration docs for how to register the queries.
The Rust binding additionally re-exports the highlights query as
HIGHLIGHTS_QUERY.
Filetype detection
The repo ships ftdetect/irules.lua and ftplugin/irules.lua for
Neovim. The ftdetect file maps *.irule and *.irules to filetype
irules unconditionally; the ftplugin then calls
vim.treesitter.start() for that filetype. Highlighting only renders
once the parser binary and queries/irules/highlights.scm are
registered with nvim-treesitter (or equivalent) — without that, the
start() call is a no-op and the buffer falls back to non-treesitter
highlighting.
iRules are also commonly stored with a plain .tcl extension — we
deliberately do not claim .tcl globally, since most .tcl files
on disk are ordinary TCL. To opt specific .tcl files into the iRules
parser, pick one of:
-
Modeline at the top of the file:
# vim: set filetype=irules : -
Per-project autocmd in
.nvim.lua(sourced after:cdinto the project via Neovim's'exrc'). Notevim.fn.getcwd()is evaluated when the autocmd is defined, so this snippet belongs in a per-project config, not a globalinit.lua:vim.api.nvim_create_autocmd({ "BufRead", "BufNewFile" }, { pattern = vim.fn.getcwd() .. "/irules/*.tcl", callback = function() vim.bo.filetype = "irules" end, })
-
Content-based detection for files that always start with a
whenblock:vim.filetype.add({ pattern = { [".*%.tcl$"] = function(_, bufnr) local first = vim.api.nvim_buf_get_lines(bufnr, 0, 1, false)[1] or "" if first:match("^%s*when%s+[A-Z][A-Z0-9_]*") then return "irules" end end, }, })
Other editors follow the same pattern: keep .tcl mapped to TCL by
default and override per-directory or via a header comment.
Layout
grammar.js— grammar definition (TCL base + iRuleswhenevent handler).queries/irules/— highlight, fold, and indent queries with iRules-aware tags.test/corpus/— corpus tests (TCL tests inherited; iRules-specific tests intest/corpus/irules.txt).bindings/— language bindings (C, Go, Node, Python, Rust, Swift).
Contributing
- Issues and feature requests: https://github.com/dekobon/tree-sitter-irules/issues
- Pull requests welcome. Read
AGENTS.mdfirst — it documents the Conventional Commits / SemVer / Keep-a-Changelog conventions, the validation gates (npx tree-sitter generate,make test,npm run lint), and the rule that committedsrc/parser.cmust be generated by thetree-sitter-cliversion recorded inpackage-lock.json.
License
MIT. See LICENSE. This grammar is a fork of
tree-sitter-tcl
by Lewis Russell; original copyright is retained alongside the
tree-sitter-irules project copyright.
Metadata
Release files for tree-sitter-irules 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tree_sitter_irules-0.2.1.tar.gz | 76.4 kB | With provenance | Details for tree_sitter_irules-0.2.1.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| tree_sitter_irules-0.2.1-cp311-abi3-win_amd64.whl | CPython 3.11 | abi3 | Windows x86-64 | Details for tree_sitter_irules-0.2.1-cp311-abi3-win_amd64.whl |
| tree_sitter_irules-0.2.1-cp311-abi3-win32.whl | CPython 3.11 | abi3 | Windows x86-32 | Details for tree_sitter_irules-0.2.1-cp311-abi3-win32.whl |
| tree_sitter_irules-0.2.1-cp311-abi3-musllinux_1_2_x86_64.whl | CPython 3.11 | abi3 | Linux musl 1.2+ x86-64 | Details for tree_sitter_irules-0.2.1-cp311-abi3-musllinux_1_2_x86_64.whl |
| tree_sitter_irules-0.2.1-cp311-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl | CPython 3.11 | abi3 | Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 | Details for tree_sitter_irules-0.2.1-cp311-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
| tree_sitter_irules-0.2.1-cp311-abi3-macosx_11_0_arm64.whl | CPython 3.11 | abi3 | macOS 11.0+ ARM64 | Details for tree_sitter_irules-0.2.1-cp311-abi3-macosx_11_0_arm64.whl |
Total release size: 354.8 kB
Release files / tree_sitter_irules-0.2.1.tar.gz
| Download URL | tree_sitter_irules-0.2.1.tar.gz |
|---|---|
| Size | 76.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1e6c22c50942c90f7b9ec1e0b72dd9e1f87d56604ff9ffeae8079edae1f3f627
|
|
BLAKE2b-256 checksum How to use checksums |
f8154b41c6f5ed33b39a4baaa728ff6213e606b11405ff8ac2869236c527e4b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / tree_sitter_irules-0.2.1-cp311-abi3-win_amd64.whl
| Download URL | tree_sitter_irules-0.2.1-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 52.3 kB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
dd7bb4d8fbde336b9469be7a2f6e61cfebc2a0652e038d85aab54da57722efa0
|
|
BLAKE2b-256 checksum How to use checksums |
6a1b46565fbdcf8138cdb04477149f5a8523411899f8962a193e95151482db01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / tree_sitter_irules-0.2.1-cp311-abi3-win32.whl
| Download URL | tree_sitter_irules-0.2.1-cp311-abi3-win32.whl |
|---|---|
| Size | 53.3 kB |
| Tags | CPython 3.11 Windows x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
48d8b109392190da09db300b3662353e011c25f94c64d5bebf3604396e7a00a2
|
|
BLAKE2b-256 checksum How to use checksums |
f32a0086e3c017306e8fbd23305358bc1c54ab54621d6b53044442045b965ff4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / tree_sitter_irules-0.2.1-cp311-abi3-musllinux_1_2_x86_64.whl
| Download URL | tree_sitter_irules-0.2.1-cp311-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 61.0 kB |
| Tags | CPython 3.11 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
d2e9b0261fe36bd1cd69e3be576ee47bccf3fca0723992bbb9f05f54b1267979
|
|
BLAKE2b-256 checksum How to use checksums |
e2c2fe2756960f2c5bb6dfb01d39b29a03868274509b119b6959b5cb533aecfc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / tree_sitter_irules-0.2.1-cp311-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | tree_sitter_irules-0.2.1-cp311-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 60.9 kB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
9f6043859be1efa5b75630d38efdf6bb426b6748590bf076758497af17848bdd
|
|
BLAKE2b-256 checksum How to use checksums |
2f00de6c09beb246a0e921bee9e6be7fbaa15784c51311e4d6cc1c080c847257
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / tree_sitter_irules-0.2.1-cp311-abi3-macosx_11_0_arm64.whl
| Download URL | tree_sitter_irules-0.2.1-cp311-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 50.9 kB |
| Tags | CPython 3.11 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f654f2ae21fd6a44a3793032c01cdf4be8cc97c2f378885680544d30c50983ed
|
|
BLAKE2b-256 checksum How to use checksums |
63572c4aa8619649ba843ae2607cd9fe4ef7855dfb69e0b27e27d21ed26d5f76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for tree-sitter-irules 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for tree_sitter_irules-0.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.