مرجع CLI

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

يتضمن Greph أربعة ملفات تنفيذية. تستخدم الأربعة المحرك نفسه، ويكمن الاختلاف في الواجهة التي توفرها.

الملف التنفيذي	الغرض
`greph`	بحث نصي أصلي، وبحث AST، وإعادة كتابة AST
`greph-index`	فهرس نصي مُحمّى، وفهرس حقائق AST، وبحث AST مخزّن مؤقتًا
`rg`	غلاف توافق بأسلوب ripgrep
`sg`	غلاف توافق بأسلوب ast-grep

تستخدم جميع المسارات في الأمثلة ./vendor/bin/<binary>، الذي يعمل مع Greph 0.2.3 أو إصدار أحدث عند تثبيته كتبعية. استبدل ./bin/<binary> إذا كنت تعمل من نسخة مستنسخة من المستودع.

`greph`

بحث نصي أصلي، وبحث AST، وإعادة كتابة AST.

سطر الأوامر

greph [options] pattern [path...]
greph -p pattern [options] [path...]
greph -p pattern -r replacement [options] [path...]

إذا لم يُحدَّد مسار، فسيُبحث في الدليل الحالي.

وضع النص

الوضع الافتراضي. الأنماط تعبيرات PCRE2 نمطية ما لم يُحدَّد -F.

سطر الأوامر

# Regex search
./vendor/bin/greph "function\s+\w+" src

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

# Case-insensitive whole-word with two lines of context
./vendor/bin/greph -F -i -w -C 2 "function" src

يتطابق تنسيق الإخراج مع grep -rn:

Text

src/Greph.php:31:final class Greph
src/Greph.php:36:    public static function walk(...

وضع AST

يُفعّل بواسطة -p. تُكتب الأنماط بصيغة PHP عادية باستخدام المتغيرات الوصفية $VAR و$$$VARIADIC. راجع الأوضاع / بحث AST للاطلاع على قواعد الأنماط كاملة.

سطر الأوامر

./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

وضع إعادة الكتابة

يُفعّل بدمج -p مع -r. يستخدم قالب الاستبدال المتغيرات الوصفية نفسها المستخدمة في نمط البحث؛ وتُدرج العقد الملتقطة بحسب الاسم.

سطر الأوامر

# 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

الخيارات

العَلَم	المعنى
`-F`	بحث بسلسلة ثابتة (دون تعبير نمطي)
`-i`	مطابقة دون تمييز حالة الأحرف
`-w`	مطابقة الكلمات كاملة
`-v`	عكس المطابقة
`-c`	عدّ المطابقات في كل ملف
`-l`	سرد مسارات الملفات المطابقة فقط
`-L`	سرد مسارات الملفات غير المطابقة فقط
`-h`	إخفاء بادئات أسماء الملفات في وضع النص
`-H`	طباعة بادئات أسماء الملفات دائمًا في وضع النص
`-n`	إظهار أرقام الأسطر (مفعّل افتراضيًا)
`-A N`	إظهار N من الأسطر بعد كل مطابقة
`-B N`	إظهار N من الأسطر قبل كل مطابقة
`-C N`	إظهار N من أسطر السياق قبل كل مطابقة وبعدها
`-m N`	التوقف بعد N من المطابقات لكل ملف
`-j N`	استخدام N من العمال المتوازيين
`-p PATTERN`	نمط بحث AST
`-r TEMPLATE`	قالب إعادة كتابة AST (يتطلب `-p`)
`--glob GLOB`	تضمين الملفات التي تطابق مساراتها GLOB فقط
`--type NAME`	تضمين اسم مستعار لنوع ملف (`php`، `js`، `md`، ...)
`--type-not NAME`	استبعاد اسم مستعار لنوع ملف
`--lang NAME`	لغة AST. الافتراضية: `php`
`--json`	إصدار مخرجات JSON
`--no-ignore`	تجاهل قواعد `.gitignore` و`.grephignore`
`--hidden`	تضمين الملفات المخفية
`--dry-run`	طباعة عمليات إعادة الكتابة دون كتابة الملفات
`--interactive`	تأكيد إعادة كتابة كل ملف
`--help`	إظهار تعليمات الاستخدام المضمنة

`greph-index`

فهرس نصي مُحمّى، وفهرس حقائق AST، وبحث AST مخزّن مؤقتًا.

سطر الأوامر

greph-index build [path] [--index-dir DIR]
greph-index refresh [path] [--index-dir DIR]
greph-index search [options] pattern [path...]

greph-index set build [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set refresh [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set stats [manifest] [--manifest FILE] [--mode MODE] [--index NAME...] [--dry-refresh]
greph-index set search [options] pattern [path...]

greph-index ast-index build [path] [--index-dir DIR]
greph-index ast-index refresh [path] [--index-dir DIR]
greph-index ast-index search [options] pattern [path...]

greph-index ast-cache build [path] [--index-dir DIR]
greph-index ast-cache refresh [path] [--index-dir DIR]
greph-index ast-cache search [options] pattern [path...]

الفهرس النصي

سطر الأوامر

# Build (full)
./vendor/bin/greph-index build .

# Build with lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

# Refresh (incremental: added, updated, deleted, unchanged)
./vendor/bin/greph-index refresh .

# Query
./vendor/bin/greph-index search -F "function" .
./vendor/bin/greph-index search -i -w "function" .
./vendor/bin/greph-index search -c "function" .
./vendor/bin/greph-index search --trace-plan -F "function" .
./vendor/bin/greph-index search -F "function" . \
  --index-dir core/.greph-index \
  --index-dir plugins/demo/.greph-index \
  --show-index-origin

الفهرس النصي مخزن مُحمّى لمنشورات الثلاثيات والمعرّفات. يوجد افتراضيًا في .greph-index/ ضمن الجذر المفهرس.

مجموعات الفهارس

تحوّل مجموعات الفهارس سير العمل المتكرر متعدد الفهارس إلى بيان مُسمّى:

سطر الأوامر

./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "function" .
./vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
./vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

ملف البيان الافتراضي هو .greph-index-set.json. يشير كل إدخال إلى جذر ووضع وملف تعريف لدورة الحياة. يعمل set build وset refresh على الإدخالات المفعّلة؛ ويوزّع set search العمل على الإدخالات المحددة ويزيل تكرار المطابقات المتداخلة.

فهرس حقائق AST

سطر الأوامر

./vendor/bin/greph-index ast-index build .
./vendor/bin/greph-index ast-index refresh .
./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src
./vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir core/.greph-ast-index \
  --index-dir plugins/demo/.greph-ast-index \
  --show-index-origin

يستخرج فهرس حقائق AST حقائق على مستوى العقد (الاستدعاءات، والإنشاءات، والفئات، والأساليب) إلى مخزن قابل للاستعلام. تُجرى عمليات البحث باستخدام O(log n) على مفتاح الحقيقة، ثم تُتحقق بمقارنتها بالمصدر. يُخزّن افتراضيًا في .greph-ast-index/.

ذاكرة AST المؤقتة

سطر الأوامر

./vendor/bin/greph-index ast-cache build .
./vendor/bin/greph-index ast-cache refresh .
./vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src

تخزّن ذاكرة AST المؤقتة الأشجار المحللة على القرص، فتتجاوز عمليات البحث المحلل بالكامل. تُخزّن افتراضيًا في .greph-ast-cache/.

الخيارات

تطابق خيارات البحث النصي مجموعة أعلام greph (-F، -i، -w، -v، -c، -l، -L، -A، -B، -C، -m، --glob، --type، --type-not، --json، --no-ignore، --hidden).

أعلام إضافية:

العَلَم	المعنى
`--index-dir DIR`	استخدام دليل فهرس مُحمّى غير افتراضي. قابل للتكرار للبحث متعدد الفهارس والإحصاءات.
`--lifecycle PROFILE`	سياسة الإنشاء: `static`، `manual-refresh`، `opportunistic-refresh`، `strict-stale-check`
`--auto-refresh-max-files N`	حد الملفات للتحديث الانتهازي
`--auto-refresh-max-bytes N`	حد البايتات للتحديث الانتهازي
`--manifest FILE`	تحميل بيان مجموعة الفهارس. الافتراضي: `.greph-index-set.json`
`--mode MODE`	حصر عمليات المجموعة في `text` أو `ast-index` أو `ast-cache`
`--index NAME`	حصر عمليات المجموعة في إدخال مُسمّى في البيان. قابل للتكرار.
`--show-index-origin`	إضافة بادئة باسم إدخال الفهرس المطابق إلى مخرجات البحث متعدد الفهارس المُحمّى أو المجموعة
`--trace-plan`	إصدار تشخيصات المخطط المُحمّى إلى `stderr`
`--dry-refresh`	في `stats`، الإبلاغ عما سيفعله البحث المُحمّى دون تغيير أي شيء
`--lang NAME`	لغة AST لعمليات البحث `ast-index` / `ast-cache`. الافتراضية: `php`
`-j N`، `--jobs N`	العمال لفحوص AST
`-l`، `--files-with-matches`	سرد مسارات الملفات المطابقة فقط (وضع AST)
`--strict-parse`	الإخفاق عند أخطاء التحليل بدلًا من تخطيها
`--fallback MODE`	سلوك الفهرس المفقود: `fail` (افتراضيًا) أو `scan`
`--help`	إظهار تعليمات الاستخدام المضمنة

`rg`

غلاف توافق بأسلوب ripgrep. يدعم أعلام ripgrep الأكثر استخدامًا. نُشر النطاق المتحقق منه في مصفوفة الميزات.

سطر الأوامر

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

أمثلة

سطر الأوامر

./vendor/bin/rg -F "function" src
./vendor/bin/rg --json -F "function" src
./vendor/bin/rg --files src
./vendor/bin/rg --files --type php .
./vendor/bin/rg --type-not js -F "function" .

الخيارات المدعومة

العَلَم	المعنى
`-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`	إظهار N من الأسطر بعد كل مطابقة
`-B N`، `--before-context N`	إظهار N من الأسطر قبل كل مطابقة
`-C N`، `--context N`	إظهار N من الأسطر قبل كل مطابقة وبعدها
`-m N`، `--max-count N`	التوقف بعد N من المطابقات لكل ملف
`-j N`، `--threads N`	استخدام N من العمال المتوازيين
`-e P`، `--regexp P`	نمط البحث
`-L`، `--follow`	اتباع الروابط الرمزية
`--glob GLOB`	تضمين الملفات التي تطابق مساراتها GLOB فقط
`--type NAME`	تضمين نوع ملف
`--type-not NAME`	استبعاد نوع ملف
`--json`	إصدار أحداث JSON بأسلوب ripgrep
`--no-ignore`	تجاهل قواعد `.gitignore` و`.grephignore`
`--hidden`	تضمين الملفات المخفية
`--files`	سرد الملفات المرشحة بدلًا من البحث
`--help`	إظهار تعليمات الاستخدام المضمنة

`sg`

غلاف توافق بأسلوب ast-grep. يدعم أعلام ast-grep الأكثر استخدامًا. نُشر النطاق المتحقق منه في مصفوفة الميزات.

سطر الأوامر

sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]

run هو الأمر الأساسي المعتمد في ast-grep. أما scan وrewrite فهما اسمان مستعاران خاصان بالغلاف يعكسان الاستخدام الشائع. يعمل أيضًا الاستدعاء المجرد (sg --pattern ... .) كبحث لمرة واحدة.

أمثلة

سطر الأوامر

./vendor/bin/sg run --pattern 'array($$$ITEMS)' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src/App.php
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src/App.php
./vendor/bin/sg scan -p 'array($$$ITEMS)' src/App.php
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src/App.php

الخيارات المدعومة

العَلَم	المعنى
`-p`، `--pattern PATTERN`	نمط AST
`-r`، `--rewrite TEMPLATE`	قالب إعادة الكتابة
`-l`، `--lang NAME`	لغة AST. الافتراضية: `php`
`-j`، `--threads N`	استخدام N من العمال المتوازيين
`-i`، `--interactive`	تأكيد كل عملية إعادة كتابة
`-U`، `--update-all`	تطبيق عمليات إعادة الكتابة دون تأكيد
`--files-with-matches`	طباعة مسارات الملفات ذات المطابقات فقط
`--json[=STYLE]`	إصدار مخرجات JSON. النمط = `pretty` أو `stream` أو `compact`
`--no-ignore [MODE]`	تجاهل قواعد استبعاد المستودع
`--hidden`	تضمين الملفات المخفية
`--glob GLOB`، `--globs GLOB`	تضمين الملفات التي تطابق مساراتها GLOB فقط
`--type NAME`	تضمين نوع ملف
`--type-not NAME`	استبعاد نوع ملف
`--dry-run`	معاينة عمليات إعادة الكتابة دون كتابة الملفات
`--help`	إظهار تعليمات الاستخدام المضمنة

رموز الخروج

يتبع Greph أعراف grep / ripgrep:

الرمز	المعنى
`0`	عُثر على مطابقة واحدة على الأقل (أو تغيّر ملف واحد على الأقل عند إعادة الكتابة)
`1`	لم يُعثر على مطابقات
`2`	خطأ في الاستخدام أو فشل أثناء التشغيل (وسيط غير صالح، أو فهرس مفقود، أو خطأ تحليل في وضع `--strict-parse`)