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

مخرجات ANSI

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

عيّن 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 ينطبقان أيضًا على ألوان 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.