API reference¶

The public surface of gmat_script. It is deliberately minimal and additive: the parse entry point and the Tree it returns, the ErrorNode / Position records that describe syntax errors, the typed Script overlay with its mutation API (ObjectRef, RawValue, MutationError), the canonical format pretty-printer, the lint checker with its Diagnostic / Severity records, and the Catalog field catalogue (load_catalog, FieldSpec, TypeSpec). Each layer is re-exported here as it lands.

For a worked introduction see Getting started; for the error model see Error reporting; for the linter see Linting; for the catalogue see The field catalogue.

gmat_script ¶

gmat-script — parse, format, lint, and edit GMAT mission scripts from Python.

The whole stack operates on script text; nothing here requires a GMAT install. parse is the entry point returning the concrete syntax tree; :class:Script is the typed overlay over it (typed resources, dict-like field access, an ordered mission sequence) and the mutation root — editing a field, resource, or command splices the source and re-parses, raising :class:MutationError on a corrupting edit. The formatter and linter are re-exported here as they land. See the design decisions under docs/design/ for the contract this package implements.

Array `dataclass` ¶

A square-bracket value — a 1-D array [a b c] or a 2-D matrix [r1; r2] (D13).

Distinguishes GMAT's whitespace-separated […] array / matrix from the comma-separated {…} brace-list (a plain :class:list): both coerce element-wise, but they emit to different GMAT forms, so the type must be preserved for a lossless round-trip. A 2-D matrix is an :class:Array whose every element is itself an :class:Array row. elements is a tuple so the value stays immutable and hashable, like the other value types.

MutationError ¶

Bases: Exception

A mutation was refused: it targets a script with syntax errors, would produce one, its edits overlap, or it was given a malformed name / field. The source is left unchanged when raised.

ObjectRef `dataclass` ¶

A reference to a GMAT object, or a dotted member of one — e.g. Earth, Sat.SMA.

Distinguishes a bare or dotted name used as a value (an object reference) from a quoted string with the same text. Whether the referenced object actually exists is the linter's concern, not this layer's.

RawValue `dataclass` ¶

The raw source text of a value with no structural Python reduction (the fallback).

Carries GMAT's unquoted rest-of-line values (multi-word enums, unquoted paths / dates, the doubled-quote artifact) and computed right-hand sides (arithmetic, function calls, indexed or parenthesised expressions). The text is the exact source slice (D6); interpreting it further is left to the consumer (or the linter / catalogue).

Script ¶

A typed, mutable overlay over a parsed GMAT script.

Construct it from a :class:~gmat_script.Tree (Script(tree)) or parse in one call (:meth:Script.parse). Resources are reachable by name (:attr:resources), by type (:attr:resources_by_type, or the script.<lowercased-type> sugar — script.spacecraft), and the mission sequence is the ordered :attr:mission_sequence. Field and operand values are coerced on access; nothing is copied eagerly.

It is also the mutation root. Field edits go through a :class:Resource (script.spacecraft["Sat"]["SMA"] = 7000); resource and command edits are the methods here (:meth:add_resource, :meth:rename_resource, :meth:insert_command, …). Every mutator re-parses and returns self for chaining; reads after an edit reflect it.

tree `property` ¶

tree: Tree

The underlying :class:~gmat_script.Tree (the CST, current after edits).

resources `property` ¶

resources: Mapping[str, Resource]

All configured resources, keyed by name.

resources_by_type `property` ¶

resources_by_type: Mapping[str, Mapping[str, Resource]]

Resources grouped by GMAT type, e.g. resources_by_type["Spacecraft"]["Sat"].

mission_sequence `property` ¶

mission_sequence: tuple[Command, ...]

The ordered mission-sequence commands (empty for a configuration-only script).

The returned commands are a snapshot of the current tree; re-read this attribute after a command edit rather than reusing handles from before it.

byte_range `property` ¶

byte_range: tuple[int, int]

The script's (start_byte, end_byte) span (provenance).

has_errors `property` ¶

has_errors: bool

Whether the underlying parse carried any syntax error (delegates to the tree).

parse `classmethod` ¶

parse(source: str) -> Script

Parse source and overlay the typed model — Script(parse(source)) in one call.

to_source ¶

to_source() -> str

Re-emit the script source — byte-for-byte to the input until the first edit, and exact on every untouched byte after one (D6).

set_field ¶

set_field(
    resource: str, field: str, value: Value
) -> Script

Set <resource>.<field> to value, formatting the literal value-type-aware.

Rewrites the field's value in place when it is already assigned (the last-winning assignment), else appends a canonical <resource>.<field> = <value> line next to the resource's configuration. This backs script.spacecraft["Sat"]["SMA"] = 7000.

delete_field ¶

delete_field(resource: str, field: str) -> Script

Delete every assignment of <resource>.<field>; raise KeyError if it has none.

add_resource ¶

add_resource(
    resource_type: str,
    name: str,
    fields: Mapping[str, Value] | None = None,
) -> Script

Append Create <resource_type> <name> (plus any fields) to the configuration.

The declaration lands just before BeginMissionSequence (or at end of file when the script has no marker). Raises :class:~gmat_script.ast.edit.MutationError if name exists.

remove_resource ¶

remove_resource(name: str) -> Script

Remove resource name: drop its Create (or just its name from a multi-name one) and every configuration assignment rooted at it. References elsewhere are left as-is — use :meth:rename_resource to rewrite them.

rename_resource ¶

rename_resource(
    old: str, new: str, *, update_references: bool = True
) -> Script

Rename resource old to new, rewriting references unless update_references is false.

With references on (the default), every dotted reference root, array-index / call head, bare operand, and the declaration name is rewritten — best-effort over the textual reference forms (the scope is :func:~gmat_script.ast.edit.collect_reference_edits's). With it off, only the declaration name changes. Raises :class:~gmat_script.ast.edit.MutationError on a name clash.

insert_command ¶

insert_command(index: int, text: str) -> Script

Insert text as a new mission-sequence command before position index (or at the end).

text is raw command source, inserted as its own line(s). Requires a mission sequence to insert into (a BeginMissionSequence marker) when the sequence is empty.

remove_command ¶

remove_command(index: int) -> Script

Remove the mission-sequence command at index (a whole block, if it is one).

replace_command ¶

replace_command(index: int, text: str) -> Script

Replace the command at index with text (its operands, re-emitted), in place.

Rewrites only the command node's own span, so leading indentation and the trailing newline are preserved; pass text without a trailing newline.

move_command ¶

move_command(from_index: int, to_index: int) -> Script

Move the command at from_index so it ends up at to_index in the sequence.

Catalog ¶

A loaded GMAT field catalogue with a typed, alias-aware query API.

gmat_version `property` ¶

gmat_version: str

The GMAT release this catalogue was reflected from (e.g. "R2026a").

generated `property` ¶

generated: str

The ISO date the catalogue was generated.

load `classmethod` ¶

load(target_version: str | None = None) -> Catalog

Load a shipped catalogue. target_version defaults to the newest available (D11).

from_dict `classmethod` ¶

from_dict(data: Mapping[str, Any]) -> Catalog

Build a catalogue from a parsed JSON mapping (the on-disk schema).

types ¶

types() -> list[str]

All canonical type names, sorted (excludes alias spellings).

resolve ¶

resolve(name: str) -> str | None

Resolve a script type name (possibly an alias) to its canonical key, or None.

has_type ¶

has_type(name: str) -> bool

Whether name is a known type (directly or via an alias).

type_spec ¶

type_spec(name: str) -> TypeSpec | None

The :class:TypeSpec for name (alias-resolved), or None if unknown.

fields ¶

fields(type_name: str) -> list[str]

Sorted field names for type_name; [] if the type is unknown.

field ¶

field(type_name: str, field_name: str) -> FieldSpec | None

The :class:FieldSpec for type_name.field_name, or None if either is unknown.

field_type ¶

field_type(type_name: str, field_name: str) -> str | None

The normalised type of a field, or None if unknown.

enum_values ¶

enum_values(
    type_name: str, field_name: str
) -> tuple[str, ...] | None

A field's allowed enum values where GMAT exposes them, else None.

ref_target ¶

ref_target(type_name: str, field_name: str) -> str | None

The target GMAT type of an object-reference field, or None.

FieldSpec `dataclass` ¶

A single field of a resource type, as reflected from GMAT.

type is the normalised catalogue type (real / integer / string / bool / enum / object / object_array / string_array / real_array / matrix / filename / on_off / color / gmat_time / ...); gmat_type keeps GMAT's raw type label. allowed is populated for enums where GMAT exposes the values, ref_target for object references, and default for settable scalar fields — each None where absent.

TypeSpec `dataclass` ¶

A resource type: its GMAT object-type category and its fields by name.

Diagnostic `dataclass` ¶

One linter finding: a rule code, a severity, a message, and a 1-indexed source range.

line `property` ¶

line: int

The 1-indexed start line — the physical line suppression and reporting key off.

sort_key ¶

sort_key() -> tuple[int, int, str]

Order diagnostics by position, then rule code, for a stable report.

Severity ¶

Bases: str, Enum

A diagnostic's severity. A str enum so it serialises to its value verbatim in JSON.

ErrorNode `dataclass` ¶

A syntax error surfaced from the concrete syntax tree.

One record per ERROR or MISSING node: its :class:Position range and a short message. These are data, not exceptions — :func:parse never raises on malformed input (D7).

Position `dataclass` ¶

A 1-indexed line/column position into the source (compiler / human convention).

tree-sitter's native points are 0-indexed; the wrapper converts (decision D8). column is a 1-indexed byte offset within its line.

Tree ¶

A thin wrapper over the tree-sitter concrete syntax tree of a parsed GMAT script.

Returned by :func:parse. v0.1 exposes only what the parser contract needs: byte-exact re-emission (:attr:text / :meth:to_source), syntax-error access (:attr:errors / :attr:has_errors), and the raw :attr:root_node for layers built on top (the v0.2 typed-AST overlay, the parse CLI).

root_node `property` ¶

root_node: Node

The root :class:~tree_sitter.Node of the concrete syntax tree (a source_file).

text `property` ¶

text: str

The script's source text, byte-for-byte identical to the input of :func:parse (D6).

errors `property` ¶

errors: list[ErrorNode]

The ERROR / MISSING nodes in source order — empty if it parsed cleanly.

has_errors `property` ¶

has_errors: bool

Whether the tree contains any ERROR or MISSING node.

Reads tree-sitter's own has_error flag, which is authoritative: it counts a MISSING instance of a hidden token (the statement terminator) that the node-child API does not expose, so this never under-reports relative to :attr:errors (see :func:_collect_errors).

to_source ¶

to_source() -> str

Re-emit the script source, identical byte-for-byte to the text passed to :func:parse.

Equivalent to :attr:text. The CST preserves every leaf token and all interstitial layout (whitespace, comments, the ... continuation, the optional ;), so concatenating them in order reproduces the input exactly; the test suite asserts that reconstruction directly.

load_catalog `cached` ¶

load_catalog(target_version: str | None = None) -> Catalog

Load (and cache) a shipped catalogue — the convenience entry point most consumers want.

parse ¶

parse(source: str) -> Tree

Parse GMAT script source into a concrete syntax tree.

Loads the vendored grammar (no GMAT, C, or Node toolchain needed) and returns a :class:Tree. source is UTF-8 text; its line endings are preserved exactly — the library performs no EOL normalisation (D6). Malformed input never raises: the returned tree carries ERROR / MISSING nodes localised to the broken construct, surfaced via :attr:Tree.errors (D7).

Parameters:

Name	Type	Description	Default
`source`	`str`	the `.script` or `.gmf` text to parse.	required

Returns:

Type	Description
`Tree`	a :class:`Tree` wrapping the parsed concrete syntax tree.

API reference¶

gmat_script ¶

Array dataclass ¶

MutationError ¶

ObjectRef dataclass ¶

RawValue dataclass ¶

Script ¶

tree property ¶

resources property ¶

resources_by_type property ¶

mission_sequence property ¶

byte_range property ¶

has_errors property ¶

parse classmethod ¶

to_source ¶

set_field ¶

delete_field ¶

add_resource ¶

remove_resource ¶

rename_resource ¶

insert_command ¶

remove_command ¶

replace_command ¶

move_command ¶

Catalog ¶

gmat_version property ¶

generated property ¶

load classmethod ¶

from_dict classmethod ¶

types ¶

resolve ¶

has_type ¶

type_spec ¶

fields ¶

field ¶

field_type ¶

enum_values ¶

ref_target ¶

FieldSpec dataclass ¶

TypeSpec dataclass ¶

Diagnostic dataclass ¶

line property ¶

sort_key ¶

Severity ¶

ErrorNode dataclass ¶

Position dataclass ¶

Tree ¶

root_node property ¶

text property ¶

errors property ¶

has_errors property ¶

to_source ¶

load_catalog cached ¶

parse ¶

Array `dataclass` ¶

ObjectRef `dataclass` ¶

RawValue `dataclass` ¶

tree `property` ¶

resources `property` ¶

resources_by_type `property` ¶

mission_sequence `property` ¶

byte_range `property` ¶

has_errors `property` ¶

parse `classmethod` ¶

gmat_version `property` ¶

generated `property` ¶

load `classmethod` ¶

from_dict `classmethod` ¶

FieldSpec `dataclass` ¶

TypeSpec `dataclass` ¶

Diagnostic `dataclass` ¶

line `property` ¶

ErrorNode `dataclass` ¶

Position `dataclass` ¶

root_node `property` ¶

text `property` ¶

errors `property` ¶

has_errors `property` ¶

load_catalog `cached` ¶