Hoppa till innehåll

Kom igång

Visa som Markdown Redigera på GitHub Dokumentation på d105217

Installation

Installera Greph med Composer:

Shell
composer require greph/greph

Detta installerar biblioteket och fyra körbara filer i vendor/bin/:

  • greph: inbyggd textsökning, AST-sökning och AST-omskrivning
  • greph-index: uppvärmt textindex, AST-faktindex och cachad AST-sökning
  • rg: kompatibilitetsomslag i ripgrep-stil
  • sg: kompatibilitetsomslag i ast-grep-stil

De här körbara filerna fungerar från projektets vendor/bin/ eftersom Greph 0.2.3. Tidigare versioner hittade bara autoladdaren Composer inuti en klon av kodförrådet Greph, så använd minst den versionen:

Shell
composer require greph/greph:^0.2.3

Krav

  • PHP 8.2+ för readonly-klasser, enums, syntax för förstklassiga anropbara objekt och konstruktorpromotion
  • ext-json för JSONutdata och nyttolaster för index på disk
  • ext-ctype för mönster- och alternativtolkning
  • ext-tokenizer för PHP-Parser och AST-förfilter
  • ext-zlib för det cachade AST-lagret (greph-index ast-cache)
  • nikic/php-parser (installeras automatiskt som ett Composer-beroende)

ext-json, ext-ctype och ext-tokenizer är aktiverade i nästan varje PHP-bygge. composer.json deklarerar för närvarande bara ext-json (#5), så Composer varnar inte om något av de andra saknas.

Valfritt:

  • ext-pcntl för parallella genomsökningar. Greph fungerar utan problem i en enda process om det saknas.
  • Externa binärer för rg, grep och sg för jämförelser i prestandatester. De krävs aldrig vid körning.

Sökning, omskrivning och indexering anropar aldrig proc_open() eller shell_exec(); endast parallella genomsökningar startar underprocesser, och de återgår till en enda process utan pcntl_fork(). Se Värdar med processbegränsningar för värdar som inaktiverar proc_open(), shell_exec() eller pcntl_fork().

Din första textsökning

Grephs standardläge är grep-kompatibel textsökning:

Shell
vendor/bin/greph -F "function" src

Utdata använder det kanoniska formatet file:line:content som grep, ripgrep och de flesta editorintegrationer förväntar sig.

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(

Lägg till -i för skiftlägesokänslig matchning, -w för matchning av hela ord, -c för antal, -l för endast filsökvägar, -C 2 för två kontextrader och så vidare. Hela listan finns i referensen CLI.

Ange -p och ett mönster med formen PHP för att växla till strukturell sökning:

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

$CLASS är en metavariabel som fångar upp valfritt klassnamn. Mönstret new $CLASS() matchar varje new-uttryck utan argument, oavsett klass, formatering eller kommentarer. Använd new $CLASS($$$ARGS) för att matcha anrop med valfria argument.

Varje AST-träff skrivs ut med filen, startraden och den matchade koden:

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

Andra användbara mönster:

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

Se Lägen / AST-sökning för hela mönstersyntaxen.

Din första omskrivning

Lägg till -r för att omvandla AST-sökningen till en omskrivning:

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

Omskrivningar bevarar formateringen utanför träffen: endast den matchade noden ersätts, medan omgivande blanksteg, indrag och kommentarer bevaras. Den matchade noden skrivs ut på nytt från mallen, så dess egen layout normaliseras och en kommentar inuti den kan gå förlorad. Se Lägen / Omskrivning för mer information.

PHP API

Den statiska Greph\Greph-fasaden exponerar samma operationer som 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";
}

Hela gränssnittet beskrivs i API.

Återkommande arbetsbelastningar drar nytta av uppvärmda index. Bygg indexet en gång och gör sedan många sökningar:

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

Som standard lagras indexen i .greph-index, .greph-ast-index och .greph-ast-cache i projektroten.

För träd som ändras ofta väljer du en livscykelprofil i stället för att behandla alla uppvärmda index på samma sätt:

Shell
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

Vanligtvis gör man så här:

  • behåll en stabil baslinje som static
  • behåll överlagringar som ändras ofta som opportunistic-refresh
  • granska inaktuellt beteende med stats --dry-refresh

Du kan söka i flera uppvärmda index med ett enda kommando:

Shell
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

Namngivna indexuppsättningar

Om du gör det upprepade gånger kan du lägga in upplägget i .greph-index-set.json och använda underkommandona för uppsättningar i stället för att upprepa flaggor:

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

Planerarspårning

Lägg till --trace-plan för att se hur den uppvärmda sökningen begränsar kandidaterna:

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

Se Indexerad / Text och Indexerad / AST för hela arbetsflödet med uppvärmda index.

Kompatibilitetsomslag

Om du har verktyg eller agenter som redan använder ripgrep eller ast-grep kan du lägga till omslagen:

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

Båda omslagen återanvänder samma motor och har verifierats med sonder mot uppströmsbinärerna. Det verifierade gränssnittet beskrivs i Kompatibilitet / rg och Kompatibilitet / sg och återges i den genererade funktionsmatrisen.

Konfiguration

Greph hanterar två konventioner på disk:

  • .gitignore: följs som standard. Ange --no-ignore för att inaktivera.
  • .grephignore: samma syntax som .gitignore, tillämpad ovanpå. Användbart för verktygsspecifika undantag som du inte vill versionshantera.

Standardkatalogerna för index är .greph-index, .greph-ast-index och .greph-ast-cache i den valda roten. Åsidosätt med --index-dir i ett valfritt greph-index-underkommando eller använd .greph-index-set.json för upprepningsbara upplägg med flera index.