Darba sākšana

Instalēšana

Instalējiet Greph, izmantojot Composer:

composer require greph/greph

Tiek instalēta bibliotēka un četras izpildāmās programmas mapē vendor/bin/:

• greph: vietējā teksta meklēšana, AST meklēšana un AST pārrakstīšana
• greph-index: uzsildīts teksta indekss, AST faktu indekss un kešota AST meklēšana
• rg: ar ripgrep saderīgs wrapper
• sg: ar ast-grep saderīgs wrapper

Šīs izpildāmās programmas darbojas no jūsu projekta vendor/bin/, jo Greph 0.2.3. Iepriekšējie laidieni atrada Composer automātiskās ielādes failu tikai Greph repozitorija klonā, tāpēc nepieciešama vismaz šī versija:

composer require greph/greph:^0.2.3

Prasības

• PHP 8.2+ tikai lasāmām klasēm, enum tipiem, pirmšķirīgai izsaucamo funkciju sintaksei un konstruktoru parametru paaugstināšanai
• ext-json JSON izvadei un diskā glabātām indeksa datu kopām
• ext-ctype paraugu un opciju parsēšanai
• ext-tokenizer PHP-Parser un AST priekšfiltriem
• ext-zlib kešotajai AST krātuvei (greph-index ast-cache)
• nikic/php-parser (tiek instalēts automātiski kā Composer atkarība)

ext-json, ext-ctype un ext-tokenizer ir iespējoti gandrīz katrā PHP būvējumā. composer.json pašlaik deklarē tikai ext-json (#5), tāpēc Composer nebrīdina, ja trūkst kāda no pārējiem paplašinājumiem.

Pēc izvēles:

• ext-pcntl paralēlai skenēšanai. Ja tā trūkst, Greph bez problēmām pārslēdzas uz viena procesa izpildi.
• Ārējie rg, grep un sg binārie faili salīdzināšanai etalonpārbaudēs. Tie nekad nav nepieciešami darbības laikā.

Meklēšana, pārrakstīšana un indeksēšana nekad neizsauc proc_open() vai shell_exec(); tiek izveidoti atvasināti procesi tikai paralēlās skenēšanas laikā, un bez pcntl_fork() tā pārslēdzas uz viena procesa režīmu. Par resursdatoriem, kas atspējo proc_open(), shell_exec() vai pcntl_fork(), skatiet sadaļu Procesiem ierobežotas vides.

Pirmā teksta meklēšana

Greph noklusējuma režīms ir ar grep saderīga teksta meklēšana:

vendor/bin/greph -F "function" src

Izvade izmanto kanonisko file:line:content formātu, ko sagaida grep, ripgrep un lielākā daļa redaktoru integrāciju.

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(

Pievienojiet -i reģistrnejutīgai atbilstībai, -w pilnu vārdu atbilstībai, -c atrasto gadījumu skaitam, -l tikai failu ceļiem, -C 2 divām konteksta rindām un tā tālāk. Pilns saraksts ir atrodams atsauces rokasgrāmatāCLI.

Pirmā AST meklēšana

Lai pārslēgtos uz strukturālo meklēšanu, norādiet -p un PHP formas paraugu:

vendor/bin/greph -p 'new $CLASS()' src

$CLASS ir metamainīgais, kas uztver jebkuru klases nosaukumu. Paraugs new $CLASS() atbilst katrai new izteiksmei bez argumentiem neatkarīgi no klases, formatējuma vai komentāriem. Lai atrastu izsaukumus ar jebkādiem argumentiem, izmantojiet new $CLASS($$$ARGS).

Katra AST atbilstība tiek izvadīta kā fails, sākuma rinda un atbilstošais kods:

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

Citi noderīgi paraugi:

# 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

Pilnu paraugu sintaksi skatiet sadaļā Režīmi / AST meklēšana.

Pirmā pārrakstīšana

Pievienojiet -r, lai AST meklēšanu pārvērstu par pārrakstīšanu:

# 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

Ārpus atbilstības vietas pārrakstīšana saglabā formatējumu: tiek aizstāts tikai atbilstošais mezgls, bet apkārtējās atstarpes, atkāpes un komentāri paliek neskarti. Pats atbilstošais mezgls tiek izvadīts no jauna, izmantojot veidni, tāpēc tā izkārtojums tiek normalizēts un tajā ievietots komentārs var pazust. Plašāku informāciju skatiet sadaļā Režīmi / pārrakstīšana.

PHP API

Statiskā Greph\Greph fasāde nodrošina tādas pašas darbības kā 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";
}

Visa funkcionalitāte ir aprakstīta sadaļā API.

Indeksētā meklēšana

Atkārtotām slodzēm noder uzsildīti indeksi. Izveidojiet indeksu vienreiz un pēc tam veiciet daudz vaicājumu:

# 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

Pēc noklusējuma indeksi projekta saknes mapē tiek glabāti mapēs .greph-index, .greph-ast-index un .greph-ast-cache.

Bieži mainīgām koda kokstruktūrām izvēlieties dzīves cikla profilu, nevis visiem uzsildītajiem indeksiem izmantojiet vienādu pieeju:

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

Parasti to dara šādi:

• uzturiet stabilu pamatstāvokli kā static
• uzturiet aktīvi mainīgus pārklājumus kā opportunistic-refresh
• pārbaudiet novecojušu datu uzvedību ar stats --dry-refresh

Vairāku indeksu uzsildītā meklēšana

Vienā komandā varat meklēt vairākos uzsildītos indeksos:

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

Nosauktas indeksu kopas

Ja to darāt atkārtoti, saglabājiet izkārtojumu .greph-index-set.json un indeksu kopu apakškomandas izmantojiet karodziņu atkārtotas norādīšanas vietā:

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)' .

Plānotāja izsekošana

Lai redzētu, kā uzsildītā meklēšana sašaurina kandidātu loku, pievienojiet --trace-plan:

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

Pilnu uzsildīto darbplūsmu skatiet sadaļās Indeksētais / teksts un Indeksētais / AST.

Saderības wrapperi

Ja jums ir rīki vai aģenti, kas jau izmanto ripgrep vai ast-grep, pievienojiet wrapperus:

vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php

Abi wrapperi atkārtoti izmanto vienu un to pašu dzini, un to atbilstība upstream binārajiem failiem ir pārbaudīta ar zondēm. Pārbaudītā funkcionalitāte ir dokumentēta sadaļās Saderība / rg un Saderība / sg, kā arī atspoguļota ģenerētajā funkciju matricā.

Konfigurācija

Greph atpazīst divas diskā izmantotas konvencijas:

• .gitignore: tiek ievērota pēc noklusējuma. Lai atspējotu, norādiet --no-ignore.
• .grephignore: tāda pati sintakse kā .gitignore, tiek lietota papildus. Noder rīkiem specifiskiem izņēmumiem, kurus nevēlaties iekļaut versiju vadībā.

Noklusētās indeksu mapes izvēlētajā saknes mapē ir .greph-index, .greph-ast-index un .greph-ast-cache. Pārrakstiet tās ar --index-dir jebkurā greph-index apakškomandā vai izmantojiet .greph-index-set.json atkārtojamiem vairāku indeksu izkārtojumiem.