v5.22.0 v5.22.0 new syntax+cli+features#

Added#

cling — new default CLI#

  • Three subcommands: tatsu run (parse files), tatsu boot (show boot grammar), tatsu grammar (grammar transformations)

  • Multi-file batch parsing with live dual-column progress bars — overall progress + per-file heartbeat powered by the new parser-level heartbeat hook

  • Per-file verbose output (--verbose) with timing and error details

  • Summary table with file/line counts, successes, failures, success rate, lines/sec, and elapsed time

  • --quiet to suppress progress and summary, --nproc for parallel workers

  • Files read once; all reports use cached content

  • The previous CLI is still available as otatsu

Heartbeat protocol — per-token progress hook#

  • Heart protocol in tatsu/util/heart.py with a single beat(mark, total) method; NullHeart no-op for parallel or unobserved parsing

  • ParserConfig.heart field lets applications inject a heartbeat receiver; ParserCore issues a heart.beat(pos, len) on token advancement and rule calls with a 0.128s cooldown for real-time reporting of parsing progress

New colorize module in tatsu/util/colorize/:#

  • Color/Style ANSI colour library in tatsu/util/colorize/ with zero dependencies, dynamic TTY/NO_COLOR/FORCE_COLOR support, 256-colour palettes, 24-bit RGB, and 148 CSS named colours

  • Color.default() factory method for the system-default colour policy

  • Style chainable modifier methods (bold(), dim(), fg(), bg(), etc.) all returning immutable copies; instances are callable (equivalent to .apply()), so a single style can be reused: hl = Style().red().bold(); print(hl("text"))

  • Lazy-loaded named_color() and css_color() standalone lookup functions re-exported from the package

  • ConsoleTracer and _ColorSet (exceptions.py) now compose Style objects instead of concatenating ANSI strings, eliminating bleeding between trace/error colour spans

    from tatsu.colorize import Style

style = Style().red().bold()
print(style("text"))

Meta expressions in grammars#

  • @name, @int, @uint, @float, @bool meta-expressions for typed matching (identifiers, signed/unsigned integers, floating point literals, and boolean literals)

  • FailedMeta exception for @ meta failures

  • -z / --optimize CLI option to optimize the grammar model before generating output

Changed#

  • Cache optimized grammar models; inline single-element sequences and call chains in Rule.optimized()

  • Cursor/Text protocols moved from input/text.py → input/cursor.py

  • Versioning via uv-dynamic-versioning; _version.py reads from importlib.metadata

  • CI: upgrade to checkout@v6, setup-uv@v7, setup-python@v6; all dependencies via uv sync

Removed#

  • Deprecated override_single_deprecated (bare @ as override) from grammar and boot parser to allow the symbol to be used for the new meta-expressions

CLING The New Console Interface#

Options the run subcommand#

sage: tatsu run [-h] [-q] [-v] [-t] [-o OUTPUT] [-c {auto,always,never}] [-j] [-m] [-s START] [-n NPROC]
                 path inputs [inputs ...]

positional arguments:
  path                  Path to a grammar in EBNF or JSON format
  inputs                The files to be parsed

options:
  -h, --help            show this help message and exit
  -j, --json            Print output in JSON format
  -m, --model           Print the model code
  -s, --start START     Name of the start rule
  -n, --nproc NPROC     Number of concurrent workers

global options:
  -q, --quiet           Suppress progress bar and spinner output
  -v, --verbose         Provide more detailed information about the parsing process
  -t, --trace           Display a detailed trace of the parsing process
  -o, --output OUTPUT   Output to a file or directory instead of stdout
  -c, --color {auto,always,never}
                        Control colorized output (default: auto)

Console output for the run subcommand#

results:
✗ Ternary1.java                             0.0s
✓ Ternary2.java                             0.2s
✓ JavaTernaryOperatorExamples.java          0.2s
✓ NavPanelCore.java                         2.3s
✓ GwpCreditcardOperations.java              3.8s


FAILURES: 1

error: Expected one of: ';' 'annotation_type_declaration' 'class_declaration' 'enum_declaration' 'interface_declaration' 'type_declaration'

  --> datasets/Ternary1.java@23[1:1]
   |
 1 | #public class Ternary1
   | ^ Expected one of: ';' 'annotation_type...

→ compilation_unit
→ start


        files input             5
 source lines input          2047
      success lines          2019
               sloc          1724
          successes             4
           failures             1
       success rate            80 %
           sloc/sec           318 sl/s
           run time          0:06
          wall time          0:00