Referencia CLI

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

Greph obsahuje štyri spustiteľné súbory. Všetky štyri zdieľajú rovnaký modul; líšia sa tým, aké rozhranie poskytujú.

Binárny súbor	Účel
`greph`	Natívne textové vyhľadávanie, vyhľadávanie AST a prepisovanie AST
`greph-index`	Zahriaty textový index, index faktov AST a vyhľadávanie AST s vyrovnávacou pamäťou
`rg`	Obal kompatibilný so štýlom ripgrep
`sg`	Obal kompatibilný so štýlom ast-grep

Všetky cesty v príkladoch používajú ./vendor/bin/<binary>, ktoré funguje s Greph 0.2.3 alebo novším nainštalovaným ako závislosť. Ak pracujete s klonom repozitára, nahraďte ho hodnotou ./bin/<binary>.

`greph`

Natívne textové vyhľadávanie, vyhľadávanie AST a prepisovanie AST.

Shell

greph [options] pattern [path...]
greph -p pattern [options] [path...]
greph -p pattern -r replacement [options] [path...]

Ak cestu vynecháte, prehľadá sa aktuálny adresár.

Textový režim

Predvolený režim. Vzory sú regulárne výrazy PCRE2, pokiaľ nie je nastavené -F.

Shell

# Regex search
./vendor/bin/greph "function\s+\w+" src

# Fixed-string search
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word with two lines of context
./vendor/bin/greph -F -i -w -C 2 "function" src

Formát výstupu zodpovedá grep -rn:

Text

src/Greph.php:31:final class Greph
src/Greph.php:36:    public static function walk(...

Režim AST

Aktivuje sa pomocou -p. Vzory sa zapisujú ako bežné PHP s metapremennými $VAR a $$$VARIADIC. Úplnú gramatiku vzorov nájdete v časti Režimy / Vyhľadávanie AST.

Shell

./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

Režim prepisovania

Aktivuje sa kombináciou -p a -r. Šablóna náhrady používa rovnaké metapremenné ako vzor vyhľadávania; zachytené uzly sa vkladajú podľa názvu.

Shell

# Preview only
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Možnosti

Prepínač	Význam
`-F`	Vyhľadávanie pevného reťazca (bez regulárnych výrazov)
`-i`	Zhoda bez rozlišovania veľkých a malých písmen
`-w`	Zhoda celého slova
`-v`	Obrátiť podmienku zhody
`-c`	Počítať zhody v jednotlivých súboroch
`-l`	Vypísať iba cesty súborov so zhodou
`-L`	Vypísať iba cesty súborov bez zhody
`-h`	V textovom režime potlačiť predpony s názvami súborov
`-H`	V textovom režime vždy vypisovať predpony s názvami súborov
`-n`	Zobrazovať čísla riadkov (predvolené: zapnuté)
`-A N`	Zobraziť N riadkov za každou zhodou
`-B N`	Zobraziť N riadkov pred každou zhodou
`-C N`	Zobraziť N kontextových riadkov pred každou zhodou aj za ňou
`-m N`	Zastaviť po N zhodách v každom súbore
`-j N`	Použiť N paralelných pracovníkov
`-p PATTERN`	Vzor vyhľadávania AST
`-r TEMPLATE`	Šablóna na prepis AST (vyžaduje `-p`)
`--glob GLOB`	Zahrnúť iba súbory, ktorých cesty zodpovedajú GLOB
`--type NAME`	Zahrnúť alias typu súboru (`php`, `js`, `md`, ...)
`--type-not NAME`	Vylúčiť alias typu súboru
`--lang NAME`	Jazyk AST. Predvolený: `php`
`--json`	Vytvárať výstup JSON
`--no-ignore`	Ignorovať pravidlá `.gitignore` a `.grephignore`
`--hidden`	Zahrnúť skryté súbory
`--dry-run`	Vypísať prepísané zmeny bez zápisu do súborov
`--interactive`	Potvrdiť každý prepísaný súbor
`--help`	Zobraziť stručný návod na použitie

`greph-index`

Zahriaty textový index, index faktov AST a vyhľadávanie AST s vyrovnávacou pamäťou.

Shell

greph-index build [path] [--index-dir DIR]
greph-index refresh [path] [--index-dir DIR]
greph-index search [options] pattern [path...]

greph-index set build [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set refresh [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set stats [manifest] [--manifest FILE] [--mode MODE] [--index NAME...] [--dry-refresh]
greph-index set search [options] pattern [path...]

greph-index ast-index build [path] [--index-dir DIR]
greph-index ast-index refresh [path] [--index-dir DIR]
greph-index ast-index search [options] pattern [path...]

greph-index ast-cache build [path] [--index-dir DIR]
greph-index ast-cache refresh [path] [--index-dir DIR]
greph-index ast-cache search [options] pattern [path...]

Textový index

Shell

# Build (full)
./vendor/bin/greph-index build .

# Build with lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

# Refresh (incremental: added, updated, deleted, unchanged)
./vendor/bin/greph-index refresh .

# Query
./vendor/bin/greph-index search -F "function" .
./vendor/bin/greph-index search -i -w "function" .
./vendor/bin/greph-index search -c "function" .
./vendor/bin/greph-index search --trace-plan -F "function" .
./vendor/bin/greph-index search -F "function" . \
  --index-dir core/.greph-index \
  --index-dir plugins/demo/.greph-index \
  --show-index-origin

Textový index je zahriaté úložisko trigramov a príspevkov identifikátorov. Predvolene sa nachádza v .greph-index/ v koreňovom adresári indexu.

Množiny indexov

Množiny indexov premenia opakované pracovné postupy s viacerými indexmi na pomenovaný manifest:

Shell

./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "function" .
./vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
./vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

Predvolený súbor manifestu je .greph-index-set.json. Každá položka odkazuje na koreňový adresár, režim a profil životného cyklu. set build a set refresh pracujú so zapnutými položkami; set search spracuje vybrané položky a odstráni duplicitné prekrývajúce sa zhody.

Index faktov AST

Shell

./vendor/bin/greph-index ast-index build .
./vendor/bin/greph-index ast-index refresh .
./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src
./vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir core/.greph-ast-index \
  --index-dir plugins/demo/.greph-ast-index \
  --show-index-origin

Index faktov AST získava fakty na úrovni uzlov (volania, vytvorenia inštancií, triedy, metódy) a ukladá ich do úložiska, v ktorom možno vyhľadávať. Vyhľadávania sú O(log n) podľa kľúča faktu a následne sa overujú v zdrojovom kóde. Predvolene sa ukladajú do .greph-ast-index/.

Vyrovnávacia pamäť AST

Shell

./vendor/bin/greph-index ast-cache build .
./vendor/bin/greph-index ast-cache refresh .
./vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src

Vyrovnávacia pamäť AST ukladá parsované stromy na disk, takže pri vyhľadávaní sa celý parser preskočí. Predvolene sa ukladá do .greph-ast-cache/.

Možnosti

Možnosti textového vyhľadávania zodpovedajú množine prepínačov greph (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Ďalšie prepínače:

Prepínač	Význam
`--index-dir DIR`	Použiť nepredvolený adresár zahriateho indexu. Možno opakovať pri vyhľadávaní a štatistikách vo viacerých indexoch.
`--lifecycle PROFILE`	Politika zostavovania: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Prahová hodnota počtu súborov na príležitostné obnovenie
`--auto-refresh-max-bytes N`	Prahová hodnota počtu bajtov na príležitostné obnovenie
`--manifest FILE`	Načítať manifest množiny indexov. Predvolený: `.greph-index-set.json`
`--mode MODE`	Obmedziť operácie s množinami na `text`, `ast-index` alebo `ast-cache`
`--index NAME`	Obmedziť operácie s množinami na pomenovanú položku manifestu. Možno opakovať.
`--show-index-origin`	Predponou výstupu pri zahriatom vyhľadávaní vo viacerých indexoch alebo množinách označiť názov príslušnej položky indexu
`--trace-plan`	Odosielať diagnostiku zahriateho plánovača do `stderr`
`--dry-refresh`	V `stats` oznámiť, čo by zahriaté vyhľadávanie vykonalo, bez zmeny čohokoľvek
`--lang NAME`	Jazyk AST pre vyhľadávanie `ast-index` / `ast-cache`. Predvolený: `php`
`-j N`, `--jobs N`	Pracovníci pre prehľadávanie AST
`-l`, `--files-with-matches`	Vypísať iba cesty súborov so zhodou (režim AST)
`--strict-parse`	Pri chybách parsovania skončiť namiesto preskočenia
`--fallback MODE`	Správanie pri chýbajúcom indexe: `fail` (predvolené) alebo `scan`
`--help`	Zobraziť stručný návod na použitie

`rg`

Obal kompatibilný so štýlom ripgrep. Podporuje najčastejšie používané prepínače ripgrep. Overený rozsah je uvedený v matica funkcií.

Shell

rg [options] pattern [path...]
rg --files [options] [path...]

Príklady

Shell

./vendor/bin/rg -F "function" src
./vendor/bin/rg --json -F "function" src
./vendor/bin/rg --files src
./vendor/bin/rg --files --type php .
./vendor/bin/rg --type-not js -F "function" .

Podporované možnosti

Prepínač	Význam
`-F`, `--fixed-strings`	Vyhľadávanie pevného reťazca
`-i`, `--ignore-case`	Vyhľadávanie bez rozlišovania veľkých a malých písmen
`-w`, `--word-regexp`	Vyhľadávanie celého slova
`-v`, `--invert-match`	Obrátiť podmienku zhody
`-c`, `--count`	Počítať riadky so zhodou
`-l`, `--files-with-matches`	Vypísať súbory so zhodou
`--files-without-match`	Vypísať súbory bez zhody
`-I`, `--no-filename`	Potlačiť predpony s názvami súborov
`-H`, `--with-filename`	Vždy vypisovať predpony s názvami súborov
`-n`, `--line-number`	Zobrazovať čísla riadkov
`-A N`, `--after-context N`	Zobraziť N riadkov za každou zhodou
`-B N`, `--before-context N`	Zobraziť N riadkov pred každou zhodou
`-C N`, `--context N`	Zobraziť N riadkov pred každou zhodou aj za ňou
`-m N`, `--max-count N`	Zastaviť po N zhodách v každom súbore
`-j N`, `--threads N`	Použiť N paralelných pracovníkov
`-e P`, `--regexp P`	Vzor vyhľadávania
`-L`, `--follow`	Nasledovať symbolické odkazy
`--glob GLOB`	Zahrnúť iba súbory, ktorých cesty zodpovedajú GLOB
`--type NAME`	Zahrnúť typ súboru
`--type-not NAME`	Vylúčiť typ súboru
`--json`	Vytvárať udalosti ripgrep v štýle JSON
`--no-ignore`	Ignorovať pravidlá `.gitignore` a `.grephignore`
`--hidden`	Zahrnúť skryté súbory
`--files`	Vypísať kandidátne súbory namiesto vyhľadávania
`--help`	Zobraziť stručný návod na použitie

`sg`

Obal kompatibilný so štýlom ast-grep. Podporuje najčastejšie používané prepínače ast-grep. Overený rozsah je uvedený v matica funkcií.

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. Funguje aj samotné zavolanie (sg --pattern ... .) ako jednorazové vyhľadávanie.

Príklady

Shell

./vendor/bin/sg run --pattern 'array($$$ITEMS)' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src/App.php
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src/App.php
./vendor/bin/sg scan -p 'array($$$ITEMS)' src/App.php
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src/App.php

Podporované možnosti

Prepínač	Význam
`-p`, `--pattern PATTERN`	Vzor AST
`-r`, `--rewrite TEMPLATE`	Šablóna na prepisovanie
`-l`, `--lang NAME`	Jazyk AST. Predvolený: `php`
`-j`, `--threads N`	Použiť N paralelných pracovníkov
`-i`, `--interactive`	Potvrdiť každý prepis
`-U`, `--update-all`	Použiť prepisy bez potvrdenia
`--files-with-matches`	Vypísať iba cesty súborov so zhodami
`--json[=STYLE]`	Vytvárať výstup JSON. ŠTÝL = `pretty`, `stream` alebo `compact`
`--no-ignore [MODE]`	Ignorovať pravidlá na ignorovanie súborov v repozitári
`--hidden`	Zahrnúť skryté súbory
`--glob GLOB`, `--globs GLOB`	Zahrnúť iba súbory, ktorých cesty zodpovedajú GLOB
`--type NAME`	Zahrnúť typ súboru
`--type-not NAME`	Vylúčiť typ súboru
`--dry-run`	Zobraziť náhľad prepisov bez zápisu do súborov
`--help`	Zobraziť stručný návod na použitie

Návratové kódy

Greph dodržiava konvencie grep / ripgrep:

Kód	Význam
`0`	Našla sa aspoň jedna zhoda (alebo sa v prípade prepisovania zmenil aspoň jeden súbor)
`1`	Nenašli sa žiadne zhody
`2`	Chyba pri používaní alebo zlyhanie za behu (nesprávne argumenty, chýbajúci index, chyba parsovania v režime `--strict-parse`)