Вклад

Добро пожаловать в решение для подсветки синтаксиса на стороне сервера! Если вы хотите внести свой вклад в проект, вот несколько вещей, о которых следует помнить!

Определения языка + стили

Мы не принимаем PR с новыми или обновленными определениями языка или таблицами стилей. Вместо этого их следует вносить в проект highlight.js. Процесс поддержки стилей и преобразования определений языка полностью автоматизирован и оставлен на усмотрение сопровождающих проекта, которые должны запускать его каждый раз, когда выходит новая версия highlight.js.

Обновления из `highlight.js`

Если вы хотите сделать PR, содержащий изменения поведения, сделанные в проекте highlight.js, пожалуйста, убедитесь, что вы ссылаетесь на соответствующие коммиты highlight.js и журналы изменений. Поскольку этот проект является прямым переносом, мы должны сделать все возможное, чтобы поведение было как можно более идентичным.

PR, отражающие изменения, сделанные в highlight.js, должны только делаться после того, как в highlight.js будет выпущен релиз, помеченный этими изменениями. Этот проект всегда будет выпускать обновления после highlight.js релизов.

Мы не даем никаких гарантий, что последняя мастер-версия highlight.php будет совместима с последней мастер-версией highlight.js.

Структура проекта

Проект содержит следующие папки:

Highlight

Эта папка содержит основной исходный текст и следующие файлы (классы):

Highlight.php (Highlight)

Это тот, который делает подсветку для вас и тот, который вы, вероятно, будете искать.

Language.php (Language)

Вспомогательный класс, используемый в классе Highlight. Экземпляры этих классов представляют собой довольно сложные структуры регулярных выражений, необходимых для сканирования программного кода с целью его выделения.

Вам этот класс не нужен.

JsonRef.php (JsonRef)

Вспомогательный класс для декодирования JSON-файлов, содержащих ссылки на пути. Данные определения языка из highlight.js слишком сложны для описания в обычных JSON-файлах. Поэтому для их экспорта было решено использовать dojox.json.ref. Этот класс способен (в очень ограниченном объеме) декодировать данные JSON, созданные с помощью инструментария dojo.

Этот класс имеет очень четкое назначение и может быть полезен и в других проектах (и может быть хорошей отправной точкой для нового проекта ;). ).

Autoloader.php (Autoloader)

Простой класс автозагрузчика, который вы можете захотеть или, скорее всего, не захотите использовать. Он используется для инструментов и тестов.

папка languages

Эта папка содержит все определения языков: по одному JSON-файлу для каждого языка. Эти файлы не закодированы вручную, а извлечены из оригинального проекта highlight.js.

Стили

Это CSS-файлы, необходимые для раскраски кода. Здесь не о чем говорить: они просто скопированы из проекта highlight.js.

Demo

Эта папка содержит две демонстрационные страницы, доступ к которым можно получить через браузер.

demo.php

Тестовая страница, показывающая все поддерживаемые языки и стили.

compare.php

Похожа на demo.php, но эта страница посвящена сравнению между highlight.php и highlight.js. Оба варианта должны дать одинаковые результаты.

Тест

Эта папка содержит модульные тесты для highlight.php. Чтобы запустить их, запустите phpunit из этой папки:

phpnunit .

Обратите внимание, что следующие тесты для highlight.js не были переписаны для highlight.php:

специальный explicitLanguage

Управление выбором языка путем установки атрибута, содержащего <div>, неактуально для highlight.php

специальный customMarkup

В highlight.js код может содержать дополнительную HTML-разметку, как в следующем фрагменте PHP: $sum = <b>$a</b> + $b;. В настоящее время это не поддерживается highlight.php, который может выделять только (unescaped) код. Также не поддерживается выделение <br> (HTML break element). Однако highlight.php поддерживает замену табуляции (по умолчанию 4 пробела).

специальный noHighlight

Нет необходимости отключать подсветку через имя класса в контейнере кода.

special buildClassName

highlight.php не изменяет имена классов контейнеров кода.

Инструменты

Набор скриптов, которые используются для извлечения данных из исходного проекта highlight.js.

Процесс извлечения языков из highlight.js был вынесен в один скрипт. Этот скрипт требует, чтобы на вашей машине были установлены cURL, PHP и node.js. Это необходимо только в том случае, если вы хотите обновить языки или добавить новые языки, это не требуется для использования этой библиотеки в вашем приложении.

cd tools
bash process.sh

Почему мы обычно не используем `mb_*` функции?

PHP предлагает mb_ префиксные строковые функции для поддержки многобайтовых строк, что означает поддержку символов юникода. Однако функции PREG в PHP вычисляют длины и позиции строк в байтах, а не длины символов. По этой причине мы обычно не используем многобайтовые варианты строковых функций; из этой политики есть исключения.

Исключением из этой политики является использование функций, которые не используются для вычисления длин или позиций строк; например, mb_strtolower.