Darbo pradžia

Peržiūrėti kaip Markdown Redaguoti per GitHub Dokumentacija: d105217

Diegimas

Įdiekite Greph naudodami Composer:

Shell

composer require greph/greph

Taip vendor/bin/ įdiegiama biblioteka ir keturi vykdomieji failai:

greph: vietinė tekstinė paieška, AST paieška ir AST perrašymas
greph-index: įšildytas tekstinis indeksas, AST faktų indeksas ir spartinančioji AST paieška
rg: ripgrep stiliaus suderinamumo apvalkalas
sg: ast-grep stiliaus suderinamumo apvalkalas

Šie vykdomieji failai veikia iš jūsų projekto vendor/bin/, nes Greph 0.2.3. Ankstesnės versijos Composer įkėliklį rasdavo tik Greph saugyklos klone, todėl reikalinga bent ši versija:

Shell

composer require greph/greph:^0.2.3

Reikalavimai

PHP 8.2+ readonly klasėms, enum tipams, pirmos klasės iškviečiamų funkcijų sintaksei ir konstruktoriaus savybių propagavimui
ext-json JSON išvestims ir diske saugomiems indeksų duomenims
ext-ctype šablonų ir parinkčių analizei
ext-tokenizer PHP-Parser ir AST išankstiniams filtrams
ext-zlib podėlyje saugomai AST saugyklai (greph-index ast-cache)
nikic/php-parser (automatiškai įdiegiama kaip Composer priklausomybė)

ext-json, ext-ctype ir ext-tokenizer įjungti beveik kiekvienoje PHP versijoje. Šiuo metu composer.json deklaruoja tik ext-json (#5), todėl Composer neįspėja, jei trūksta kurio nors kito plėtinio.

Pasirenkama:

ext-pcntl lygiagrečioms paieškoms. Jei jo nėra, Greph sklandžiai pereina prie vykdymo viename procese.
Išoriniai rg, grep ir sg dvejetainiai failai palyginimams su etalonais. Vykdymo metu jų niekada nereikia.

Paieška, perrašymas ir indeksavimas niekada nekviečia proc_open() ar shell_exec(); tik lygiagrečios paieškos sukuria atskirus procesus, o be pcntl_fork() jos grįžta prie vieno proceso. Apie prieglobos serverius, kuriuose išjungti proc_open(), shell_exec() arba pcntl_fork(), žr. Procesais apribotos prieglobos aplinkos.

Pirmoji teksto paieška

Numatytasis Greph režimas – su grep suderinama teksto paieška:

Shell

vendor/bin/greph -F "function" src

Išvestis pateikiama kanoniniu file:line:content formatu, kurio tikisi grep, ripgrep ir dauguma redaktorių integracijų.

Text

src/Greph.php:41:    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList
src/Greph.php:50:    public static function searchText(string $pattern, string|array $paths, ?TextSearchOptions $options = null): array
src/Greph.php:81:    public static function buildTextIndex(

Pridėkite -i, kad paieška neskirtų didžiųjų ir mažųjų raidžių, -w, kad būtų ieškoma ištisų žodžių, -c, kad būtų rodomi atitikmenų skaičiai, -l, kad būtų ieškoma tik failų keliuose, -C 2, kad būtų rodomos dvi konteksto eilutės ir pan. Visas sąrašas pateiktas CLI nuorodoje.

Pirmoji AST paieška

Norėdami įjungti struktūrinę paiešką, perduokite -p ir PHP formos šabloną:

Shell

vendor/bin/greph -p 'new $CLASS()' src

$CLASS yra metakintamasis, atitinkantis bet kurį klasės pavadinimą. Šablonas new $CLASS() atitinka kiekvieną new išraišką be argumentų, nepriklausomai nuo klasės, formatavimo ar komentarų. Naudokite new $CLASS($$$ARGS), jei norite atitikti iškvietimus su bet kokiais argumentais.

Kiekviena AST atitiktis išvedama kaip failas, pradžios eilutė ir atitinkantis kodas:

Text

src/Greph.php:43:new FileWalker()
src/Greph.php:52:new TextSearchOptions()
src/Greph.php:54:new TextSearcher()

Kiti naudingi šablonai:

Shell

# Any method call with any arguments
vendor/bin/greph -p '$obj->$method($$$ARGS)' src

# Any function declaration with a void return type
vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

# Old-style array calls
vendor/bin/greph -p 'array($$$ITEMS)' src

Visą šablonų sintaksę rasite skiltyje Režimai / AST paieška.

Pirmasis perrašymas

Pridėkite -r, kad AST paiešką paverstumėte perrašymu:

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

Už atitikties ribų perrašymai išsaugo formatavimą: pakeičiamas tik atitinkantis mazgas, o aplinkiniai tarpai, įtraukos ir komentarai lieka nepakeisti. Pats atitinkantis mazgas iš naujo sugeneruojamas pagal šabloną, todėl jo išdėstymas normalizuojamas, o jame esantis komentaras gali būti prarastas. Daugiau informacijos rasite skiltyje Režimai / Perrašymas.

PHP API

Statinė Greph\Greph fasadinė sąsaja pateikia tas pačias operacijas kaip ir CLI:

PHP

use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true, caseInsensitive: true),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

$matches = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}

Visas funkcijas apima API.

Indeksuota paieška

Pasikartojančios užduotys greičiau atliekamos naudojant įkeltus indeksus. Sukurkite indeksą vieną kartą, tada vykdykite daug užklausų:

Shell

# Text index
vendor/bin/greph-index build .
vendor/bin/greph-index search -F "function" .

# AST fact index
vendor/bin/greph-index ast-index build .
vendor/bin/greph-index ast-index search 'new $CLASS()' src

# Cached parsed-tree index
vendor/bin/greph-index ast-cache build .
vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src

Pagal numatytuosius nustatymus indeksai projekto šakiniame kataloge saugomi .greph-index, .greph-ast-index ir .greph-ast-cache.

Aktyviai kintančiam kodui pasirinkite gyvavimo ciklo profilį, užuot visiems įkeltiems indeksams taikę tą patį režimą:

Shell

vendor/bin/greph-index build . --lifecycle static
vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576
vendor/bin/greph-index stats . --dry-refresh

Dažniausiai naudojamas šablonas:

stabilų pagrindą laikykite kaip static
aktyviai kintančius perdengimus laikykite kaip opportunistic-refresh
pasenusią būseną tikrinkite naudodami stats --dry-refresh

Paieška keliuose įkeltuose indeksuose

Viena komanda galite ieškoti keliuose įkeltuose indeksuose:

Shell

vendor/bin/greph-index search -F "apply_filters" . \
  --index-dir wordpress/.greph-index \
  --index-dir wp-content/plugins/my-plugin/.greph-index \
  --show-index-origin

vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir wordpress/.greph-ast-index \
  --index-dir wp-content/plugins/my-plugin/.greph-ast-index \
  --show-index-origin

Pavadinti indeksų rinkiniai

Jei tai darote pakartotinai, aprašykite išdėstymą faile .greph-index-set.json ir vietoj pakartotinai nurodomų vėliavėlių naudokite rinkinio subkomandas:

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 "apply_filters" .
vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

Planavimo pėdsakas

Norėdami matyti, kaip įkelta paieška susiaurina kandidatų ratą, pridėkite --trace-plan:

Shell

vendor/bin/greph-index search --trace-plan -F "function" .
vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' .

Visą įkeltų indeksų darbo eigą rasite skiltyse Indeksuota / Tekstas ir Indeksuota / AST.

Suderinamumo apvalkalai

Jei jūsų įrankiai ar agentai jau naudoja ripgrep arba ast-grep, tiesiog įtraukite apvalkalus:

Shell

vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php

Abu apvalkalai naudoja tą patį variklį, o jų suderinamumas patikrintas su pirminiais dvejetainiais failais. Patikrintos funkcijos aprašytos skiltyse Suderinamumas / rg ir Suderinamumas / sg, taip pat pateiktos sugeneruotoje funkcijų matricoje.

Konfigūracija

Greph atpažįsta dvi diske naudojamas konvencijas:

.gitignore: pagal numatytuosius nustatymus paisoma. Norėdami išjungti, perduokite --no-ignore.
.grephignore: ta pati sintaksė kaip .gitignore, taikoma papildomai. Naudinga įrankiui būdingoms išimtims, kurių nenorite įtraukti į versijų kontrolę.

Pasirinktame šakniniame kataloge numatytieji indeksų katalogai yra .greph-index, .greph-ast-index ir .greph-ast-cache. Bet kurioje greph-index subkomandoje nurodykite kitą katalogą naudodami --index-dir arba naudokite .greph-index-set.json, jei reikia pakartotinai naudojamų kelių indeksų išdėstymų.