# Začíname ## Inštalácia Nainštalujte Greph pomocou Composer: ```bash 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: ```bash 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](https://github.com/inline0/greph/issues/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](https://greph.inline0.dev/sk/docs/advanced/process-restricted-hosts). ## Prvé vyhľadávanie v texte Predvolený režim nástroja Greph je textové vyhľadávanie kompatibilné s grep: ```bash 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](https://greph.inline0.dev/sk/docs/cli). ## Prvé vyhľadávanie v AST Ak chcete prejsť na štrukturálne vyhľadávanie, zadajte `-p` a vzor v tvare PHP: ```bash 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: ```bash # 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](https://greph.inline0.dev/sk/docs/modes/ast). ## Prvé prepisovanie Pridaním `-r` zmeníte vyhľadávanie v AST na prepisovanie: ```bash # 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](https://greph.inline0.dev/sk/docs/modes/rewrite). ## 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](https://greph.inline0.dev/sk/docs/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: ```bash # 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: ```bash 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: ```bash 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: ```bash 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`: ```bash 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](https://greph.inline0.dev/sk/docs/indexed/text) a [Indexované / AST](https://greph.inline0.dev/sk/docs/indexed/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: ```bash 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](https://greph.inline0.dev/sk/docs/compatibility/rg) a [Kompatibilita / sg](https://greph.inline0.dev/sk/docs/compatibility/sg) a sú uvedené aj vo vygenerovanej [matici funkcií](https://greph.inline0.dev/sk/docs/advanced/feature-matrix). ## 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.