Přejít k obsahu

Kompatibilita s sg

Zobrazit jako Markdown Upravit na GitHub Dokumentace na d105217

vendor/bin/sg je wrapper kompatibilní se stylem ast-grep. Přijímá nejčastěji používané příznaky ast-grep a znovu používá stejný engine Greph\Ast\AstSearcher, který používá vendor/bin/greph -p. Ověřené možnosti vycházejí z testovacích běhů s upstreamovým binárním souborem sg a jsou uvedeny v Rozšířené funkce / Matice funkcí.

Kdy jej použít

Wrapper použijte, když:

  • Máte existující nástroj, agenta nebo skript, který už spouští sg.
  • Chcete přímou náhradu, která funguje v prostředích, kde nelze nainstalovat samotný ast-grep.
  • Chcete pohodlí ast-grep v instalaci, která obsahuje pouze Composer.

Nativní vendor/bin/greph -p použijte, když:

  • Píšete nový kód a nepotřebujete rozhraní ast-grep CLI.
  • Chcete používat stejnou sadu příznaků jako v textovém režimu (nativní binární soubor oba režimy sjednocuje).

Použití

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

run je kanonický příkaz ast-grep. scan a rewrite jsou pouze aliasy wrapperu, které odpovídají běžnému použití. Funguje i samotné spuštění jako jednorázové vyhledávání:

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

Vzory

Gramatika vzorů je totožná s nativním vyhledáváním v AST. Úplné informace najdete v části Režimy / Vyhledávání v 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

Přepisy

Wrapper podporuje stejný pracovní postup nanečisto / interaktivní / zápis jako nativní přepis; používá názvy příznaků 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 vydává ast-grep ve formátu JSON. Podporuje tři styly:

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
Styl Formát
--json (výchozí pretty) Jediné hezky formátované pole JSON
--json=stream Jedna shoda na řádek, data JSON oddělená novým řádkem
--json=compact Jediné kompaktní pole JSON

Ověřené možnosti

Následující příznaky jsou ověřeny proti upstreamovému binárnímu souboru sg v matici funkcí. Má-li příznak dva zápisy (-p a --pattern, --glob a --globs), test používá jeden z nich a wrapper oba zpracuje jako tutéž volbu.

Příznaky vzoru

  • --pattern PATTERN (na nejvyšší úrovni i uvnitř run)
  • -p PATTERN (alias)
  • --rewrite TEMPLATE
  • -r TEMPLATE
  • --lang NAME, -l NAME

Příznaky shody

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

Příznaky procházení

  • --no-ignore hidden (kombinovaná forma)
  • --glob GLOB, --globs GLOB

Příznaky pracovníků

  • -j N, --threads N

Přijímané bez testu

Wrapper přijímá také následující příznaky, na které se zatím nevztahuje žádný test matice funkcí:

  • --no-ignore samostatně nebo s jinou hodnotou než hidden
  • --type NAME, --type-not NAME

Další možnosti pouze ve wrapperu

Wrapper nabízí několik pomocných možností, které samotné ast-grep nemá:

  • Aliasy scan a rewrite pro run
  • Příznak --hidden (ast-grep jej zahrnuje do --no-ignore hidden)
  • Alias --dry-run pro náhled přepisu
  • Průběh potvrzení přepisu --interactive

Omezení

Wrapper sg pro Greph pokrývá možnosti strukturálního vyhledávání a přepisu, které využívá většina nástrojů a agentů. V současnosti nezpřístupňuje tyto funkce ast-grep:

  • Soubory pravidel YAML (--rule, --config)
  • Prohledávání více jazyků kromě PHP
  • Transformátory, které nepoužívají vzory (--debug-query, --inspect)
  • Integrace LSP

Pokud narazíte na chybějící příznak, založte hlášení a přiložte test provedený proti upstreamovému sg i očekávaný výstup.

Shoda chování

Cílem wrapperu je shoda chování, nikoli shoda po bajtech. Výstup je sémanticky rovnocenný, ale může se lišit v kosmetických detailech. Testy použité v matici funkcí ověřují shodu polí důležitých pro parser (cesta k souboru, číslo řádku, zachycený kód, zachycené hodnoty, struktura JSON), nikoli bajtového proudu.