tree-sitter-strdl

!npm version
!License

A Tree-sitter parser for Strudel, a port of the Tidal Cycles live coding environment to JavaScript.

This project provides robust syntax highlighting and parsing for:
1. Strudel DSL: The core JavaScript-like chainable syntax (e.g., s("bd").fast(2)).
2. Mini-Notation: The internal pattern language inside strings (e.g., "bd*2 [sn cp]"), parsed via a dedicated secondary grammar (strdl_mini) and injected automatically.

---

✨ Features

- Complete DSL Parsing: Covers variable declarations, function chaining, and object/array literals.
- Mini-Notation Injection: Strings passed to pattern functions (s, note, stack, etc.) are parsed as a separate language, enabling detailed highlighting of beats, groups, and modifiers.
- Neovim Ready: Includes queries for highlighting, injections, and locals.
- Multi-Language Bindings: Node.js, Rust, Python, Go, Swift, C.

---

🚀 Neovim Integration

To get full highlighting (DSL + Mini-Notation) in Neovim, you need to register both parsers and configure filetype detection.

$3

Add the following Lua code to your init.lua or a separate module (e.g., lua/plugins/strudel.lua):

``lua
-- 1. Register Parsers (Main + Mini)
local parser_config = require("nvim-treesitter.parsers").get_parser_configs()

-- Main Strudel Parser
parser_config.strudel = {
install_info = {
url = "~/path/to/tree-sitter-strdl", -- ⚠️ Change this to your local path
files = { "src/parser.c" },
branch = "main",
},
filetype = "strdl",
}

-- Mini-Notation Parser (for inside strings)
parser_config.strudel_mini = {
install_info = {
url = "~/path/to/tree-sitter-strdl/mini", -- ⚠️ Change this to your local path (mini subdir)
files = { "src/parser.c" },
branch = "main",
},
filetype = "strdl_mini",
}

-- 2. Filetype Detection
vim.filetype.add({
extension = {
str = "strdl",
strdl = "strdl",
strudel = "strdl",
},
})

-- 3. Configure nvim-treesitter
require("nvim-treesitter.configs").setup({
highlight = {
enable = true,
additional_vim_regex_highlighting = false,
},
})
`

$3


To make the highlighting and injections work, copy the query files (highlights.scm, injections.scm) to your Neovim runtime.

Run this command from the repo root:
`bash
npm run local_install
`
(This script copies queries/.scm to ~/.local/share/nvim/lazy/nvim-treesitter/queries/strudel)*

$3


1. Restart Neovim.
2. Open a .strdl file.
3. Run :TSInstall strudel and :TSInstall strudel_mini (if not installed automatically).
4. Type s("bd*4 [sn cp]"). You should see distinct highlighting inside the string.

---

🛠️ Development

$3

- Node.js & npm
- Tree-sitter CLI (cargo install tree-sitter-cli or via npm)
- C Compiler (clang/gcc)

$3

| Task | Command |
| :--- | :--- |
| Install Deps | npm install |
| Playground | npm start (Builds WASM & opens browser) |
| Test (Main) | npm test (Runs corpus tests for DSL) |
| Test (Mini) | npm run test:mini (Runs corpus tests for mini-notation) |
| Gen (Main) | npx tree-sitter generate |
| Gen (Mini) | npm run generate:mini |

$3

- grammar.js: Definition of the main Strudel language.
- mini/grammar.js: Definition of the Mini-Notation language.
- queries/: Tree-sitter queries for Neovim.
- highlights.scm: Syntax coloring rules.
- injections.scm: Logic to inject strdl_mini into specific function calls.
- test/corpus/: Test cases for the main language.
- mini/test/corpus/: Test cases for the mini-notation.

---

🧠 Architecture & Injections

The parser uses Tree-sitter's Language Injection system.

1. The Main Parser identifies function calls like s("..."), note("..."), stack("...").
2. The Injection Query (queries/injections.scm) matches these specific function names.
3. It marks the string content as injection.content and requests the strdl_mini language.
4. The Mini Parser takes over for that range, parsing the beats, rests, and modifiers.

Supported Injection Functions:
s, sound, n, note, scale, chord, arp, gain, speed, pan, cutoff, lpf, hpf, hpq, delay, rev, stack, cat`.

---

📚 References

- Strudel Website
- Tidal Cycles
- Tree-sitter Documentation

---

> Maintained fork of Strudel Tree Sitter Grammar by Pedro Zappa — extends grammar beyond upstream v1.1.8; actively maintained for LSP, Neovim plugin, diagnostics, etc.