Začíname

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

Inštalácia

Nainštalujte Greph pomocou Composer:

Shell

composer require greph/greph

Tým sa nainštaluje knižnica spolu so štyrmi spustiteľnými súbormi v vendor/bin/:

greph: natívne vyhľadávanie v texte, vyhľadávanie v AST a prepisovanie AST
greph-index: zahriaty textový index, index faktov AST a vyhľadávanie v AST s vyrovnávacou pamäťou
rg: obal kompatibilný so štýlom ripgrep
sg: obal kompatibilný so štýlom ast-grep

Tieto spustiteľné súbory fungujú z adresára projektu vendor/bin/, pretože Greph 0.2.3. Staršie vydania našli zavádzač autoloadu Composer iba v klone repozitára Greph, preto požadujte aspoň túto verziu:

Shell

composer require greph/greph:^0.2.3

Požiadavky

PHP 8.2+ pre triedy iba na čítanie, enumy, syntax prvotriednych volateľných objektov a povýšenie konštruktorových parametrov
ext-json pre výstup JSON a dáta indexu na disku
ext-ctype na parsovanie vzorov a možností
ext-tokenizer pre PHP-Parser a predbežné filtre AST
ext-zlib pre úložisko AST s vyrovnávacou pamäťou (greph-index ast-cache)
nikic/php-parser (inštaluje sa automaticky ako závislosť Composer)

ext-json, ext-ctype a ext-tokenizer sú povolené takmer v každom zostavení PHP. composer.json momentálne deklaruje iba ext-json (#5), takže Composer nevaruje, ak niektoré z ostatných chýba.

Voliteľné:

ext-pcntl na paralelné skenovanie. Greph pri jeho absencii bez problémov prejde na vykonávanie v jednom procese.
Externé binárne súbory rg, grep a sg na porovnávanie benchmarkov. Počas behu sa nikdy nevyžadujú.

Vyhľadávanie, prepisovanie a indexovanie nikdy nevolajú proc_open() ani shell_exec(); iba paralelné skenovanie vytvára procesy a bez pcntl_fork() prejde na jeden proces. Ďalšie informácie o hostiteľoch, ktoré zakazujú proc_open(), shell_exec() alebo pcntl_fork(), nájdete v časti Hostitelia s obmedzenými procesmi.

Prvé vyhľadávanie v texte

Predvolený režim nástroja Greph je textové vyhľadávanie kompatibilné s grep:

Shell

vendor/bin/greph -F "function" src

Výstup používa kanonický formát file:line:content, ktorý očakávajú grep, ripgrep a väčšina integrácií editorov.

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(

Pridajte -i pre vyhľadávanie bez rozlišovania veľkosti písmen, -w na vyhľadávanie celých slov, -c na počty, -l iba pre cesty k súborom, -C 2 pre dva riadky kontextu a podobne. Úplný zoznam nájdete v referenčnej príručkeCLI.

Prvé vyhľadávanie v AST

Ak chcete prejsť na štrukturálne vyhľadávanie, zadajte -p a vzor v tvare PHP:

Shell

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

$CLASS je metavariabilná premenná, ktorá zachytáva ľubovoľný názov triedy. Vzor new $CLASS() zodpovedá každému výrazu new bez argumentov bez ohľadu na triedu, formátovanie či komentáre. Pomocou new $CLASS($$$ARGS) môžete vyhľadávať volania s ľubovoľnými argumentmi.

Každá zhoda v AST sa vypíše ako súbor, začiatočný riadok a zodpovedajúci kód:

Text

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

Ďalšie užitočné vzory:

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

Úplnú syntax vzorov nájdete v časti Režimy / Vyhľadávanie v AST.

Prvé prepisovanie

Pridaním -r zmeníte vyhľadávanie v AST na prepisovanie:

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

Pri prepisovaní sa zachováva formátovanie mimo zhody: nahradí sa iba zodpovedajúci uzol, okolité medzery, odsadenie a komentáre zostanú zachované. Samotný zodpovedajúci uzol sa vytvorí nanovo zo šablóny, takže jeho rozloženie sa normalizuje a komentár v ňom sa môže stratiť. Podrobnosti nájdete v časti Režimy / Prepisovanie.

PHP API

Statická fasáda Greph\Greph poskytuje rovnaké operácie ako 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";
}

Úplný rozsah funkcií je opísaný v API.

Indexované vyhľadávanie

Pri opakovaných úlohách pomáhajú zahriate indexy. Zostavte ich raz a potom ich opakovane používajte na vyhľadávanie:

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

Indexy sa predvolene ukladajú v koreňovom adresári projektu do priečinkov .greph-index, .greph-ast-index a .greph-ast-cache.

Pri stromoch, ktoré sa často menia, vyberte profil životného cyklu namiesto toho, aby ste so všetkými zahriatymi indexmi zaobchádzali rovnako:

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

Bežný postup je takýto:

stabilný základ ponechajte ako static
aktívne sa meniace vrstvy ponechajte ako opportunistic-refresh
správanie pri zastaraných dátach skontrolujte pomocou stats --dry-refresh

Vyhľadávanie vo viacerých zahriatych indexoch

V jednom príkaze môžete vyhľadávať vo viacerých zahriatych indexoch:

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

Pomenované súpravy indexov

Ak to robíte opakovane, uložte rozloženie do .greph-index-set.json a namiesto opakovania príznakov použite podpríkazy pre súpravy:

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

Záznam plánovača

Ak chcete vidieť, ako zahriate vyhľadávanie zužuje množinu kandidátov, pridajte --trace-plan:

Shell

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

Úplný postup práce so zahriatymi indexmi nájdete v častiach Indexované / Text a Indexované / AST.

Obaly pre kompatibilitu

Ak už máte nástroje alebo agentov, ktoré používajú ripgrep alebo ast-grep, jednoducho nasaďte príslušné obaly:

Shell

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

Oba obaly využívajú rovnaký nástroj a ich výstupy sa overujú porovnaním s pôvodnými binárnymi súbormi. Overené funkcie sú opísané v častiach Kompatibilita / rg a Kompatibilita / sg a sú uvedené aj vo vygenerovanej matici funkcií.

Konfigurácia

Greph podporuje dve konvencie používané na disku:

.gitignore: predvolene sa rešpektuje. Ak to chcete vypnúť, zadajte --no-ignore.
.grephignore: rovnaká syntax ako v .gitignore, ktorá sa uplatní navyše. Užitočné pre vylúčenia špecifické pre nástroje, ktoré nechcete ukladať do správy verzií.

Predvolené adresáre indexov sú .greph-index, .greph-ast-index a .greph-ast-cache vo vybranom koreňovom adresári. Cestu môžete zmeniť pomocou --index-dir v ľubovoľnom podpríkaze greph-index alebo použiť .greph-index-set.json pre opakovateľné rozloženia s viacerými indexmi.