İçeriğe geç

Başlarken

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: d105217

Kurulum

Composer aracılığıyla Greph yükleyin:

Kabuk
composer require greph/greph

Bu işlem, kitaplığı ve dört çalıştırılabilir dosyayı vendor/bin/ içine yükler:

  • greph: yerel metin arama, AST arama ve AST yeniden yazma
  • greph-index: ısıtılmış metin dizini, AST olgu dizini ve önbelleğe alınmış AST arama
  • rg: ripgrep tarzı uyumluluk sarmalayıcısı
  • sg: ast-grep tarzı uyumluluk sarmalayıcısı

Greph 0.2.3 olduğundan, bu çalıştırılabilir dosyalar projenizin vendor/bin/ dizininden çalışır. Önceki sürümler Greph deposunun klonunun içindeki Composer otomatik yükleyicisini bulabiliyordu; bu nedenle en az bu sürümü gerektirir:

Kabuk
composer require greph/greph:^0.2.3

Gereksinimler

  • Salt okunur sınıflar, enum'lar, birinci sınıf çağrılabilir söz dizimi ve kurucu yükseltmesi için PHP 8.2+
  • JSON çıktısı ve diskteki dizin verileri için ext-json
  • Desen ve seçenek ayrıştırma için ext-ctype
  • PHP-Parser ve AST ön filtreleri için ext-tokenizer
  • Önbelleğe alınmış AST deposu (greph-index ast-cache) için ext-zlib
  • Otomatik olarak Composer bağımlılığı olarak yüklenen nikic/php-parser

ext-json, ext-ctype ve ext-tokenizer neredeyse her PHP derlemesinde etkindir. composer.json şu anda yalnızca ext-json bildirdiğinden (#5), Composer diğerlerinden biri eksik olduğunda uyarı vermez.

İsteğe bağlı:

  • Paralel taramalar için ext-pcntl. Eksik olduğunda Greph sorunsuzca tek süreçli yürütmeye geçer.
  • Karşılaştırmalı ölçümler için harici rg, grep ve sg ikili dosyaları. Çalışma zamanında hiçbir zaman gerekmezler.

Arama, yeniden yazma ve dizin oluşturma işlemleri hiçbir zaman proc_open() veya shell_exec() çağırmaz; yalnızca paralel taramalar çatallanır ve pcntl_fork() olmadığında tek sürece geri döner. proc_open(), shell_exec() veya pcntl_fork() kullanımını devre dışı bırakan barındırma ortamları için Süreç Kısıtlı Barındırma Ortamları bölümüne bakın.

İlk metin aramanız

Greph varsayılan kipi grep uyumlu metin aramasıdır:

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

Çıktı, grep, ripgrep ve çoğu düzenleyici entegrasyonunun beklediği standart file:line:content biçimini kullanır.

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(

Büyük/küçük harf duyarsız eşleştirme için -i, tam sözcük eşleştirme için -w, sayımlar için -c, yalnızca dosya yolları için -l, iki satır bağlam için -C 2 ve benzeri seçenekleri ekleyin. Tam liste CLIbaşvuru içinde yer alır.

Yapısal aramaya geçmek için -p ve PHP biçimli bir desen geçirin:

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

$CLASS, herhangi bir sınıf adını yakalayan bir üst değişkendir. new $CLASS() deseni, sınıfından, biçimlendirmesinden veya yorumlarından bağımsız olarak, bağımsız değişken almayan her new ifadesiyle eşleşir. Herhangi bir sayıda bağımsız değişken alan çağrılarla eşleşmek için new $CLASS($$$ARGS) kullanın.

Her AST eşleşmesi dosya, başlangıç satırı ve eşleşen kod olarak yazdırılır:

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

Diğer kullanışlı desenler:

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

Tam desen söz dizimi için Kipler / AST Arama bölümüne bakın.

İlk yeniden yazmanız

AST aramasını yeniden yazmaya dönüştürmek için -r ekleyin:

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

Yeniden yazmalar, eşleşmenin dışındaki biçimi korur: yalnızca eşleşen düğüm değiştirilir; çevresindeki boşluklar, girintiler ve yorumlar aynen kalır. Eşleşen düğümün kendisi şablondan yeniden oluşturulur; bu nedenle kendi düzeni normalleştirilir ve içindeki bir yorum kaybolabilir. Ayrıntılar için Kipler / Yeniden Yazma bölümüne bakın.

PHP API

Statik Greph\Greph arayüzü, CLI ile aynı işlemleri sunar:

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";
}

Tüm kapsam API içinde açıklanmıştır.

Tekrarlanan iş yükleri, ısıtılmış dizinlerden yararlanır. Bir kez oluşturup birçok kez sorgulayın:

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

Dizinler varsayılan olarak proje kökündeki .greph-index, .greph-ast-index ve .greph-ast-cache konumlarında tutulur.

Sürekli değişen ağaçlarda, her ısıtılmış dizini aynı kabul etmek yerine bir yaşam döngüsü profili seçin:

Kabuk
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

Yaygın kullanım şöyledir:

  • Kararlı bir temel dizini static olarak tutun
  • Sürekli değişen katmanları opportunistic-refresh olarak tutun
  • Eski davranışı stats --dry-refresh ile inceleyin

Bir komutla birden çok ısıtılmış dizinde arama yapabilirsiniz:

Kabuk
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

Adlandırılmış dizin kümeleri

Bunu tekrar tekrar yapıyorsanız, düzeni .greph-index-set.json içine koyup bayrakları tekrarlamak yerine küme alt komutlarını kullanın:

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

Planlayıcı izlemesi

Isıtılmış aramanın adayları nasıl daralttığını görmek için --trace-plan ekleyin:

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

Isıtılmış iş akışının tamamı için Dizinli / Metin ve Dizinli / AST bölümlerine bakın.

Uyumluluk sarmalayıcıları

Zaten ripgrep veya ast-grep konuşan araçlarınız ya da ajanlarınız varsa, sarmalayıcıları doğrudan kullanın:

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

Her iki sarmalayıcı da aynı motoru kullanır ve üst kaynak ikili dosyalarına karşı denemelerle doğrulanmıştır. Doğrulanmış kapsam Uyumluluk / rg ve Uyumluluk / sg bölümlerinde açıklanır ve oluşturulan özellik matrisinde yeniden sunulur.

Yapılandırma

Greph, diskteki iki kuralı dikkate alır:

  • .gitignore: varsayılan olarak dikkate alınır. Devre dışı bırakmak için --no-ignore geçirin.
  • .grephignore: .gitignore ile aynı söz dizimini kullanır ve onun üzerine uygulanır. Sürüm kontrolüne almak istemediğiniz araca özgü hariç tutmalar için kullanışlıdır.

Varsayılan dizin dizinleri, seçilen kökte .greph-index, .greph-ast-index ve .greph-ast-cache konumlarındadır. Herhangi bir greph-index alt komutunda --index-dir ile geçersiz kılın veya tekrarlanabilir çok dizinli düzenler için .greph-index-set.json kullanın.