Aloitus

Asennus

Asenna Greph komennolla Composer:

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:

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), 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, jos isäntäympäristö estää proc_open()-, shell_exec()- tai pcntl_fork()-toiminnon.

Ensimmäinen tekstihakusi

Greph käyttää oletuksena grep-yhteensopivaa tekstihakua:

vendor/bin/greph -F "function" src

Tuloste noudattaa kanonista file:line:content-muotoa, jota grep, ripgrep ja useimmat editori-integraatiot odottavat.

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.

Ensimmäinen AST-hakusi

Siirry rakenteelliseen hakuun antamalla -p ja PHP-muotoinen kuvio:

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:

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

Muita hyödyllisiä kuvioita:

# 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, josta löydät kuvioiden täydellisen syntaksin.

Ensimmäinen uudelleenkirjoituksesi

Muuta AST-haku uudelleenkirjoitukseksi lisäämällä -r:

# 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.

PHP API

Staattinen Greph\Greph-julkisivu tarjoaa samat toiminnot kuin CLI:

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.

Indeksoitu haku

Toistuvissa työkuormissa lämpimistä indekseistä on hyötyä. Rakenna indeksi kerran ja tee sitten useita kyselyjä:

# 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:

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:

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:

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:

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

Katso kohdat Indeksoitu / Teksti ja Indeksoitu / 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:

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 ja Yhteensopivuus / sg, ja se on esitetty uudelleen luodussa ominaisuusmatriisissa.

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.