Przejdź do treści

Zgodność z sg

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: d105217

vendor/bin/sg to warstwa zgodności w stylu ast-grep. Przyjmuje najczęściej używane flagi ast-grep i korzysta z tego samego silnika Greph\Ast\AstSearcher co vendor/bin/greph -p. Zweryfikowany zakres odtworzono na podstawie uruchomień próbnych wobec nadrzędnego pliku wykonywalnego sg i opisano w sekcji Zaawansowane / macierz funkcji.

Kiedy używać

Użyj warstwy opakowującej, gdy:

  • Masz istniejące narzędzie, agenta lub skrypt, który już wywołuje sg.
  • Chcesz zamiennika, który działa w środowiskach, w których nie możesz zainstalować samego ast-grep.
  • Chcesz korzystać z wygody ast-grep w instalacji obsługującej wyłącznie Composer.

Użyj natywnego vendor/bin/greph -p, gdy:

  • Piszesz nowy kod i nie potrzebujesz formatu ast-grep CLI.
  • Chcesz używać tego samego zestawu flag co w trybie tekstowym (natywny plik wykonywalny łączy oba tryby).

Użycie

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

run to kanoniczne polecenie ast-grep. scan i rewrite to aliasy dostępne wyłącznie w warstwie zgodności, odzwierciedlające typowe użycie. Samo wywołanie uruchamia jednorazowe wyszukiwanie:

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

Wzorce

Składnia wzorców jest identyczna jak w natywnym wyszukiwaniu AST. Pełny opis znajdziesz w sekcji Tryby / wyszukiwanie AST.

Powłoka
./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

Przepisywanie

Warstwa opakowująca obsługuje ten sam proces próbny / interaktywny / zapisu co natywne przepisywanie, z nazwami flag ast-grep:

Powłoka
# 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

Dane wyjściowe JSON

--json emituje dane ast-grep w kształcie JSON. Obsługiwane są trzy style:

Powłoka
./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 Struktura
--json (domyślnie pretty) Pojedyncza, ładnie sformatowana tablica JSON
--json=stream Jedno dopasowanie w każdym wierszu, rozdzielane znakami nowego wiersza JSON
--json=compact Pojedyncza, zwarta tablica JSON

Zweryfikowany zakres

Poniższe flagi zweryfikowano względem nadrzędnego pliku wykonywalnego sg w macierzy funkcji. Gdy flaga ma dwie nazwy (-p i --pattern, --glob i --globs), próba używa jednej z nich, a warstwa opakowująca rozpoznaje obie jako tę samą opcję.

Flagi wzorca

  • --pattern PATTERN (na najwyższym poziomie i wewnątrz run)
  • -p PATTERN (alias)
  • --rewrite TEMPLATE
  • -r TEMPLATE
  • --lang NAME, -l NAME

Flagi dopasowania

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

Flagi przechodzenia po plikach

  • --no-ignore hidden (forma łączona)
  • --glob GLOB, --globs GLOB

Flagi procesów roboczych

  • -j N, --threads N

Akceptowane bez próby

Warstwa opakowująca akceptuje także poniższe flagi, ale nie zostały one jeszcze objęte próbą w macierzy funkcji:

  • Samo --no-ignore lub z wartością inną niż hidden
  • --type NAME, --type-not NAME

Dodatkowe opcje tylko w warstwie opakowującej

Warstwa opakowująca udostępnia kilka pomocniczych opcji, których samo ast-grep nie ma:

  • Aliasy scan i rewrite dla run
  • Flaga --hidden (ast-grep łączy tę opcję z --no-ignore hidden)
  • Alias --dry-run do podglądu przepisywania
  • --interactive do potwierdzania przepisywania

Ograniczenia

Warstwa opakowująca sg dla Greph obejmuje funkcje wyszukiwania strukturalnego i przepisywania używane przez większość narzędzi i agentów. Obecnie nie udostępnia następujących funkcji ast-grep:

  • Pliki reguł YAML (--rule, --config)
  • Skanowanie wielu języków poza PHP
  • Transformatory inne niż wzorcowe (--debug-query, --inspect)
  • Integracja LSP

Jeśli brakuje jakiejś flagi, zgłoś problem i dołącz próbę uruchomioną wobec nadrzędnego sg oraz oczekiwane dane wyjściowe.

Zgodność zachowania

Warstwa opakowująca dąży do zgodności zachowania, a nie zgodności bajtowej. Dane wyjściowe są równoważne semantycznie, ale mogą różnić się w szczegółach kosmetycznych. Próby użyte w macierzy funkcji sprawdzają równoważność pól istotnych dla parsera (ścieżki pliku, numeru wiersza, przechwyconego kodu, przechwyceń i struktury JSON), a nie strumienia bajtów.