# CLI

يوفر shikiphp أداة صغيرة لسطر الأوامر في `bin/shikiphp` (تُثبّت باسم `vendor/bin/shikiphp` في مشروعك). وتضم ثلاثة أوامر: يعرض `highlight` ملفًا واحدًا في HTML، بينما يسرد `langs` و`themes` محتويات الحزمة.

## `highlight`

ميّز ملفًا واحفظ الناتج في HTML، مع طباعته إلى stdout.

```bash
vendor/bin/shikiphp highlight <file> [--lang=<lang>] [--theme=<theme>]
```

- `<file>` — المسار المراد قراءته. يجب أن يكون ملفًا موجودًا؛ لا تُقرأ المدخلات القياسية.
- `--lang` — معرّف اللغة أو الاسم البديل. إذا لم يُحدَّد، يُستخدم امتداد الملف كما هو بوصفه المعرّف (ويُستخدم `txt` إن لم يوجد امتداد).
- `--theme` — معرّف السمة. القيمة الافتراضية هي `github-dark`.

```bash
vendor/bin/shikiphp highlight src/App.php --lang=php --theme=nord
```

الناتج هو كتلة `<pre class="shiki …">` ذات سمة واحدة، مثل التي يعيدها [`codeToHtml`](https://shikiphp.inline0.dev/ar/docs/api#shikiphpcodetohtml)، متبوعة بسطر جديد، لذا يمكن توجيهها مباشرةً إلى ملف:

```bash
vendor/bin/shikiphp highlight src/App.php --theme=github-light > app.html
```

لا يقبل الأمر خيارات أخرى. للسمات المزدوجة أو المحولات أو أي [خيار](https://shikiphp.inline0.dev/ar/docs/options) آخر، استدعِ PHP API بدلًا منه.

### الخيارات والمعاملات

يجب أن تكون الخيارات بصيغة `--name=value`. يُتجاهل أي معامل آخر يبدأ بـ `--`، ويُعتمد آخر معامل لا يبدأ بـ `--` بوصفه الملف. لذلك يميّز `--lang php file.rs` الملف `file.rs` بلغة Rust: يُتجاهل `--lang`، ويُستبدل `php` بـ `file.rs`، وتُستنتج اللغة من امتداد `.rs`.

### استنتاج اللغة

من دون `--lang`، يصبح الامتداد معرّف اللغة كما هو. وينجح ذلك عندما يكون الامتداد نفسه معرّفًا مضمّنًا أو اسمًا بديلًا — `php`، و`js`، و`ts`، و`tsx`، و`py`، و`rs`، و`go`، و`md`، و`yml`، و`json`، و`sh`، وغيرها الكثير (راجع [اللغات](https://shikiphp.inline0.dev/ar/docs/languages)). لكنه لا ينجح في الحالات التالية:

- الملفات بلا امتداد، مثل `Makefile` أو `Dockerfile`، والتي تستخدم `txt` كقيمة بديلة؛
- الامتدادات التي لا تطابق معرّف لغة، مثل `.txt`.

`txt` ليست لغة مضمّنة، لذا تنتهي الحالتان حاليًا بخطأ `Unknown language "txt"` ([#3](https://github.com/inline0/shikiphp/issues/3)).
مرّر `--lang` لهذه الملفات:

```bash
vendor/bin/shikiphp highlight Dockerfile --lang=docker
vendor/bin/shikiphp highlight Makefile --lang=make
```

## `langs`

اطبع كل معرّف تقبله الحزمة كلغة، واحدًا في كل سطر.

```bash
vendor/bin/shikiphp langs
```

تضم القائمة 350 سطرًا: معرّفات القواعد الـ253 المضمّنة بترتيب الحزمة (لا أبجديًا)، تليها الأسماء البديلة الـ97 (`js`، و`cjs`، و`mjs`، وهكذا).
تشمل معرّفات القواعد 18 قاعدة مساعدة تضمنها قواعد أخرى، مثل `vue-directives` و`es-tag-css`؛ راجع [اللغات](https://shikiphp.inline0.dev/ar/docs/languages) للفهرس الذي يضم الأسماء والأسماء البديلة. مرّر النتائج عبر `sort` للحصول على قائمة أبجدية.

## `themes`

اطبع معرّفات كل السمات المضمّنة، واحدًا في كل سطر، بترتيب أبجدي (65 سمة).

```bash
vendor/bin/shikiphp themes
```

راجع [السمات](https://shikiphp.inline0.dev/ar/docs/themes) للفهرس الذي يضم الأسماء وأنواع السمات الفاتحة والداكنة.

## المساعدة ورمز الخروج

شغّل دون أمر، أو باستخدام `-h` / `--help` / `help`، لعرض تعليمات الاستخدام.

```bash
vendor/bin/shikiphp --help
```

| الحالة | الناتج | رمز الخروج |
| --- | --- | --- |
| نجاح أو مساعدة | stdout | `0` |
| أمر غير معروف | `Unknown command: <name>` على stderr | `1` |
| `highlight` دون ملف، أو عندما لا يكون الملف موجودًا | سطر الاستخدام على stderr | `1` |
| لغة أو سمة غير معروفة | خطأ `Shikiphp\Exceptions\Highlight` غير ملتقط (خطأ فادح PHP مع تتبع المكدس) | `255` |