# مخرجات ANSI

عيّن `lang` إلى `'ansi'` لإبراز مخرجات الطرفية — أي النص الذي يحتوي على
تسلسلات هروب ANSI — بدلًا من تحليلها باستخدام قواعد لغوية. يحلل shikiphp
رموز الهروب ويلون النص من لوحة ألوان ANSI للقالب. وهو نقل لمحلل الرموز
`lang: 'ansi'` من Shiki، وتتحقق أربعة سيناريوهات مرجعية من HTML
مقارنةً بـ Shiki 3.23.0.

```php
use Shikiphp\Shikiphp;

echo Shikiphp::codeToHtml("\e[31merror\e[0m: something broke", [
    'lang'  => 'ansi',
    'theme' => 'github-dark',
]);
```

هذه طريقة طبيعية لعرض مخرجات CLI الملتقطة — مثل أدوات تشغيل الاختبارات وسجلات البناء
ومخرجات `git` — مع الحفاظ على ألوانها الأصلية. تُزال تسلسلات الهروب من المخرجات؛ ولا يبقى سوى النص داخل امتدادات ملوّنة.

لاحظ سلسلة PHP المحاطة بعلامتي اقتباس مزدوجتين: `"\e"` هو محرف الهروب. عند
عرض مخرجات ملتقطة من عملية (مثلًا باستخدام `shell_exec` أو
`proc_open`)، تكون محارف الهروب موجودة بالفعل في السلسلة.

## ما الذي يفهمه

يقرأ محلل الرموز تسلسلات SGR (Select Graphic Rendition)، `ESC [ … m`، مع
أي عدد من الرموز المفصولة بـ`;`:

| الرموز | التأثير |
| --- | --- |
| `0` | إعادة ضبط كل الألوان والسمات |
| `1`، `3`، `4`، `9` | عريض، مائل، تحته خط، يتوسطه خط |
| `2` | خافت: يُرسم اللون الأمامي بنصف العتامة |
| `7` | عكس: يتبادل اللونان الأمامي والخلفية |
| `21`، `23`، `24`، `27`، `29` | إيقاف السمة المطابقة |
| `22` | شدة عادية: إيقاف الخفوت والخط العريض |
| `30`–`37`، `90`–`97` | اللون الأمامي: الألوان القياسية الثمانية والثمانية الساطعة |
| `40`–`47`، `100`–`107` | الخلفية: الألوان القياسية الثمانية والثمانية الساطعة |
| `38;5;n`، `48;5;n` | اللون الأمامي أو الخلفية من جدول الألوان ذي 256 لونًا |
| `38;2;r;g;b`، `48;2;r;g;b` | لون أمامي أو خلفية حقيقيان بدقة 24 بت |
| `39`، `49` | اللون الأمامي أو الخلفية الافتراضيان |

تُحلل السمتان المخفية (`8`) وفوق الخط (`53`)، لكنهما لا تغيّران
المخرجات، وتُتجاهل الرموز الأخرى. تستمر الأنماط عبر فواصل الأسطر إلى أن يعاد ضبطها،
كما يحدث في الطرفية.

## الألوان

تأتي الألوان المسماة الستة عشر من ألوان `terminal.ansi*` الخاصة بالقالب
(`terminal.ansiRed` و`terminal.ansiBrightBlue` وغيرها). إذا لم يعرّف القالب لونًا، تُستخدم لوحة الألوان الافتراضية لـVS Code (مثل `#cd3131` للأحمر، و`#2472C8` للأزرق). يأخذ النص الذي لم يُعيّن له لون لون المقدمة من القالب، وتكون خلفية الكتلة من خلفية القالب، كما في الإبراز القائم على القواعد اللغوية. في جدول الألوان ذي 256 لونًا، تمثل الخانات 0–15 الألوان المسماة الستة عشر نفسها؛ أما الخانات 16–255 (مكعب الألوان 6×6×6 وتدرج الرمادي) وقيم الألوان الحقيقية فلا تعتمد على القالب.

[`colorReplacements`](https://shikiphp.inline0.dev/ar/docs/options#colorreplacements) ينطبقان أيضًا على ألوان ANSI.

## القوالب المزدوجة

تدعم ANSI خريطة `themes` مثل الإبراز القائم على القواعد اللغوية، وتصدر
متغيرات CSS لكل قالب غير افتراضي:

```php
use Shikiphp\Shikiphp;

$log = "\e[32mPASS\e[0m tests/Unit\n\e[31mFAIL\e[0m tests/Integration";

echo Shikiphp::codeToHtml($log, [
    'lang'   => 'ansi',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);
```

يُحدَّد كل لون مسمى وفق لوحة الألوان الخاصة بكل قالب، لذا قد يختلف الأحمر في
القالب الفاتح عن الأحمر في القالب الداكن.

## بلا حالة قواعد لغوية

بما أن ANSI لا تستخدم قواعد TextMate اللغوية، فلا توجد حالة قواعد لغوية للاحتفاظ بها.
ترمي `getLastGrammarState` خطأً عند `lang: 'ansi'`، وتُرجع `codeToTokensResult`
قيمة `null` `grammarState`.