tree-sitter-gregorio

Note

AI-Assisted Development

This project is developed, fully or in part, with LLM/generative AI assistance. All LLM-proposed changes go through human review and local testing before being committed.

If you object to software built with generative AI assistance, we respect your opinion and regret we cannot meet your expectations. In that case, we kindly recommend exploring alternative solutions. If you know of any, feel free to open an issue — we'll be happy to include them in our documentation.

Tree-sitter grammar for GABC+NABC notation (Gregorian chant).

Overview

This project provides a tree-sitter grammar for parsing GABC (Gregorio ABC) files with NABC (Cardine-Based Adiastematic Notation) extensions. GABC is a text-based notation system for Gregorian chant, and NABC extends it with support for adiastematic neumes.

Current Status: ✅ Complete GABC+NABC support - The parser has been fully reviewed and tested for core GABC notation and comprehensive NABC (adiastematic notation) support including all glyph descriptors, modifiers, spacing, and significant letters.

Target Compatibility: Gregorio 6.2.0 — This parser targets full compatibility with the GABC+NABC specification from Gregorio version 6.2.0. This compatibility target will be maintained for the future 1.0.0 release.

Features

Stable Node-Kind Contract

This grammar exposes a stable node-kind contract for downstream tools (such as Rust LSP integrations). The current contract version is available in bindings/rust/lib.rs as STABLE_NODE_KIND_CONTRACT_VERSION.

Rules:

• Any breaking rename/removal of existing node kinds requires bumping the contract version.
• Non-breaking additions of new node kinds do not require a bump.
• Consumers should gate strict matching behavior by contract version.

✅ Complete GABC+NABC Support (250 tests passing)

• Header Section:

  • Single-line headers (name: value;)
  • Multi-line headers (commentary: text...;;)
  • All standard header fields
  • Numeric headers: mode, staff-lines, nabc-lines with number highlighting
  • TeX headers: annotation, mode-modifier, mode-differentia, def-m0-def-m9 with LaTeX injection
  • Comment support (%)

• Lyrics and Text:

  • Syllable text with punctuation
  • Style tags: <b>, <i>, <c>, <sc>, <tt>, <ul>
  • Cross-syllable tags: All style and control tags can span multiple syllables
  • Nested tags support
  • Syllable controls: <e>, <eu>, <nlba>, <pr>, <clear>
  • Special tags: <alt>, <sp>, <v> (verbatim)
  • LaTeX injection: Syntax highlighting for TeX code in <v>, [nv:], [gv:], [ev:]
  • Translation text [...]
  • Lyric centering {...}
  • Escape sequences $

• Musical Notation (GABC):

  • Notes and Neumes:
    • Simple notes with pitch (a-n, A-N)
    • Pitched neumes (clivis, pes, torculus, porrectus, etc.)
    • Special neumes (oriscus, quilisma, stropha, virga, etc.)
    • Liquescent variants
    • Neume modifiers (episema, ictus, dot, etc.)
    • Neume fusion with @
  • Clefs: C-clefs (c1-c4), F-clefs (f1-f4), with flat variant for C-clef only (cb1-cb4)
  • Clef changes: Single and multiple clef links (::)
  • Bars: Virgula, divisio minima/minor/maior/finalis, Dominican bars
  • Line breaks: Justified (z), ragged (Z), with custos modifiers (+, -)
  • Custos: Auto-pitch (z0), manual pitch with +
  • Spacing: Small (/), medium (//), half-space (/[)
  • Alterations: Natural (x), flat (y), sharp (#)
  • Attributes: [nocustos], shape, choral signs, braces, slurs, episema tuning
  • Extra symbols: Asterisk, cross variants, R/, V/, A/

• NABC Support (complete):

  • 31 basic glyph descriptors (St. Gall and Laon styles: vi, pu, ta, cl, pe, etc.)
  • 6 glyph modifier types with variant support (S, G, M, -, >, ~)
  • Pitch descriptors (ha, hf, hn for all pitch letters a-n)
  • Glyph fusion with binary operator support
  • 9 subpunctis/prepunctis modifiers (tractulus, gravis, stropha, etc.)
  • 4 spacing types (larger/inter-element, left/right)
  • 82 significant letter codes:
    • 45 St. Gall shorthands (altius, celeriter, tenere, etc.)
    • 22 Laon shorthands (augete, humiliter, etc.)
    • 15 Tironian note shorthands (iusum, deorsum, sursum, etc.)
  • Alternation with GABC using | separator

Installation

npm install

Editor Support

Helix Editor

For detailed setup instructions for Helix editor, see docs/HELIX_SETUP.md.

Quick setup:

1. Copy helix-languages.toml content to ~/.config/helix/languages.toml
2. Update the path to point to your tree-sitter-gregorio directory
3. Run hx --grammar build

The grammar includes syntax highlighting for all GABC/NABC elements, including special markup highlighting for text inside <b>, <i>, and <ul> tags. LaTeX code inside verbatim elements (<v>, [nv:], [gv:], [ev:]) receives LaTeX syntax highlighting when both grammars are available.

Building

npm run generate
npm run build

Testing

npm test

Grammar Structure

The grammar recognizes the following main structures:

Header Section

• Headers with name: value; syntax
• Multiline headers ending with ;;
• Special headers: name, mode, nabc-lines, etc.

Notation Section

• Syllables with text and note groups
• GABC snippets: notes, clefs, bars, spacing, etc.
• NABC snippets: complex neume descriptors
• Mixed GABC|NABC patterns

GABC Elements

• Notes with pitches and modifiers
• Complex neumes (clivis, pes, torculus, etc.)
• Bars and clefs
• Line breaks and spacing
• Style tags and special elements

NABC Elements

• 31 glyph descriptors: Complete St. Gall and Laon repertoire
• 6 glyph modifier types: S, G, M, -, >, ~ with variant numbers
• Pitch descriptors: ha, hf, hn for all pitch letters (a-n)
• Glyph fusion: Binary operator for connecting glyphs
• 9 subpunctis/prepunctis modifiers: Tractulus, gravis, stropha, etc.
• 4 spacing types: Larger/inter-element space, left/right positioning
• 82 significant letters: Unified St. Gall (45) + Laon (22) + Tironian (15)

Test Coverage

The parser is validated with 231 comprehensive tests covering:

Core Tests (21 test files)

GABC Tests (14 files, 149 tests)

1. 00-basics.txt (4 tests): Basic structure, headers, multiline headers
2. 01-lyrics-notation.txt (6 tests): Style tags, syllable controls, nested tags, verbatim
3. 22-nlba-cross-syllable.txt (1 test): Cross-syllable nlba tag
4. 23-cross-syllable-all-tags.txt (4 tests): Cross-syllable support for all style and control tags
5. 02-gabc-neumes.txt (12 tests): All neume types and modifiers
6. 03-gabc-alterations.txt (10 tests): Natural, flat, sharp with variations
7. 04-gabc-complex-neumes.txt (6 tests): Pitched complex neumes
8. 05-gabc-neume-fusions.txt (13 tests): Simple and multiple fusions
9. 06-gabc-spacing.txt (12 tests): All spacing types
10. 07-gabc-extra-symbols.txt (23 tests): Asterisk, cross, R/, V/, A/, mora, ictus, episema
11. 08-gabc-separation-bars.txt (16 tests): All bar types with modifiers
12. 09-gabc-clefs.txt (21 tests): All clef types and links
13. 10-gabc-custos.txt (3 tests): Auto-pitch and manual custos
14. 11-gabc-attributes.txt (7 tests): All attribute types
15. 12-gabc-line-breaks.txt (5 tests): Line breaks with modifiers
16. 21-real-examples.txt (5 tests): Real-world liturgical chants

NABC Tests (8 files, 82 tests)

17. 13-nabc-basic-glyph-descriptors.txt (3 tests): Basic glyphs and alternation
18. 14-nabc-glyph-modifiers.txt (10 tests): All modifier types with variants
19. 15-nabc-pitch-descriptors.txt (5 tests): Pitch descriptors for all letters
20. 16-nabc-glyph-descriptors.txt (7 tests): Complex glyph descriptors
21. 17-nabc-glyph-fusion.txt (18 tests): Binary glyph fusion
22. 18-nabc-subpunctis-prepunctis-descriptors.txt (15 tests): All subpunctis/prepunctis modifiers
23. 19-nabc-spacing.txt (11 tests): All NABC spacing types
24. 20-nabc-significant-letters.txt (14 tests): St. Gall, Laon, and Tironian letters

Test Statistics

• Total tests: 240
• Pass rate: 100%
• Coverage: Complete GABC+NABC notation with cross-syllable tags and header highlighting
• GABC tests: 149 (62.1%)
• NABC tests: 82 (34.2%)
• Header tests: 9 (3.7%)

References

This grammar is based on:

• GABC Syntax Specification
• NABC Syntax Specification
• Gregorio Compiler Errors and Warnings

Project Documentation:

• Project Status - Complete status summary and metrics
• Changelog - Version history and changes
• Development Milestones - Roadmap and achievements
• Project Structure - Architecture overview
• Header Highlighting - Numeric and TeX header syntax highlighting
• LaTeX Injection - LaTeX syntax highlighting in verbatim elements
• Helix Setup - Editor configuration guide

Official Gregorio documentation:

• Gregorio project website
• GitHub repository

License

MIT