Referință pentru CLI

Vizualizați ca Markdown Editați pe GitHub Documentație la d105217

Greph include patru executabile. Toate patru folosesc același motor; diferă prin interfața pe care o expun.

Binar	Scop
`greph`	Căutare nativă în text, căutare AST și rescriere AST
`greph-index`	Index de text încălzit, index de fapte AST și căutare AST memorată în cache
`rg`	Wrapper de compatibilitate în stilul ripgrep
`sg`	Wrapper de compatibilitate în stilul ast-grep

Toate căile din exemple folosesc ./vendor/bin/<binary>, care funcționează cu Greph 0.2.3 sau cu o versiune ulterioară instalată ca dependență. Înlocuiți cu ./bin/<binary> dacă lucrați dintr-o clonă a depozitului.

`greph`

Căutare nativă în text, căutare AST și rescriere AST.

Shell

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

Dacă omiteți o cale, se caută în directorul curent.

Modul text

Modul implicit. Modelele sunt expresii regulate PCRE2, cu excepția cazului în care este activat -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

Formatul de ieșire corespunde celui din grep -rn:

Text

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

Modul AST

Se activează cu -p. Modelele sunt scrise ca PHP obișnuite, cu metacaracterele $VAR și $$$VARIADIC. Consultați Moduri / Căutare AST pentru gramatica completă a modelelor.

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

Modul de rescriere

Se activează combinând -p cu -r. Șablonul de înlocuire folosește aceleași metacaractere ca modelul de căutare; nodurile capturate sunt inserate după nume.

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

Opțiuni

Opțiune	Semnificație
`-F`	Căutare după șir fix (fără expresii regulate)
`-i`	Potrivire fără diferențiere între majuscule și minuscule
`-w`	Potrivire de cuvinte întregi
`-v`	Inversează potrivirea
`-c`	Numără potrivirile din fiecare fișier
`-l`	Listează numai căile fișierelor care se potrivesc
`-L`	Listează numai căile fișierelor care nu se potrivesc
`-h`	Ascunde prefixele cu numele fișierelor în modul text
`-H`	Afișează întotdeauna prefixele cu numele fișierelor în modul text
`-n`	Afișează numerele liniilor (implicit: activat)
`-A N`	Afișează N linii după fiecare potrivire
`-B N`	Afișează N linii înainte de fiecare potrivire
`-C N`	Afișează N linii de context înainte și după fiecare potrivire
`-m N`	Oprește după N potriviri pentru fiecare fișier
`-j N`	Folosește N lucrători paraleli
`-p PATTERN`	Model de căutare AST
`-r TEMPLATE`	Șablon de rescriere AST (necesită `-p`)
`--glob GLOB`	Include numai fișiere ale căror căi corespund cu GLOB
`--type NAME`	Include un alias de tip de fișier (`php`, `js`, `md`, ...)
`--type-not NAME`	Exclude un alias de tip de fișier
`--lang NAME`	Limbaj AST. Implicit: `php`
`--json`	Emite ieșire JSON
`--no-ignore`	Ignoră regulile `.gitignore` și `.grephignore`
`--hidden`	Include fișiere ascunse
`--dry-run`	Afișează rescrierile fără a scrie fișierele
`--interactive`	Confirmă fiecare fișier rescris
`--help`	Afișează instrucțiunile de utilizare inline

`greph-index`

Index de text încălzit, index de fapte AST și căutare AST memorată în cache.

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...]

Indexul de text

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

Indexul de text este un depozit încălzit de trigrame și postări de identificatori. În mod implicit, se află în .greph-index/ din rădăcina indexată.

Seturi de indexuri

Seturile de indexuri transformă fluxurile de lucru repetate cu mai multe indexuri într-un manifest cu nume:

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)' .

Fișierul manifest implicit este .greph-index-set.json. Fiecare intrare indică o rădăcină, un mod și un profil al ciclului de viață. set build și set refresh operează asupra intrărilor activate; set search distribuie căutarea între intrările selectate și elimină potrivirile suprapuse.

Indexul de fapte 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

Indexul de fapte AST extrage fapte la nivel de nod (apeluri, instanțieri, clase, metode) într-un depozit interogabil. Căutările folosesc O(log n) pentru cheia faptului, apoi sunt verificate în raport cu sursa. În mod implicit, este stocat în .greph-ast-index/.

Cache-ul 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

Cache-ul AST stochează arborii analizați pe disc, astfel încât căutările să sară complet peste analizator. În mod implicit, este stocat în .greph-ast-cache/.

Opțiuni

Opțiunile de căutare în text corespund setului de opțiuni greph (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Opțiuni suplimentare:

Opțiune	Semnificație
`--index-dir DIR`	Folosește un director de index încălzit diferit de cel implicit. Poate fi repetată pentru căutare și statistici cu mai multe indexuri.
`--lifecycle PROFILE`	Politică de construire: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Prag pentru reîmprospătarea oportunistă a fișierelor
`--auto-refresh-max-bytes N`	Prag pentru reîmprospătarea oportunistă a octeților
`--manifest FILE`	Încarcă un manifest de set de indexuri. Implicit: `.greph-index-set.json`
`--mode MODE`	Limitează operațiile setului la `text`, `ast-index` sau `ast-cache`
`--index NAME`	Limitează operațiile setului la o intrare de manifest cu nume. Poate fi repetată.
`--show-index-origin`	Prefixează ieșirea încălzită cu mai multe indexuri sau cu seturi cu numele intrării de index corespunzătoare
`--trace-plan`	Emite diagnosticele planificatorului încălzit în `stderr`
`--dry-refresh`	În `stats`, raportează ce ar face o căutare încălzită fără a modifica nimic
`--lang NAME`	Limbaj AST pentru căutările `ast-index` / `ast-cache`. Implicit: `php`
`-j N`, `--jobs N`	Lucrători pentru scanările AST
`-l`, `--files-with-matches`	Listează numai căile fișierelor care se potrivesc (modul AST)
`--strict-parse`	Eșuează la erorile de analiză în loc să le omită
`--fallback MODE`	Comportament când lipsește indexul: `fail` (implicit) sau `scan`
`--help`	Afișează instrucțiunile de utilizare inline

`rg`

Wrapper de compatibilitate în stilul ripgrep. Acceptă cele mai utilizate opțiuni ripgrep. Suprafața verificată este publicată în matricea de funcționalități.

Shell

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

Exemple

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" .

Opțiuni acceptate

Opțiune	Semnificație
`-F`, `--fixed-strings`	Căutare după șir fix
`-i`, `--ignore-case`	Căutare fără diferențiere între majuscule și minuscule
`-w`, `--word-regexp`	Căutare după cuvinte întregi
`-v`, `--invert-match`	Inversează potrivirile
`-c`, `--count`	Numără liniile care se potrivesc
`-l`, `--files-with-matches`	Listează fișierele care se potrivesc
`--files-without-match`	Listează fișierele care nu se potrivesc
`-I`, `--no-filename`	Ascunde prefixele cu numele fișierelor
`-H`, `--with-filename`	Afișează întotdeauna prefixele cu numele fișierelor
`-n`, `--line-number`	Afișează numerele liniilor
`-A N`, `--after-context N`	Afișează N linii după fiecare potrivire
`-B N`, `--before-context N`	Afișează N linii înainte de fiecare potrivire
`-C N`, `--context N`	Afișează N linii înainte și după fiecare potrivire
`-m N`, `--max-count N`	Oprește după N potriviri pentru fiecare fișier
`-j N`, `--threads N`	Folosește N lucrători paraleli
`-e P`, `--regexp P`	Model de căutare
`-L`, `--follow`	Urmează legăturile simbolice
`--glob GLOB`	Include numai fișiere ale căror căi corespund cu GLOB
`--type NAME`	Include un tip de fișier
`--type-not NAME`	Exclude un tip de fișier
`--json`	Emite evenimente ripgrep în stilul JSON
`--no-ignore`	Ignoră regulile `.gitignore` și `.grephignore`
`--hidden`	Include fișiere ascunse
`--files`	Listează fișierele candidate în loc să caute
`--help`	Afișează instrucțiunile de utilizare inline

`sg`

Wrapper de compatibilitate în stilul ast-grep. Acceptă cele mai utilizate opțiuni ast-grep. Suprafața verificată este publicată în matricea de funcționalități.

Shell

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

run este verbul canonic ast-grep. scan și rewrite sunt aliasuri disponibile doar în wrapper, care reflectă utilizarea obișnuită. Funcționează și o invocare fără argumente (sg --pattern ... .), pentru o căutare unică.

Exemple

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

Opțiuni acceptate

Opțiune	Semnificație
`-p`, `--pattern PATTERN`	Model AST
`-r`, `--rewrite TEMPLATE`	Șablon de rescriere
`-l`, `--lang NAME`	Limbaj AST. Implicit: `php`
`-j`, `--threads N`	Folosește N lucrători paraleli
`-i`, `--interactive`	Confirmă fiecare rescriere
`-U`, `--update-all`	Aplică rescrierile fără confirmare
`--files-with-matches`	Afișează numai căile fișierelor cu potriviri
`--json[=STYLE]`	Emite ieșire JSON. STYLE = `pretty`, `stream` sau `compact`
`--no-ignore [MODE]`	Ignoră regulile de ignorare ale depozitului
`--hidden`	Include fișiere ascunse
`--glob GLOB`, `--globs GLOB`	Include numai fișiere ale căror căi corespund cu GLOB
`--type NAME`	Include un tip de fișier
`--type-not NAME`	Exclude un tip de fișier
`--dry-run`	Previzualizează rescrierile fără a scrie fișierele
`--help`	Afișează instrucțiunile de utilizare inline

Coduri de ieșire

Greph respectă convențiile grep / ripgrep:

Cod	Semnificație
`0`	A fost găsită cel puțin o potrivire (sau, în cazul rescrierilor, s-a modificat cel puțin un fișier)
`1`	Nu s-au găsit potriviri
`2`	Eroare de utilizare sau de execuție (argumente nevalide, index lipsă, eroare de analiză în modul `--strict-parse`)