Skip to content

Кастомизация и расширение библиотеки схем

Colorer поставляется с базовой библиотекой HRC-схем и HRD-стилей, которую можно загрузить со страницы релизов проекта или получить в составе приложений (плагинов, утилит), использующих Colorer.

Данный раздел отвечает на часто задаваемые вопросы о том, как адаптировать и расширить эту библиотеку под индивидуальные нужды.

Ключевой принцип кастомизации: Настоятельно рекомендуется избегать прямой модификации файлов базовой библиотеки схем. Вместо этого, все пользовательские настройки, добавления и переопределения следует выполнять с помощью внешних механизмов (например, файла hrcsettings.xml или подключения отдельных каталогов с пользовательскими схемами). Такой подход гарантирует, что ваши изменения не будут потеряны при обновлении базовой библиотеки до новой версии.

Если же вы принимаете решение создать полностью собственную, независимую библиотеку схем, то путь к её корневому файлу catalog.xml можно указать в настройках соответствующего приложения, использующего Colorer.

Добавление новых (пользовательских) HRC-схем

Предполагается, что у вас уже есть готовый HRC-файл (или набор HRC-файлов), описывающий синтаксис нового типа файла или расширяющий существующий. Процесс создания самих HRC-схем здесь не рассматривается.

Существует несколько способов интегрировать ваши HRC-схемы в Colorer:

1. Рекомендуемый способ: Указание каталога с пользовательскими HRC-файлами

Большинство приложений, использующих Colorer (например, FarColorer), предоставляют в своих настройках возможность указать путь к файлу или каталогу, содержащим ваши пользовательские HRC-файлы. Colorer загрузит схемы из указанных источников после загрузки базовой библиотеки.

Преимущества:

  • Полная изоляция от базовой библиотеки, что упрощает её обновление.
  • Простота организации пользовательских схем.

Как это работает: Определения прототипов для ваших схем могут находиться либо в отдельных HRC-файлах (часто называемых proto.hrc по аналогии с базовой библиотекой), либо непосредственно в самих HRC-файлах схем (после тега <hrc>, без указания <location>).

2. Использование специального каталога auto в базовой библиотеке (Менее рекомендуемый)

Базовая библиотека схем обычно содержит каталог auto (например, /hrc/auto/ или /auto/ относительно catalog.xml), предназначенный для пользовательских дополнений. Схемы из этого каталога загружаются после основных схем базовой библиотеки (если порядок загрузки в catalog.xml не изменён).

Способы использования каталога auto:

  • С отдельным файлом прототипов: Создайте в каталоге auto свой файл с определениями прототипов (например, my_proto.hrc) и укажите в нём пути к вашим HRC-схемам, размещенным, например, в подкаталоге auto/types/.

Примечание: Не изменяйте empty.hrc, если он существует в дистрибутиве, так как он может быть перезаписан при обновлении.

  • Без отдельного файла прототипов: Разместите HRC-файлы ваших схем непосредственно в каталоге auto. В этом случае определение прототипа должно быть встроено в каждый HRC-файл (после тега <hrc>, без элемента <location>).

Недостатки: Хотя этот способ не требует изменения catalog.xml, он всё же предполагает размещение пользовательских файлов внутри структуры базовой библиотеки, что может усложнить её обновление или привести к потере изменений, если не быть осторожным.

3. Модификация catalog.xml базовой библиотеки (Не рекомендуется)

Вы можете напрямую отредактировать файл catalog.xml базовой библиотеки, добавив в секцию <hrc-sets> элементы <location>, указывающие на ваши HRC-файлы или каталоги с ними.

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

4. Модификация proto.hrc (или аналогичных файлов) базовой библиотеки (Не рекомендуется)

Можно добавить определение вашего прототипа и путь к HRC-схеме непосредственно в один из агрегирующих HRC-файлов базовой библиотеки (например, proto.hrc).

Недостатки: Аналогично предыдущему пункту, это прямое изменение базовой библиотеки, которое будет потеряно при обновлении.

Модификация существующих схем и прототипов

Colorer позволяет переопределять аспекты существующих прототипов из базовой библиотеки. Ключевой механизм здесь – загрузка прототипа с тем же именем (name) из пользовательского HRC-файла или hrcsettings.xml. Если Colorer встречает определение прототипа с именем, которое уже было загружено, новое определение заменяет (или дополняет, в случае параметров) старое. Порядок загрузки определяется catalog.xml и настройками приложения (пользовательские каталоги обычно загружаются позже).

Структура определения прототипа в HRC-файле (упрощенно):

<prototype name="имя_прототипа" group="группа" description="описание">
  <location link="путь_к_файлу_схемы.hrc"/>
  <filename weight="100">/\.ext/</filename>
  <firstline weight="100">/^#!/usr/bin/env interpreter/</firstline>
  <parameters>
    <param name="имя_параметра" value="значение" description="описание_параметра"/>
  </parameters>
</prototype>

Рассмотрим, как изменять различные части этого определения:

Изменение имени группы (group) или описания (description) прототипа

  1. Создайте собственный HRC-файл (например, my_custom_protos.hrc ) и подключите его одним из рекомендуемых способов (см. "Добавление новых (пользовательских) HRC-схем").
  2. В этот файл скопируйте полное определение изменяемого прототипа из базовой библиотеки.
  3. Измените значения атрибутов group и/или description на желаемые.
  4. Важно: Элемент <location link="..."/> должен по-прежнему указывать на оригинальный HRC-файл схемы из базовой библиотеки (или на вашу модифицированную версию, если вы также меняете саму схему, см. ниже). Путь в link указывается относительно вашего my_custom_protos.hrc. При загрузке ваше определение прототипа заменит оригинальное в части этих атрибутов.

Замена файла HRC-схемы для существующего прототипа

Если вы хотите, чтобы существующий тип файла (например, "cpp") использовал вашу собственную, модифицированную версию HRC-схемы вместо стандартной:

  1. Скопируйте и измените HRC-схему: Возьмите оригинальный HRC-файл для данного типа из базовой библиотеки. Сохраните его под новым именем в вашем пользовательском каталоге схем и внесите необходимые изменения.
  2. Создайте/обновите определение прототипа: В вашем пользовательском файле с определениями прототипов (например, my_custom_protos.hrc, подключенном рекомендуемым способом):
    • Создайте или скопируйте определение прототипа с тем же именем (name), что и у оригинального прототипа (например, name="cpp").
    • В элементе <location link="..."/> укажите путь к вашему модифицированному HRC-файлу (относительно my_custom_protos.hrc).

Поскольку пользовательские схемы обычно загружаются после базовых, ваше определение прототипа (с тем же именем, но ссылающееся на ваш HRC-файл) заменит оригинальное определение. Таким образом, Colorer будет использовать вашу версию HRC-схемы для данного типа файлов.

Изменение условий выбора схемы (элементы <filename> и <firstline>)

Условия, по которым Colorer выбирает HRC-схему для файла (соответствие имени файла или первой строки), определяются элементами <filename> и <firstline> внутри прототипа.

Рекомендуемый способ изменения этих условий – использование файла hrcsettings.xml:

  1. В файле hrcsettings.xml добавьте секцию для нужного прототипа, указав его имя: 
    <hrc-settings>
 <prototype name="имя_целевого_прототипа">
  <!-- Ваши новые правила <filename> и <firstline> здесь -->
 </prototype>
</hrc-settings>
  2. Внутри элемента <prototype> укажите полный набор новых правил <filename> и/или <firstline>.

Важно: При загрузке настроек из hrcsettings.xml, если для прототипа указан хотя бы один элемент <filename> или <firstline>, все ранее определённые (в базовой библиотеке или других HRC-файлах) правила <filename> и <firstline> для этого прототипа полностью заменяются теми, что указаны в hrcsettings.xml. Если вы хотите лишь дополнить существующие правила, вам необходимо скопировать их из оригинального определения прототипа в hrcsettings.xml и добавить свои. Подробнее о формате hrcsettings.xml см. в соответствующем разделе документации.

Изменение параметров схемы (элементы <param>)

Параметры, управляющие поведением HRC-схемы (определённые элементами <param> внутри блока <parameters> прототипа), также удобнее всего изменять с помощью файла hrcsettings.xml:

  1. В файле hrcsettings.xml добавьте секцию для нужного прототипа: 
    <hrc-settings>
 <prototype name="имя_целевого_прототипа">
  <parameters>
   <param name="имя_параметра_1" value="новое_значение" description="новое_описание_если_нужно"/>
   <param name="имя_нового_параметра" value="значение" description="описание"/>
   <!-- и т.д. -->
  </parameters>
 </prototype>
</hrc-settings>
  2. Внутри блока <parameters> укажите параметры, которые вы хотите изменить или добавить:
    • Для существующих параметров: Укажите параметр с тем же name. Его атрибуты value и description будут обновлены значениями из hrcsettings.xml.
    • Для добавления новых параметров: Просто укажите новый элемент <param> с его name, value и description. Он будет добавлен к набору параметров прототипа.

В отличие от правил <filename>/<firstline>, параметры из hrcsettings.xml не заменяют весь блок <parameters> целиком, а дополняют или обновляют существующие параметры индивидуально. Подробнее о формате hrcsettings.xml см. в соответствующем разделе документации.

Добавление новых (пользовательских) HRD-стилей

Предполагается, что у вас уже есть готовый HRD-файл (или набор HRD-файлов), описывающий цветовой стиль раскраски. Процесс создания самих HRD-стилей здесь не рассматривается.

Существует несколько способов интегрировать ваши HRD-стили в Colorer:

1. Рекомендуемый способ: Указание каталога с пользовательскими HRD-файлами

Большинство приложений, использующих Colorer (например, FarColorer), предоставляют в своих настройках возможность указать путь к файлу или каталогу, содержащим ваши пользовательские HRD-файлы. Colorer загрузит стили из указанных источников после загрузки базовой библиотеки.

Преимущества:

  • Полная изоляция от базовой библиотеки, что упрощает её обновление.
  • Простота организации пользовательских стилей.

Как это работает:

  • Если путь указан до каталога, то в нём будут использоваться все файлы с расширением .hrd. В основном элементе <hrd> этого xml файла должны быть заполнены его ключевые атрибуты class, name, description. 
    <?xml version="1.0" encoding="UTF-8"?>
<hrd class="rgb" name="my-super" description="My new super style">
  <assign name="def:Text" fore="#99EEEE" back="#000060"/>
  <!-- и т.д. -->
</hrd>
  • Если путь указан на файл, то в нём должны быть указаны определения hrd-стилей с путями до файлов в формате, используемом в catalog.xml. 
    <?xml version="1.0" encoding="UTF-8"?>
<hrd-sets>
    <hrd class="rgb" name="my-super" description="My new super style">
        <location link="c:/user/test/super.hrd"/>
    </hrd>
</hrd-sets>

2. Использование специального каталога auto в базовой библиотеке (Менее рекомендуемый)

Базовая библиотека схем обычно содержит каталог auto (например, /hrc/auto/ или /auto/ относительно catalog.xml), предназначенный для пользовательских дополнений. Схемы из этого каталога загружаются после основных схем базовой библиотеки (если порядок загрузки в catalog.xml не изменён).