Kompatibilita s sg

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na d105217

vendor/bin/sg je obal kompatibilný so štýlom ast-grep. Prijíma najčastejšie používané prepínače ast-grep a opätovne využíva ten istý modul Greph\Ast\AstSearcher ako vendor/bin/greph -p. Overený rozsah vychádza zo skúšobných behov s pôvodným binárnym súborom sg a je uvedený v Rozšírené / Matica funkcií.

Kedy ho použiť

Obal použite, keď:

Už máte nástroj, agenta alebo skript, ktorý volá sg.
Chcete priamu náhradu použiteľnú v prostrediach, kde nemožno nainštalovať samotné ast-grep.
Chcete pohodlné používanie ast-grep v inštalácii, ktorá obsahuje iba Composer.

Natívne vendor/bin/greph -p použite, keď:

Píšete nový kód a nepotrebujete formát ast-grep CLI.
Chcete rovnakú množinu prepínačov ako v textovom režime (natívny binárny súbor oba režimy spája).

Použitie

Shell

sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]

run je kanonické sloveso ast-grep. scan a rewrite sú aliasy dostupné iba v obaloch, ktoré kopírujú bežné používanie. Samotné zavolanie funguje ako jednorazové vyhľadávanie:

Shell

./vendor/bin/sg --pattern 'array($$$ITEMS)' src

Vzory

Gramatika vzorov je totožná s natívnym vyhľadávaním AST. Úplnú referenciu nájdete v časti Režimy / Vyhľadávanie AST.

Shell

./vendor/bin/sg run --pattern 'array($$$ITEMS)' src
./vendor/bin/sg run --pattern '$obj->$method($$$ARGS)' src
./vendor/bin/sg run --pattern 'new $CLASS()' src

Prepisovanie

Obal podporuje rovnaký pracovný postup pre skúšobné spustenie, interaktívne úpravy a zápis ako natívne prepisovanie, pričom používa názvy prepínačov ast-grep:

Shell

# Preview only (default)
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src

# Apply without confirmation
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src

# Confirm each match
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --interactive src

# Wrapper-only aliases
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Výstup JSON

--json vytvára výstup v tvare ast-grep JSON. Podporované sú tri štýly:

Shell

./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=stream --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=compact --pattern 'dispatch($EVENT)' src

Štýl	Tvar
`--json` (predvolený `pretty`)	Jedno pekne naformátované pole JSON
`--json=stream`	Jedna zhoda na riadok, oddelené znakmi nového riadka JSON
`--json=compact`	Jedno kompaktné pole JSON

Overený rozsah

Nasledujúce prepínače sú overené oproti pôvodnému binárnemu súboru sg v matica funkcií. Ak má prepínač dva zápisy (-p a --pattern, --glob a --globs), skúška používa jeden z nich a obal oba rozpozná ako rovnakú možnosť.

Prepínače vzorov

--pattern PATTERN (na najvyššej úrovni aj v rámci run)
-p PATTERN (alias)
--rewrite TEMPLATE
-r TEMPLATE
--lang NAME, -l NAME

Prepínače zhody

--files-with-matches
--json (pretty, stream, compact)
--update-all, -U

Prepínače prechádzača

--no-ignore hidden (kombinovaný tvar)
--glob GLOB, --globs GLOB

Prepínače pracovníkov

-j N, --threads N

Prijaté bez skúšobného overenia

Obal prijíma aj tieto prepínače, zatiaľ ich však neoveruje žiadna skúška matice funkcií:

Samotné --no-ignore alebo s hodnotou odlišnou od hidden
--type NAME, --type-not NAME

Doplnkové možnosti dostupné iba v obale

Obal poskytuje niekoľko pomocných možností, ktoré samotné ast-grep nemá:

Aliasy scan a rewrite pre run
Prepínač --hidden (ast-grep zlučuje túto možnosť s --no-ignore hidden)
Alias --dry-run na zobrazenie náhľadu prepisu
Postup na potvrdenie prepisu --interactive

Obmedzenia

Obal Greph pre sg pokrýva funkcie štrukturálneho vyhľadávania a prepisovania, ktoré používajú najčastejšie nástroje a agenti. V súčasnosti neposkytuje nasledujúce funkcie ast-grep:

Súbory pravidiel YAML (--rule, --config)
Prehľadávanie vo viacerých jazykoch okrem PHP
Transformátory, ktoré nepoužívajú vzory (--debug-query, --inspect)
Integrácia s LSP

Ak vám chýba nejaký prepínač, nahláste problém spolu s výsledkom skúšky, ktorú ste vykonali voči pôvodnému sg, a očakávaným výstupom.

Zhoda správania

Obal sa zameriava na zhodu správania, nie na zhodu bajtov. Výstup je sémanticky ekvivalentný, no v kozmetických detailoch sa môže líšiť. Testy použité v matici funkcií kontrolujú zhodu polí dôležitých pre parser (cesta k súboru, číslo riadka, zachytený kód, zachytené hodnoty, tvar JSON), nie zhodu bajtového toku.