Головні розділи файлів визначення підсвічування 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 — назва контексту. За допомогою цієї назви правила визначатимуть контекст, на який слід перемкнутися у випадку виявлення відповідника правила.

attribute визначає стиль, який слід використати для символу, якщо не виявлено відповідності жодному правилу або якщо правило не визначає атрибута. У другому випадку буде використано атрибут контексту, який вказано у контексті правила.

lineEndContext визначає контекст, на який має перемкнутися система підсвічування у разі досягнення кінця рядка. Значенням може бути назва іншого контексту, #stay означатиме, що контекст не слід перемикати (тобто нічого не робити), або #pop означатиме, що слід вийти з контексту. Наприклад, можна скористатися значенням #pop#pop#pop для того, щоб система після виходу піднялася на три контексти вище, або навіть #pop#pop!ІншийКонтекст, щоб піднятися на два контексти вище і перемкнутися на контекст з назвою ІншийКонтекст. Також можна перемкнутися на контекст, який належить визначенню іншої мови, так само, як у правилах IncludeRules, наприклад, ЯкийсьКонтекст##JavaScript. Перемикачі контексту також описано у розділі «Правила визначення способу підсвічування». Типове значення: #stay.

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 визначає властивості коментаря, які буде використано для дій за пунктами меню Інструменти → Закоментувати, Інструменти → Розкоментувати and Інструменти → Додати або вилучити коментування. Серед доступних атрибутів:

name: може мати значення singleLine або multiLine. Якщо буде обрано варіант multiLine, слід буде також вказати атрибути end і region. Якщо ви виберете singleLine, ви зможете додати необов'язковий атрибут position.

start визначає рядок, який використовується для позначення початку коментаря. У C++ цим рядком для багаторядкових коментарів є "/*". Цей атрибут є обов'язковим для типів multiLine і singleLine.

end визначає рядок, яким завершуватиметься коментар. У C++ цим рядком буде "*/". Цей атрибути є доступним лише для коментарів типу multiLine і є для них обов'язковим.

Атрибут region повинен мати значення назви придатного для згортання багаторядкового коментаря. Припустімо, що у правилах вказано beginRegion="Comment" ... endRegion="Comment", тоді вам слід взяти значення region="Comment". За допомогою цього атрибута можна користуватися дією з розкоментування, навіть якщо було виділено не весь текст багаторядкового коментаря. Потрібно лише, щоб курсор знаходився всередині цього багаторядкового коментаря. Цей атрибут є доступним лише для типу multiLine.

position визначає місце вставлення однорядкового коментування. Типово, однорядкове коментування буде вставлено на початку рядка у позиції 0, але якщо ви скористаєтеся записом 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 — другий.

Це правило лишилося з історичних міркувань. Для того, щоб зробити читання зручнішим варто користуватися StringDetect.

AnyChar

Перевірка на рівність одному з символів вказаного набору.

<AnyChar String="(рядок)" (загальні атрибути) />

Атрибут String визначає набір символів.

StringDetect

Перевірка на рівність вказаному рядку.

<StringDetect String="(рядок)" [insensitive="true|false"] (загальні атрибути) (dynamic) />

Атрибут String визначає рядок для порівняння. Типовим значенням атрибута insensitive є false, цей атрибут передається функції порівняння рядків. Якщо значенням атрибута буде true, порівняння відбуватиметься без врахування регістру.

WordDetect

Виявити рядок, але з додатковою вимогою щодо меж слів, зокрема крапки, '.', або пробілу на початку або у кінці слова. Обробка \b<рядок>\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 (загальні атрибути) />

У цього правила немає особливих атрибутів.

Це правило слід використовувати для пропуску рядка з символів, які складають слова, замість послідовної перевірки на основі декількох правил, кожне з яких надаватиме змогу відкидати по одному символу за один прийом через невідповідність.