Skip to main content

tree-sitter-irules

CI CodeQL npm crates.io PyPI License: MIT

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 optional priority N and timing on|off modifiers.
  • 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 expr contexts must be quoted or braced, as in stock TCL. if {$x eq foo} produces an (ERROR ...) node because TCL's own expr rejects unquoted barewords (invalid bareword "foo"); write if {$x eq "foo"} or if {$x eq {foo}}. $var, numbers, booleans, [cmd], and "strings" are all accepted operands.
  • Plain matches operator (no _glob/_regex suffix) is accepted by the grammar but is not documented on F5's Operators page. It is retained for upstream tree-sitter-tcl compatibility; prefer matches_glob or matches_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 :cd into the project via Neovim's 'exrc'). Note vim.fn.getcwd() is evaluated when the autocmd is defined, so this snippet belongs in a per-project config, not a global init.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 when block:

    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 + iRules when event handler).
  • queries/irules/ — highlight, fold, and indent queries with iRules-aware tags.
  • test/corpus/ — corpus tests (TCL tests inherited; iRules-specific tests in test/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.md first — 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 committed src/parser.c must be generated by the tree-sitter-cli version recorded in package-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)

Source distribution for tree-sitter-irules 0.2.1
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)

Table of built distributions (wheels) for tree-sitter-irules 0.2.1
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 6 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page