Основные разделы файлов определения синтаксиса KatePart

Файл подсветки содержит заголовок, в котором задаётся версия XML:

<?xml version="1.0" encoding="UTF-8"?>

Корневым элементом файла определения является элемент language. Доступные атрибуты:

Обязательные атрибуты:

name задаёт название языка, которое затем будет отображаться в меню и диалоговых окнах.

section определяет категорию.

extensions определяет суффиксы названий файлов, например "*.cpp;*.h".

version задаёт текущую версию файла определения в формате целого числа. Не забывайте увеличивать номер версии при каждом внесении изменений в файл.

kateversion задаёт последнюю поддерживаемую версию KatePart.

Необязательные атрибуты:

mimetype выполняет привязку файлов на основе типа MIME.

casesensitive определяет, чувствительны ли ключевые слова к регистру.

priority требуется, если в другом файле определения подсветки используются те же суффиксы файлов. Для подсветки будут использованы правила с более высоким приоритетом.

author содержит имя автора и его адрес электронной почты.

license содержит название лицензии нового файла подсветки синтаксиса, обычно это MIT.

style содержит данные о языке программирования и используется средствами расстановки отступов для атрибута required-syntax-style.

indenter определяет используемое по умолчанию средство расстановки отступов. Доступные варианты: ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby и xml.

hidden определяет, следует ли отображать название подсветки в меню KatePart.

Поэтому следующая строка может выглядеть так:

<language name="C++" version="1" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />

Следующим элементом является highlighting. В этом элементе содержится необязательный элемент list и обязательные элементы contexts и itemDatas.

Элементы list содержат список ключевых слов. В этом случае ключевыми словами являются class и const. Возможно добавить неограниченное количество списков.

Начиная с KDE Frameworks™ 5.53, в список возможно включать ключевые слова из другого списка, языка или файла с помощью элемента include. Для разделения названия списка и названия определения языка следует использовать символы ## таким же образом, что и в правиле IncludeRules. Это позволяет предотвратить дублирование списков ключевых слов, когда требуется включить ключевые слова из другого языка или файла. Например, список othername содержит ключевое слово str и все ключевые слова из списка types, который относится к языку программирования ISO C++.

В элементе contexts содержатся все контексты. По умолчанию первым контекстом является начало диапазона подсветки. В контексте Normal Text существуют два правила: одно сопоставляет список ключевых слов с названием somename, другое определяет кавычки и переключает контекст на контекст string. Дополнительные сведения о правилах приводятся в следующей главе.

Третья часть состоит из элемента itemDatas. В этом элементе содержатся все цвета и гарнитуры шрифтов, необходимые для контекстов и правил. В примере использовано itemData Normal Text, String и Keyword.

<highlighting>
    <list name="somename">
      <item>class</item>
      <item>const</item>
    </list>
    <list name="othername">
      <item>str</item>
      <include>types##ISO C++</include>
    </list>
    <contexts>
      <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
        <keyword attribute="Keyword" context="#stay" String="somename" />
        <keyword attribute="Keyword" context="#stay" String="othername" />
        <DetectChar attribute="String" context="string" char="&quot;" />
      </context>
      <context attribute="String" lineEndContext="#stay" name="string" >
        <DetectChar attribute="String" context="#pop" char="&quot;" />
      </context>
    </contexts>
    <itemDatas>
      <itemData name="Normal Text" defStyleNum="dsNormal" />
      <itemData name="Keyword" defStyleNum="dsKeyword" />
      <itemData name="String" defStyleNum="dsString" />
    </itemDatas>
  </highlighting>

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

В разделе comment определяется последовательность символов, с помощью которой возможно добавить однострочный комментарий. Также возможно определить многострочный комментарий с помощью элемента multiLine с дополнительным атрибутом end. Эти определения будут использованы при выполнении пользователем действий закомментировать/раскомментировать.

В разделе keywords определяется, следует ли учитывать регистр символов в списках ключевых слов или нет. Описание других атрибутов приводится далее.

В других разделах, folding, emptyLines и spellchecking, как правило, необходимости нет. Сведения об этих разделах приводятся далее.

<general>
    <comments>
      <comment name="singleLine" start="#"/>
      <comment name="multiLine" start="###" end="###" region="CommentFolding"/>
    </comments>
    <keywords casesensitive="1"/>
    <folding indentationsensitive="0"/>
    <emptyLines>
      <emptyLine regexpr="\s+"/>
      <emptyLine regexpr="\s*#.*"/>
    </emptyLines>
    <spellchecking>
      <encoding char="á" string="\'a"/>
      <encoding char="à" string="\`a"/>
    </spellchecking>
  </general>
</language>

Элемент context относится к группе contexts. Этот элемент определяет связанные с контекстом правила (например, что должно произойти, если система подсветки достигнет конца строки). Доступные атрибуты:

name — название контекста. С помощью этого названия правила будут определять контекст, на который следует переключиться в случае выявления соответствия правила.

lineEndContext определяет контекст, на который переключается система подсветки при достижении конца строки. Значением этого атрибута может быть либо название другого контекста, либо #stay для запрета смены контекста (ничего не делать), либо #pop для выхода из контекста. Возможно, например, указать #pop#pop#pop, чтобы система поднялась на три контекста выше, или даже #pop#pop!OtherContext, чтобы система поднялась на два контекста выше и переключилась на контекст с названием OtherContext. Также возможно переключиться на контекст, который принадлежит другому определению языка, так же, как в правилах IncludeRules (например, SomeContext##JavaScript). Обратите внимание, что это переключение контекста невозможно использовать совместно с #pop: например, #pop!SomeContext##JavaScript является некорректным. Переключения контекста также описаны в «Правила определения способа подсветки».

lineEmptyContext определяет контекст, который используется при обнаружении пустой строки. Номенклатура переключений контекста та же, что и описанная ранее для lineEndContext. Значение по умолчанию: #stay.

fallthroughContext указывает следующий контекст для переключения, если ни одно из правил не было признано соответствующим. Номенклатура переключений контекста та же, что и описанная ранее для lineEndContext. Значение по умолчанию: #stay.

fallthrough определяет, будет ли система подсветки переключаться на контекст, определённый в fallthroughContext, если ни одно из правил не было признано соответствующим. Обратите внимание, что с версии KDE Frameworks™ 5.62 этот атрибут является устаревшим. Вместо него следуетиспользовать fallthroughContext: если указан атрибут fallthroughContext, неявным образомпредполагается значение fallthrough равное true. Значение по умолчанию: false.

noIndentationBasedFolding отключает сворачивание на основе отступов в контексте. Если сворачивание на основе отступов неактивно, этот атрибут не имеет смысла. Этот атрибут указывается в элементе folding группы general. Значение по умолчанию: false.

Элемент itemData находится в группе itemDatas. Она определяет гарнитуры шрифтов и цвета. Возможно указывать пользовательские гарнитуры и цвета. Рекомендуется использовать стили по умолчанию, чтобы пользователь всегда видел одинаковые цвета в файлах различных форматов. Но всё же иногда другого способа нет, и придётся изменить атрибуты цветов и шрифтов. Обязательные атрибуты — name и defStyleNum, прочие являются необязательными. Доступные атрибуты:

name задаёт название itemData. Оно будет использоваться в контекстах и правилах для ссылки на itemData в атрибуте attribute.

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

color определяет цвет. Возможные форматы: '#rrggbb' или '#rgb'.

selColor определяет цвет выделенного текста.

italic, если значение true, текст будет выделен курсивом.

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

underline, если значение true, текст будет подчёркнут.

strikeout, если значение true, текст будет перечёркнут.

spellChecking, если значение true, будет проверено правописание текста.

Элемент keywords в группе general определяет свойства ключевых слов. Доступные атрибуты:

casesensitive может иметь значение true или false. Если значение true, все ключевые слова сопоставляются с учётом регистра.

weakDeliminator — список символов, которые не являются символами разделения слов. Например, точка '.' является символом разделения слов. Допустим, что ключевое слово в list содержит точку: это слово будет задействовано, только если точка будет указана среди значений этого аргумента.

additionalDeliminator определяет дополнительные символы разметки.

wordWrapDeliminator определяет символы, после которых возможен перенос строки.

Стандартные символы разметки и разделения слов: .():!+,-<=>%&*/;?[]^{|}~\, пробел (' ') и символ табуляции ('\t').

Элемент comment в группе comments определяет свойства комментариев, которые будут использованы для действий в пунктах меню Сервис → Закомментировать, Сервис → Раскомментировать и Сервис → Закомментировать или раскомментировать. Доступные атрибуты:

name может иметь иметь значение singleLine или multiLine. Если выбрано значение multiLine, необходимо также указать атрибуты end и region. Если выбрано значение singleLine, возможно добавить необязательный атрибут position.

start определяет строку, которая используется для обозначения начала комментария. В C++ этой строкой для многострочных комментариев является "/*". Этот атрибут является обязательным для типов multiLine и singleLine.

end определяет строку, которой завершается комментарий. В C++ этой строкой будет "*/". Этот атрибут доступен только для комментариев типа multiLine и является обязательным для них.

Атрибут region должен иметь значение названия пригодного для сворачивания многострочного комментария. Например, если в правилах указано beginRegion="Comment" ... endRegion="Comment", следует использовать значение region="Comment". Это позволяет применять действие раскомментирования, даже если был выделен не весь текст многострочного комментария. Нужно только, чтобы курсор находился внутри этого многострочного комментария. Этот атрибут доступен только для типа multiLine.

position определяет место вставки однострочного комментария. По умолчанию однострочный комментарий будет вставлен в начале строки в нулевой позиции. Но если использовать запись position="afterwhitespace", комментарий будет вставлен справа после первого пробельного блока, перед первым непробельным символом. Эта возможность полезна для языков, где важны отступы в строках, таких как Python и YAML. Этот атрибут является необязательным, его единственное возможное значение — это afterwhitespace. Он доступен только для типа singleLine.

Элемент folding в группе general определяет свойства сворачивания кода. Доступны атрибуты:

indentationsensitive, если значение true, отметки сворачивания кода будут добавлены на основе отступов, как в языке сценариев Python. Обычно не требуется указывать этот атрибут, так как его значением по умолчанию является false.

Элемент emptyLine в группе emptyLines определяет, какие из строк следует считать пустыми. Это позволяет изменить поведение атрибута lineEmptyContext в элементах context. Доступные атрибуты:

regexpr определяет регулярное выражение, соответствие которому будет считаться пустой строкой. По умолчанию пустые строки не содержат никаких символов, поэтому это регулярное выражение добавляет «пустые» строки, например, если следует считать строки из пробелов пустыми. Впрочем, для большинства определений синтаксиса в этом атрибуте нет необходимости.

Элемент encoding в группе spellchecking определяет кодировку символов, которая используется для проверки орфографии. Доступные атрибуты:

char — кодированный символ.

string — последовательность символов, которая будет закодирована как символ char при проверке правописания. Например, если выполняется обработка кода на языке LaTeX, строка \"{A} соответствует символу Ä.

Общие стили по умолчанию:

dsNormal, если не требуется особая подсветка.

dsKeyword, встроенные ключевые слова языка.

dsFunction, вызовы и определения функций.

dsVariable, если применимо: названия переменных (например, $someVar в PHP/Perl).

dsControlFlow, ключевые слова управления обработкой, включая if, else, switch, break, return, yield, ...

dsOperator, операторы, например + - * / :: < >

dsBuiltIn, встроенные функции, классы и объекты.

dsExtension, общие расширения, например классы Qt™ и функции и макросы в C++ и Python.

dsPreprocessor, инструкции препроцессора или определения макросов.

dsAttribute, аннотации, например @override и __declspec(...).

Стили по умолчанию, связанные со строками:

dsChar, отдельные символы, например 'x'.

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

dsString, строки, например "hello world".

dsVerbatimString, буквальные или необработанные строки, например 'raw \backlash' в Perl, CoffeeScript и командных оболочках, а также r'\raw' в Python.

dsSpecialString, SQL, регулярные выражения, документация HERE, математический режим L^AT_EX, ...

dsImport, импорт, включение или потребность в модулях.

Стили по умолчанию, связанные с числами:

dsDataType, встроенные типы данных, например int, void, u64.

dsDecVal, десятичные значения.

dsBaseN, значения с основой, отличной от 10.

dsFloat, значения с плавающей точкой.

dsConstant, встроенные и заданные пользователем константы, например PI.

Стили по умолчанию, связанные с комментариями и документацией:

dsComment, комментарии.

dsDocumentation, /** Комментарии в документах */ или """docstrings""".

dsAnnotation, команды документации, например @param, @brief.

dsCommentVar, названия переменных, используемых в приведённых выше командах, например "foobar" в @param foobar.

dsRegionMarker, отметки области, например //BEGIN, //END в комментариях.

Прочие стили по умолчанию:

dsInformation, примечания и подсказки, например @note в doxygen.

dsWarning, предупреждения, например @warning в doxygen.

dsAlert, специальные слова, например TODO, FIXME, XXXX.

dsError, подсветка ошибок и синтаксических неточностей.

dsOthers, если не подходит иное.

DetectChar

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

<DetectChar char="(символ)" (общие атрибуты) (dynamic) />

Атрибут char определяет символ, с которым будет происходить сравнение.

Detect2Chars

Проверка на соответствие двум определённым символам в заданном порядке.

<Detect2Chars char="(символ)" char1="(символ)" (общие атрибуты) />

Атрибут char определяет первый символ, с которым будет происходить сравнение, char1 — второй.

AnyChar

Проверка на соответствие одному символу из набора указанных символов.

<AnyChar String="(строка)" (общие атрибуты) />

Атрибут String определяет набор символов.

StringDetect

Проверка на соответствие указанной строке.

<StringDetect String="(строка)" [insensitive="true|false"] (общие атрибуты) (dynamic) />

Атрибут String определяет строку, с которой будет происходить сравнение. Атрибут insensitive по умолчанию имеет значение false, этот атрибут передаётся функции сравнения строк. Если он имеет значение true, сравнение выполняется без учёта регистра.

WordDetect

Проверка на соответствие указанной строке, но с дополнительным требованием относительно границ слов, в частности, точки '.' или пробела в начале и конце слова. Обработка \b<string>\b выполняется подобно обработке регулярного выражения, но быстрее, чем обработка правила RegExpr.

<WordDetect String="(строка)" [insensitive="true|false"] (общие атрибуты) (локальные разделители) />

Атрибут String определяет строку, с которой будет происходить сравнение. Атрибут insensitive по умолчанию имеет значение false, этот атрибут передаётся функции сравнения строк. Если он имеет значение true, сравнение выполняется без учёта регистра.

Начиная с Kate 3.5 (KDE 4.5)

RegExpr

Проверка на совпадение с регулярным выражением.

<RegExpr String="(строка)" [insensitive="true|false"] [minimal="true|false"] (общие атрибуты) (dynamic) />

Атрибут String определяет регулярное выражение.

insensitive по умолчанию имеет значение false, этот атрибут передаётся движку поиска по регулярным выражениям.

minimal по умолчанию имеет значение false, этот атрибут передаётся движку поиска по регулярным выражениям.

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

Подробные сведения доступны в разделе Регулярные выражения.

keyword

Проверка на соответствие ключевому слову из указанного списка.

<keyword String="(название списка)" (общие атрибуты) (локальные разделители) />

Атрибут String определяет название списка ключевых слов. Список с указанным названием уже должен существовать.

Система подсветки обрабатывает правила ключевых слов оптимизированным способом. Поэтому совершенно необходимо, чтобы все ключевые слова, которые следует найти, были ограничены заданными разделителями, заранее предусмотренными (разделителями по умолчанию) или явно указанными в свойстве additionalDeliminator тега keywords.

Если ключевое слово, которое следует найти, должно содержать символ разделителя, соответствующий символ следует добавить в свойство weakDeliminator тега keywords. После этого символ утратит своё свойство разделителя во всех правилах keyword. Также можно воспользоваться атрибутом weakDeliminator тега keyword, чтобы конкретное изменение применялось только к конкретному правилу.

Int

Проверка на соответствие целому числу (регулярное выражение: \b[0-9]+).

<Int (общие атрибуты) (локальные разделители) />

У этого правила нет специфичных атрибутов.

Float

Проверка на соответствие числу с плавающей точкой (регулярное выражение: (\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?).

<Float (общие атрибуты) (локальные разделители) />

У этого правила нет специфичных атрибутов.

HlCOct

Проверка на соответствие восьмеричному преставлению числа (регулярное выражение: \b0[0-7]+).

<HlCOct (общие атрибуты) (локальные разделители) />

У этого правила нет специфичных атрибутов.

HlCHex

Проверка на соответствие шестнадцатеричному представлению числа (регулярное выражение: \b0[xX][0-9a-fA-F]+).

<HlCHex (общие атрибуты) (локальные разделители) />

У этого правила нет специфичных атрибутов.

HlCStringChar

Проверка на соответствие символу управляющей последовательности.

<HlCStringChar (общие атрибуты) />

У этого правила нет специфичных атрибутов.

Проверка на соответствие символам, которые часто используются в коде программ, например \n (переход на новую строку) или \t (табуляция).

Поиск будет выполняться по перечисленным далее символам, если эти символы расположены сразу после обратной косой черты (\): abefnrtv"'?\. Кроме того, соответствующими считаются экранированные шестнадцатеричные числа, например \xff, и экранированные восьмеричные числа, например \033.

HlCChar

Проверка на соответствие символу C.

<HlCChar (общие атрибуты) />

У этого правила нет специфичных атрибутов.

Проверка на соответствие символам C, заключённым в одинарные кавычки (пример: 'c'). Кавычки могут содержать обычный или экранированный символ. Сведения о поиске экранированных последовательностей символов доступны в пункте, посвящённом HlCStringChar.

RangeDetect

Проверка на соответствие строке с заданными символами начала и конца.

<RangeDetect char="(символ)"  char1="(символ)" (общие атрибуты) />

char определяет символ начала диапазона, char1 — символ конца диапазона.

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

LineContinue

Проверка на соответствие указанному символу в конце строки.

<LineContinue (общие атрибуты) [char="\"] />

Необязательный для установления соответствия атрибут char, значением по умолчанию является символ обратной косой черты ('\'). Введён с KDE 4.13.

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

IncludeRules

Включение правил из другого контекста, языка или файла.

<IncludeRules context="ссылка на контекст" [includeAttrib="true|false"] />

Атрибут context определяет контекст, который следует включить.

Если значением является простая строка, в текущий контекст будут включены все заданные правила, например:

<IncludeRules context="anotherContext" />

Если строка содержит последовательность символов ##, система подсветки выполнит поиск контекста в другом определении языка с указанным названием. Например,

<IncludeRules context="String##C++" />

позволяет включить контекст String из определения правил подсветки C++.

Если атрибут includeAttrib имеет значение true, атрибут назначения будет изменён на атрибут источника. Это необходимо, например, для выполнения комментирования в том случае, если подсветка соответствующего включённому контексту текста отличается от подсветки из основного контекста.

DetectSpaces

Поиск пробелов.

<DetectSpaces (общие атрибуты) />

У этого правила нет специфичных атрибутов.

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

DetectIdentifier

Поиск строк идентификаторов (регулярное выражение: [a-zA-Z_][a-zA-Z0-9_]*).

<DetectIdentifier (общие атрибуты) />

У этого правила нет специфичных атрибутов.

С помощью этого правила возможно сразу пропустить строку из словообразующих символов, а не выполнять последовательную проверку на основе нескольких правил, каждое из которых будет предоставлять возможность отвергать по одному символу за раз из-за несоответствия.