.gl syntax

A .gl file is a line-oriented script executed by gapline run. Each non-empty, non-comment line is a directive: either a session control (feed, save) or one of the main gapline commands without the -f flag.

Grammar

script      := (line "\n")*
line        := comment | blank | directive [comment]
comment     := "#" <any char>*
blank       := /[ \t]*/
directive   := session_directive | command_directive

session_directive := "feed" path
                   | "save" [path]

command_directive := "validate" validate_args
                   | "read"     crud_target read_args
                   | "create"   crud_target create_args
                   | "update"   crud_target update_args
                   | "delete"   crud_target delete_args

Values that contain whitespace can be double-quoted ("Gare du Nord"). Escape sequences inside quotes are not processed — the content is taken verbatim until the closing quote.

Directives

`feed <path>`

Loads a GTFS archive or directory into memory. Must be the first non-comment directive in the file.

feed ./data/gtfs.zip
feed /absolute/path/to/gtfs/

Only one feed directive is allowed per script — the session is single-tenant.

`save [path]`

Writes the current in-memory feed back to disk atomically. Without an argument, save rewrites the path passed to feed; with an argument, it writes to that path (leaving the source untouched).

save                        # Overwrite the source feed.
save ./data/gtfs-patched.zip

save is not implicit. A script with no save directive exits without persisting anything — the point is that .gl scripts are safe to re-run.

`validate [--format FORMAT] [-o PATH]`

Runs the full validation suite against the in-memory feed.

validate
validate --format json
validate --format json -o report.json

Flags accepted: --format, -o / --output.

--min-severity and --disable-rule are not accepted inside a .gl script — pin them in gapline.toml instead. The batch runner reads the same config chain as the top-level CLI.

`read <target> [-w QUERY] [--format FORMAT] [-o PATH]`

Reads records from a GTFS file in memory.

read stops
read stops -w "stop_name LIKE Gare%"
read routes --format csv -o routes.csv

Flags accepted: -w / --where, --format, -o / --output.

`create <target> -s KEY=VALUE [KEY=VALUE...] [--confirm]`

Inserts a new record into a GTFS file.

create stops -s stop_id=NEW_01 stop_name="Place du marché" stop_lat=45.5017 stop_lon=-73.5673 --confirm

-s / --set is required. Everything after -s until the next flag is consumed as KEY=VALUE pairs.

Inside a script, --confirm is generally required — there is no interactive prompt on a non-TTY runner.

`update <target> -w QUERY -s KEY=VALUE [KEY=VALUE...] [--confirm] [--cascade]`

Updates every record matching -w.

update stops -w "stop_id=S01" -s stop_name="Gare Centrale" --confirm
update stops -w "stop_id=S01" -s stop_id=STOP_MAIN --cascade --confirm

Both -w / --where and -s / --set are required. --cascade is needed when -s rewrites a primary key.

`delete <target> [-w QUERY] [--confirm]`

Removes every record matching -w. In scripts, --confirm is required — the script runner cannot prompt interactively.

delete trips -w "route_id=OLD_LINE" --confirm

Comments

Lines starting with # are comments. # can also appear at the end of a directive line — everything from # to the end of the line is ignored (tokens inside a double-quoted string are not affected).

feed ./data/gtfs.zip                     # Loads once.

# Block comment between directives.
validate --format json -o report.json    # Snapshot.

Execution semantics

.gl scripts are linear and stop-on-error:

Directives execute in source order.
The first failure aborts the script with a non-zero exit code.
Nothing is persisted unless a save directive succeeded earlier in the run.

See concepts / .gl session model for the rationale.

What `.gl` does not support

Variables, substitution, interpolation. Paths and values are literal.
Control flow. No if, no loops, no try/catch.
Nested scripts. run is not a directive — a .gl file cannot call another.
Sub-commands beyond the ones listed above. rules and completion are CLI-only.

Minimal example

feed ./data/gtfs.zip
validate
save

Realistic example

feed ./data/gtfs.zip

delete trips --where "route_id=OLD_LINE" --confirm
delete routes --where "route_id=OLD_LINE" --confirm
update routes --where "route_type=700" --set route_type=3 --confirm

validate --format json -o reports/weekly.json

save ./data/gtfs-patched.zip

.gl syntax

Grammar

Directives

feed <path>

save [path]

validate [--format FORMAT] [-o PATH]

read <target> [-w QUERY] [--format FORMAT] [-o PATH]

create <target> -s KEY=VALUE [KEY=VALUE...] [--confirm]

update <target> -w QUERY -s KEY=VALUE [KEY=VALUE...] [--confirm] [--cascade]

delete <target> [-w QUERY] [--confirm]