gmat-script 0.2.0

Parse, format, lint, and edit GMAT mission scripts from Python — a tree-sitter grammar and tooling.

gmat-script

Parse, format, lint, and edit GMAT .script mission files from Python — built on a tree-sitter grammar. The whole stack operates on script text; nothing here requires a GMAT install.

It ships the parser, a typed AST with a mutation API, and a canonical formatter, plus a gmat-script command-line tool over the same engine. The linter and editor tooling build on top of the same tree as they land.

Install

pip install gmat-script

gmat-script supports Python 3.10, 3.11, and 3.12. The wheel bundles a precompiled grammar, so the install needs no C or Node toolchain — and never GMAT.

Quick start

Parse a script — parse never raises on malformed input: it returns a tree carrying ERROR / MISSING nodes localised to the broken construct, surfaced through tree.errors.

from gmat_script import parse

tree = parse("Create Spacecraft Sat\nSat.SMA = 7000\n")

tree.has_errors      # False — the script is well-formed
tree.to_source()     # round-trips byte-for-byte to the input

Edit it through the typed AST — typed resources with dict-like field access. Each edit splices the source and re-parses, so untouched bytes are never disturbed and a corrupting edit is refused.

from gmat_script import Script

script = Script.parse("Create Spacecraft Sat\nSat.SMA = 7000\n")

script.spacecraft["Sat"]["SMA"]         # 7000 — read a field
script.spacecraft["Sat"]["SMA"] = 8000  # set it
script.rename_resource("Sat", "MainSat")  # rename, rewriting references
script.to_source()                      # the edited source

Format it — a deterministic, idempotent pretty-printer that re-lays-out without reordering.

from gmat_script import format

format("GMAT Sat.SMA=7000;\n")   # 'Sat.SMA = 7000\n'

Command line

The same engine drives the gmat-script command-line tool — a fast, install-free gate for CI:

$ gmat-script parse mission.script     # print the syntax tree; exit non-zero on a syntax error
$ gmat-script format --check *.script   # fail if any file is not in canonical form

format rewrites files in place by default, or checks / diffs them with ruff-style exit codes. It also ships pre-commit hooks, so scripts are formatted on every commit — add the repo to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/astro-tools/gmat-script
    rev: v0.2.0
    hooks:
      - id: gmat-script-format        # auto-format on commit
      # - id: gmat-script-format-check  # or: check only, never write (CI)

The grammar surface

The tree-sitter grammar parses GMAT scripts (.script) and GmatFunctions (.gmf) — the same grammar for both — and re-emits any input byte-for-byte, comments and layout included. It is a deliberately permissive superset: Create <Type> <name> accepts any resource type and unknown command keywords parse as generic command nodes, so a new resource or command never needs a grammar change. The acceptance bar is concrete: every one of the 162 .script and 9 .gmf files shipped with NASA GMAT R2026a parses with zero errors and round-trips exactly.

See the grammar surface reference for the node taxonomy and the covered / deferred constructs.

The GMAT-free guarantee

Reading, checking, formatting, and transforming a script needs only this package — never a GMAT install. pip install gmat-script never pulls in, requires, or looks for GMAT or gmatpy; the only runtime dependency is tree-sitter. (GMAT is used at build time only, to generate the field catalogue that later semantic tooling will check against.)

GMAT version

The grammar targets GMAT R2026a. Because it never enumerates resource types or command keywords, parsing is effectively version-independent — scripts from other releases parse too. Semantics that do vary by release (valid field names, enums, defaults) belong to the later linter and are scoped to R2026a.

What gmat-script is not

• Not a propagator or astrodynamics engine. It reads and transforms script text; it computes no orbits and models no physics.
• Not a mission runner. Running a script is GMAT's job — gmat-script does no execution.
• Not an engine-dependent validator. "Does it parse" is a structural question answered here; "does it run / converge" is a different question that needs GMAT.

Documentation

Full documentation — getting started, the grammar surface, the typed AST and editing guides, the formatter, the command-line tool, the error-reporting model, and the API reference — is at astro-tools.github.io/gmat-script.

License

MIT — part of the astro-tools organization.