Alustamine

Paigaldamine

Installige Greph käsuga Composer:

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:

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), 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 hostide kohta, kus proc_open(), shell_exec() või pcntl_fork() on keelatud.

Esimene tekstiotsing

Greph vaikimisi režiim on grep-iga ühilduv tekstiotsing:

vendor/bin/greph -F "function" src

Väljund kasutab kanoonilist vormingut file:line:content, mida grep, ripgrep ja enamik redaktorite integratsioone eeldavad.

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.

Esimene AST-otsing

Struktuuriotsingule lülitumiseks edastage -p ja mustri kujul PHP:

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:

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

Veel kasulikke mustreid:

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

Esimene ümberkirjutus

AST-otsingu ümberkirjutuseks muutmiseks lisage -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

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

PHP API

Staatiline Greph\Greph fassaad pakub samu toiminguid mis 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";
}

Kogu funktsionaalsust käsitleb API.

Indekseeritud otsing

Korduvate töökoormuste korral on soojendatud registritest kasu. Looge register üks kord ja tehke seejärel mitu päringut:

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

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:

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:

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:

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 ja Indekseeritud / AST.

Ühilduvuskihid

Kui teie tööriistad või agendid kasutavad juba ripgrep või ast-grep, võtke kasutusele ühilduvuskihid:

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 ja Ühilduvus / sg ning seda korratakse loodud funktsioonide maatriksis.

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.