انتقل إلى المحتوى

توافق rg

عرض بتنسيق Markdown التعديل على GitHub التوثيق في d105217

vendor/bin/rg غلاف توافق بأسلوب ripgrep. يقبل أعلام ripgrep الأكثر استخدامًا، ويتنقل في شجرة الملفات كما يفعل ripgrep، ويُصدر المخرجات المطابقة. أُعيد إنتاج نطاق التوافق المتحقق منه استنادًا إلى عمليات فحص للملف التنفيذي الأصلي rg، وهو متاح في متقدم / مصفوفة الميزات.

الغلاف مترجم CLI بسيط؛ أما البحث الفعلي فينفذه المحرك نفسه Greph\Text\TextSearcher الذي يستخدمه vendor/bin/greph.

متى تستخدمه

استخدم الغلاف عندما:

  • لديك أداة أو وكيل أو نص برمجي موجود يستدعي rg بالفعل.
  • تريد بديلًا جاهزًا للاستخدام في بيئات لا يمكنك فيها تثبيت ripgrep نفسه (مثل الاستضافة المشتركة، أو الحاويات المحصّنة، أو PaaS المقيّد).
  • تريد سهولة استخدام ripgrep على بنية تحتية لا يتوفر عليها سوى PHP.

استخدم vendor/bin/greph الأصلي عندما:

  • تكتب تعليمات برمجية جديدة ولا تحتاج إلى صيغة ripgrep CLI.
  • تريد الوصول إلى أعلام أصلية لا يوفرها الغلاف (مثل وضع AST).

الاستخدام

سطر الأوامر
rg [options] pattern [path...]
rg --files [options] [path...]

يبحث الاستدعاء المجرد تكراريًا في .:

سطر الأوامر
./vendor/bin/rg -F "function"

يسرد --files الملفات المرشحة بدلًا من البحث:

سطر الأوامر
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden

مخرجات JSON

يُصدر --json الحمولة نفسها المنظّمة كأحداث التي ينتجها ripgrep:

سطر الأوامر
./vendor/bin/rg --json -F "function walk" src/Greph.php
JSON
{"type":"begin","data":{"path":{"text":"src/Greph.php"}}}
{"type":"match","data":{"path":{"text":"src/Greph.php"},"lines":{"text":"    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList\n"},"line_number":41,"absolute_offset":1034,"submatches":[{"match":{"text":"function walk"},"start":18,"end":31}]}}
{"type":"end","data":{"path":{"text":"src/Greph.php"},"binary_offset":null,"stats":{"elapsed":{"secs":0,"nanos":0,"human":"0.000000s"},"searches":1,"searches_with_match":1,"bytes_searched":13383,"bytes_printed":282,"matched_lines":1,"matches":1}}}
{"type":"summary","data":{"elapsed_total":{"human":"0.000000s","nanos":0,"secs":0},"stats":{"bytes_printed":282,"bytes_searched":13383,"matched_lines":1,"matches":1,"searches":1,"searches_with_match":1,"elapsed":{"human":"0.000000s","nanos":0,"secs":0}}}}

تُعرض دائمًا التوقيتات في كائنات stats على أنها صفر.

هذا هو المخطط الذي تتوقعه الأدوات اللاحقة عند تفعيل المخرجات المنظّمة في ripgrep. إذا أردت بنية أبسط، فاستخدم vendor/bin/greph --json بدلًا من ذلك.

نطاق التوافق المتحقق منه

الرايات التالية مُتحقق منها باستخدام rg نفسه في مصفوفة الميزات. يُصدر الملف التنفيذي الأصلي والغلاف مخرجات متكافئة لكل اختبار. وإذا كان للراية اسم مختصر وآخر طويل، يستخدم الاختبار أحدهما ويحلل الغلاف كليهما باعتبارهما الخيار نفسه.

أعلام البحث

  • -F, --fixed-strings
  • -i, --ignore-case
  • -w, --word-regexp
  • -v, --invert-match
  • -c, --count
  • -l, --files-with-matches
  • --files-without-match
  • -I, --no-filename
  • -H, --with-filename
  • -n, --line-number
  • -A N, --after-context N
  • -B N, --before-context N
  • -C N, --context N
  • -m N, --max-count N
  • -e P, --regexp P

أعلام التنقل

  • -L, --follow
  • --glob GLOB
  • --type NAME
  • --type-not NAME
  • --no-ignore
  • --hidden
  • --files
  • --files --hidden
  • --files --type NAME

أعلام الإخراج

  • --json

خيارات مقبولة دون اختبار

يقبل الغلاف أيضًا هذه الأعلام، لكن لم يختبرها أي اختبار لمصفوفة الميزات بعد:

القيود

يغطي غلاف rg الخاص بـGreph نطاق البحث والتنقل الذي تستخدمه معظم الأدوات والوكلاء. ولا يوفّر حاليًا ميزات ripgrep التالية:

  • التعبيرات النمطية متعددة الأسطر (-U، --multiline)
  • الاستبدال (-r، --replace) في وضع النص (استخدم إعادة كتابة AST عبر vendor/bin/greph بدلًا من ذلك)
  • تعريفات الأنواع المخصصة (--type-add، --type-clear)
  • أعلام الترميز (-E، --encoding)
  • نصوص ترشيح --pre
  • --sort، --sortr

إذا واجهت عَلَمًا غير مدعوم، فأرسل بلاغًا يتضمن الاختبار الذي أجريته على ripgrep الأصلي rg والمخرجات المتوقعة. تُضاف الميزات الجديدة مع اختبارات مرجعية لها، لكي يتسع نطاق التوافق المتحقق منه باستمرار.

تكافؤ السلوك

يسعى الغلاف إلى تكافؤ السلوك لا إلى التطابق على مستوى البايتات. المخرجات متكافئة سطرًا بسطر، لكن قد تختلف في تفاصيل شكلية (مثل رموز الألوان والاقتطاع بحسب عرض الطرفية). تتحقق الاختبارات المستخدمة في مصفوفة الميزات من التكافؤ الدلالي، لا من الفروق المطابقة على مستوى البايتات.

بالنسبة إلى الوكلاء والأدوات التي تحلل المخرجات، تتطابق الحقول ذات الصلة بالتحليل (مسار الملف، ورقم السطر، والمحتوى، وموضع المطابقة) بايتًا ببايت مع rg الأصلي في كل اختبار متحقق منه.