Parametry i zmienne w skryptach .goat

Parametry i zmienne w skryptach .goat

Skrypty .goat mogą korzystać z argumentów przekazanych podczas uruchomienia, lokalnych zmiennych oraz zmiennych środowiskowych.

Dostępne są cztery podstawowe mechanizmy:

• {{args}} — wszystkie argumenty przekazane do skryptu,
• {{args.nazwa}} — wybrany argument nazwany,
• {{zmienna}} — lokalna zmienna zdefiniowana przez set,
• {{env.NAZWA}} — zmienna środowiskowa.

Argumenty i lokalne zmienne należą do bieżącego skryptu. Podskrypt otrzymuje je tylko wtedy, gdy zostaną mu jawnie przekazane.

Przekazywanie argumentów do skryptu

Argumenty skryptu przekazuje się po separatorze --.

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

W tym przykładzie:

--path=herd/translate.goat

jest opcją run:script, natomiast:

--force

jest argumentem skryptu translate.goat.

Można przekazać dowolną liczbę argumentów:

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

Bez separatora -- argumenty są interpretowane jako opcje polecenia run:script.

Wszystkie argumenty — {{args}}

{{args}} rozwija się do wszystkich argumentów przekazanych do bieżącego skryptu.

Przykład:

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

Uruchomienie:

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

jest w tym przypadku równoważne przekazaniu do translate:sync:

--force --model=gpt-5

Kolejność argumentów zostaje zachowana.

Jeżeli do skryptu nie przekazano żadnych argumentów, {{args}} rozwija się do pustej listy. Nie powoduje to błędu.

Dzięki temu można bezpiecznie pisać:

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

i używać tego samego skryptu zarówno bez dodatkowych opcji:

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

jak i z nimi:

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

{{args}} jako osobny token

{{args}} może występować wyłącznie jako osobny token.

Poprawnie:

command {{args}}

Niepoprawnie:

command --options={{args}}

Jest to konieczne, ponieważ {{args}} może rozwinąć się do zera, jednego albo wielu argumentów.

Argumenty nazwane — {{args.nazwa}}

Do konkretnego argumentu można odwołać się przez:

{{args.nazwa}}

Na przykład:

command {{args.model}}

Obsługiwane są długie argumenty w formach:

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

Zachowanie oryginalnej formy

Argument jest przekazywany w takiej samej postaci, w jakiej został podany.

Dla:

--model=gpt-5

wyrażenie:

{{args.model}}

przekazuje:

--model=gpt-5

Dla:

--model gpt-5

przekazuje natomiast dwa tokeny:

--model
gpt-5

Wielokrotne wystąpienia

Jeżeli ten sam argument występuje kilka razy, wszystkie jego wystąpienia są zachowywane w oryginalnej kolejności.

Przykład:

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

Odwołanie:

{{args.tag}}

przekaże wszystkie trzy wystąpienia.

Brak argumentu

Odwołanie do argumentu, którego nie przekazano, kończy wykonanie skryptu błędem.

Przykład:

command {{args.model}}

wymaga obecności argumentu --model.

Jeżeli argument jest opcjonalny, zwykle wygodniej przekazać wszystkie opcjonalne argumenty przez:

{{args}}

Osobny token

Tak jak {{args}}, również {{args.nazwa}} może występować wyłącznie jako osobny token.

Poprawnie:

command {{args.model}}

Niepoprawnie:

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

Lokalne zmienne — set

Lokalną zmienną można zdefiniować przez:

set model = "gpt-5"

Następnie można jej używać w kolejnych poleceniach:

command --model={{model}}

lub jako osobnego argumentu:

command {{model}}

Zmienne są dostępne od miejsca ich deklaracji i należą wyłącznie do aktualnego skryptu.

Przykład:

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

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

Wartości zmiennych nie są ponownie dzielone

Wartość lokalnej zmiennej jest zawsze traktowana jako jedna wartość.

Przykład:

set options = "--foo --bar"

command {{options}}

przekazuje jeden argument:

--foo --bar

a nie dwa osobne argumenty:

--foo
--bar

Jeżeli potrzebujesz przekazać wiele argumentów, użyj {{args}} albo zapisz je bezpośrednio w poleceniu.

Zmienne środowiskowe — {{env.NAZWA}}

Do zmiennych środowiskowych można odwoływać się przez:

{{env.NAZWA}}

Przykład:

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

Można ich także używać wewnątrz tokenów:

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

Wartość zmiennej środowiskowej jest traktowana jako jedna wartość i nie jest ponownie dzielona na argumenty.

Jeżeli wskazana zmienna środowiskowa nie istnieje, wykonanie skryptu kończy się błędem.

Używanie zmiennych w wartościach cytowanych

Zmienne lokalne i środowiskowe mogą być używane również wewnątrz wartości cytowanych.

set model = "gpt-5"

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

oraz:

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

Można również łączyć je ze stałym tekstem:

set locale = "pl"

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

Zakres argumentów i zmiennych

Każdy skrypt .goat ma własne:

• argumenty,
• lokalne zmienne zdefiniowane przez set.

Nie są one automatycznie dostępne w uruchamianych podskryptach.

Przykład:

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

child.goat uruchamia się bez argumentów skryptu i bez lokalnych zmiennych rodzica.

Zmienne środowiskowe są nadal dostępne przez:

{{env.NAZWA}}

Przekazywanie argumentów do podskryptu

Jeżeli podskrypt ma otrzymać argumenty skryptu nadrzędnego, trzeba przekazać je jawnie.

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

Wtedy child.goat otrzyma wszystkie argumenty aktualnego skryptu.

Można przekazać tylko wybrany argument:

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

albo zbudować argument na podstawie lokalnej zmiennej:

set model = "gpt-5"

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

Dzięki temu każdy skrypt otrzymuje tylko te dane, które zostały mu jawnie przekazane.

Dostępne formy interpolacji

Przykłady poprawnego użycia:

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

Niepoprawne:

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

Przykład: przekazywanie opcji do translate:sync

Skrypt może przekazywać wszystkie otrzymane argumenty bezpośrednio do translate:sync:

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

Standardowe uruchomienie:

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

nie przekazuje żadnych dodatkowych opcji.

Uruchomienie:

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

przekazuje --force do translate:sync.

Analogicznie:

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

przekazuje obie opcje w tej samej kolejności.

Przykład kompletnego skryptu

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

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

Skrypt można uruchomić bez dodatkowych argumentów:

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

albo przekazać dodatkowe opcje:

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

Błędy

Wykonanie skryptu zostaje przerwane między innymi wtedy, gdy:

• użyta zostanie niezdefiniowana lokalna zmienna,
• wskazana zmienna środowiskowa nie istnieje,
• {{args.nazwa}} odwołuje się do argumentu, którego nie przekazano,
• {{args}} lub {{args.nazwa}} zostanie użyte wewnątrz innego tokenu.

Komunikat błędu wskazuje miejsce problemu w skrypcie, dzięki czemu można zidentyfikować niepoprawne odwołanie.