# Alustamine ## Paigaldamine Installige Greph käsuga Composer: ```bash composer require greph/greph ``` See installib teegi ja neli käivitatavat faili asukohta `vendor/bin/`: - `greph`: natiivne tekstiotsing, AST-otsing ja AST ümberkirjutamine - `greph-index`: eelsoojendatud tekstiindeks, AST faktide indeks ja vahemällu salvestatud AST-otsing - `rg`: ripgrep-stiilis ühilduvusümbris - `sg`: ast-grep-stiilis ühilduvusümbris Need käivitatavad failid töötavad teie projekti kataloogis `vendor/bin/`, kuna Greph 0.2.3. Varasemad versioonid leidsid Composer autoloaderi ainult hoidla Greph klooni seest, seega nõutav on vähemalt see versioon: ```bash composer require greph/greph:^0.2.3 ``` ## Nõuded - **PHP 8.2+** readonly-klasside, enum’ide, esimese klassi kutsutava süntaksi ja konstruktori edendamise jaoks - **ext-json** JSON väljundi ja kettal olevate registriandmete jaoks - **ext-ctype** mustrite ja suvandite sõelumiseks - **ext-tokenizer** PHP-Parser ja AST eelfiltrite jaoks - **ext-zlib** vahemällu salvestatud AST hoidla jaoks (`greph-index ast-cache`) - **nikic/php-parser** (paigaldatakse automaatselt kui Composer sõltuvus) `ext-json`, `ext-ctype` ja `ext-tokenizer` on lubatud peaaegu igas PHP järgus. `composer.json` deklareerib praegu ainult `ext-json` ([#5](https://github.com/inline0/greph/issues/5)), seega Composer ei hoiata, kui mõni muu neist puudub. Valikuline: - **ext-pcntl** paralleelsete skannimiste jaoks. Puudumisel Greph jätkab sujuvalt tööd ühe protsessiga. - Välised `rg`, `grep` ja `sg` binaarfailid võrdlusuuringuteks. Need pole käitamisel kunagi vajalikud. Otsimine, ümberkirjutamine ja indekseerimine ei kutsu kunagi `proc_open()` ega `shell_exec()`; ainult paralleelsed skannimised käivitavad alamprotsesse ning ilma `pcntl_fork()`-ta kasutatakse selle asemel üht protsessi. Vaadake jaotist [Protsessipiirangutega hostid](https://greph.inline0.dev/et/docs/advanced/process-restricted-hosts) hostide kohta, kus `proc_open()`, `shell_exec()` või `pcntl_fork()` on keelatud. ## Esimene tekstiotsing Greph vaikimisi režiim on grep-iga ühilduv tekstiotsing: ```bash vendor/bin/greph -F "function" src ``` Väljund kasutab kanoonilist vormingut `file:line:content`, mida grep, ripgrep ja enamik redaktorite integratsioone eeldavad. ```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( ``` Lisage `-i` tõstutundetuks vasteotsinguks, `-w` terve sõna leidmiseks, `-c` vastete arvu kuvamiseks, `-l` ainult failiteede kuvamiseks, `-C 2` kahe kontekstirea lisamiseks jne. Täielik loend on [CLI viites](https://greph.inline0.dev/et/docs/cli). ## Esimene AST-otsing Struktuuriotsingule lülitumiseks edastage `-p` ja mustri kujul PHP: ```bash vendor/bin/greph -p 'new $CLASS()' src ``` `$CLASS` on metamuutuja, mis püüab kinni suvalise klassi nime. Muster `new $CLASS()` leiab iga argumentideta `new`-avaldise, olenemata klassist, vormindusest või kommentaaridest. Suvaliste argumentidega kutsete leidmiseks kasutage `new $CLASS($$$ARGS)`. Iga AST vaste prinditakse kujul: fail, algusrida ja leitud kood: ```text src/Greph.php:43:new FileWalker() src/Greph.php:52:new TextSearchOptions() src/Greph.php:54:new TextSearcher() ``` Veel kasulikke mustreid: ```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 ``` Täieliku mustrisüntaksi leiate jaotisest [Režiimid / AST-otsing](https://greph.inline0.dev/et/docs/modes/ast). ## Esimene ümberkirjutus AST-otsingu ümberkirjutuseks muutmiseks lisage `-r`: ```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 ``` Ümberkirjutused säilitavad vormingu väljaspool vastet: asendatakse ainult vastav sõlm ning ümbritsev tühik, taane ja kommentaarid jäävad alles. Vastav sõlm ise prinditakse malli põhjal uuesti, mistõttu selle paigutus normaliseeritakse ja selle sees olev kommentaar võib kaduda. Üksikasju leiate jaotisest [Režiimid / Ümberkirjutus](https://greph.inline0.dev/et/docs/modes/rewrite). ## PHP API Staatiline `Greph\Greph` fassaad pakub samu toiminguid mis 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"; } ``` Kogu funktsionaalsust käsitleb [API](https://greph.inline0.dev/et/docs/api). ## Indekseeritud otsing Korduvate töökoormuste korral on soojendatud registritest kasu. Looge register üks kord ja tehke seejärel mitu päringut: ```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 ``` Vaikimisi asuvad registrid projekti juurkaustas kataloogides `.greph-index`, `.greph-ast-index` ja `.greph-ast-cache`. Sageli muutuvate failipuude jaoks valige elutsükli profiil, selle asemel et käsitleda kõiki soojendatud registreid ühtemoodi: ```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 ``` Tüüpiline muster on järgmine: - hoidke stabiilset baasi kui `static` - hoidke aktiivselt muutuvaid kihte kui `opportunistic-refresh` - uurige aegunud registri käitumist käsuga `stats --dry-refresh` ### Mitme registri soojendatud otsing Ühe käsuga saab otsida mitmest soojendatud registrist: ```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 ``` ### Nimega registrikomplektid Kui teete seda korduvalt, määrake paigutus failis `.greph-index-set.json` ja kasutage lippude kordamise asemel komplekti alamkäske: ```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)' . ``` ### Plaanuri jälg Et näha, kuidas soojendatud otsing kandidaatide hulka kitsendab, lisage `--trace-plan`: ```bash vendor/bin/greph-index search --trace-plan -F "function" . vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' . ``` Täieliku soojendatud töövoo leiate jaotistest [Indekseeritud / tekst](https://greph.inline0.dev/et/docs/indexed/text) ja [Indekseeritud / AST](https://greph.inline0.dev/et/docs/indexed/ast). ## Ühilduvuskihid Kui teie tööriistad või agendid kasutavad juba ripgrep või ast-grep, võtke kasutusele ühilduvuskihid: ```bash vendor/bin/rg --json -F "function" src vendor/bin/sg --pattern 'new $CLASS()' src --lang php ``` Mõlemad ühilduvuskihid kasutavad sama mootorit ja nende ühilduvust on kontrollitud algsete binaarfailidega. Kontrollitud funktsionaalsust kirjeldatakse jaotistes [Ühilduvus / rg](https://greph.inline0.dev/et/docs/compatibility/rg) ja [Ühilduvus / sg](https://greph.inline0.dev/et/docs/compatibility/sg) ning seda korratakse loodud [funktsioonide maatriksis](https://greph.inline0.dev/et/docs/advanced/feature-matrix). ## Konfiguratsioon Greph järgib kaht kettal kasutatavat tava: - `.gitignore`: vaikimisi järgitakse. Keelamiseks edastage `--no-ignore`. - `.grephignore`: sama süntaks mis `.gitignore`-il, lisatakse selle peale. Sobib tööriistapõhiste välistuste jaoks, mida ei soovi versioonihaldusesse lisada. Vaikimisi asuvad registrikataloogid valitud juurkaustas: `.greph-index`, `.greph-ast-index` ja `.greph-ast-cache`. Alistage need käsuga `--index-dir` mis tahes `greph-index` alamkäsu puhul või kasutage korratavate mitme registriga paigutuste jaoks `.greph-index-set.json`.