v0.24.0

mccode-antlr v0.24.0

This release teaches the intermediate representation the TRACE %include file
hierarchy, so a multi-file instrument keeps its structure through parsing,
assembly, serialization, and writing back out. On top of that sits a new
mccode-antlr extract command that unpacks a portable instrument into a
self-contained directory, with unzip-style member selection and a --list
dry-run.

Upgrading

Instr.included now holds Instr objects, not file names. It was a
tuple[str, ...] recording the names of %include-d definitions; it is now the
included instruments themselves, whose component instances are shared with the
parent's sequence. Use child.name where you previously used the string.

mccode_antlr.export has moved into mccode_antlr.io. The export package
is gone; import instr_to_python and save_instr_as_python from
mccode_antlr.io instead.

Repeated inclusion of the same instrument is rejected. %include cycles
(including self-inclusion) raise instead of recursing forever, and including the
same instrument twice -- directly or as a diamond -- is refused, since instruments
sharing Instance objects cannot represent it. Instr.detached() returns a
copy that is safe to include again.

An included file's DEPENDENCY is honored. It was silently dropped; it is
now merged, de-duplicated, into the parent's dependency string, so the
compilation command line for an affected instrument can change.

New

The %include hierarchy survives. Instr.included holds the child
instruments, nested to any depth; component-name lookups, PREVIOUS(n)
counting, and PREVIOUS-in-expression resolve through every enclosing scope.
JSON and msgpack round-trips preserve both the hierarchy and the object
sharing. Instr.to_files(directory) writes the parent with %include
directives plus one file per included instrument; to_file stays flat by
default, and saving flat warns when a %include cannot be resolved.

The assembler can build hierarchies too. with assembler.included(name) as sub: opens a child instrument that is merged into the parent on exit, and
Assembler.include() merges a pre-built instrument. A child assembler is
invalidated once merged: mutating it afterwards raises rather than silently
diverging from what was absorbed.

mccode-antlr extract unpacks a portable instrument (.instr or .json)
into a single directory -- the instrument hierarchy, its stashed and embedded
files, and held component definitions -- translatable from there with no -I
needed. --include-remote also pulls in files otherwise fetched from remote
registries; naming such a file explicitly selects it without the flag.
Selection mirrors unzip: positional MEMBER glob patterns, a repeatable
-x/--exclude, and --list previews exactly what would be written, with each
file's category and source.

Fixes

• RotationPart.is_identity agrees with is_rotation for tiny rotation
  angles, where the numeric trace comparison rounded to exactly 3.0 while the
  symbolic check knew better (#296).
• Instr.make_instance passed group and removable into the wrong
  positional slots.
• The CLI documentation table now covers -g/--debug and
  --trust-local-registries, and no longer presents the deprecated
  -L/--line-directives as current.

What's Changed

Exciting New Features 🎉

• Implement the instr hierarchy model by @g5t in #295
• Add convert target for single directory complete instrument contents by @g5t in #297
• Add unzip-like selection and --list dry-run to mccode-antlr extract by @g5t in #299

Other Changes

• Fix inconsistency between RotationPart.is_identity and is_rotation angles by @g5t in #298
• Test fewer configurations in workflows by @g5t in #300

Full Changelog: v0.23.0...v0.24.0