# اللغات والسمات المخصصة

تغطي المجموعة المضمّنة فهرس Shiki كاملًا، لكن يمكنك تسجيل قاعدة TextMate أو سمة VS Code خاصة بك انطلاقًا من JSON مفكوك الترميز. ويُتاح كلاهما على نسخة `Highlighter`.

## السمات المخصصة

فك ترميز ملف سمة VS Code JSON ومرّره إلى `loadTheme`. يُحدَّد مفتاح السمة بواسطة `name`، وتطغى السمة المخصصة على أي سمة مضمّنة تحمل الاسم نفسه.

```php
use Shikiphp\Shikiphp;

$highlighter = Shikiphp::highlighter();

$theme = json_decode(file_get_contents('my-theme.json'), true);
$highlighter->loadTheme($theme);

$code = '<?php echo "hello";';

echo $highlighter->codeToHtml($code, [
    'lang'  => 'php',
    'theme' => $theme['name'], // the theme's own name
]);
```

## القواعد المخصصة

يسجّل `loadGrammar` قيمة `.tmLanguage.json` مفكوكة الترميز، كي تتمكن أي نقطة دخول من استخدامها عبر معرّف اللغة:

```php
public function loadGrammar(
    array $rawTmLanguage,
    ?string $langId = null,
    array $aliases = [],
    array $embedded = [],
): void
```

- `$langId` — المعرّف الذي ستُشار به إليها. إذا لم يُحدَّد، يُستخدم `name` الخاص بالقواعد، ثم `scopeName`.
- `$aliases` — معرّفات إضافية تشير إلى القاعدة نفسها.
- `$embedded` — معرّفات اللغات التي تضمّنها هذه القاعدة، ليُحلّ أيضًا ما يقابلها من قواعد.

```php
use Shikiphp\Shikiphp;

$highlighter = Shikiphp::highlighter();

$grammar = json_decode(file_get_contents('mylang.tmLanguage.json'), true);
$highlighter->loadGrammar($grammar, 'mylang', aliases: ['ml']);

$code = file_get_contents('example.mylang');

echo $highlighter->codeToHtml($code, [
    'lang'  => 'mylang',
    'theme' => 'github-dark',
]);
```

تُحل مراجع Grammar `include` (`#repo`، و`$self`، و`$base`، و`other.scope`) واللغات المضمّنة بالرجوع إلى القواعد المسجّلة مسبقًا في أداة التمييز؛ لذا سجّل أي تبعيات أولًا.

## استخدام أداة تمييز مخصصة عبر الواجهة الوسيطة

إذا أردت أن تستخدم الواجهة الوسيطة الثابتة `Shikiphp` أداة التمييز المخصصة، مرّرها إليها باستخدام `Shikiphp::use`:

```php
use Shikiphp\Highlighter;
use Shikiphp\Shikiphp;

$myTheme = json_decode(file_get_contents('my-theme.json'), true);
$myGrammar = json_decode(file_get_contents('mylang.tmLanguage.json'), true);
$code = file_get_contents('example.mylang');

$highlighter = Highlighter::createBundled();
$highlighter->loadTheme($myTheme);
$highlighter->loadGrammar($myGrammar, 'mylang');

Shikiphp::use($highlighter);

// Now the facade delegates to your highlighter.
echo Shikiphp::codeToHtml($code, ['lang' => 'mylang', 'theme' => $myTheme['name']]);
```

استدعِ `Shikiphp::reset()` للعودة إلى أداة التمييز المضمّنة الافتراضية.