البحث في النصوص

وضع النص في Greph هو بحث بايتات موجّه حسب السطر ضمن شجرة ملفات يجري استعراضها. وهو الوضع الافتراضي لكل من greph CLI وواجهة Greph::searchText(). تستخدم المخرجات التنسيق القياسي file:line:content الذي تحلله grep وripgrep ومعظم تكاملات المحررات.

أمثلة سريعة

# Regex search across the current directory
./vendor/bin/greph "function\s+\w+"

# Fixed-string search across src/
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word search
./vendor/bin/greph -F -i -w "function" src

# Two lines of context around each match
./vendor/bin/greph -F -C 2 "TODO" src

# Stop after the first three matches per file
./vendor/bin/greph -F -m 3 "TODO" src

# Files that contain the pattern
./vendor/bin/greph -F -l "TODO" src

# Files that do not contain the pattern
./vendor/bin/greph -F -L "TODO" src

# Count matches per file
./vendor/bin/greph -F -c "TODO" src

# Inverted match
./vendor/bin/greph -F -v "TODO" src/notes.txt

الأنماط

افتراضيًا، يُعامل النمط على أنه تعبير نمطي PCRE2. تعتمد آلية المطابقة على دوال preg_* في PHP، لذا تطابق الصياغة مرجع PCRE الرسميPHP.

عطّل محرّك التعبيرات النمطية باستخدام -F لمعاملة النمط كسلسلة بايتات حرفية. وضع المطابقة الحرفية هو المسار الأسرع: يستخدم strpos() للمطابقة ويتجاوز خطوة تجميع PCRE2 بالكامل.

يجعل -i كلا الوضعين غير حسّاسين لحالة الأحرف. ويضيف -w حدودًا للكلمات الكاملة على جانبي التطابق.

تصفية الملفات

يستعرض Greph شجرة الملفات قبل البحث. يُستخدم المستعرِض نفسه في وضع AST والوضع المفهرس، لذا تنطبق أعلام التصفية نفسها في كل الأوضاع.

يحترم مستعرِض الملفات .gitignore و.grephignore افتراضيًا، ويتخطى الملفات الثنائية (التي تُكتشف عبر بايتات null في أول 512 بايتًا)، ويحدد حجم الملف الأقصى بـ 10 MiB. يمكن ضبط الحدين عبر WalkOptions.

راجع API / مرشح أنواع الملفات للاطلاع على القائمة الكاملة للأسماء المستعارة للأنواع المضمنة.

السياق والعدّ والأوضاع المقتصرة على الملفات

# Two lines before and after each match
./vendor/bin/greph -F -C 2 "needle" src

# Two lines after, no lines before
./vendor/bin/greph -F -A 2 "needle" src

# Two lines before, no lines after
./vendor/bin/greph -F -B 2 "needle" src

# Count matches per file
./vendor/bin/greph -F -c "needle" src

# List matching files only
./vendor/bin/greph -F -l "needle" src

# List non-matching files only
./vendor/bin/greph -F -L "needle" src

تتجاوز -c و-l و-L المنسّق لتفادي إنشاء كل سطر في الذاكرة. وهي الأوضاع المناسبة لأسئلة «كم عددها؟» و«أين توجد؟».

عمليات الفحص المتوازية

مرّر -j N لتوزيع الفحص على N عاملًا. يستخدم Greph pcntl_fork() لمجموعة العمال، ويعود إلى التنفيذ بعملية واحدة عندما لا يكون ext-pcntl متاحًا.

./vendor/bin/greph -F -j 8 "function" src

تحسب الواجهة ما إذا كان التنفيذ المتوازي يستحق تكلفته الإضافية، استنادًا إلى عدد الملفات والوضع وشكل النمط. وتظل بعملية واحدة إذا كان العدد دون الحد. راجع متقدم / العمال المتوازيون للاطلاع على أساليب التقييم.

مخرجات JSON

يصدر --json حمولة منظّمة تستطيع الأدوات اللاحقة تحليلها دون استخراج البيانات من تنسيق grep المعروض على الشاشة:

./vendor/bin/greph --json -F "function" src

[
  {
    "file": "src/Greph.php",
    "matches": [
      {
        "line": 31,
        "column": 1,
        "content": "final class Greph",
        "matched_text": "function",
        "captures": []
      }
    ]
  }
]

بدلًا من ذلك، يصدر غلاف rg بيانات JSON بهيئة أحداث ripgrep. استخدمه عندما يتوقع مستهلك موجود مخطط ripgrep.

الاستخدام البرمجي

use Greph\Greph;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(
        fixedString: true,
        caseInsensitive: true,
        beforeContext: 1,
        afterContext: 1,
        jobs: 4,
    ),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

يوثّق API / كائنات النتائج كائنات النتائج.

طريقة العمل

لمحرّك النص مساران:

• المسار الحرفي: عند ضبط -F، يجري البحث strpos() باستخدام قارئ ذي مخزن مؤقت بسعة 64 KiB، مع تتبّع الأسطر لترقيمها. لا توجد خطوة لتجميع التعبير النمطي.
• مسار التعبير النمطي: عند عدم ضبط -F، يستخرج Greph مقاطع حرفية من النمط باستخدام محلّل صغير شبيه بـ PCRE (Greph\Text\LiteralExtractor)، ويستخدمها كمرشح مسبق strpos(). ثم تُطابق الأسطر التي تجتاز المرشح مع نمط PCRE2 المجمّع، مع تفعيل JIT.

يستخدم المساران BufferedReader نفسه لإجراء الإدخال والإخراج. يقرأ القارئ البيانات على دفعات بحجم 64 KiB بدلًا من fgets() لكل سطر، ما يقلل عدد استدعاءات النظام كثيرًا في الملفات الكبيرة.

في أحمال العمل المتكررة، يستبدل وضع النص المفهرس القارئ ذا المخزن المؤقت بمخزن منشورات ثلاثية الكلمات والمعرّفات، ويُعاد استخدامه بعد تهيئته، متجاوزًا معظم الملفات بالكامل.