tree-sitter-gregorio

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.1.0 — This parser targets full compatibility with the GABC+NABC specification from Gregorio version 6.1.0. This compatibility target will be maintained for the future 1.0.0 release.

Features

✅ Complete GABC+NABC Support (240 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