# توافق rg

`vendor/bin/rg` غلاف توافق بأسلوب ripgrep. يقبل أعلام ripgrep الأكثر استخدامًا، ويتنقل في شجرة الملفات كما يفعل ripgrep، ويُصدر المخرجات المطابقة. أُعيد إنتاج نطاق التوافق المتحقق منه استنادًا إلى عمليات فحص للملف التنفيذي الأصلي `rg`، وهو متاح في [متقدم / مصفوفة الميزات](https://greph.inline0.dev/ar/docs/advanced/feature-matrix).

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

## متى تستخدمه

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

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

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

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

## الاستخدام

```bash
rg [options] pattern [path...]
rg --files [options] [path...]
```

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

```bash
./vendor/bin/rg -F "function"
```

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

```bash
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden
```

## مخرجات JSON

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

```bash
./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` نفسه في [مصفوفة الميزات](https://greph.inline0.dev/ar/docs/advanced/feature-matrix). يُصدر الملف التنفيذي الأصلي والغلاف مخرجات متكافئة لكل اختبار. وإذا كان للراية اسم مختصر وآخر طويل، يستخدم الاختبار أحدهما ويحلل الغلاف كليهما باعتبارهما الخيار نفسه.

### أعلام البحث

- `-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`

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

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

- `-j N`، `--threads N` (عدد العمال، راجع [العمال المتوازيون](https://greph.inline0.dev/ar/docs/advanced/parallel))
- `-q`، `--quiet`
- `--no-follow`

## القيود

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

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

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

## تكافؤ السلوك

يسعى الغلاف إلى تكافؤ السلوك لا إلى التطابق على مستوى البايتات. المخرجات متكافئة سطرًا بسطر، لكن قد تختلف في تفاصيل شكلية (مثل رموز الألوان والاقتطاع بحسب عرض الطرفية). تتحقق الاختبارات المستخدمة في [مصفوفة الميزات](https://greph.inline0.dev/ar/docs/advanced/feature-matrix) من التكافؤ الدلالي، لا من الفروق المطابقة على مستوى البايتات.

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