CLI uzziņu rokasgrāmata

Skatīt kā Markdown Rediģēt vietnē GitHub Dokumentācija vietnē d105217

Greph ietver četrus izpildāmos failus. Visiem četriem ir viens un tas pats dzinis; atšķiras tikai to piedāvātā saskarne.

Binārais fails	Mērķis
`greph`	Vietējā teksta meklēšana, AST meklēšana un AST pārrakstīšana
`greph-index`	Uzsildīts teksta indekss, AST faktu indekss un kešota AST meklēšana
`rg`	Ar ripgrep saderīgs iesaiņotājs
`sg`	Ar ast-grep saderīgs iesaiņotājs

Visos piemēros izmantoti ceļi ./vendor/bin/<binary> formātā. Tie darbojas, ja Greph 0.2.3 ir instalēts kā atkarība vai vēlāk tiek instalēts. Ja strādājat ar repozitorija klonu, aizstājiet to ar ./bin/<binary>.

`greph`

Vietējā teksta meklēšana, AST meklēšana un AST pārrakstīšana.

Apvalks

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

Ja ceļš nav norādīts, meklēšana tiek veikta pašreizējā mapē.

Teksta režīms

Noklusējuma režīms. Raksti ir PCRE2 regulārās izteiksmes, ja vien nav iestatīts -F.

Apvalks

# 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

Izvades formāts atbilst grep -rn:

Text

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

AST režīms

Aktivizē ar -p. Raksti tiek veidoti kā parasts PHP, izmantojot metavariablos $VAR un $$$VARIADIC. Pilnu raksta gramatiku skatiet sadaļā AST režīmi / AST meklēšana.

Apvalks

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

Pārrakstīšanas režīms

Aktivizē, apvienojot -p ar -r. Aizvietošanas veidne izmanto tos pašus metavariablos kā meklēšanas raksts; uztvertie mezgli tiek ievietoti pēc nosaukuma.

Apvalks

# 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

Opcijas

Karodziņš	Nozīme
`-F`	Meklēšana pēc precīzas virknes (bez regex)
`-i`	Meklēšana, neņemot vērā reģistru
`-w`	Meklēšana pēc pilna vārda
`-v`	Apgriezt atbilstības nosacījumu
`-c`	Saskaitīt atbilstības katrā failā
`-l`	Norādīt tikai atbilstošo failu ceļus
`-L`	Norādīt tikai neatbilstošo failu ceļus
`-h`	Teksta režīmā nerādīt failu nosaukumu prefiksus
`-H`	Teksta režīmā vienmēr rādīt failu nosaukumu prefiksus
`-n`	Rādīt rindu numurus (pēc noklusējuma ieslēgts)
`-A N`	Rādīt N rindas pēc katras atbilstības
`-B N`	Rādīt N rindas pirms katras atbilstības
`-C N`	Rādīt N konteksta rindas pirms un pēc katras atbilstības
`-m N`	Pārtraukt pēc N atbilstībām katrā failā
`-j N`	Izmantot N paralēlos darbplūsmu izpildītājus
`-p PATTERN`	AST meklēšanas raksts
`-r TEMPLATE`	AST pārrakstīšanas veidne (nepieciešams `-p`)
`--glob GLOB`	Iekļaut tikai failus, kuru ceļi atbilst GLOB
`--type NAME`	Iekļaut faila tipa aizstājvārdu (`php`, `js`, `md`, ...)
`--type-not NAME`	Izslēgt faila tipa aizstājvārdu
`--lang NAME`	AST valoda. Noklusējums: `php`
`--json`	Izvadīt JSON formāta izvadi
`--no-ignore`	Ignorēt `.gitignore` un `.grephignore` noteikumus
`--hidden`	Iekļaut slēptos failus
`--dry-run`	Parādīt pārrakstījumus, nemainot failus
`--interactive`	Apstiprināt katru failu, kurā veikta pārrakstīšana
`--help`	Rādīt lietošanas informāciju iekļautajā saskarnē

`greph-index`

Uzsildīts teksta indekss, AST faktu indekss un kešota AST meklēšana.

Apvalks

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

Teksta indekss

Apvalks

# 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

Teksta indekss ir uzsildīta trigrammu un identifikatoru ierakstu krātuve. Pēc noklusējuma tā atrodas mapē .greph-index/ indeksētajā saknes mapē.

Indeksu kopas

Indeksu kopas ļauj atkārtotas vairāku indeksu darbplūsmas aprakstīt nosauktā manifestā:

Apvalks

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

Noklusējuma manifesta fails ir .greph-index-set.json. Katrs ieraksts norāda saknes mapi, režīmu un dzīves cikla profilu. set build un set refresh darbojas ar iespējotajiem ierakstiem; set search vienlaikus apstrādā atlasītos ierakstus un izslēdz dublējošās atbilstības.

AST faktu indekss

Apvalks

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

AST faktu indekss izgūst mezglu līmeņa faktus (izsaukumus, instancēšanas, klases, metodes) un saglabā tos vaicājumiem pieejamā krātuvē. Vispirms tiek veikta O(log n) meklēšana pēc fakta atslēgas, pēc tam rezultāti tiek pārbaudīti, salīdzinot tos ar avotu. Pēc noklusējuma dati tiek glabāti mapē .greph-ast-index/.

AST kešatmiņa

Apvalks

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

AST kešatmiņa saglabā diskā parsētos kokus, lai meklēšanas laikā varētu pilnībā izlaist parsētāju. Pēc noklusējuma dati tiek glabāti mapē .greph-ast-cache/.

Opcijas

Teksta meklēšanas opcijas atbilst greph karodziņu kopai (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Papildu karodziņi:

Karodziņš	Nozīme
`--index-dir DIR`	Izmantot uzsildītu indeksu mapē, kas nav noklusējuma mape. Atkārtojams vairāku indeksu meklēšanai un statistikai.
`--lifecycle PROFILE`	Veidošanas politika: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Failu skaita slieksnis neregulārai atsvaidzināšanai
`--auto-refresh-max-bytes N`	Baitu slieksnis neregulārai atsvaidzināšanai
`--manifest FILE`	Ielādēt indeksu kopas manifestu. Noklusējums: `.greph-index-set.json`
`--mode MODE`	Ierobežot kopas darbības līdz `text`, `ast-index` vai `ast-cache`
`--index NAME`	Ierobežot kopas darbības līdz nosauktam manifesta ierakstam. Atkārtojams.
`--show-index-origin`	Vairāku uzsildītu indeksu vai kopas izvadei pievienot prefiksu ar atbilstošā indeksa ieraksta nosaukumu
`--trace-plan`	Izvadīt uzsildītā plānotāja diagnostikas informāciju uz `stderr`
`--dry-refresh`	Ar `stats` ziņot, ko veiktu uzsildīta meklēšana, neko nemainot
`--lang NAME`	AST valoda `ast-index` / `ast-cache` meklēšanai. Noklusējums: `php`
`-j N`, `--jobs N`	Darbplūsmu izpildītāji AST skenēšanai
`-l`, `--files-with-matches`	Norādīt tikai atbilstošo failu ceļus (AST režīms)
`--strict-parse`	Kļūdas gadījumā neizlaist failus ar parsēšanas kļūdām
`--fallback MODE`	Rīcība, ja trūkst indeksa: `fail` (noklusējums) vai `scan`
`--help`	Rādīt lietošanas informāciju iekļautajā saskarnē

`rg`

ripgrep tipa saderības iesaiņotājs. Atbalsta visbiežāk lietotos ripgrep karodziņus. Pārbaudītā funkcionalitāte publicēta sadaļā funkciju matrica.

Apvalks

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

Piemēri

Apvalks

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

Atbalstītās opcijas

Karodziņš	Nozīme
`-F`, `--fixed-strings`	Meklēšana pēc precīzas virknes
`-i`, `--ignore-case`	Meklēšana, neņemot vērā reģistru
`-w`, `--word-regexp`	Meklēšana pēc pilna vārda
`-v`, `--invert-match`	Apgriezt atbilstības nosacījumu
`-c`, `--count`	Saskaitīt atbilstošās rindas
`-l`, `--files-with-matches`	Norādīt atbilstošos failus
`--files-without-match`	Norādīt neatbilstošos failus
`-I`, `--no-filename`	Nerādīt failu nosaukumu prefiksus
`-H`, `--with-filename`	Vienmēr rādīt failu nosaukumu prefiksus
`-n`, `--line-number`	Rādīt rindu numurus
`-A N`, `--after-context N`	Rādīt N rindas pēc katras atbilstības
`-B N`, `--before-context N`	Rādīt N rindas pirms katras atbilstības
`-C N`, `--context N`	Rādīt N rindas pirms un pēc katras atbilstības
`-m N`, `--max-count N`	Pārtraukt pēc N atbilstībām katrā failā
`-j N`, `--threads N`	Izmantot N paralēlos darbplūsmu izpildītājus
`-e P`, `--regexp P`	Meklēšanas raksts
`-L`, `--follow`	Sekot simboliskajām saitēm
`--glob GLOB`	Iekļaut tikai failus, kuru ceļi atbilst GLOB
`--type NAME`	Iekļaut faila tipu
`--type-not NAME`	Izslēgt faila tipu
`--json`	Izvadīt ripgrep tipa JSON notikumus
`--no-ignore`	Ignorēt `.gitignore` un `.grephignore` noteikumus
`--hidden`	Iekļaut slēptos failus
`--files`	Meklēšanas vietā uzskaitīt kandidātfailus
`--help`	Rādīt lietošanas informāciju iekļautajā saskarnē

`sg`

ast-grep tipa saderības iesaiņotājs. Atbalsta visbiežāk lietotos ast-grep karodziņus. Pārbaudītā funkcionalitāte publicēta sadaļā funkciju matrica.

Apvalks

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

run ir kanoniskā ast-grep komanda. scan un rewrite ir tikai iesaiņotāja aizstājvārdi, kas atbilst ierastajam lietojumam. Var izmantot arī vienkāršu izsaukumu (sg --pattern ... .), lai veiktu vienreizēju meklēšanu.

Piemēri

Apvalks

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

Atbalstītās opcijas

Karodziņš	Nozīme
`-p`, `--pattern PATTERN`	AST raksts
`-r`, `--rewrite TEMPLATE`	Pārrakstīšanas veidne
`-l`, `--lang NAME`	AST valoda. Noklusējums: `php`
`-j`, `--threads N`	Izmantot N paralēlos darbplūsmu izpildītājus
`-i`, `--interactive`	Apstiprināt katru pārrakstīšanu
`-U`, `--update-all`	Veikt pārrakstīšanu bez apstiprinājuma
`--files-with-matches`	Norādīt tikai to failu ceļus, kuros ir atbilstības
`--json[=STYLE]`	Izvadīt JSON izvadi. STILS = `pretty`, `stream` vai `compact`
`--no-ignore [MODE]`	Ignorēt repozitorija ignorēšanas noteikumus
`--hidden`	Iekļaut slēptos failus
`--glob GLOB`, `--globs GLOB`	Iekļaut tikai failus, kuru ceļi atbilst GLOB
`--type NAME`	Iekļaut faila tipu
`--type-not NAME`	Izslēgt faila tipu
`--dry-run`	Priekšskatīt pārrakstījumus, nemainot failus
`--help`	Rādīt lietošanas informāciju iekļautajā saskarnē

Izejas kodi

Greph ievēro grep / ripgrep konvencijas:

Kods	Nozīme
`0`	Atrasta vismaz viena atbilstība (vai pārrakstīšanas gadījumā mainīts vismaz viens fails)
`1`	Nav atrasta neviena atbilstība
`2`	Lietošanas kļūda vai izpildlaika kļūme (nepareizi argumenti, trūkst indeksa, parsēšanas kļūda režīmā `--strict-parse`)