Parameter und Variablen in .goat-Skripten

Parameter und Variablen in .goat-Skripten

.goat-Skripte können beim Start übergebene Argumente, lokale Variablen und Umgebungsvariablen verwenden.

Es stehen vier grundlegende Mechanismen zur Verfügung:

• {{args}} — alle an das Skript übergebenen Argumente,
• {{args.name}} — ein ausgewähltes benanntes Argument,
• {{variable}} — eine mit set definierte lokale Variable,
• {{env.NAME}} — eine Umgebungsvariable.

Argumente und lokale Variablen gehören zum aktuellen Skript. Ein Unterskript erhält sie nur, wenn sie explizit weitergegeben werden.

Argumente an ein Skript übergeben

Skriptargumente werden nach dem Separator -- angegeben.

goat run:script --path=herd/translate.goat -- --force

In diesem Beispiel ist:

--path=herd/translate.goat

eine Option von run:script, während:

--force

ein Argument des Skripts translate.goat ist.

Es können beliebig viele Argumente übergeben werden:

goat run:script --path=herd/example.goat -- --force --model=gpt-5 --verbose

Ohne den Separator -- werden Argumente als Optionen des Befehls run:script interpretiert.

Alle Argumente — {{args}}

{{args}} wird zu allen Argumenten expandiert, die dem aktuellen Skript übergeben wurden.

Beispiel:

translate:sync --catalog="catalog.json" {{args}}

Der Aufruf:

goat run:script --path=herd/translate.goat -- --force --model=gpt-5

entspricht in diesem Fall der Übergabe von:

--force --model=gpt-5

an translate:sync.

Die Reihenfolge der Argumente bleibt erhalten.

Wenn dem Skript keine Argumente übergeben wurden, wird {{args}} zu einer leeren Liste expandiert. Dies ist gültig und verursacht keinen Fehler.

Daher kann beispielsweise Folgendes sicher verwendet werden:

translate:sync --catalog="catalog.json" {{args}}

Dasselbe Skript kann sowohl ohne zusätzliche Optionen:

goat run:script --path=herd/translate.goat

als auch mit zusätzlichen Optionen ausgeführt werden:

goat run:script --path=herd/translate.goat -- --force

{{args}} als eigenständiges Token

{{args}} darf nur als eigenständiges Token verwendet werden.

Gültig:

command {{args}}

Ungültig:

command --options={{args}}

Diese Einschränkung ist notwendig, da {{args}} zu null, einem oder mehreren Argumenten expandieren kann.

Benannte Argumente — {{args.name}}

Auf ein bestimmtes Argument kann über folgende Syntax zugegriffen werden:

{{args.name}}

Zum Beispiel:

command {{args.model}}

Long-Form-Argumente werden in folgenden Formen unterstützt:

--model
--model=gpt-5
--model gpt-5

Beibehaltung der ursprünglichen Form

Ein Argument wird in derselben Form weitergegeben, in der es ursprünglich angegeben wurde.

Für:

--model=gpt-5

übergibt:

{{args.model}}

folgenden Wert:

--model=gpt-5

Für:

--model gpt-5

werden dagegen zwei Tokens übergeben:

--model
gpt-5

Mehrfaches Auftreten

Wenn dasselbe Argument mehrfach angegeben wird, bleiben alle Vorkommen in ihrer ursprünglichen Reihenfolge erhalten.

Beispiel:

--tag=a --tag b --tag=c

Die Referenz:

{{args.tag}}

übergibt alle drei Vorkommen.

Fehlendes Argument

Der Zugriff auf ein Argument, das nicht übergeben wurde, beendet die Skriptausführung mit einem Fehler.

Zum Beispiel:

command {{args.model}}

setzt voraus, dass das Argument --model vorhanden ist.

Wenn ein Argument optional ist, ist es in der Regel einfacher, alle optionalen Argumente mit:

{{args}}

weiterzugeben.

Eigenständiges Token

Wie {{args}} darf auch {{args.name}} nur als eigenständiges Token verwendet werden.

Gültig:

command {{args.model}}

Ungültig:

command --model={{args.model}}

Lokale Variablen — set

Eine lokale Variable kann mit set definiert werden:

set model = "gpt-5"

Anschließend kann sie in folgenden Befehlen verwendet werden:

command --model={{model}}

oder als eigenständiges Argument:

command {{model}}

Variablen stehen ab dem Zeitpunkt ihrer Deklaration zur Verfügung und gehören ausschließlich zum aktuellen Skript.

Beispiel:

set catalog = "catalog.json"
set model = "gpt-5"

translate:sync --catalog={{catalog}} --model={{model}}

Variablenwerte werden nicht erneut aufgeteilt

Der Wert einer lokalen Variable wird immer als ein einzelner Wert behandelt.

Beispiel:

set options = "--foo --bar"

command {{options}}

übergibt ein einzelnes Argument:

--foo --bar

und nicht zwei separate Argumente:

--foo
--bar

Wenn mehrere Argumente übergeben werden sollen, kann {{args}} verwendet oder können die Argumente direkt im Befehl angegeben werden.

Umgebungsvariablen — {{env.NAME}}

Auf Umgebungsvariablen kann mit folgender Syntax zugegriffen werden:

{{env.NAME}}

Beispiel:

translate:sync --model={{env.GOAT_OPENAI_MODEL}}

Sie können auch innerhalb eines Tokens verwendet werden:

command --endpoint={{env.API_ENDPOINT}}

Der Wert einer Umgebungsvariable wird als ein einzelner Wert behandelt und nicht in zusätzliche Argumente aufgeteilt.

Wenn die angeforderte Umgebungsvariable nicht existiert, wird die Skriptausführung mit einem Fehler beendet.

Variablen in quotierten Werten verwenden

Lokale Variablen und Umgebungsvariablen können auch innerhalb von quotierten Werten verwendet werden.

set model = "gpt-5"

translate:sync --model="{{model}}"

sowie:

translate:sync --model="{{env.GOAT_OPENAI_MODEL}}"

Variablen können auch mit statischem Text kombiniert werden:

set locale = "pl"

command --catalog="catalog-{{locale}}.json"

Gültigkeitsbereich von Argumenten und Variablen

Jedes .goat-Skript besitzt eigene:

• Argumente,
• mit set definierte lokale Variablen.

Diese sind nicht automatisch in Unterskripten verfügbar.

Beispiel:

run:script --path=herd/child.goat

child.goat wird ohne die Argumente und lokalen Variablen des übergeordneten Skripts gestartet.

Umgebungsvariablen bleiben weiterhin über:

{{env.NAME}}

verfügbar.

Argumente an ein Unterskript weitergeben

Wenn ein Unterskript die Argumente seines übergeordneten Skripts erhalten soll, müssen sie explizit weitergegeben werden.

run:script --path=herd/child.goat -- {{args}}

In diesem Fall erhält child.goat alle Argumente des aktuellen Skripts.

Es kann auch nur ein bestimmtes benanntes Argument weitergegeben werden:

run:script --path=herd/child.goat -- {{args.model}}

Alternativ kann ein Argument aus einer lokalen Variable aufgebaut werden:

set model = "gpt-5"

run:script --path=herd/child.goat -- --model={{model}}

Dadurch bleiben die Grenzen zwischen Skripten explizit: Jedes Skript erhält nur die Werte, die bewusst an dieses Skript übergeben wurden.

Verfügbare Interpolationsformen

Gültige Beispiele:

command {{args}}
command {{args.model}}
command {{model}}
command --model={{model}}
command --model={{env.GOAT_OPENAI_MODEL}}

Ungültige Beispiele:

command prefix-{{args}}
command --model={{args.model}}

Beispiel: Optionen an translate:sync weitergeben

Ein Skript kann alle erhaltenen Argumente direkt an translate:sync weitergeben:

translate:sync --catalog="catalog.json" {{args}}

Ein normaler Aufruf:

goat run:script --path=herd/translate.goat

übergibt keine zusätzlichen Optionen.

Der Aufruf:

goat run:script --path=herd/translate.goat -- --force

übergibt --force an translate:sync.

Analog dazu übergibt:

goat run:script --path=herd/translate.goat -- --force --model=gpt-5

beide Optionen in derselben Reihenfolge.

Vollständiges Skriptbeispiel

set catalog = "catalog.json"
set defaultModel = "gpt-5"

translate:prepare --catalog={{catalog}}
translate:sync --catalog={{catalog}} --fallback-model={{defaultModel}} {{args}}

Das Skript kann ohne zusätzliche Argumente ausgeführt werden:

goat run:script --path=herd/example.goat

oder mit zusätzlichen Optionen:

goat run:script --path=herd/example.goat -- --force --model=gpt-5

Fehler

Die Skriptausführung wird unter anderem in folgenden Fällen beendet:

• eine nicht definierte lokale Variable wird verwendet,
• die angeforderte Umgebungsvariable existiert nicht,
• {{args.name}} verweist auf ein Argument, das nicht übergeben wurde,
• {{args}} oder {{args.name}} wird innerhalb eines anderen Tokens verwendet.

Die Fehlermeldung verweist auf die entsprechende Stelle im Skript, sodass die ungültige Referenz identifiziert werden kann.