# Aloitus ## Asennus Asenna Greph komennolla Composer: ```bash composer require greph/greph ``` Tämä asentaa kirjaston ja neljä suoritettavaa tiedostoa kohteeseen `vendor/bin/`: - `greph`: natiivi tekstihaku, AST-haku ja AST-uudelleenkirjoitus - `greph-index`: lämmitetty tekstihakemisto, AST-faktahakemisto ja välimuistissa oleva AST-haku - `rg`: ripgrep-tyylinen yhteensopivuuskerros - `sg`: ast-grep-tyylinen yhteensopivuuskerros Nämä suoritettavat tiedostot toimivat projektisi `vendor/bin/`-hakemistosta, koska Greph 0.2.3. Aiemmat julkaisut löysivät Composer-lataajan vain Greph-arkiston kloonista, joten vaaditaan vähintään kyseinen versio: ```bash composer require greph/greph:^0.2.3 ``` ## Vaatimukset - **PHP 8.2+** readonly-luokille, enum-tyypeille, ensiluokkaiselle callable-syntaksille ja konstruktorin promootiolle - **ext-json** JSON-tulosteelle ja levyllä tallennettaville indeksisisällöille - **ext-ctype** kuvioiden ja asetusten jäsentämiseen - **ext-tokenizer** PHP-Parser-toiminnolle ja AST-esisuodattimille - **ext-zlib** välimuistissa säilytettävälle AST-tallennukselle (`greph-index ast-cache`) - **nikic/php-parser** (asennetaan automaattisesti Composer-riippuvuutena) `ext-json`, `ext-ctype` ja `ext-tokenizer` ovat käytössä lähes jokaisessa PHP-koontiversiossa. `composer.json` määrittelee tällä hetkellä vain `ext-json`-riippuvuuden ([#5](https://github.com/inline0/greph/issues/5)), joten Composer ei varoita, jos jokin muista puuttuu. Valinnainen: - **ext-pcntl** rinnakkaisiin skannauksiin. Greph siirtyy puuttuessaan ongelmitta yhden prosessin suoritukseen. - Ulkoiset `rg`-, `grep`- ja `sg`-binäärit vertailutesteihin. Niitä ei koskaan tarvita suorituksen aikana. Haku, uudelleenkirjoitus ja indeksointi eivät koskaan kutsu `proc_open()`- tai `shell_exec()`-toimintoa; vain rinnakkaiset skannaukset käynnistävät aliprosesseja, ja ilman `pcntl_fork()`-toimintoa ne siirtyvät yhden prosessin suoritukseen. Katso [Prosessirajoitetut isännät](https://greph.inline0.dev/fi/docs/advanced/process-restricted-hosts), jos isäntäympäristö estää `proc_open()`-, `shell_exec()`- tai `pcntl_fork()`-toiminnon. ## Ensimmäinen tekstihakusi Greph käyttää oletuksena grep-yhteensopivaa tekstihakua: ```bash vendor/bin/greph -F "function" src ``` Tuloste noudattaa kanonista `file:line:content`-muotoa, jota grep, ripgrep ja useimmat editori-integraatiot odottavat. ```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( ``` Lisää `-i` kirjainkoon sivuuttavaan hakuun, `-w` kokonaisten sanojen hakuun, `-c` osumien lukumäärään, `-l` pelkkiin tiedostopolkuihin, `-C 2` kahteen kontekstiriviin ja niin edelleen. Täydellinen luettelo löytyy [CLI-viiteosiosta](https://greph.inline0.dev/fi/docs/cli). ## Ensimmäinen AST-hakusi Siirry rakenteelliseen hakuun antamalla `-p` ja PHP-muotoinen kuvio: ```bash vendor/bin/greph -p 'new $CLASS()' src ``` `$CLASS` on metamuuttuja, joka tallentaa minkä tahansa luokan nimen. Kuvio `new $CLASS()` vastaa jokaista argumentitonta `new`-lauseketta luokasta, muotoilusta tai kommenteista riippumatta. Käytä `new $CLASS($$$ARGS)`-merkintää, jos haluat vastata kutsuja, joissa on mitkä tahansa argumentit. Jokainen AST-osuma tulostetaan muodossa tiedosto, aloitusrivi ja osunut koodi: ```text src/Greph.php:43:new FileWalker() src/Greph.php:52:new TextSearchOptions() src/Greph.php:54:new TextSearcher() ``` Muita hyödyllisiä kuvioita: ```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 ``` Katso [Tilat / AST-haku](https://greph.inline0.dev/fi/docs/modes/ast), josta löydät kuvioiden täydellisen syntaksin. ## Ensimmäinen uudelleenkirjoituksesi Muuta AST-haku uudelleenkirjoitukseksi lisäämällä `-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 ``` Uudelleenkirjoitukset säilyttävät muotoilun osuman ulkopuolella: vain osunut solmu korvataan, ja ympäröivät välilyönnit, sisennykset ja kommentit säilyvät ennallaan. Osunut solmu tulostetaan uudelleen mallineesta, joten sen oma asettelu normalisoidaan ja sen sisällä oleva kommentti voi kadota. Lisätietoja on kohdassa [Tilat / Uudelleenkirjoitus](https://greph.inline0.dev/fi/docs/modes/rewrite). ## PHP API Staattinen `Greph\Greph`-julkisivu tarjoaa samat toiminnot kuin 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"; } ``` Koko rajapinta on kuvattu kohdassa [API](https://greph.inline0.dev/fi/docs/api). ## Indeksoitu haku Toistuvissa työkuormissa lämpimistä indekseistä on hyötyä. Rakenna indeksi kerran ja tee sitten useita kyselyjä: ```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 ``` Indeksit tallennetaan oletusarvoisesti projektin juuressa hakemistoihin `.greph-index`, `.greph-ast-index` ja `.greph-ast-cache`. Usein muuttuvissa hakemistorakenteissa valitse elinkaariprofiili sen sijaan, että käsittelisit kaikkia lämpimiä indeksejä samalla tavalla: ```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 ``` Tavallinen toimintamalli on: - pidä vakaa perusindeksi muodossa `static` - pidä aktiivisesti muuttuvat päällekkäisindeksit muodossa `opportunistic-refresh` - tarkastele vanhentunutta toimintaa komennolla `stats --dry-refresh` ### Usean indeksin lämminhaku Voit hakea useasta lämpimästä indeksistä yhdellä komennolla: ```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 ``` ### Nimetyt indeksijoukot Jos toistat tämän usein, määritä asettelu tiedostossa `.greph-index-set.json` ja käytä joukon alikomentoja sen sijaan, että toistaisit valitsimet: ```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)' . ``` ### Suunnittelijan jäljitys Näet, miten lämminhaku rajaa ehdokkaita, lisää `--trace-plan`: ```bash vendor/bin/greph-index search --trace-plan -F "function" . vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' . ``` Katso kohdat [Indeksoitu / Teksti](https://greph.inline0.dev/fi/docs/indexed/text) ja [Indeksoitu / AST](https://greph.inline0.dev/fi/docs/indexed/ast), joissa kuvataan koko lämminhakutyönkulku. ## Yhteensopivuuskääreet Jos käytössäsi on työkaluja tai agentteja, jotka käyttävät jo ripgrep- tai ast-grep-rajapintaa, ota käyttöön kääreet: ```bash vendor/bin/rg --json -F "function" src vendor/bin/sg --pattern 'new $CLASS()' src --lang php ``` Molemmat kääreet käyttävät samaa moottoria, ja niiden yhteensopivuus on tarkistettu koeluonteisesti alkuperäisiä binäärejä vasten. Tarkistettu toiminnallisuus on kuvattu kohdissa [Yhteensopivuus / rg](https://greph.inline0.dev/fi/docs/compatibility/rg) ja [Yhteensopivuus / sg](https://greph.inline0.dev/fi/docs/compatibility/sg), ja se on esitetty uudelleen luodussa [ominaisuusmatriisissa](https://greph.inline0.dev/fi/docs/advanced/feature-matrix). ## Määritykset Greph ottaa käyttöön kaksi levyllä tallennettavaa käytäntöä: - `.gitignore`: käytössä oletusarvoisesti. Poista käytöstä antamalla `--no-ignore`. - `.grephignore`: sama syntaksi kuin `.gitignore`-määrityksessä, sovelletaan sen lisäksi. Hyödyllinen työkalukohtaisiin poissulkuihin, joita et halua versionhallintaan. Oletusarvoiset indeksihakemistot ovat valitun juurihakemiston `.greph-index`, `.greph-ast-index` ja `.greph-ast-cache`. Ohita ne antamalla `--index-dir` missä tahansa `greph-index`-alikomennossa tai käytä `.greph-index-set.json`-komentoa toistettaviin usean indeksin asetteluihin.